text-number-parser

Parse localized Unicode number words into JavaScript number or bigint values.

Features

• TypeScript source with generated declaration files.
• Narrow public API with throwing and non-throwing parse functions.
• Unicode-aware tokenization and normalization.
• Parser modes for connector words and hyphenated input.
• Extensible lexicons for custom scale words and localization.
• Typed error objects for empty input, invalid tokens, and invalid number syntax.
• Vitest coverage for the public API.
• Tinybench suite for quick performance checks.

Installation

npm install text-number-parser

Usage

import {
  InvalidTokenError,
  createParser,
  parseTextNumber,
  tryParseTextNumber,
} from "text-number-parser";

parseTextNumber("one hundred and twenty-one");
// 121

parseTextNumber("nine quadrillion nine trillion");
// 9009000000000000n

parseTextNumber("one hundred and one", { allowAnd: false });
// throws InvalidSyntaxError

const result = tryParseTextNumber("twenty hundred million cat");

if (!result.ok) {
  console.error(result.error.code, result.error.message);
}

try {
  parseTextNumber("two cats");
} catch (error) {
  if (error instanceof InvalidTokenError) {
    console.error(error.token, error.index);
  }
}

const indianParser = createParser({
  extendLexicon: [
    { word: "dozen", type: "multiplier", value: 12 },
    { word: "lakh", type: "multiplier", value: 100_000 },
    { word: "crore", type: "multiplier", value: 10_000_000 },
  ],
});

indianParser.parse("three crore five lakh");
// 30500000

const spanishParser = createParser({
  lexicon: [{ word: "veintidós", type: "number", value: 22, cls: "teen" }],
  locale: "es",
  normalization: "NFC",
});

spanishParser.parse("VEINTIDO\u0301S");
// 22

Public API

parseTextNumber(input, modes?)

Parses an English number phrase and returns either a number or a bigint when the value exceeds Number.MAX_SAFE_INTEGER.

Supported modes:

type ParserModes = {
  allowAnd?: boolean;
  allowHyphen?: boolean;
};

tryParseTextNumber(input, modes?)

Returns a discriminated union:

type ParseResult =
  | { ok: true; value: number | bigint }
  | { ok: false; error: TextNumberError };

createParser(options)

Builds an isolated parser instance with its own lexicon, default modes, locale-aware lowercasing, and Unicode normalization strategy.

type CreateParserOptions = {
  lexicon?: Iterable<LexiconEntry>;
  extendLexicon?: Iterable<LexiconEntry>;
  locale?: string | string[];
  normalization?: "NFC" | "NFD" | "NFKC" | "NFKD" | false;
  modes?: ParserModes;
};

englishLexicon

Readonly default English lexicon used by the top-level parser.

Error classes

• TextNumberError
• EmptyInputError
• InvalidTokenError
• InvalidSyntaxError

Each error carries the original input. Token and syntax errors also expose the offending token and character index.

Supported language rules

• Units: zero through nine
• Teens: ten through nineteen
• Tens: twenty through ninety
• Multipliers: hundred, thousand, million, billion, trillion, quadrillion
• Optional filler: and
• Optional sign prefix: minus, negative
• Hyphenated inputs are accepted by default and can be disabled with allowHyphen: false
• Connector words can be disabled with allowAnd: false

Extensibility

• Use extendLexicon to add new words such as dozen, lakh, and crore.
• Use lexicon to replace the default dictionary entirely for localization.
• Unicode words are normalized before lookup, so composed and decomposed forms can resolve to the same entry.

Development

npm install
npm run build
npm test
npm run bench