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[] | string[] | JsonName | Parser<unknown>
element to parse.
options?
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
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
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
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; 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()
Fetches the raw form of a name piece.
Parameters
key
string | Namon
Returns
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[]
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
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?
withPeriod?
boolean
Returns
string
See
flatten() for more details.
parse()
staticparse(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?
Returns
Promise<Namefully>
Throws
a NameError if the
tryParse()
statictryParse(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?
Returns
Namefully