Utilities

Four small lookup functions and two constant registries. Digits drive one deterministic automaton compiled from Google’s metadata; the helpers on this page do not feed digits through the automaton, they read the metadata tables that ship alongside it: example numbers, formats, calling codes, and each region’s number type table.

Import

import {
  getCallingCodeForRegion,
  getPlaceholders,
  isNationalPrefixOptional,
  regionSupportsNumberTypes,
  NUMBER_TYPES,
  REGION_CODES,
} from '@telixon/core';
import type { NumberType, Placeholders, RegionCode } from '@telixon/core';

The four functions read engine metadata, so the engine must be initialized first; see Errors. Every example below runs after await ensureEngineReady().

getPlaceholders

Returns example placeholder variants for a (region, type) pair, or null if the metadata has no example for it.

Signature

export function getPlaceholders(region: RegionCode, type: NumberType): Placeholders | null;

/** Example placeholder variants for one number type, all optional. */
export interface Placeholders {
  readonly national?: string;
  readonly nationalWithPrefix?: string;
  readonly international?: string;
}

Parameters

Parameter	Type	Default	Meaning
region	RegionCode	required	CLDR two-letter region code, e.g. 'US'.
type	NumberType	required	The number type to look up an example number of.

Returns

Placeholders | null. The variants render the region’s example number for the type through the same formats the resolve layer uses.

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

await ensureEngineReady();

getPlaceholders('US', 'MOBILE');
// { national: '(201) 555-0123', nationalWithPrefix: '1 (201) 555-0123', international: '201-555-0123' }

getPlaceholders('GB', 'MOBILE');
// { national: '7400 123456', nationalWithPrefix: '07400 123456', international: '7400 123456' }

getPlaceholders('DE', 'FIXED_LINE');
// { national: '30 123456', nationalWithPrefix: '030 123456', international: '30 123456' }

Behavior

• national is the example number in the national format without the national prefix; nationalWithPrefix includes the region’s national prefix (1 (201) 555-0123, 07400 123456).

• international renders the example number with the international format. The calling code is not part of it; compose the full string yourself when you need it:

  const placeholders = getPlaceholders('US', 'MOBILE');
  const international = `+${getCallingCodeForRegion('US')} ${placeholders?.international}`;
  // '+1 201-555-0123'

• Every field is optional. A variant is absent when the metadata defines no mask for it.

• Returns null when the region is unknown or the metadata has no example number for the type:

  getPlaceholders('US', 'UNKNOWN'); // null

• A FIXED_LINE_OR_MOBILE query looks up FIXED_LINE first, then MOBILE.

Use it for the placeholder attribute of a phone input, typically next to a controller-driven field. Pick the variant with isNationalPrefixOptional: national where the prefix is optional, nationalWithPrefix where users expect to type it.

isNationalPrefixOptional

Returns true when the format matching the example number for (region, type) allows the national prefix to be omitted.

Signature

export function isNationalPrefixOptional(region: RegionCode, type: NumberType): boolean;

Parameters

Parameter	Type	Default	Meaning
region	RegionCode	required	CLDR two-letter region code.
type	NumberType	required	The number type whose format is checked.

Returns

boolean.

isNationalPrefixOptional('US', 'MOBILE'); // true
isNationalPrefixOptional('GB', 'MOBILE'); // false
isNationalPrefixOptional('DE', 'FIXED_LINE'); // false

Behavior

• 'US' is true: US numbers are written with or without the leading 1. 'GB' and 'DE' are false: the national writing requires the leading 0, and omitting it is the NATIONAL_PREFIX_MISSING validation error.
• Returns false for an unknown region and for a type with no matching format.

Use it to choose between the national and nationalWithPrefix variants of getPlaceholders.

getCallingCodeForRegion

Returns the calling code for a region as a string of digits, without the plus.

Signature

export function getCallingCodeForRegion(region: RegionCode): string;

Parameters

Parameter	Type	Default	Meaning
region	RegionCode	required	CLDR two-letter region code.

Returns

string.

getCallingCodeForRegion('US'); // '1'
getCallingCodeForRegion('UA'); // '380'
getCallingCodeForRegion('GB'); // '44'

Behavior

• Returns '0' for a region the metadata does not know, mirroring Google libphonenumber’s getCountryCodeForRegion. Under the RegionCode type this only happens with unchecked JavaScript input:

  getCallingCodeForRegion('ZZ' as RegionCode); // '0'

Use it for calling code labels in a region picker and for composing full international placeholders from getPlaceholders.

regionSupportsNumberTypes

Returns true when the region supports at least one of the given number types.

Signature

export function regionSupportsNumberTypes(region: RegionCode, types: readonly NumberType[]): boolean;

Parameters

Parameter	Type	Default	Meaning
region	RegionCode	required	CLDR two-letter region code.
types	readonly NumberType[]	required	Types to test; one match returns true.

Returns

boolean.

regionSupportsNumberTypes('US', ['MOBILE']); // true
regionSupportsNumberTypes('US', ['FIXED_LINE_OR_MOBILE']); // true
regionSupportsNumberTypes('UA', ['MOBILE']); // true
regionSupportsNumberTypes('US', ['SHARED_COST']); // false

Behavior

• The US answers true for both MOBILE and FIXED_LINE_OR_MOBILE even though a parsed US number reports getType() as FIXED_LINE_OR_MOBILE, because the US classifies most numbers as FIXED_LINE_OR_MOBILE while its metadata still defines both underlying types.

• A FIXED_LINE_OR_MOBILE entry in types matches a region that supports FIXED_LINE or MOBILE.

• UNKNOWN matches nothing, an empty types array returns false, and an unknown region returns false:

  regionSupportsNumberTypes('US', []); // false

Use it to validate filter configuration: before restricting a field to specific types for a chosen region, check that the region defines them at all.

REGION_CODES

The readonly registry of every region the engine knows, in alphabetical order. The RegionCode type is derived from it.

Signature

export const REGION_CODES: readonly ['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM' /* ...237 more */];
export type RegionCode = (typeof REGION_CODES)[number];

Returns

REGION_CODES.length; // 245
REGION_CODES.slice(0, 8); // ['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM']

Behavior

• A compile-time constant: safe to read before engine initialization, so a region picker can render while ensureEngineReady is still loading.

• Use it to enumerate regions for a picker and to narrow untrusted strings to RegionCode:

  function toRegionCode(value: string): RegionCode | null {
    return (REGION_CODES as readonly string[]).includes(value) ? (value as RegionCode) : null;
  }
  
  toRegionCode('UA'); // 'UA'
  toRegionCode('XX'); // null

NUMBER_TYPES

The readonly registry of every number type, exhaustive over the NumberType union.

Signature

export const NUMBER_TYPES: readonly NumberType[];

export type NumberType =
  | 'FIXED_LINE'
  | 'MOBILE'
  | 'FIXED_LINE_OR_MOBILE'
  | 'TOLL_FREE'
  | 'PREMIUM_RATE'
  | 'SHARED_COST'
  | 'VOIP'
  | 'PERSONAL_NUMBER'
  | 'PAGER'
  | 'UAN'
  | 'VOICEMAIL'
  | 'UNKNOWN';

Returns

NUMBER_TYPES;
// ['FIXED_LINE', 'MOBILE', 'FIXED_LINE_OR_MOBILE', 'TOLL_FREE',
//  'PREMIUM_RATE', 'SHARED_COST', 'VOIP', 'PERSONAL_NUMBER',
//  'PAGER', 'UAN', 'VOICEMAIL', 'UNKNOWN']

Behavior

• A compile-time constant, safe to read before engine initialization. The list is type-checked to stay exhaustive: it fails to compile if NumberType gains a value it misses.
• UNKNOWN is the classification a PhoneNumber reports when no type pattern matches; as an input to the lookup functions on this page it matches nothing.
• Use it to build number type filter options and to iterate all types, for example against regionSupportsNumberTypes.

Errors

The four lookup functions require an initialized engine and throw when called before ensureEngineReady resolves. The throw is a plain TypeError from the missing metadata tables, not the typed EngineNotReadyError that parsePhoneNumber raises; when initialization timing is uncertain, check isEngineReady() first.

An unknown region never throws after initialization: getPlaceholders returns null, isNationalPrefixOptional and regionSupportsNumberTypes return false, and getCallingCodeForRegion returns '0'.

REGION_CODES and NUMBER_TYPES are constants; they never touch the engine and never throw.

Used in guides

• Drive an input
• Engine loading

See also

• ensureEngineReady
• parsePhoneNumber
• PhoneNumber
• createNationalInputController
• The model