Locale and Options Processing

/**
 * Canonicalizes a locale list according to ECMA-402 specification
 * @param locales - Single locale string or array of locale strings
 * @returns Array of canonicalized locale strings
 */
function CanonicalizeLocaleList(locales?: string | ReadonlyArray<string>): string[];

import { CanonicalizeLocaleList } from "@formatjs/ecma402-abstract";

// Single locale
const locales1 = CanonicalizeLocaleList('en-US');
console.log(locales1); // ['en-US']

// Multiple locales
const locales2 = CanonicalizeLocaleList(['en-US', 'fr-FR', 'de-DE']);
console.log(locales2); // ['en-US', 'fr-FR', 'de-DE']

// Undefined input
const locales3 = CanonicalizeLocaleList();
console.log(locales3); // []

/**
 * Canonicalizes timezone names according to IANA timezone database
 * @param tz - Timezone identifier to canonicalize
 * @param options - Timezone data and uppercase links mapping
 * @returns Canonicalized timezone name
 */
function CanonicalizeTimeZoneName(
  tz: string,
  options: {
    zoneNames: readonly string[];
    uppercaseLinks: Record<string, string>;
  }
): string;

/**
 * Coerces options parameter to an object
 * @param options - Options value to coerce
 * @returns Object representation of options, empty object if undefined
 */
function CoerceOptionsToObject<T>(options?: T): T;

import { CoerceOptionsToObject } from "@formatjs/ecma402-abstract";

// Valid object
const opts1 = CoerceOptionsToObject({ locale: 'en-US' });
console.log(opts1); // { locale: 'en-US' }

// Undefined
const opts2 = CoerceOptionsToObject();
console.log(opts2); // {}

// Null
const opts3 = CoerceOptionsToObject(null);
console.log(opts3); // {}

/**
 * Extracts and validates an option from a configuration object
 * @param opts - Options object to extract from
 * @param prop - Property key to extract
 * @param type - Expected type ('string' or 'boolean')
 * @param values - Allowed values for the option
 * @param fallback - Fallback value if option is undefined
 * @returns Extracted option value or fallback
 */
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;

import { GetOption } from "@formatjs/ecma402-abstract";

const options = { style: 'currency', currency: 'USD', useGrouping: true };

// String option with allowed values
const style = GetOption(
  options,
  'style',
  'string',
  ['decimal', 'currency', 'percent'],
  'decimal'
);
console.log(style); // 'currency'

// Boolean option
const grouping = GetOption(
  options,
  'useGrouping',
  'boolean',
  undefined,
  false
);
console.log(grouping); // true

// Missing option with fallback
const notation = GetOption(
  options,
  'notation',
  'string',
  ['standard', 'scientific'],
  'standard'
);
console.log(notation); // 'standard'

/**
 * Validates and returns options object, throws TypeError if not object
 * @param options - Options to validate
 * @returns Validated options object
 * @throws TypeError if options is not an object
 */
function GetOptionsObject<T extends object>(options?: T): T;

/**
 * Extracts and validates a number option with range checking
 * @param options - Options object containing the number property
 * @param property - Property key to extract
 * @param minimum - Minimum allowed value
 * @param maximum - Maximum allowed value
 * @param fallback - Fallback value if property is undefined
 * @returns Extracted number value or fallback
 */
function GetNumberOption<T extends object, K extends keyof T, F extends number | undefined>(
  options: T,
  property: K,
  minimum: number,
  maximum: number,
  fallback: F
): F extends number ? number : number | undefined;

import { GetNumberOption } from "@formatjs/ecma402-abstract";

const options = { minimumFractionDigits: 2, maximumFractionDigits: 4 };

// Extract number with range validation
const minDigits = GetNumberOption(
  options,
  'minimumFractionDigits',
  0,
  20,
  0
);
console.log(minDigits); // 2

// Extract with fallback
const signDigits = GetNumberOption(
  options,
  'minimumSignificantDigits',
  1,
  21,
  undefined
);
console.log(signDigits); // undefined

/**
 * Processes a default number option with range validation
 * @param inputVal - Input value to process
 * @param min - Minimum allowed value
 * @param max - Maximum allowed value
 * @param fallback - Fallback value if input is invalid
 * @returns Processed number value or fallback
 */
function DefaultNumberOption<F extends number | undefined>(
  inputVal: unknown,
  min: number,
  max: number,
  fallback: F
): F extends number ? number : number | undefined;

/**
 * Extracts string or boolean option with special value handling
 * @param opts - Options object
 * @param prop - Property key to extract
 * @param values - Allowed string values
 * @param trueValue - Value to return when option is true
 * @param falsyValue - Value to return when option is false/undefined
 * @param fallback - Fallback value
 * @returns Extracted option value, boolean equivalent, or fallback
 */
function GetStringOrBooleanOption<T extends object, K extends keyof T>(
  opts: T,
  prop: K,
  values: T[K][] | undefined,
  trueValue: T[K] | boolean,
  falsyValue: T[K] | boolean,
  fallback: T[K] | boolean
): T[K] | boolean;

/**
 * Returns supported locales from requested list
 * @param availableLocales - Set of available locale identifiers
 * @param requestedLocales - Array of requested locale identifiers
 * @param options - Locale matching options
 * @returns Array of supported locale identifiers
 */
function SupportedLocales(
  availableLocales: Set<string>,
  requestedLocales: string[],
  options?: {
    localeMatcher?: 'best fit' | 'lookup';
  }
): string[];

import { SupportedLocales } from "@formatjs/ecma402-abstract";

const available = new Set(['en-US', 'fr-FR', 'de-DE', 'ja-JP']);
const requested = ['en-GB', 'en-US', 'fr-FR', 'es-ES'];

const supported = SupportedLocales(available, requested);
console.log(supported); // ['en-US', 'fr-FR']

// With lookup matcher
const supported2 = SupportedLocales(available, requested, {
  localeMatcher: 'lookup'
});
console.log(supported2); // ['en-US', 'fr-FR']