Load the engine

Composes: ensureEngineReady + isEngineReady + EngineNotReadyError

This guide initializes Telixon correctly in your environment: Node, the browser, an edge runtime, or a synchronous CLI or test process. Every Telixon API queries one deterministic automaton compiled from Google’s metadata, and loading is the step that puts that automaton in memory, once per process.

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

await ensureEngineReady();

const phone = parsePhoneNumber('+14155550132');

console.log(phone.isValid()); // true
console.log(phone.formatE164()); // '+14155550132'
console.log(phone.formatNational()); // '(415) 555-0132'

Expected result: the await resolves once the engine is decoded, and from that point every API call is synchronous.

1. Import from ‘@telixon/core’

The import specifier is always '@telixon/core'. The package’s export conditions resolve it to a per-environment entry automatically: a Node entry in Node, a browser entry in browsers, an edge entry in edge runtimes (workerd, edge-light, worker). Your bundler or runtime picks the entry; your code never changes.

Importing the package has no side effects: the library never loads the engine at import time; you choose the moment.

2. Await ensureEngineReady() once

One await at startup, before the first API call. Loading fetches or imports the base64-of-gzip engine modules and decodes them off-thread where the environment allows; the mechanism is described in How the engine works.

Calling ensureEngineReady() more than once is safe. Concurrent calls share one in-flight load, and calls after readiness resolve immediately:

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

// Two concurrent calls trigger exactly one load.
await Promise.all([ensureEngineReady(), ensureEngineReady()]);

// The engine is ready: this resolves immediately.
await ensureEngineReady();

3. Handle the not-ready state

Calling any API before the engine is ready throws EngineNotReadyError:

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

// No ensureEngineReady() call has resolved yet.
parsePhoneNumber('+14155550132');
// throws EngineNotReadyError: Telixon engine is not initialized.
//
// Initialization is explicit. Call ensureEngineReady() before the first API call: ...
// (the message continues with the exact fix and the sync-init alternative)

The throw signals an ordering bug, not a runtime condition to retry: fix the call order instead of catching. For code paths that may legitimately run while the engine is still loading, guard with isEngineReady():

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

function validate(input: string): boolean | null {
  if (!isEngineReady()) return null; // engine still loading, no result yet
  return parsePhoneNumber(input, { defaultRegion: 'US' }).isValid();
}

4. Initialize synchronously in CLIs and tests

When top-level await is unavailable or unwanted, import ensureEngineReadySync from '@telixon/core/sync-init'; it decodes the bundled engine modules synchronously on the calling thread. Prefer the awaited entry anywhere startup latency matters; the full entry and decode matrix is on ensureEngineReady.

import { ensureEngineReadySync } from '@telixon/core/sync-init';
import { parsePhoneNumber } from '@telixon/core';

ensureEngineReadySync();

console.log(parsePhoneNumber('+14155550132').formatNational()); // '(415) 555-0132'

Both initializers ready the same process-wide engine: whichever runs first wins, and the other returns immediately.

Next steps

• Validate numbers at the moment they are submitted: Validate on submit
• Drive a phone input per keystroke: Drive an input
• What the engine is and how it is built: How the engine works