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 turns a plain <input> into a phone field, handling the events, the caret, and the 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, while the established libraries interpret regex metadata on every call. The live benchmark proves the gap on every push.
• A real input controller. Formatting on every keystroke, with caret tracking, undo and redo, and the full query surface mid-typing.
• Every JavaScript runtime. Node.js, browsers, Deno, Bun, and edge, selected through package export conditions and each exercised in CI.
• 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 push and pull request. 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		planned	drop-in Web Component (<tel-input>)
@telixon/angular		building	Angular binding on web-sdk
@telixon/react		planned	React binding (hook + component)
@telixon/vue		planned	Vue binding

Support

Questions belong in Discussions. Bugs and feature requests belong in Issues. Vulnerabilities follow SECURITY.md.

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