Skip to main content
Version: 2.2.0

FAQ

The short answers. Follow the links for the long ones.

Why doesn't namefully figure out my name automatically?​

Because no library can do this reliably across cultures, languages, and naming traditions. A name like Maria de la Cruz García is ambiguous on its own — is de la Cruz a surname, a particle plus surname, a two-word surname? namefully makes you tell it. In exchange, it gives you a stable API once you have.

If you're really after auto-detection, you'd want a different tool. namefully is for the case where you know the structure and want help shaping the output.

Can I store a single-word name like Plato or Madonna?​

Yes — with the mono flag. By default the constructor rejects single-token names because most apps want the safety, but you can opt in:

new Namefully('Plato', { mono: true });

See the mono option for details and caveats.

How do I handle a Hispanic surname with both father and mother names?​

Construct the LastName directly with both values, and pick the Surname format:

new Namefully(
  [new FirstName('Rosanna'), new LastName('De La Cruz', 'García')],
  { surname: Surname.HYPHENATED },
);

See Compound names.

How do I deal with a nickname inside the name (Dwayne "The Rock" Johnson)?​

There's no nickname slot in the standard. Use NameIndex to declare the real slot positions and ignore the rest:

const indexing = NameIndex.only({ firstName: 0, lastName: 3 });
Namefully.tryParse('Dwayne "The Rock" Johnson', indexing);

See NameIndex.

Is Namefully mutable? Can I change the first name after construction?​

No. Once built, a Namefully is read-only. If the name is wrong, throw it away and build a new one. This is by design — see Immutability & Config.

Will validation reject Müller, María, or Δημήτριος?​

When bypass: true (the default), nothing is rejected — names pass through whatever they are. When bypass: false, Latin Extended, German, Greek, Cyrillic, and Icelandic characters are all in the supported set. CJK, Arabic, Hebrew, and many other scripts are not in the default validator set. See Writing systems & validation.

How do I save a Namefully to a database and read it back?​

In v2, use serialize() and deserialize():

const json = name.serialize();
const restored = deserialize(json);

In v1.3.1 this round-trip isn't available. See JSON serialization and Migrating from v1.

Where can I see it running before I install it?​

The live StackBlitz editor has a working sandbox you can edit in the browser. Open the console to see the output.