tessl/npm-formatjs--ecma402-abstract

A collection of implementation for ECMAScript abstract operations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

ECMA402 Abstract

Name: tessl/npm-formatjs--ecma402-abstract
Author: tessl

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;
}