A JavaScript utility for handling person names

What is namefully?

It's a JavaScript library written in TypeScript for handling person names, including titles and initials. It relies actually on how you indicate each name part's role to internally perform certain operations and save you some hurdles. As a matter of fact, namefully can be constructed using distinct raw data shapes. That is intended to give you some flexibility so that you are not bound to a particular data input.

Easy to Use

Accept various name shapes and optional parameters in order to access advanced features and have more control over the outputs.

Shape a Name as Desired

Provide an easy API for handling different name parts (surname, given name, title, etc.) of a person in a particular order, way, or shape.

Related Packages

Available as a wrapper in both Angular and React, with its own declaration files for TypeScript support.

Easy Instantiation

Build an instance of Namefully using different types of raw data:

  • string literal
  • string array
  • Name class
  • JSON object
  • Full name builder

import {
Firstname, Lastname, FullnameBuilder
} from 'namefully'
const fromString = new Namefully('Jane Doe')
const fromArray = new Namefully([ 'Jane', 'Doe' ])
const fromJSON = new Namefully({
firstname: 'Jane',
lastname: 'Doe'
const fromName = new Namefully([
new Firstname('Jane'),
new Lastname('Doe')
const fromBuilder = new Namefully(
new FullnameBuilder()

Full Control and Flexibility

Access more features with the optional parameters to have more control over the outputs:

  • Alter the order of appearance of a name: by given name or surname
  • Handle various subparts of a surname and given name
  • Use punctuations to reshape prefixes and suffixes
  • Get the initials of a name

import { Namefully, Separator } from 'namefully'
const name = new Namefully(
'Lic, De La Cruz, Rosanna, María',
orderedBy: 'lastname',
separator: Separator.COMMA,
titling: 'us',
bypass: true
name.fn() // Rosanna // María
name.ln() // De La Cruz
name.full() // Lic. De La Cruz Rosanna María
name.format('f L') //Rosanna DE LA CRUZ'firstmid') // De La Cruz R. M.

Do It Yourself

Customize your own parser to indicate the full name:

  • Decide whether or not to use validation rules
  • Bypass directly existing validators
  • Define your own set of restricted characters

import {
Namefully, Firstname, Lastname,
} from 'namefully'
class MyParser implements Parser<string> {
constructor(public raw: string) {}
parse() {
const [fn, ln] = this.raw.split('#')
return {
firstname: new Firstname(fn.trim()),
lastname: new Lastname(ln.trim()),
const name = new Namefully(null, {
parser: new MyParser('John # Smith')
})'dot') // john.smith