to-words/dist/types/ToWords.d.ts

Convert numbers to words in 132 locales with currency, ordinal, and BigInt support (TypeScript, ESM/CJS/UMD).

/**
 * ToWords - Full-featured class with all bundled locales.
 *
 * This class extends ToWordsCore and adds locale lookup by code string.
 * It imports all locales, so use this when you need dynamic locale switching
 * or don't care about bundle size.
 *
 * For tree-shaken single-locale imports, use per-locale entry points instead:
 *
 * @example
 * // Full package (all locales ~55KB gzipped)
 * import { ToWords } from 'to-words';
 * const tw = new ToWords({ localeCode: 'en-IN' });
 *
 * // Single locale (~3-4KB gzipped) - SAME API!
 * import { ToWords } from 'to-words/en-IN';
 * const tw = new ToWords();
 */
import { type ConstructorOf, type ConverterOptions, type LocaleInterface, type NumberInput, type OrdinalOptions } from './types.js';
import { ToWordsCore, DefaultConverterOptions, DefaultToWordsOptions } from './ToWordsCore.js';
import LOCALES from './locales/index.js';
export { DefaultConverterOptions, DefaultToWordsOptions };
export { LOCALES };
export declare function setLocaleDetector(fn: (() => string) | null): void;
export declare class ToWords extends ToWordsCore {
    /**
     * Get the locale class, either from setLocale() or by looking up the localeCode.
     * This overrides ToWordsCore to add LOCALES lookup.
     */
    getLocaleClass(): ConstructorOf<LocaleInterface>;
}
/**
 * Detect the current locale from the environment and match it against the supported
 * locale list. This is the single entry point for all auto-detection.
 *
 * Detection order:
 *  1. Custom detector (if registered via `setLocaleDetector()`).
 *  2. `navigator.language` — browser / React Native.
 *  3. `Intl.DateTimeFormat().resolvedOptions().locale` — Node.js, Deno, Bun, CF Workers.
 *
 * Once a raw locale string is obtained it is normalised and matched:
 *  1. Exact match (e.g. `fr-FR`).
 *  2. Strip BCP 47 script tag (e.g. `zh-Hant-TW` → `zh-TW`).
 *  3. Language-prefix fallback (e.g. `sw-ZZ` → first `sw-*` locale in the list).
 *
 * Returns `fallback` (default `'en-IN'`) when nothing matches.
 *
 * @param fallback  Locale code to return when detection yields no match.
 */
export declare function detectLocale(fallback?: string): string;
/**
 * Convert a number to words.
 * Uses the full bundle (all locales). For tree-shaken single-locale usage import from `to-words/<locale>`.
 * Internally caches one `ToWords` instance per locale — no performance penalty on repeated calls.
 * When `localeCode` is omitted, the runtime locale is auto-detected via `detectLocale()`.
 *
 * @example
 * import { toWords } from 'to-words';
 * toWords(12345, { localeCode: 'en-US' }); // "Twelve Thousand Three Hundred Forty Five"
 * toWords(12345); // uses auto-detected runtime locale, falls back to 'en-IN'
 */
export declare function toWords(number: NumberInput, options?: ConverterOptions & {
    localeCode?: string;
}): string;
/**
 * Convert a number to ordinal words.
 * Uses the full bundle (all locales). For tree-shaken single-locale usage import from `to-words/<locale>`.
 * When `localeCode` is omitted, the runtime locale is auto-detected via `detectLocale()`.
 *
 * @example
 * import { toOrdinal } from 'to-words';
 * toOrdinal(21, { localeCode: 'en-US' }); // "Twenty First"
 * toOrdinal(21); // uses auto-detected runtime locale, falls back to 'en-IN'
 */
export declare function toOrdinal(number: NumberInput, options?: OrdinalOptions & {
    localeCode?: string;
}): string;
/**
 * Convert a number to currency words.
 * Uses the full bundle (all locales). For tree-shaken single-locale usage import from `to-words/<locale>`.
 * Shorthand for `toWords(number, { currency: true, ...options })`.
 * When `localeCode` is omitted, the runtime locale is auto-detected via `detectLocale()`.
 *
 * @example
 * import { toCurrency } from 'to-words';
 * toCurrency(1234.56, { localeCode: 'en-US' }); // "One Thousand Two Hundred Thirty Four Dollars And Fifty Six Cents Only"
 * toCurrency(1234.56); // uses auto-detected runtime locale, falls back to 'en-IN'
 */
export declare function toCurrency(number: NumberInput, options?: ConverterOptions & {
    localeCode?: string;
}): string;