@telixon/core

Phone-number parser, formatter, and validator built on Google libphonenumber metadata.

Documentation · Live demo

Install

npm install @telixon/core

Quick start

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

await ensureEngineReady(); // load the engine once; the API is synchronous afterward

const number = parsePhoneNumber('+12015550123');

number.isValid(); // true
number.getRegion(); // 'US'
number.formatE164(); // '+12015550123'
number.formatInternational(); // '+1 201-555-0123'

Input controllers take the field's value and selection, and return the formatted value and the caret to write back:

import { createNationalInputController } from '@telixon/core';

const controller = createNationalInputController({ defaultRegion: 'US' });

controller.insert('', '4155550132', 0, 0);
// { value: '(415) 555-0132', region: 'US', selectionStart: 14, selectionEnd: 14 }

// Deleting the selected '5) 55' drops its digits and reflows what remains.
controller.deleteBackward('(415) 555-0132', 3, 8);
// { value: '(415) 013-2', region: 'US', selectionStart: 3, selectionEnd: 3 }

Highlights

• Conformance-verified. Every query method with a Google libphonenumber counterpart is compared against it in CI, on every push.
• One deterministic finite automaton. Google publishes its metadata as regular expressions; Telixon compiles them ahead of time into one automaton. A single linear-time walk yields validity, number type, region, and format.
• An order of magnitude faster. A single linear 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.
• Every JavaScript runtime. Node.js, browsers, Deno, Bun, and edge, selected through package export conditions and each exercised in CI.
• Zero dependencies.

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.

License

Apache-2.0 © Martsin Labs