Getting started

@telixon/core parses, validates, and formats phone numbers. The same engine drives phone-number fields. It runs in Node.js, browsers, Deno, Bun, and edge runtimes, with no dependencies.

Install

npm

npm install @telixon/core

pnpm

pnpm add @telixon/core

Yarn

yarn add @telixon/core

Bun

bun add @telixon/core

Deno

deno add npm:@telixon/core

Parse a number

One await at startup loads the engine. Everything after it is synchronous. Load the engine covers the per-runtime builds and the synchronous entry.

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

await ensureEngineReady();

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

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

A leading + reads as international. Anything else needs a region to resolve against:

parsePhoneNumber('(415) 555-0132', { defaultRegion: 'US' }).formatE164(); // '+14155550132'

Inspect invalid input

parsePhoneNumber never throws: bad input still comes back as a PhoneNumber, with a typed reason:

const wrongLength = parsePhoneNumber('+57 321 123 456');

wrongLength.isValid(); // false
wrongLength.getValidationError(); // { kind: 'INVALID_LENGTH', possibleLengths: [8, 10, 11] }

Colombia dials numbers of 8, 10, and 11 digits. Nine digits falls in a gap. The error carries the lengths that exist.

ValidationError lists all nine variants. Validate user input turns them into messages.

Drive an input

An input controller is the same engine called once per keystroke. It takes the field’s value and caret, then returns the next ones. The field formats from the first digit:

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

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

controller.insert('', '4', 0, 0);
// { value: '(4)', region: 'US', selectionStart: 2, selectionEnd: 2 }

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

controller.getPhoneNumber().formatE164(); // '+14155550132'

Build a phone input covers the field wiring.

The model behind all of this is in How Telixon works.