Phone-number parser, formatter, and validator for JavaScript and TypeScript.

Documentation · Playground · How it works

Quick start

npm install @telixon/core

import { ensureEngineReady, parsePhoneNumber } from '@telixon/core';

await ensureEngineReady();

const number = parsePhoneNumber('+1 (415) 555-0132');

number.isValid(); // true
number.getRegion(); // 'US'
number.formatE164(); // '+14155550132'

@telixon/web-sdk drives a plain <input>. It formats every keystroke, keeps the caret in place, and records undo history:

npm install @telixon/web-sdk

import { ensureEngineReady } from '@telixon/core';
import { createPhoneInput } from '@telixon/web-sdk';

await ensureEngineReady();

const input = document.querySelector('input')!;

const phone = createPhoneInput({
  mode: 'national',
  defaultRegion: 'US',
  input,
});

phone.subscribe((state) => {
  // After typing 4155550132:
  // state.value            '(415) 555-0132'
  // state.region           'US'
  // state.validationError  null
});

Highlights

• Compiled to one automaton. Google publishes its metadata as regular expressions; Telixon compiles them ahead of time into a single deterministic finite automaton. Resolving a number is one linear-time walk; the state it ends on carries validity, type, region, and format.
• An order of magnitude faster. That one walk parses millions of numbers a second. The live benchmark publishes the per-method ratios.
• A full input controller. Formatting on every keystroke, with caret tracking, undo and redo, and the full query surface mid-typing.
• Node.js, browsers, Deno, Bun, and edge runtimes. Package export conditions pick the build. CI runs each one.
• TypeScript-first. Region codes and number types are closed unions; a typo fails to compile.
• Zero dependencies.

Conformance

Every query method with a Google libphonenumber counterpart is compared against it, across all 245 regions. The oracle runs Google's own source at the commit PROVENANCE.json pins for the engine, which rules out version drift. The gate runs in CI on every pull request and every push to main. Any divergence fails the build.

Run it locally with pnpm conformance. The live report publishes every run; the methodology covers the corpus. Found a divergence the gate misses? Report it.

Packages

Package	Version	Status	Role
@telixon/core		shipped	parsing, formatting, validation
@telixon/web-sdk		shipped	headless phone-field widgets
@telixon/web-components		shipped	custom elements around your own <input>
@telixon/angular		shipped	phone field directive and region picker
@telixon/react		planned	React binding
@telixon/vue		planned	Vue binding

Support

Questions belong in Discussions. Bugs and feature requests belong in Issues. Report a vulnerability as SECURITY.md describes.

Contributing

Setup, workflow, and the engineering standards are in CONTRIBUTING.md. The system design is in ARCHITECTURE.md; benchmark methodology is in bench/README.md.

License

Apache-2.0 © Martsin Labs