name-tools - Name Parsing & Formatting Library

Interactive Demo

Enter full name(s) (one per line):

Enter any name to see it classified (person, organization, family, compound) with confidence scores. Try: Acme Corp, Inc. | Bob & Mary Smith | The Smith Family | Smith, John, Jr.

Use US first-name evidence

Uses the US SSA first-name data already loaded for gender guessing as weak evidence for ambiguous middle-vs-family tokens. It checks only the uncertain interior token, such as Garcia in Gabriel Garcia Lopez, not the given name or the final token we already treat as family. If that interior token is not found as a first name, the selected parse may move it into a compound family name. This is not locale-aware truth; warnings remain so consumers can review or override.

Gender Probability Lookup

Enter a first name:

Look up gender probability based on US Social Security Administration data. Try: Chris | Taylor | Jordan | Michael | Jennifer

Pronoun Lookup

Enter a pronoun spec:

Get a complete pronoun set from a shorthand spec. Try: he/him | she/her | ze/zir | xe/xem | any

Pronouns for Entity

Enter a name to get suggested pronouns:

Uses entity classification + gender lookup to suggest appropriate pronouns. Try: Mary Johnson | Acme Inc. | The Smith Family | Alex (they/them)

Test Results - Live Parsing Validation

All test cases validated in real-time. Green = passing, Red = failing.

Original String	Prefix	First	Nickname	Middle	Last	Suffix

Installation

pnpm add name-tools

Quick Start

import { parseName, formatName } from 'name-tools';

// Parse and classify a name - returns a typed entity
const person = parseName("Dr. John Franklin Jr.");
console.log(person.kind);    // 'person'
console.log(person.given);   // 'John'
console.log(person.family);  // 'Franklin'

// Detect organizations automatically
const org = parseName("Acme Corporation, Inc.");
console.log(org.kind);       // 'organization'

// Detect compound names (couples)
const couple = parseName("Bob & Mary Smith");
console.log(couple.kind);    // 'compound'

// Format names with presets
console.log(formatName("Dr. John Franklin Jr."));
// "John Franklin, Jr."

Features

Entity Classification: Automatically detect person, organization, family, or compound names
Parse Names: Extract components (prefix, first, middle, last, suffix, nickname)
Format Names: Multiple formatting presets (display, formal, alphabetical, initialed)
Reversed Names: Support for "Smith, John, Jr." format
Recipient Lists: Parse email To/CC lines with parseNameList()
TypeScript Support: Full type definitions with discriminated unions
Zero Dependencies: Lightweight and fast

API Reference

Classification & Parsing

parseName(input, options?) - Classify and parse into entity type (person, org, family, compound)
parseNameList(input) - Parse email recipient lists (To/CC lines)
getFirstName(fullName) - Extract first name
getLastName(fullName) - Extract last name

Type Guards

isPerson(entity) - Check if entity is a person
isOrganization(entity) - Check if entity is an organization
isFamily(entity) - Check if entity is a family/household
isCompound(entity) - Check if entity is a compound name

Formatting Functions

formatName(input, options?) - Single rendering entry point (presets + options)

Data & Utilities

PARTICLES - Array of surname particles (van, von, de, etc.)
COMMON_SURNAMES, COMMON_FIRST_NAMES - Name datasets
isParticle(), isCommonSurname(), isCommonFirstName()

Pronouns

getPronounSet(spec) - Get complete pronoun set from "he/him", "she/her", etc.
getPronouns(entity, options?) - Get pronouns for any entity with optional gender lookup
formatPronoun(set, role, options?) - Format a single pronoun with capitalization
fillPronounTemplate(template, set) - Fill {{subject}}, {{object}}, etc. placeholders
extractPronouns(name) - Extract pronouns from "Alex (they/them)" format
BUILT_IN_PRONOUNS - Map of built-in pronoun sets (he, she, they, ze-hir, etc.)