Docs | namefully

What is namefully?

It is a JavaScript library written in TypeScript that manipulates people's names, including prefixes, suffixes 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 types. That is intended to give you some flexibility so that you are not bound to a particular data type.

Easy to Use

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

Shape Names as Desired

Provide a rich API to format different name parts (surname, given name, title, etc.) 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 literals
string arrays
JSON objects
predefined classes (e.g., Name).

import { Namefully, Name } 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([
    Name.first('Jane'),
    Name.last('Doe')
])

Full Control and Flexibility

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

alter a full name's order on the fly;
handle various parts of a surname and given name;
use punctuations to reshape prefixes and suffixes;
retrieve the names' initials.

import { Namefully, NameOrder, Title, Separator } from 'namefully'

const name = new Namefully(
    'Lic, De La Cruz, Rosanna, María',
    {
        orderedBy: NameOrder.LAST_NAME,
        separator: Separator.COMMA,
        title: Title.US
    }
)
name.first // Rosanna
name.middle // María
name.last // De La Cruz
name.full // Lic. De La Cruz Rosanna María
name.format('f L') // Rosanna DE LA CRUZ

Do It Yourself

Customize your own parser to indicate the full name:

decide whether to rely on the existing parsing methods;
use business-tailored validators as needed;
parse non-standard name cases.

import { Config, FullName, Namefully, Parser } from 'namefully'

class SimpleParser extends Parser<string> {
    parse(options?: Partial<Config>): FullName {
        const [firstName, lastName] = this.raw.split('#')
        return FullName.parse({
            firstName,
            lastName
        }, Config.merge(options))
    }
}

const name = new Namefully(new SimpleParser('Juan#Garcia'))
name.full // Juan Garcia