Another Name Parser

0.1.0 verified Sun Apr 19 auth: no javascript

Another Name Parser is a lightweight JavaScript utility designed to break down personal names into their constituent parts: prefix (title), first name, middle name/initial, last name (family name), and suffix. It is primarily built for US English name conventions but can be useful in other contexts. The current stable version is 0.1.0, which includes TypeScript typing definitions. Release cadence appears infrequent, mainly driven by dependency updates and feature additions like the recent TypeScript support. Key differentiators include its ability to handle common prefixes, retain periods in titles, recognize compound first and last names, correctly parse 'Last Name, First Name' order, and intelligently ignore quoted or parenthesized nicknames, providing a clean parsed output.

Common errors

error TypeError: another_name_parser_1.default is not a function ↓

cause Attempting to import `another-name-parser` as a default export in a pure CommonJS environment or when the bundler/runtime doesn't correctly resolve `module.exports` to a default export.

fix

In CommonJS, use const parser = require('another-name-parser');. If using ESM syntax in a setup that still treats it as CJS, ensure your build tools (e.g., Babel, TypeScript) or Node.js runtime (type: module in package.json) are configured correctly for ESM interoperability, or stick to require.

error Name contains a nickname (e.g., 'John "Johnny" Doe') but the parser is not extracting 'Johnny'. ↓

cause The parser's design explicitly ignores quoted or parenthesized nicknames, treating them as extraneous information not part of the formal name components.

fix

This is intended behavior. If you need to retain or extract nicknames, this library may not be suitable, or you would need to pre-process the name string before passing it to the parser.

Warnings

gotcha The release `v0.1.0` which added TypeScript support was incorrectly tagged as `v0.10.0` in the changelog and GitHub release notes. The actual package version on npm remains `0.1.0`. ↓

fix Refer to the npm registry for the correct version number. If referencing git tags, be aware of this discrepancy for `v0.1.0`.

gotcha This library is designed primarily for US English name conventions. While it might work for some international names, its rules for prefixes, suffixes, and compound names are tailored to common Western patterns and may produce incorrect results for other cultures. ↓

fix Test thoroughly with names from diverse backgrounds if using outside of US English contexts. Consider alternative libraries for broader international name parsing.

gotcha The library is still in a pre-1.0 state (version `0.1.0`), meaning its API might not be fully stable and could introduce breaking changes in minor versions, though this is not explicitly stated. Developers should exercise caution with dependency ranges. ↓

fix Pin exact versions (`"another-name-parser": "0.1.0"`) or use caret ranges cautiously (`"^0.1.0"`) after thorough testing. Monitor release notes for any API changes.

Install

npm install another-name-parser

yarn add another-name-parser

pnpm add another-name-parser

Imports

parser
wrong
```
const parser = require('another-name-parser');
```
correct
```
import parser from 'another-name-parser';
```
While the README shows `require`, `another-name-parser` is a CommonJS module that can be imported as a default export in ESM environments. For pure CommonJS, `require` is correct.
NameParserFunction
```
import type { NameParserFunction } from 'another-name-parser';
```
Type import for the main parser function, available since v0.1.0 (tagged as v0.10.0).
ParsedName
```
import type { ParsedName } from 'another-name-parser';
```
Type import for the object returned by the parser, available since v0.1.0 (tagged as v0.10.0).

Quickstart

Demonstrates parsing complex personal name strings, including those with prefixes, suffixes, middle initials, nicknames, and 'Last, First' order, into structured objects.

import parser from 'another-name-parser';

const nameString1 = 'Commissioner James "Jim" W. Gordon, Sr.';
const parsedName1 = parser(nameString1);

console.log('Parsed name 1:');
console.log(parsedName1);
/*
Output:
{
  prefix: 'Commissioner',
  first: 'James',
  middle: 'W.',
  last: 'Gordon',
  suffix: 'Sr.',
  original: 'Commissioner James "Jim" W. Gordon, Sr.'
}
*/

const nameString2 = 'Gordon, James W.';
const parsedName2 = parser(nameString2);

console.log('\nParsed name 2:');
console.log(parsedName2);
/*
Output:
{
  prefix: null,
  first: 'James',
  middle: 'W.',
  last: 'Gordon',
  suffix: null,
  original: 'Gordon, James W.'
}
*/