Skip to content
Telixon

Getting started

@telixon/core parses, validates, and formats phone numbers in Node.js, browsers, and edge runtimes.

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


await ensureEngineReady();


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


phone.isValid(); // true
phone.getRegion(); // 'US'
phone.getNumberType(); // 'FIXED_LINE_OR_MOBILE'
phone.formatE164(); // '+14155550132'
phone.formatNational(); // '(415) 555-0132'

Every output on this page is real, executed against the engine in CI. (The number itself is from the NANP fictional 555-01XX block, reserved for examples.)

Install

Section titled “Install”
Terminal window
pnpm add @telixon/core

The package has zero runtime dependencies. Node.js 18 or later is required; browsers and edge runtimes are supported through their own entry points, resolved automatically by your bundler or runtime.

Load the engine

Section titled “Load the engine”

The engine loads once per process with a single await:

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


await ensureEngineReady();

ensureEngineReady() resolves to the loader for your environment (Node.js, browser, or edge) and is safe to call more than once; after the first resolution it returns immediately. Calling any parsing API before it throws:

parsePhoneNumber('+1 (415) 555-0132');
// EngineNotReadyError: Telixon engine is not initialized.

See ensureEngineReady for the per-environment entry points and a synchronous alternative, and Engine loading for choosing a loading strategy.

Parse a number

Section titled “Parse a number”

Input with a leading + carries its own calling code. Input without one needs a defaultRegion:

const phone = parsePhoneNumber('(415) 555-0132', { defaultRegion: 'US' });


phone.isValid(); // true
phone.formatE164(); // '+14155550132'

The returned PhoneNumber answers every query on the parsed input; the options are documented on parsePhoneNumber.

Handle invalid input

Section titled “Handle invalid input”

Invalid input never throws. isValid() returns false, formatters return null, and getValidationError() names the exact reason:

const phone = parsePhoneNumber('415 555', { defaultRegion: 'US' });


phone.isValid(); // false
phone.getValidationError(); // { kind: 'TOO_SHORT', minLength: 10 }
phone.formatE164(); // null

All eight error variants and their fields are documented on ValidationError.

Next steps

Section titled “Next steps”