Error handling

namefully throws a single error class, NameError, which extends the built-in Error. You catch it the same way you'd catch anything else.

import { Namefully, NameError } from 'namefully';

try {
  return new Namefully(rawInput);
} catch (e) {
  if (e instanceof NameError) return null; // or log, or fall back
  throw e;                                 // anything else is unexpected
}

When NameError is thrown

There are three broad categories:

1. Parse failure — the input doesn't match any of the supported shapes (string, string[], Name[], JsonName, or a Parser). Passing null / undefined / an unrelated object trips this.

2. Validation failure — with Config.bypass: false, an input passes shape checks but fails a validation rule (unsupported characters, prefix/suffix not in the known list, minimum length, missing required slots).

3. Disallowed operation — you asked for something the current Namefully can't do. The most common example is an unrecognized format token:

   new Namefully('John Smith').format('z l'); // throws

All three throw the same NameError. The message tells you which case you've hit; if you need to branch on it programmatically, parse the message or use the lenient Namefully.tryParse() and check for undefined.

:::info v2 hierarchy v2 splits NameError into a proper subclass hierarchy (InputError, ValidationError, NotAllowedError, UnknownError) so you can branch with instanceof. v1.3.1 keeps a single class. See What's new in v2. :::

Working with Namefully.tryParse()

If you'd rather not write a try/catch at all, Namefully.tryParse() is the synchronous helper that returns undefined instead of throwing on parse and validation failures. Its async sibling Namefully.parse() does throw — wrapped in a rejected promise. See parse() and tryParse().