First Name Parser

Extract a greeting-safe first name from a full name submitted through a website form.

first-name-parser is a zero-runtime-dependency JavaScript and TypeScript library built for contact forms, lead forms, CRM submissions, and customer follow-up. It returns a first name when the input is structurally safe enough for a real message, and returns undefined when guessing would be risky.

npm install first-name-parser

import { getFirstName } from "first-name-parser";

getFirstName("Austin P. Smith");      // "Austin"
getFirstName("Dr. Austin Smith Jr."); // "Austin"
getFirstName("Mary-Jane Smith");     // "Mary-Jane"
getFirstName("Smith, Austin P.");     // undefined
getFirstName("J. Austin Smith");      // undefined
getFirstName("Dr. Smith");            // undefined

Why use it?

• Built specifically for website Full Name fields and customer messaging.
• Avoids turning ambiguous input into awkward greetings.
• Zero runtime dependencies.
• TypeScript declarations included.
• Supports ESM and CommonJS.
• Handles titles, suffixes, credentials, initials, odd whitespace, apostrophes, hyphenated names, and common multi-person submissions.
• Rejects obvious non-name values such as emails, URLs, placeholders, and organization-shaped input.
• Benchmarked against large public name datasets.

If the parser cannot confidently determine a greeting name, getFirstName() returns undefined so your application can fall back naturally:

const firstName = getFirstName(submission.fullName);

const message = firstName
  ? `Hey ${firstName}, thanks for reaching out...`
  : "Thanks for reaching out...";

API

getFirstName(fullName)

Returns a high-confidence greeting name as string | undefined.

import { getFirstName } from "first-name-parser";

getFirstName("Jordan P. Smith"); // "Jordan"
getFirstName("J. Smith");        // undefined

parseFirstName(fullName)

Returns the parser candidate plus confidence and detected format. Use this lower-level API when you want to inspect medium- or low-confidence results yourself.

import { parseFirstName } from "first-name-parser";

parseFirstName("Smith, Jordan P.");
// {
//   firstName: "Jordan",
//   confidence: "medium",
//   format: "family-first"
// }

confidence is high, medium, or low. format is empty, single, given-first, or family-first.

For normal customer messaging, prefer getFirstName().

What it handles

Full name input	getFirstName()
Austin Smith	Austin
Austin P. Smith	Austin
Dr. Austin Smith Jr.	Austin
Austin Smith, MPH	Austin
Mary-Jane Smith	Mary-Jane
D'Andre Johnson	D'Andre
John & Jane Smith	John
Smith, Austin P.	undefined
J. Austin Smith	undefined
Dr. Smith	undefined
Example Auto Repair	undefined

Accuracy and benchmarks

The parser is tested against two complementary public fixture sets:

• 804,225 generated US name forms using 53,615 first names and 156,621 last names from US Census name datasets. The current parser reaches 99.9745% candidate accuracy on the reconstructed benchmark suite.
• 2,352 labeled person-name records from the probablepeople test/training corpus. parseFirstName().firstName reaches 98.64% exact-match accuracy.

These measure candidate extraction, not guaranteed greeting accuracy. getFirstName() is intentionally stricter and may return undefined for cases that a benchmark still considers parseable. See BENCHMARKS.md for methodology and limitations.

Scope and limitations

This parser is optimized for expected US website-form input where unpunctuated names usually follow First [Middle...] Last order. It does not use first-name or surname frequency databases to guess ambiguous names.

It is intended for practical first-name extraction and personalized customer messaging. It is not intended for universal international name-order detection, legal-name decomposition, identity verification, or extracting every possible name component.

If you need title, first, middle, last, suffix, and other components from arbitrary human names, use a broader full-name parser.

Development

npm install
npm test
npm run typecheck
npm run build
npm run benchmark:public

The library has no runtime dependencies.

Attribution

Created and maintained by Serbyte Development.