Getting started

@telixon/core parses, validates, and formats phone numbers, while its input controllers give a flexible API for entering them. All of 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

Bad input never throws. It comes back as a PhoneNumber carrying 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 a phone number turns them into messages.

Drive an input

An input controller takes the field’s value and selection, and returns the formatted value and the caret to write back. Formatting starts at 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.