intl-formatter 1.0.0

package/dist/esm/core/formatter.js

@@ -0,0 +1,468 @@
+const DEFAULT_RULES = {
+    compactThreshold: 10000,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+    currencyDisplay: "narrowSymbol",
+    numberFormat: {},
+    currencyFormat: {},
+    relativeTimeFormat: { style: "long", numeric: "auto" },
+    dateFormat: { year: "numeric", month: "short", day: "2-digit" },
+    dateTimeFormat: {
+        year: "numeric",
+        month: "short",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: true,
+    },
+    fallback: "—",
+    numberFallback: "",
+    currencyFallback: "",
+    percentageFallback: "",
+    durationFallback: "",
+    dateFallback: "",
+    dateTimeFallback: "",
+    relativeTimeFallback: "",
+};
+const DEFAULT_DURATION_LABELS = {
+    h: "h",
+    m: "m",
+    s: "s",
+    hour: { one: "hour", other: "hours" },
+    minute: { one: "minute", other: "minutes" },
+    second: { one: "second", other: "seconds" }
+};
+// ─── Module-Level High Performance Global Caches ──────────────────────────────
+const MAX_CACHE_SIZE = 1000;
+const numberFormatters = new Map();
+const dateTimeFormatters = new Map();
+const relativeTimeFormatters = new Map();
+const pluralRulesFormatters = new Map();
+function serializeOptions(locale, opts) {
+    const keys = Object.keys(opts);
+    if (keys.length === 0)
+        return locale;
+    keys.sort();
+    let parts = [locale];
+    for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        const v = opts[k];
+        if (v === undefined)
+            continue;
+        // escape backslashes, pipes, commas, and colons to prevent cache key collisions
+        const safeK = k.replace(/[\\|:,]/g, '\\$&');
+        const safeV = String(v).replace(/[\\|:,]/g, '\\$&');
+        parts.push(`${safeK}:${safeV}`);
+    }
+    return parts.join("|");
+}
+function getNumberFormatter(locale, options) {
+    const key = serializeOptions(locale, options);
+    if (numberFormatters.has(key)) {
+        const entry = numberFormatters.get(key);
+        numberFormatters.delete(key);
+        numberFormatters.set(key, entry);
+        return entry;
+    }
+    const formatter = new Intl.NumberFormat(locale, options);
+    if (numberFormatters.size >= MAX_CACHE_SIZE) {
+        const oldestKey = numberFormatters.keys().next().value;
+        if (oldestKey !== undefined)
+            numberFormatters.delete(oldestKey);
+    }
+    numberFormatters.set(key, formatter);
+    return formatter;
+}
+function getDateTimeFormatter(locale, options) {
+    const key = serializeOptions(locale, options);
+    if (dateTimeFormatters.has(key)) {
+        const entry = dateTimeFormatters.get(key);
+        dateTimeFormatters.delete(key);
+        dateTimeFormatters.set(key, entry);
+        return entry;
+    }
+    const formatter = new Intl.DateTimeFormat(locale, options);
+    if (dateTimeFormatters.size >= MAX_CACHE_SIZE) {
+        const oldestKey = dateTimeFormatters.keys().next().value;
+        if (oldestKey !== undefined)
+            dateTimeFormatters.delete(oldestKey);
+    }
+    dateTimeFormatters.set(key, formatter);
+    return formatter;
+}
+function getRelativeTimeFormatter(locale, options) {
+    const key = serializeOptions(locale, options);
+    if (relativeTimeFormatters.has(key)) {
+        const entry = relativeTimeFormatters.get(key);
+        relativeTimeFormatters.delete(key);
+        relativeTimeFormatters.set(key, entry);
+        return entry;
+    }
+    const formatter = new Intl.RelativeTimeFormat(locale, options);
+    if (relativeTimeFormatters.size >= MAX_CACHE_SIZE) {
+        const oldestKey = relativeTimeFormatters.keys().next().value;
+        if (oldestKey !== undefined)
+            relativeTimeFormatters.delete(oldestKey);
+    }
+    relativeTimeFormatters.set(key, formatter);
+    return formatter;
+}
+function getPluralRulesFormatter(locale, options) {
+    const key = serializeOptions(locale, options);
+    if (pluralRulesFormatters.has(key)) {
+        const entry = pluralRulesFormatters.get(key);
+        pluralRulesFormatters.delete(key);
+        pluralRulesFormatters.set(key, entry);
+        return entry;
+    }
+    const rulesInstance = new Intl.PluralRules(locale, options);
+    if (pluralRulesFormatters.size >= MAX_CACHE_SIZE) {
+        const oldestKey = pluralRulesFormatters.keys().next().value;
+        if (oldestKey !== undefined)
+            pluralRulesFormatters.delete(oldestKey);
+    }
+    pluralRulesFormatters.set(key, rulesInstance);
+    return rulesInstance;
+}
+export function createFormatter(config = {}) {
+    const locale = config.locale ?? "en-US";
+    let defaultCurrency = config.currency ?? "USD";
+    if (typeof defaultCurrency === "string") {
+        defaultCurrency = defaultCurrency.toUpperCase();
+        if (!/^[A-Z]{3}$/.test(defaultCurrency)) {
+            console.warn(`[intl-formatter] Invalid currency code "${defaultCurrency}". Falling back to "USD".`);
+            defaultCurrency = "USD";
+        }
+    }
+    const fallback = config.fallback ?? "—";
+    const rules = {
+        ...DEFAULT_RULES,
+        ...config.rules,
+        numberFormat: { ...DEFAULT_RULES.numberFormat, ...config.rules?.numberFormat },
+        currencyFormat: { ...DEFAULT_RULES.currencyFormat, ...config.rules?.currencyFormat },
+        relativeTimeFormat: { ...DEFAULT_RULES.relativeTimeFormat, ...config.rules?.relativeTimeFormat },
+        dateFormat: { ...DEFAULT_RULES.dateFormat, ...config.rules?.dateFormat },
+        dateTimeFormat: { ...DEFAULT_RULES.dateTimeFormat, ...config.rules?.dateTimeFormat },
+    };
+    // Specialized Fallbacks Resolution
+    const defaultNumberFallback = rules.numberFallback || rules.fallback || fallback;
+    const defaultCurrencyFallback = rules.currencyFallback || rules.fallback || fallback;
+    const defaultPercentageFallback = rules.percentageFallback || rules.fallback || fallback;
+    const defaultDurationFallback = rules.durationFallback || rules.fallback || fallback;
+    const defaultDateFallback = rules.dateFallback || rules.fallback || fallback;
+    const defaultDateTimeFallback = rules.dateTimeFallback || rules.fallback || fallback;
+    const defaultRelativeTimeFallback = rules.relativeTimeFallback || rules.fallback || fallback;
+    function toNumber(value) {
+        if (value == null || value === "")
+            return null;
+        try {
+            if (typeof value === "boolean")
+                return null;
+            if (Array.isArray(value))
+                return null;
+            const n = typeof value === "number" ? value : Number(value);
+            return Number.isNaN(n) ? null : n;
+        }
+        catch {
+            return null;
+        }
+    }
+    function toValidDate(value) {
+        if (value == null || value === "")
+            return null;
+        try {
+            if (value instanceof Date) {
+                return Number.isNaN(value.getTime()) ? null : value;
+            }
+            if (typeof value === "number") {
+                const d = new Date(value);
+                return Number.isNaN(d.getTime()) ? null : d;
+            }
+            if (typeof value === "string") {
+                const isDigitsOnly = /^-?\d+$/.test(value);
+                const isCalendarDate = /^(?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])(?:[01]\d|2[0-3])?$/.test(value);
+                if (isDigitsOnly && value.length === 10 && !isCalendarDate) {
+                    // Second UNIX timestamp: convert to milliseconds
+                    const parsedValue = Number(value) * 1000;
+                    const d = new Date(parsedValue);
+                    return Number.isNaN(d.getTime()) ? null : d;
+                }
+                if (isDigitsOnly && value.length >= 12) {
+                    // Millisecond UNIX timestamp
+                    const parsedValue = Number(value);
+                    const d = new Date(parsedValue);
+                    return Number.isNaN(d.getTime()) ? null : d;
+                }
+                const d = new Date(value);
+                return Number.isNaN(d.getTime()) ? null : d;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function isLarge(n) {
+        return Math.abs(n) >= rules.compactThreshold;
+    }
+    function normalizeICU(str, localeStr) {
+        // Normalize both narrow no-break space and standard non-breaking space to regular space
+        let normalized = str.replace(/[\u202f\u00a0]/g, " ").trim();
+        // Only apply English-style compact suffix normalizer if locale is English to avoid breaking other languages
+        if (localeStr.startsWith("en")) {
+            normalized = normalized.replace(/(\d)\s*([kKmMbBtT])\b/g, (match, p1, p2) => p1 + p2.toUpperCase());
+        }
+        return normalized;
+    }
+    function safeFormat(formatterFn, fallbackValue) {
+        try {
+            return formatterFn();
+        }
+        catch (err) {
+            console.error(`[intl-formatter] Formatting failed. Returning fallback. Error:`, err);
+            return fallbackValue;
+        }
+    }
+    function resolvePluralLabel(v, form, localeStr) {
+        if (typeof form === "string") {
+            // Singular/plural backwards fallback
+            return v === 1 ? (form === "hours" ? "hour" : form === "minutes" ? "minute" : form === "seconds" ? "second" : form) : form;
+        }
+        // Backward compatibility for legacy option keys { singular, plural }
+        const legacyForm = form;
+        if (legacyForm.singular !== undefined || legacyForm.plural !== undefined) {
+            return v === 1 ? (legacyForm.singular ?? legacyForm.other) : (legacyForm.plural ?? legacyForm.other);
+        }
+        const rulesInstance = getPluralRulesFormatter(localeStr, { type: "cardinal" });
+        const category = rulesInstance.select(v);
+        return form[category] ?? form.other;
+    }
+    const formatters = {
+        number(value, options = {}) {
+            const n = toNumber(value);
+            const callFallback = options.fallback ?? defaultNumberFallback;
+            if (n == null)
+                return callFallback;
+            return safeFormat(() => {
+                const { fallback: _, ...rest } = options;
+                const resolvedOptions = {
+                    style: "decimal",
+                    notation: isLarge(n) ? "compact" : "standard",
+                    minimumFractionDigits: rules.minimumFractionDigits,
+                    maximumFractionDigits: rules.maximumFractionDigits,
+                    ...rules.numberFormat,
+                    ...rest,
+                };
+                return normalizeICU(getNumberFormatter(locale, resolvedOptions).format(n), locale);
+            }, callFallback);
+        },
+        currency(value, options = {}) {
+            const n = toNumber(value);
+            const callFallback = options.fallback ?? defaultCurrencyFallback;
+            if (n == null)
+                return callFallback;
+            return safeFormat(() => {
+                const { currency: overrideCurrency, currencyDisplay, fallback: _, ...rest } = options;
+                let finalCurrency = overrideCurrency ?? defaultCurrency;
+                if (typeof finalCurrency === "string") {
+                    finalCurrency = finalCurrency.toUpperCase();
+                    if (!/^[A-Z]{3}$/.test(finalCurrency)) {
+                        console.warn(`[intl-formatter] Invalid override currency code "${finalCurrency}". Falling back to default: "${defaultCurrency}".`);
+                        finalCurrency = defaultCurrency;
+                    }
+                }
+                const resolvedOptions = {
+                    style: "currency",
+                    currency: finalCurrency,
+                    notation: isLarge(n) ? "compact" : "standard",
+                    minimumFractionDigits: rules.minimumFractionDigits,
+                    maximumFractionDigits: rules.maximumFractionDigits,
+                    currencyDisplay: currencyDisplay ?? rules.currencyDisplay,
+                    ...rules.currencyFormat,
+                    ...rest,
+                };
+                return normalizeICU(getNumberFormatter(locale, resolvedOptions).format(n), locale);
+            }, callFallback);
+        },
+        percentage(value, options = {}) {
+            const n = toNumber(value);
+            const callFallback = options.fallback ?? defaultPercentageFallback;
+            if (n == null)
+                return callFallback;
+            return safeFormat(() => {
+                const { inputMode, fallback: _, ...intlOptions } = options;
+                const normalized = inputMode === "fraction" ? n : n / 100;
+                const checkMaxFraction = intlOptions.maximumFractionDigits ?? rules.maximumFractionDigits;
+                const wouldBeZero = Math.abs(normalized) > 0 && parseFloat(Math.abs(normalized).toFixed(checkMaxFraction + 2)) === 0;
+                const sigDigits = Math.max(checkMaxFraction, 4);
+                const resolvedOptions = {
+                    style: "percent",
+                    ...(wouldBeZero
+                        ? { maximumSignificantDigits: sigDigits }
+                        : {
+                            minimumFractionDigits: rules.minimumFractionDigits,
+                            maximumFractionDigits: rules.maximumFractionDigits,
+                        }),
+                    ...intlOptions,
+                };
+                return normalizeICU(getNumberFormatter(locale, resolvedOptions).format(normalized), locale);
+            }, callFallback);
+        },
+        duration(value, options = {}) {
+            const n = toNumber(value);
+            const callFallback = options.fallback ?? defaultDurationFallback;
+            if (n == null)
+                return callFallback;
+            return safeFormat(() => {
+                const absN = Math.abs(n);
+                const fracDigits = options.fractionalDigits ?? 0;
+                const roundedAbsN = fracDigits > 0
+                    ? Math.round(absN * Math.pow(10, fracDigits)) / Math.pow(10, fracDigits)
+                    : Math.round(absN);
+                const totalSec = Math.floor(roundedAbsN);
+                const h = Math.floor(totalSec / 3600);
+                const m = Math.floor((totalSec % 3600) / 60);
+                let s;
+                let sVal;
+                if (fracDigits > 0) {
+                    sVal = roundedAbsN % 60;
+                    s = sVal.toFixed(fracDigits);
+                }
+                else {
+                    sVal = totalSec % 60;
+                    s = String(sVal);
+                }
+                const sign = n < 0 && absN >= 0.0001 ? "-" : "";
+                const userHour = options.labels?.hour;
+                const resolvedHour = typeof userHour === "string"
+                    ? userHour
+                    : { ...DEFAULT_DURATION_LABELS.hour, ...userHour };
+                const userMinute = options.labels?.minute;
+                const resolvedMinute = typeof userMinute === "string"
+                    ? userMinute
+                    : { ...DEFAULT_DURATION_LABELS.minute, ...userMinute };
+                const userSecond = options.labels?.second;
+                const resolvedSecond = typeof userSecond === "string"
+                    ? userSecond
+                    : { ...DEFAULT_DURATION_LABELS.second, ...userSecond };
+                const labels = {
+                    h: options.labels?.h ?? DEFAULT_DURATION_LABELS.h,
+                    m: options.labels?.m ?? DEFAULT_DURATION_LABELS.m,
+                    s: options.labels?.s ?? DEFAULT_DURATION_LABELS.s,
+                    hour: resolvedHour,
+                    minute: resolvedMinute,
+                    second: resolvedSecond,
+                };
+                if (options.format === "verbose") {
+                    const parts = [];
+                    if (h)
+                        parts.push(`${h} ${resolvePluralLabel(h, labels.hour, locale)}`);
+                    if (m)
+                        parts.push(`${m} ${resolvePluralLabel(m, labels.minute, locale)}`);
+                    if (sVal > 0 || fracDigits > 0 || !parts.length) {
+                        parts.push(`${s} ${resolvePluralLabel(sVal, labels.second, locale)}`);
+                    }
+                    return sign + parts.join(", ");
+                }
+                if (h > 0)
+                    return `${sign}${h}${labels.h} ${m}${labels.m}`;
+                if (m > 0)
+                    return `${sign}${m}${labels.m} ${s}${labels.s}`;
+                return `${sign}${s}${labels.s}`;
+            }, callFallback);
+        },
+        date(value, options = {}) {
+            const date = toValidDate(value);
+            const callFallback = options.fallback ?? defaultDateFallback;
+            if (!date)
+                return callFallback;
+            return safeFormat(() => {
+                const { fallback: _, ...rest } = options;
+                const resolvedOptions = rest.dateStyle
+                    ? rest
+                    : { ...rules.dateFormat, ...rest };
+                return normalizeICU(getDateTimeFormatter(locale, resolvedOptions).format(date), locale);
+            }, callFallback);
+        },
+        dateTime(value, options = {}) {
+            const date = toValidDate(value);
+            const callFallback = options.fallback ?? defaultDateTimeFallback;
+            if (!date)
+                return callFallback;
+            return safeFormat(() => {
+                const { fallback: _, ...rest } = options;
+                const resolvedOptions = rest.dateStyle || rest.timeStyle
+                    ? rest
+                    : { ...rules.dateTimeFormat, ...rest };
+                return normalizeICU(getDateTimeFormatter(locale, resolvedOptions).format(date), locale);
+            }, callFallback);
+        },
+        relativeTime(value, optionsOrNow) {
+            const date = toValidDate(value);
+            let opts = {};
+            let now = Date.now();
+            if (typeof optionsOrNow === "number") {
+                now = optionsOrNow;
+            }
+            else if (optionsOrNow && typeof optionsOrNow === "object") {
+                const { now: overrideNow, ...rest } = optionsOrNow;
+                opts = rest;
+                if (overrideNow !== undefined) {
+                    now = overrideNow;
+                }
+            }
+            const callFallback = opts.fallback ?? defaultRelativeTimeFallback;
+            if (!date)
+                return callFallback;
+            return safeFormat(() => {
+                const diffSec = Math.round((date.getTime() - now) / 1000);
+                const abs = Math.abs(diffSec);
+                const resolvedOptions = {
+                    style: opts.style ?? rules.relativeTimeFormat?.style ?? "long",
+                    numeric: opts.numeric ?? rules.relativeTimeFormat?.numeric ?? "auto",
+                };
+                const rtfInstance = getRelativeTimeFormatter(locale, resolvedOptions);
+                let formatted;
+                if (abs < 60) {
+                    formatted = rtfInstance.format(diffSec, "second");
+                }
+                else {
+                    const min = Math.round(diffSec / 60);
+                    if (Math.abs(min) < 60) {
+                        formatted = rtfInstance.format(min, "minute");
+                    }
+                    else {
+                        const hr = Math.round(min / 60);
+                        if (Math.abs(hr) < 24) {
+                            formatted = rtfInstance.format(hr, "hour");
+                        }
+                        else {
+                            const day = Math.round(hr / 24);
+                            if (Math.abs(day) < 7) {
+                                formatted = rtfInstance.format(day, "day");
+                            }
+                            else {
+                                const week = Math.round(day / 7);
+                                if (Math.abs(week) < 4) {
+                                    formatted = rtfInstance.format(week, "week");
+                                }
+                                else {
+                                    const month = Math.round(day / 30);
+                                    if (Math.abs(month) < 12) {
+                                        formatted = rtfInstance.format(month, "month");
+                                    }
+                                    else {
+                                        const year = Math.round(day / 365);
+                                        formatted = rtfInstance.format(year, "year");
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                return normalizeICU(formatted, locale);
+            }, callFallback);
+        },
+    };
+    return Object.freeze(formatters);
+}

package/dist/esm/core/types.d.ts

@@ -0,0 +1,164 @@
+export type NumericInput = number | string | null | undefined;
+export type DateInput = string | number | Date | null | undefined;
+export type NumberOptions = Pick<Intl.NumberFormatOptions, "notation" | "minimumFractionDigits" | "maximumFractionDigits" | "minimumSignificantDigits" | "maximumSignificantDigits" | "minimumIntegerDigits" | "useGrouping" | "signDisplay"> & {
+    /** Override global fallback string for this call */
+    fallback?: string;
+};
+export type CurrencyOptions = NumberOptions & {
+    currency?: string;
+    currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
+    currencySign?: "standard" | "accounting";
+};
+export type PercentageOptions = Pick<Intl.NumberFormatOptions, "minimumFractionDigits" | "maximumFractionDigits" | "minimumSignificantDigits" | "maximumSignificantDigits" | "signDisplay"> & {
+    /** "percent" (default): 50 → "50%". "fraction": 0.5 → "50%" */
+    inputMode?: "percent" | "fraction";
+    /** Override global fallback string for this call */
+    fallback?: string;
+};
+export type DateOptions = Intl.DateTimeFormatOptions & {
+    /** Override global fallback string for this call */
+    fallback?: string;
+};
+export type DateTimeOptions = Intl.DateTimeFormatOptions & {
+    /** Override global fallback string for this call */
+    fallback?: string;
+};
+export type PluralForm = string | {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+};
+export type DurationLabels = {
+    h?: string;
+    m?: string;
+    s?: string;
+    hour?: PluralForm;
+    minute?: PluralForm;
+    second?: PluralForm;
+};
+export type DurationOptions = {
+    /**
+     * "compact" (default): produces compact output like "2m 30s" or "1h 0m".
+     * "verbose": produces spelled-out output like "1 hour, 1 minute, 1 second".
+     */
+    format?: "compact" | "verbose";
+    /** Override global fallback string for this call */
+    fallback?: string;
+    /** Custom localization labels for durations */
+    labels?: DurationLabels;
+    /** Number of decimal places for seconds. Default: 0 */
+    fractionalDigits?: number;
+};
+export type RelativeTimeOptions = {
+    /** The format style. Default: "long" */
+    style?: "long" | "short" | "narrow";
+    /** The numeric values display format. Default: "auto" */
+    numeric?: "always" | "auto";
+    /** Override global fallback string for this call */
+    fallback?: string;
+};
+export type FormatterRules = {
+    /** Numbers >= this use compact notation (1.2K, 3.4M). Default: 10000 */
+    compactThreshold?: number;
+    /** Minimum fraction digits for number, currency, percentage. Default: 0 */
+    minimumFractionDigits?: number;
+    /** Maximum fraction digits for number, currency, percentage. Default: 2 */
+    maximumFractionDigits?: number;
+    /** Default currency display style. Default: "narrowSymbol" */
+    currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
+    /** Default date format options */
+    dateFormat?: Intl.DateTimeFormatOptions;
+    /** Default dateTime format options */
+    dateTimeFormat?: Intl.DateTimeFormatOptions;
+    /** Default number format options — merged with per-call overrides */
+    numberFormat?: NumberOptions;
+    /** Default currency format options — merged with per-call overrides */
+    currencyFormat?: CurrencyOptions;
+    /** Default relativeTime format options */
+    relativeTimeFormat?: RelativeTimeOptions;
+    /** Specialized Default Fallbacks */
+    fallback?: string;
+    numberFallback?: string;
+    currencyFallback?: string;
+    percentageFallback?: string;
+    durationFallback?: string;
+    dateFallback?: string;
+    dateTimeFallback?: string;
+    relativeTimeFallback?: string;
+};
+export type FormatterConfig = {
+    locale?: string;
+    currency?: string;
+    fallback?: string;
+    rules?: FormatterRules;
+};
+export interface Formatter {
+    /**
+     * Format a plain number. Uses compact notation above compactThreshold.
+     * @example
+     * fmt.number(1234567)                              // "1.2M"
+     * fmt.number(1234, { notation: "standard" })       // "1,234"
+     * fmt.number(1.5678, { maximumFractionDigits: 1 }) // "1.6"
+     */
+    number(value: NumericInput, options?: NumberOptions): string;
+    /**
+     * Format a currency value. Uses compact notation above compactThreshold.
+     * @example
+     * fmt.currency(49900)                                // "$49.9K"
+     * fmt.currency(1234, { currency: "EUR" })            // "€1,234"
+     * fmt.currency(1234, { currencyDisplay: "code" })    // "USD 1,234"
+     * fmt.currency(1234, { minimumFractionDigits: 2 })   // "$1,234.00"
+     */
+    currency(value: NumericInput, options?: CurrencyOptions): string;
+    /**
+     * Format a percentage. Input treated as raw percentage by default (50 → "50%").
+     * For values that round to zero, uses significantDigits to preserve precision.
+     * @example
+     * fmt.percentage(12.5)                              // "12.5%"
+     * fmt.percentage(0.001)                             // "0.001%"
+     * fmt.percentage(0.5, { inputMode: "fraction" })    // "50%"
+     * fmt.percentage(12.5, { maximumFractionDigits: 0 }) // "13%"
+     */
+    percentage(value: NumericInput, options?: PercentageOptions): string;
+    /**
+     * Format a duration in seconds. Pure math — no Intl, no ICU risk.
+     * Output is always in English by default, but customizable via labels.
+     * Negative values are supported and produce a leading "-" sign.
+     * @example
+     * fmt.duration(150)                        // "2m 30s"
+     * fmt.duration(3661, { format: "verbose" }) // "1 hour, 1 minute, 1 second"
+     * fmt.duration(-90)                         // "-1m 30s"
+     */
+    duration(value: NumericInput, options?: DurationOptions): string;
+    /**
+     * Format a Date or ISO string as a human-readable date.
+     * @example
+     * fmt.date("2024-01-15")                         // "Jan 15, 2024"
+     * fmt.date("2024-01-15", { dateStyle: "full" })  // "Monday, January 15, 2024"
+     */
+    date(value: DateInput, options?: DateOptions): string;
+    /**
+     * Format a Date or ISO string as a human-readable date and time.
+     * @example
+     * fmt.dateTime("2024-01-15T14:30:00") // "Jan 15, 2024, 2:30 PM"
+     */
+    dateTime(value: DateInput, options?: DateTimeOptions): string;
+    /**
+     * Format a Date or ISO string as relative time.
+     * `now` defaults to `Date.now()` at call time. In Server Components, always pass
+     * a fixed timestamp to prevent SSR/client hydration clock drift.
+     * Supports an options object for custom styling or a backward-compatible timestamp.
+     * @example
+     * const now = Date.now(); // capture once per request
+     * fmt.relativeTime("2024-01-15T10:00:00Z", { now }) // "2 hours ago"
+     * fmt.relativeTime("2024-01-15T10:00:00Z", { now, style: "short" }) // "2 hr. ago"
+     * fmt.relativeTime(new Date())                       // "just now"
+     */
+    relativeTime(value: DateInput, optionsOrNow?: (RelativeTimeOptions & {
+        now?: number;
+    }) | number): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { createFormatter } from "./core/formatter.js";
+export type { Formatter, FormatterConfig } from "./core/types.js";
+export type { NumericInput, DateInput, NumberOptions, CurrencyOptions, PercentageOptions, DurationOptions, DateOptions, DateTimeOptions, FormatterRules, } from "./core/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1 @@
+export { createFormatter } from "./core/formatter.js";

package/dist/esm/testing.d.ts

@@ -0,0 +1,4 @@
+import type { Formatter } from "./core/types.js";
+export declare const mockFormatter: Formatter;
+export type { Formatter, FormatterConfig } from "./core/types.js";
+//# sourceMappingURL=testing.d.ts.map

package/dist/esm/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EASV,MAAM,iBAAiB,CAAC;AAezB,eAAO,MAAM,aAAa,EAAE,SA0C1B,CAAC;AAEH,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}