Check out the official documentation at https://namefully.netlify.app.
Have you ever had to format a user's name in a particular order, way, or shape? Probably yes. If not, it will come at some point. Be patient.
- Offer supports for Latin alphabet, including other European ones (e.g., German, Greek, Cyrillic, Icelandic characters)
- Accept different data shapes as input
- Use of optional parameters to access advanced features
- Format a name as desired
- Offer support for prefixes and suffixes
- Access to names' initials
- Allow hyphenated names, including with apostrophes
- Alter the order of appearance of a name: by given name or surname
- Handle various subparts of a surname and given name
- Use tokens (separators) to reshape prefixes and suffixes
- Accept customized parsers (do it yourself)
npm i namefully
console.logname.format'L, f m' // => SMITH, John Joeconsole.logname.zip // => John J. Smith
NOTE: This package comes with its own declaration file for TypeScript support.
Options and default values
Below are enlisted the options supported by
string: 'firstname' | 'lastname', default:
Indicate in what order the names appear when set as a raw string values or
string array values. That is, the first element/piece of the name is either the
given name (e.g.,
Jon Snow) or the surname (e.g.,
// 'Smith' is the surname in this raw string caseconsole.logname.ln // => Smith// 'Edison' is the surname in this string array caseconsole.logname.fn // => Thomas
NOTE: This option also affects all the other results of the API. In other words, the results will prioritize the order of appearance set in the first place for the other operations. Keep in mind that in some cases, it can be altered on the go. See the example below.
// 'Smith' is the surname in this raw string caseconsole.logname.full // => Smith John Joe// Now alter the order by choosing the given name firstconsole.logname.full'firstname' // => John Joe Smith
enum: Separator, default:
Only valid for raw string values, this option indicates how to split the parts of a raw string name under the hood.
console.logname.full // => Adam Sandler
string: 'uk' | 'us', default:
Abide by the ways the international community defines an abbreviated title.
American and Canadian English follow slightly different rules for abbreviated
titles than British and Australian English. In North American English, titles
before a name require a period:
Mr., Mrs., Ms., Dr.. In British and Australian
English, no periods are used in these abbreviations.
console.logname.full // => Mr. John Smithconsole.logname.px // => Mr.
Set an ending character after the full name (a comma before the suffix actually).
console.logname.full // => Mr John Smith, PhD
string: 'father' | 'mother' | 'hyphenated' | 'all', default:
Defines the distinct formats to output a compound surname (e.g., Hispanic surnames).
console.logname.full // => Jaden Smith-Pinkett
Skip all the validators (i.e., validation rules, regular expressions).
console.logname.fn // => 2Pac
NOTE: This option can help to trick the utility and allow us to use it for unsupported languages or inner contents like prefixes or suffixes. For example, the Hindi characters will not pass the validation rules. Or, the Spanish equivalent for
Srwill raise an exception as it is not part of the predefined prefixes.
Customize your own parser to indicate the full name yourself.
// Suppose you want to cover this '#' separatorconsole.logname.full // => Juan Garcia
To sum up, the default values are:
Concepts and examples
The name standards used for the current version of this library are as follows:
[Prefix] Firstname [Middlename] Lastname [Suffix]
[ and closing
] brackets mean that these parts are optional. In
other words, the most basic/typical case is a name that looks like this:
John Smith, where
John is the Firstname and
Smith, the Lastname.
NOTE: Do notice that the order of appearance matters and (as shown here) can be altered through configured parameters. 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 an instance of
Namefully and the rest will follow.
Let us take a common example:
Mr John Joe Smith PhD
So, this utility understands the name parts as follows:
- typical name:
- first name:
- middle name:
- last name:
- full name:
Mr John Joe Smith PhD
- birth name:
John Joe Smith
John J. Smith
J J S
jsmith, johnsmith, etc.
namefully does not have support for certain use cases:
Plato. It can be tricked though by setting the mononame as both first and last name;
- multiple surnames:
De La Cruz,
Da Vinci. You can also trick it using your own parsing method or setting separately each name part via the
Nama|Nametype or the string array input;
- multiple prefixes:
Prof. Dr. Einstein. An alternative would be to use the
See the use cases for further details.
||Gets the prefix part of the full name, if any|
||Gets the first name part of the full name|
||Gets the middle name part of the full name, if any|
||Gets the last name part of the full name|
||Gets the suffix part of the full name, if any|
||Gets the full name|
||Gets the birth name, no prefix or suffix|
||Gets the initials of the first and last names|
||Gives some descriptive statistics of the characters' distribution.|
||Returns a typical name (e.g. first and last name)|
||Compresses a name using different forms of variants|
||Suggests possible (randomly) usernames closest to the name|
||Formats the name as desired|
||Shortens a full name|
||Returns the count of characters of the birth name, excluding punctuations|
||Returns an ascii representation of each characters|
||Transforms a birth name to a specific title case|
||Returns a password-like representation of a name|
If you find the names of the methods somewhat too long, we provide aliases to make your life easier as a coder.
Developed by Ralph Florent.
The underlying content of this utility is licensed under MIT.