phone

phone (by AfterShip) validates a phone number and formats it to the E.164 international standard, given either an explicit ISO 3166 country code or by detecting the country directly from a +-prefixed number. It handles the messy real-world edge cases of phone formatting: leading trunk zeros, country-specific mobile-prefix validation, and ambiguous country-code overlaps (like Russia’s leading 8 or shared North American Numbering Plan codes).

The library ships a bundled dataset of per-country phone metadata (valid number lengths, mobile prefixes, calling codes) rather than depending on an external API, making it a fast, offline-capable validator commonly used for signup forms, SMS/notification pipelines, and any system that needs consistently formatted phone numbers.

What You Get

• A single phone() function returning { isValid, phoneNumber, countryIso2, countryIso3, countryCode }
• Automatic country detection from a +-prefixed international number when no country is specified
• Explicit country-code mode (ISO 3166 alpha-2 or alpha-3) for formatting numbers known to belong to a specific country
• Country-specific normalization rules (trunk-prefix stripping, Russia’s leading-8 handling, North American Numbering Plan disambiguation)
• An optional validateMobilePrefix flag to enforce mobile-specific number-prefix rules per country
• Full TypeScript type definitions for the result shapes

Common Use Cases

• Validating and normalizing phone numbers submitted through signup or checkout forms
• Formatting phone numbers to E.164 before sending them to SMS/notification providers (Twilio, etc.)
• Detecting a user’s country from a pasted international phone number without asking them to select it manually
• Cleaning and standardizing legacy phone number data across a mixed-format dataset

Under The Hood

Architecture - The library is centered on a single exported phone() function (src/index.ts) that branches on whether a country was supplied and whether the number carries a + sign, delegating country lookups to findCountryPhoneDataByCountry/findCountryPhoneDataByPhoneNumber and length/prefix validation to validatePhoneISO3166, all backed by a static, generated country_phone_data dataset (src/data/) containing per-country calling codes, valid length lists, and mobile prefixes. A scripts/add-new-rules tool exists to regenerate this dataset from source CSV data rather than maintaining it by hand.

Tech Stack - TypeScript compiled via tsc to CommonJS with bundled type declarations, tested with Jest, and bundled for browser use via Webpack for the included example app. The dataset-generation tooling uses papaparse to process CSV inputs.

Code Quality - __tests__/index.spec.ts plus a CSV-driven test_match.ts exercise the validator against a large matrix of real per-country number examples (data.csv), which is a strong testing strategy for a rules-heavy validation library where individual country edge cases matter more than generic unit tests. The core function handles numerous documented country-specific quirks (CIV/COG leading zeros, Russian 8-prefix, NANP overlap) as explicit branches, which keeps behavior traceable but means correctness depends on the completeness of the bundled dataset staying current.

API Design - The function signature is minimal — a phone number string plus an optional { country, validateMobilePrefix, strictDetection } object — returning a discriminated union (PhoneValidResult | PhoneInvalidResult) that TypeScript consumers can narrow on isValid directly, which is a clean, type-safe result shape for a validation library.