e164-compact

Zero runtime dependencies. Helpers for compact E.164 storage (+ + country calling code + national digits without a leading national zero), syntax checks aligned with common international practice, national length checks against embedded coarse ranges (with optional hand-tuned overrides), and picker data with English default labels plus bundled partial translations (Arabic, French, Spanish, German, Portuguese, Urdu, Hindi, Turkish, Russian).

If your GitHub repo URL differs from /e164-compact, update repository / homepage in package.json and the badge URLs above so npm and CI badges stay accurate.

Why this package

| Need | e164-compact | Heavier full-feature phone stacks | | ------------------- | ------------------------------------------------- | ---------------------------------------------- | | Install size / tree | Small, no runtime deps | Often large metadata + parsing logic | | Goal | Normalize + validate shape/length for storage | Full carrier/type rules, formatting everywhere | | Data in repo | Plain src/data/*.ts you can PR | Often generated blobs or vendored copies |

Use this when you want a predictable normalization path for APIs and databases, optional strict errors for bad input, and country picker rows without pulling a full phone-number engine.

Install

npm

npm install e164-compact

pnpm

pnpm add e164-compact

Yarn

yarn add e164-compact

Until published, link from a monorepo sibling:

"e164-compact": "file:../e164-compact"

Quick start

import {
  normalizeE164,
  tryNormalizeE164,
  isNationalLengthValidStrict,
} from "e164-compact";

// Lenient (UX): always returns a string starting with +
const stored = normalizeE164("00971 50 123 4567");

// Strict (APIs): ok / error
const strict = tryNormalizeE164("00971 50 123 4567");
if (strict.ok && isNationalLengthValidStrict(strict.value)) {
  // persist strict.value
}

Validation helper (no extra packages)

import { tryNormalizeE164, isNationalLengthValidStrict } from "e164-compact";

export function assertStorageE164(raw: string): string {
  const n = tryNormalizeE164(raw);
  if (!n.ok) throw new Error(n.error);
  if (!isNationalLengthValidStrict(n.value)) {
    throw new Error("National number length out of range for this country code");
  }
  return n.value;
}

Wire this into your own form or API layer however you prefer.

Bundle footprint

Published tarball includes dist/ (ESM + CJS + types) and NOTICE. There is no separate runtime dependency tree. Measure unpacked size under node_modules/e164-compact/dist after install if you need exact bytes.

API overview

| Export | Description | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | normalizeE164(input) | Lenient storage form; strips leading national zero after CC. If no known calling code matches, returns + + stripped digits. | | tryNormalizeE164(input) | Strict: ok / error — fails on unknown calling code or empty national after strip. | | parseE164Parts(value) | { countryCallingCode, nationalNumber }. Lenient: non-+ or unknown prefix uses fallback 971. | | tryParseE164Parts(value) | Strict: requires +, known CC, non-empty national. | | buildE164(cc, nationalDigits) | Build +cc + national. | | isE164Syntax(value) | + + 1…15 digits, first digit after + is 1–9. | | isNationalLengthValid(value) | National length vs bounds (lenient parse). | | isNationalLengthValidStrict(value) | Same with strict parse. | | getNationalLengthBounds(cc) | { min, max } for form messages. | | formatE164ForDisplay(value, opts?) | Spacing for display only. | | filterSupportedCountries(countries, query) | Match code, label, or cca2. | | localizeSupportedCountryLabels(countries, byCca2) | Set label from cca2 → name map. | | withLocalePickerLabels(countries, map) | Alias of localizeSupportedCountryLabels. | | withArabicPickerLabels(countries) | Applies bundled Arabic map. | | SUPPORTED_COUNTRIES | { code, label, cca2 }[] — default English label. | | COUNTRY_LABELS_BY_LOCALE | ar, fr, es, de, pt, ur, hi, tr, ru → partial cca2 maps. | | COUNTRY_LABELS_AR, …_FR, …_ES, … | Individual partial maps (same as values in COUNTRY_LABELS_BY_LOCALE). | | CALLING_CODE_PREFIXES | 206 unique CC digit prefixes, longest first. | | NATIONAL_LENGTH_BOUNDS | Embedded coarse ranges merged with MANUAL_NATIONAL_LENGTH_OVERRIDES. | | MANUAL_NATIONAL_LENGTH_OVERRIDES | Stricter overrides where you need them (e.g. GCC). | | DEFAULT_NATIONAL_LENGTH_BOUNDS | Fallback { min: 7, max: 12 }. |

Locales

• English is the default on SUPPORTED_COUNTRIES[].label.
• Other languages are partial: some territories may be missing in a given map; missing keys keep the English row unchanged.
• Hindi (hi) may be sparse in the bundled map; supply your own map via localizeSupportedCountryLabels if needed.

Example:

import {
  SUPPORTED_COUNTRIES,
  withLocalePickerLabels,
  COUNTRY_LABELS_BY_LOCALE,
} from "e164-compact";

const frRows = withLocalePickerLabels(
  SUPPORTED_COUNTRIES,
  COUNTRY_LABELS_BY_LOCALE.fr as Record<string, string>,
);

Lenient vs strict

• parseE164Parts / normalizeE164 favor forgiving form UX.
• tryParseE164Parts / tryNormalizeE164 suit APIs and validation where silent guessing is undesirable.

Troubleshooting

• tryNormalizeE164 fails on valid-looking numbers — The library only accepts known ITU-style calling-code prefixes from embedded data. Update src/data/itu-calling-data.ts if a prefix is missing.
• isNationalLengthValidStrict is false — Length tables are coarse; tune src/manual-national-overrides.ts or src/data/national-length-bounds.ts for your region.
• Wrong country after paste — Lenient APIs may infer CC from digits; use strict APIs for unambiguous validation.

Contributing / updating data

All dialing prefixes, picker rows, length tables, and locale maps live under src/data/ as normal source files. Updates are done by editing those modules and opening a PR (see CONTRIBUTING.md). Hand-tuned national length overrides remain in src/manual-national-overrides.ts.

Changelog

See CHANGELOG.md.

License

MIT. See NOTICE for third-party data attribution required by upstream licenses.