or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdlocale-options.mdmathematical.mdnumber-formatting.mdutilities.mdvalidation.md
tile.json

index.mddocs/

ECMA402 Abstract

A comprehensive collection of implementations for ECMAScript 402 abstract operations, providing foundational utilities for internationalization (i18n) functionality in JavaScript applications. This package serves as a low-level utility library that other FormatJS packages depend on, offering functions for locale handling, number formatting, currency validation, timezone processing, and various ECMA-402 specification abstractions.

Package Information

  • Package Name: @formatjs/ecma402-abstract
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @formatjs/ecma402-abstract

Core Imports

import { 
  CanonicalizeLocaleList,
  GetOption,
  ToNumber,
  FormatNumeric,
  IsWellFormedCurrencyCode 
} from "@formatjs/ecma402-abstract";

For CommonJS:

const { 
  CanonicalizeLocaleList,
  GetOption,
  ToNumber,
  FormatNumeric,
  IsWellFormedCurrencyCode 
} = require("@formatjs/ecma402-abstract");

Basic Usage

import { 
  CanonicalizeLocaleList,
  GetOption,
  IsWellFormedCurrencyCode,
  ToNumber,
  ZERO
} from "@formatjs/ecma402-abstract";

// Locale processing
const locales = CanonicalizeLocaleList(['en-US', 'fr-FR']);
console.log(locales); // ['en-US', 'fr-FR']

// Options extraction
const options = { style: 'currency', currency: 'USD' };
const style = GetOption(options, 'style', 'string', ['decimal', 'currency'], 'decimal');
console.log(style); // 'currency'

// Currency validation
console.log(IsWellFormedCurrencyCode('USD')); // true
console.log(IsWellFormedCurrencyCode('usd')); // false

// Mathematical operations
const number = ToNumber('123.45');
console.log(number.toString()); // '123.45'
console.log(ZERO.toString()); // '0'

Architecture

The package is organized around several key components:

  • Locale Processing: Functions for canonicalizing and validating locales and timezone names
  • Options Handling: Generic utilities for extracting and validating options from configuration objects
  • Validation Functions: Validators for currency codes, unit identifiers, and other internationalization data
  • Mathematical Operations: ECMA-262 abstract operations using Decimal.js for precision
  • Number Formatting: Comprehensive number formatting utilities following ECMA-402 specification
  • Type System: Complete TypeScript definitions for all internationalization data structures
  • Utility Functions: Internal slot management, memoization, and helper functions

Capabilities

Locale and Options Processing

Core utilities for handling locale lists, extracting options, and processing internationalization configuration. Essential for building locale-aware applications.

function CanonicalizeLocaleList(locales?: string | ReadonlyArray<string>): string[];

function GetOption<T extends object, K extends keyof T, F>(
  opts: T,
  prop: K,
  type: 'string' | 'boolean',
  values: readonly T[K][] | undefined,
  fallback: F
): Exclude<T[K], undefined> | F;

function CoerceOptionsToObject<T>(options?: T): T;

Locale and Options Processing

Validation Functions

Validation utilities for currency codes, unit identifiers, timezone names, and other internationalization identifiers according to ECMA-402 standards.

function IsWellFormedCurrencyCode(currency: string): boolean;

function IsWellFormedUnitIdentifier(unit: string): boolean;

function IsValidTimeZoneName(
  tz: string,
  options: {
    zoneNamesFromData: readonly string[];
    uppercaseLinks: Record<string, string>;
  }
): boolean;

function IsSanctionedSimpleUnitIdentifier(unitIdentifier: string): boolean;

Validation Functions

Mathematical Operations

ECMA-262 abstract operations implemented with Decimal.js for high-precision arithmetic, type conversion, and mathematical utilities.

function ToNumber(arg: any): Decimal;

function ToString(o: unknown): string;

function ToPrimitive<T extends 'string' | 'number' = 'string' | 'number'>(
  input: any,
  preferredType: T
): string | number | boolean | undefined | null;

function ToIntlMathematicalValue(input: unknown): Decimal;

Mathematical Operations

Number Formatting

Comprehensive number formatting system implementing ECMA-402 NumberFormat abstract operations, including pattern processing, rounding, and localized number display.

function FormatNumeric(internalSlots: NumberFormatInternal, x: Decimal): string;

function FormatNumericToParts(
  internalSlots: NumberFormatInternal,
  x: Decimal
): NumberFormatPart[];

function InitializeNumberFormat(
  nf: Intl.NumberFormat,
  locales: string | string[] | undefined,
  opts: NumberFormatOptions | undefined,
  options: NumberFormatInitOptions
): void;

Number Formatting

Utility Functions

Internal utilities for slot management, memoization, property operations, and other helper functions used throughout the FormatJS ecosystem.

function setInternalSlot<Instance extends object, Internal extends object, Field extends keyof Internal>(
  map: WeakMap<Instance, Internal>,
  pl: Instance,
  field: Field,
  value: NonNullable<Internal>[Field]
): void;

function getInternalSlot<Instance extends object, Internal extends object, Field extends keyof Internal>(
  map: WeakMap<Instance, Internal>,
  pl: Instance,
  field: Field
): Internal[Field];

function invariant(
  condition: boolean,
  message: string,
  Err?: any
): asserts condition;

Utility Functions

Constants

const ZERO: Decimal;

Core Types

type Locale = string;

interface LocaleData<T> {
  data: T;
  locale: Locale;
}

interface LookupMatcherResult {
  locale: string;
  extension?: string;
  nu?: string;
}

interface LiteralPart {
  type: 'literal';
  value: string;
}