Skip to main content
Version: 2.2.0

Class: Namefully

A utility for organizing human names in a particular order, way, or shape.

Though namefully is designed to be easy to use, it does not magically guess which part of the name is what (prefix, suffix, first, last, or middle names). It relies actually on how the name parts are indicated (i.e., their roles) so that it can perform internally certain operations and saves us some extra calculations/processing. Additionally, Namefully objects may be created using distinct raw data shapes. This is intended to give some flexibility to you so that you are not bound to a particular data format (e.g., string). Follow the API reference to know how to harness its usability as this utility aims to save time in formatting names.

namefully also works like a trapdoor. Once some name data is provided and validated, you may only access it but not update any part of it. This means that no editing is possible. If the name is mistaken, a new instance of Namefully must be created. In simple terms, it's immutable. Remember, this utility's primary objective is to help manipulate human names, not the opposite.

Note that the name standards used for the current version of this utility are as follows: [prefix] firstName [middleName] lastName [suffix] where the opening [ and closing ] brackets mean that these parts are optional. In other words, the most basic and typical case is a name that looks like this: John Smith, where John is the first name piece and Smith, the last name piece.

See​

https://www.fbiic.gov/public/2008/nov/Naming_practice_guide_UK_2006.pdf for more info on name standards.

IMPORTANT: Keep in mind that the order of appearance (or name order) matters and may be altered through configurable parameters, which will be seen later. By default, the order of appearance is as shown above and will be used as a basis for future examples and use cases.

Once imported, all that is required to do is to create instances of Namefully as you see fit and the rest will follow.

Some terminologies used across the library are:

  • namon: 1 piece of name (e.g., prefix)
  • nama: a combination of 2+ pieces of name (e.g., first name + last name)

Happy name handling 😊!

Constructors​

Constructor​

new Namefully(names, options?): Namefully

Creates a name with distinguishable parts.

Parameters​

names​

string | Name[] | JsonName | string[] | Parser<unknown>

element to parse.

options?​

NameOptions

additional settings.

Optional parameters may be provided with specifics on how to treat a full name during its existence. All name parts must have at least one (1) character to proceed. That is the only requirement/validation of namefully.

Returns​

Namefully

Properties​

json​

json: () => JsonName

Returns​

JsonName

Accessors​

birth​

Get Signature​

get birth(): string

The birth name part of the name set.

Returns​

string

config​

Get Signature​

get config(): Config

The configuration dictating this name's behavior.

Returns​

Config

first​

Get Signature​

get first(): string

The firt name part of the name set.

Returns​

string

full​

Get Signature​

get full(): string

The entire name set.

Returns​

string

hasMiddle​

Get Signature​

get hasMiddle(): boolean

Returns true if any middle name has been set.

Returns​

boolean

isMono​

Get Signature​

get isMono(): boolean

Whether the name is a single word name.

Returns​

boolean

last​

Get Signature​

get last(): string

The last name part of the name set.

Returns​

string

length​

Get Signature​

get length(): number

The number of characters of the birthName, including spaces.

Returns​

number

long​

Get Signature​

get long(): string

The longest version of a human name (a.k.a birth name).

Returns​

string

middle​

Get Signature​

get middle(): string

The first middle name part of the name set if any.

Returns​

string

parts​

Get Signature​

get parts(): Iterable<Name>

Returns an iterable of the name components in their natural form.

Regardless of the order of appearance, this method will always return the existing Names according to the name standards upon which this library is based.

This is useful for iterating over the name parts in a consistent manner and this automatically enables operations such as mapping, filtering, etc.

Returns​

Iterable<Name>

prefix​

Get Signature​

get prefix(): string

The prefix part of the name set.

Returns​

string

public​

Get Signature​

get public(): string

The first name combined with the last name's initial.

Returns​

string

salutation​

Get Signature​

get salutation(): string

The combination of prefix and last name.

Returns​

string

short​

Get Signature​

get short(): string

The shortest version of a human name (first + last name).

Returns​

string

size​

Get Signature​

get size(): number

The number of name components.

Returns​

number

suffix​

Get Signature​

get suffix(): string

The suffix part of the name set.

Returns​

string

Methods​

[iterator]()​

[iterator](): Iterator<Name>

Makes the name set iterable (i.e., for-of statements).

This is similar to parts with the exception that all name components are returned as Name classes (instead of their natural form - e.g., FirstName) to maintain certain homogeneity and consistency across each name piece.

Returns​

Iterator<Name>

birthName()​

birthName(orderedBy?): string

Gets the birth name ordered as configured, no prefix or suffix.

Parameters​

orderedBy?​

NameOrder | "firstName" | "lastName"

forces to order by first or last name by overriding the preset configuration.

Returns​

string

deepEqual()​

deepEqual(other): boolean

Whether this name is equal to another one from a component perspective.

Parameters​

other​

Namefully

Returns​

boolean

equal()​

equal(other): boolean

Whether this name is equal to another one from a raw-string perspective.

Parameters​

other​

Namefully

Returns​

boolean

firstName()​

firstName(withMore?): string

Gets the first name part of the FullName.

Parameters​

withMore?​

boolean

determines whether to include other pieces of the first name.

Returns​

string

flatten()​

flatten(options): string

Flattens long names using the name types as variants.

While

Parameters​

options​

Partial<{ by: Flat | "firstName" | "lastName" | "middleName" | "birthName" | "firstMid" | "midLast" | "all" | "*"; limit: number; recursive: boolean; surname: NameOptions["surname"]; withMore: boolean; withPeriod: boolean; }>

Returns​

string

flip()​

flip(): void

Flips or swaps the name order from the preset/current config.

Returns​

void

format()​

format(pattern): string

Formats the full name as desired.

Parameters​

pattern​

string

character used to format it.

string format​

  • 'short': typical first + last name
  • 'long': birth name (without prefix and suffix)
  • 'public': first name combined with the last name's initial.
  • 'official': official document format

char format​

  • 'b': birth name
  • 'B': capitalized birth name
  • 'f': first name
  • 'F': capitalized first name
  • 'l': last name
  • 'L': capitalized last name
  • 'm': middle names
  • 'M': capitalized middle names
  • 'o': official document format
  • 'O': official document format in capital letters
  • 'p': prefix
  • 'P': capitalized prefix
  • 's': suffix
  • 'S': capitalized suffix
  • '$': an escape character to select only the initial of the next char.

Given the name Joe Jim Smith, use format with the pattern string.

  • format('l f') => 'Smith Joe'
  • format('L, f') => 'SMITH, Joe'
  • format('short') => 'Joe Smith'
  • format() => 'SMITH, Joe Jim'
  • format(r'f $l.') => 'Joe S.'.

Do note that the escape character is only valid for the birth name parts: first, middle, and last names.

Returns​

string

fullName()​

fullName(orderedBy?): string

Gets the full name ordered as configured.

Parameters​

orderedBy?​

NameOrder | "firstName" | "lastName"

forces to arrange a name set by first or last name, overriding the preset configuration.

Namefully.format() may also be used to alter manually the order of appearance of a full name. For example:

const name = new Namefully('Jon Stark Snow');
console.log(name.fullName(NameOrder.LAST_NAME)); // "Snow Jon Stark"
console.log(name.format('l f m')); // "Snow Jon Stark"

Returns​

string

get()​

get(key): Name | Name[]

Fetches the raw form of a name piece.

Parameters​

key​

string | Namon

Returns​

Name | Name[]

has()​

has(namon): boolean

Confirms whether a name component exists.

Parameters​

namon​

string | Namon

Returns​

boolean

initials()​

initials(options?): string[] | Record<string, string[]>

Gets the initials of the FullName.

Parameters​

options?​

when getting the initials.

asJson?​

boolean

whether to return initials as an array or JSON.

For example, given the names:

  • John Smith => ['J', 'S']
  • John Ben Smith => ['J', 'B', 'S'].
only?​

"firstName" | "lastName" | NameType | "middleName" | "birthName"

selects initials of only certain name parts.

orderedBy?​

NameOrder | "firstName" | "lastName"

forces to order by first or last name by overriding the preset configuration.

Returns​

string[] | Record<string, string[]>

join()​

join(separator?): string

Joins the name parts of a birth name.

Parameters​

separator?​

string

token for the junction.

Returns​

string

lastName()​

lastName(format?): string

Gets the last name part of the FullName.

Parameters​

format?​

Surname | "father" | "mother" | "hyphenated" | "all"

overrides the how-to formatting of a surname output, considering its sub-parts.

Returns​

string

middleName()​

middleName(): string[]

Gets the middle name part of the FullName.

Returns​

string[]

serialize()​

serialize(): SerializedName

Serializes this Namefully instance to a JSON object.

This includes both the name data (with full hierarchy for FirstName and LastName) and the configuration, allowing for complete reconstruction of the Namefully instance.

Returns​

SerializedName

a JSON-serializable object containing name data and config.

shorten()​

shorten(orderedBy?): string

Shortens a complex full name to a simple typical name, a combination of first and last name.

Parameters​

orderedBy?​

NameOrder | "firstName" | "lastName"

forces to order by first or last name, overriding the preset configuration.

For a given name such as Mr Keanu Charles Reeves, shortening this name is equivalent to making it Keanu Reeves.

As a shortened name, the namon of the first name is favored over the other names forming part of the entire first names, if any. Meanwhile, for the last name, the configured surname is prioritized.

For a given FirstName FatherName MotherName, shortening this name when the surname is set as mother is equivalent to making it: FirstName MotherName.

Returns​

string

split()​

split(separator?): string[]

Splits the name parts of a birth name.

Parameters​

separator?​

string | RegExp

token for the split.

Returns​

string[]

toCamelCase()​

toCamelCase(): string

Transforms a birth name into camelCase.

Returns​

string

toDotCase()​

toDotCase(): string

Transforms a birth name into dot.case.

Returns​

string

toHyphenCase()​

toHyphenCase(): string

Transforms a birth name into hyphen-case.

Returns​

string

toJson()​

toJson(): JsonName

Gets a JSON representation of the full name.

Returns​

JsonName

toLowerCase()​

toLowerCase(): string

Transforms a birth name into lowercase.

Returns​

string

toPascalCase()​

toPascalCase(): string

Transforms a birth name into PascalCase.

Returns​

string

toSnakeCase()​

toSnakeCase(): string

Transforms a birth name into snake_case.

Returns​

string

toString()​

toString(): string

Gets a string representation of the full name.

Returns​

string

toToggleCase()​

toToggleCase(): string

Transforms a birth name into ToGgLeCaSe.

Returns​

string

toUpperCase()​

toUpperCase(): string

Transforms a birth name into UPPERCASE.

Returns​

string

zip()​

zip(by?, withPeriod?): string

Zips or compacts a name using different forms of variants.

Parameters​

by?​

Flat

withPeriod?​

boolean

Returns​

string

See​

flatten() for more details.

parse()​

static parse(text, index?): Promise<Namefully>

Constructs a Namefully instance from a text.

Parameters​

text​

string

cannot be parsed. Use tryParse instead if a null return is preferred over a throwable error.

This operation is computed asynchronously, which gives more flexibility at the time of catching the error (and stack trace if any). The acceptable text format is a string composed of two or more name pieces. For instance, John Lennon, or John Winston Ono Lennon are parsable names and follow the basic name standard rules (i.e., first-middle-last).

Keep in mind that prefix and suffix are not considered during the parsing process.

index?​

NameIndex

Returns​

Promise<Namefully>

Throws​

a NameError if the

tryParse()​

static tryParse(text, index?): Namefully

Constructs a Namefully instance from a text.

It works like parse except that this function returns undefined when parse would throw a NameError.

Parameters​

text​

string

index?​

NameIndex

Returns​

Namefully