@automattic/number-formatters 1.0.0-alpha.1 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.0.0] - 2025-04-29
+### Changed
+- Internal updates.
+
+## [1.0.0] - 2025-04-29
+### Changed
+- Build CJS and ESM versions with TypeScript [#43106]
+
+## [1.0.0-alpha.2] - 2025-04-10
+### Changed
+- Adjust relative imports in TypeScript sources to use correct extensions after enabling TypeScript's new `rewriteRelativeImportExtensions` option. The built JS should be unaffected, so this is not a breaking change. [#42990]
+- Convert build to common-js [#42982]
+
+## [1.0.0-alpha.1] - 2025-04-10
+### Changed
+- Internal updates.
+
 ## [1.0.0-alpha.1] - 2025-04-07
 ### Added
 - initial release [#42639]
@@ -20,4 +37,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Initial release
 - Basic number formatting functionality
 
+[1.0.0]: https://github.com/Automattic/number-formatters/compare/1.0.0-alpha.2...1.0.0
+[1.0.0-alpha.2]: https://github.com/Automattic/number-formatters/compare/1.0.0-alpha.1...1.0.0-alpha.2
 [1.0.0-alpha.1]: https://github.com/Automattic/number-formatters/compare/0.1.0...1.0.0-alpha.1

package/dist/cjs/constants.cjs

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_CURRENCY = exports.FALLBACK_LOCALE = void 0;
+exports.FALLBACK_LOCALE = 'en';
+exports.FALLBACK_CURRENCY = 'USD';

package/dist/cjs/create-number-formatters.cjs

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const date_1 = require("@wordpress/date");
+const constants_ts_1 = require("./constants.cjs");
+const index_ts_1 = require("./number-format-currency/index.cjs");
+const number_format_ts_1 = require("./number-format.cjs");
+/**
+ * Creates a NumberFormatters instance that provides number and currency formatting functionality with locale awareness
+ * @return {NumberFormatters} A NumberFormatters instance
+ */
+function createNumberFormatters() {
+    let localeState;
+    let geoLocationState;
+    const setLocale = (locale) => {
+        /**
+         * The `Intl.NumberFormat` constructor fails only when there is a variant, divided by `_`.
+         * These suffixes should be removed. Values like `de-at` or `es-mx`
+         * should all be valid inputs for the constructor.
+         */
+        localeState = locale;
+    };
+    /**
+     * Returns the locale defined on the module instance (through `setLocale`)
+     * or the "fallback locale" if no locale has been set.
+     *
+     * The "fallback locale" is defined as:
+     * - the current WP user locale, if available through `@wordpress/date` settings (assuming this runs in a WordPress context)
+     * - or the browser locale, if available through `window.navigator.language`
+     * - or the fallback locale constant (`FALLBACK_LOCALE`)
+     *
+     * @return {string} The locale to use for formatting.
+     */
+    const getBrowserSafeLocale = () => {
+        const { l10n: { locale: localeFromUserSettings }, } = (0, date_1.getSettings)();
+        return (localeState ??
+            (localeFromUserSettings || global?.window?.navigator?.language) ??
+            constants_ts_1.FALLBACK_LOCALE).split('_')[0];
+    };
+    const setGeoLocation = (geoLocation) => {
+        geoLocationState = geoLocation;
+    };
+    const formatNumber = (number, { decimals = 0, forceLatin = true, numberFormatOptions = {} } = {}) => {
+        try {
+            const formatter = (0, number_format_ts_1.numberFormat)({
+                browserSafeLocale: getBrowserSafeLocale(),
+                decimals,
+                forceLatin,
+                numberFormatOptions,
+            });
+            return formatter.format(number);
+        }
+        catch {
+            return String(number);
+        }
+    };
+    const formatNumberCompact = (number, { decimals = 0, forceLatin = true, numberFormatOptions = {} } = {}) => {
+        try {
+            const formatter = (0, number_format_ts_1.numberFormatCompact)({
+                browserSafeLocale: getBrowserSafeLocale(),
+                decimals,
+                forceLatin,
+                numberFormatOptions,
+            });
+            return formatter.format(number);
+        }
+        catch {
+            return String(number);
+        }
+    };
+    const formatCurrency = (number, currency, { stripZeros = false, isSmallestUnit = false, signForPositive = false, forceLatin = true } = {}) => {
+        return (0, index_ts_1.numberFormatCurrency)({
+            number,
+            currency,
+            browserSafeLocale: getBrowserSafeLocale(),
+            stripZeros,
+            isSmallestUnit,
+            signForPositive,
+            geoLocation: geoLocationState,
+            forceLatin,
+        });
+    };
+    const getCurrencyObject = (number, currency, { stripZeros = false, isSmallestUnit = false, signForPositive = false, forceLatin = true } = {}) => {
+        return (0, index_ts_1.getCurrencyObject)({
+            number,
+            currency,
+            browserSafeLocale: getBrowserSafeLocale(),
+            stripZeros,
+            isSmallestUnit,
+            signForPositive,
+            geoLocation: geoLocationState,
+            forceLatin,
+        });
+    };
+    return {
+        setLocale,
+        setGeoLocation,
+        formatNumber,
+        formatNumberCompact,
+        formatCurrency,
+        getCurrencyObject,
+    };
+}
+exports.default = createNumberFormatters;

package/dist/cjs/get-cached-formatter.cjs

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedFormatter = getCachedFormatter;
+const tslib_1 = require("tslib");
+const debug_1 = tslib_1.__importDefault(require("debug"));
+const constants_ts_1 = require("./constants.cjs");
+const debug = (0, debug_1.default)('number-formatters:get-cached-formatter');
+const formatterCache = new Map();
+/**
+ * Get a cached formatter for a given locale and options.
+ * @param  params                - The parameters for the formatter.
+ * @param  params.locale         - The locale to format the number in.
+ * @param  params.options        - Intl.NumberFormatOptions to pass to the formatter.
+ * @param  params.fallbackLocale - The locale to fallback to if the locale is not supported.
+ * @param  params.retries        - The number of retries to attempt if the formatter is not created.
+ * @return {Intl.NumberFormat} A cached formatter for the given locale and options.
+ */
+function getCachedFormatter({ locale, fallbackLocale = constants_ts_1.FALLBACK_LOCALE, options, retries = 1, }) {
+    const cacheKey = JSON.stringify([locale, options]);
+    try {
+        return (formatterCache.get(cacheKey) ??
+            formatterCache.set(cacheKey, new Intl.NumberFormat(locale, options)).get(cacheKey));
+    }
+    catch (error) {
+        // If the locale is invalid, creating the NumberFormat will throw.
+        debug(`Intl.NumberFormat was called with a non-existent locale "${locale}"; falling back to ${fallbackLocale}`);
+        if (retries) {
+            return getCachedFormatter({
+                locale: fallbackLocale,
+                options,
+                retries: retries - 1,
+            });
+        }
+        throw error;
+    }
+}

package/dist/cjs/index.cjs

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNumberFormatters = exports.getCurrencyObject = exports.formatCurrency = exports.formatNumberCompact = exports.formatNumber = exports.setGeoLocation = exports.setLocale = void 0;
+const tslib_1 = require("tslib");
+const create_number_formatters_ts_1 = tslib_1.__importDefault(require("./create-number-formatters.cjs"));
+exports.createNumberFormatters = create_number_formatters_ts_1.default;
+const defaultFormatter = (0, create_number_formatters_ts_1.default)();
+exports.setLocale = defaultFormatter.setLocale, exports.setGeoLocation = defaultFormatter.setGeoLocation, exports.formatNumber = defaultFormatter.formatNumber, exports.formatNumberCompact = defaultFormatter.formatNumberCompact, exports.formatCurrency = defaultFormatter.formatCurrency, exports.getCurrencyObject = defaultFormatter.getCurrencyObject;
+// We can optionally export the formatters individually if we want to use them in a more granular way.
+// export { numberFormat, numberFormatCompact, numberFormatCurrency, getCurrencyObject };

package/dist/cjs/number-format-currency/currencies.cjs

@@ -0,0 +1,488 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCurrencyOverrides = void 0;
+exports.defaultCurrencyOverrides = {
+    AED: {
+        symbol: 'د.إ.‏',
+    },
+    AFN: {
+        symbol: '؋',
+    },
+    ALL: {
+        symbol: 'Lek',
+    },
+    AMD: {
+        symbol: '֏',
+    },
+    ANG: {
+        symbol: 'ƒ',
+    },
+    AOA: {
+        symbol: 'Kz',
+    },
+    ARS: {
+        symbol: '$',
+    },
+    AUD: {
+        symbol: 'A$',
+    },
+    AWG: {
+        symbol: 'ƒ',
+    },
+    AZN: {
+        symbol: '₼',
+    },
+    BAM: {
+        symbol: 'КМ',
+    },
+    BBD: {
+        symbol: 'Bds$',
+    },
+    BDT: {
+        symbol: '৳',
+    },
+    BGN: {
+        symbol: 'лв.',
+    },
+    BHD: {
+        symbol: 'د.ب.‏',
+    },
+    BIF: {
+        symbol: 'FBu',
+    },
+    BMD: {
+        symbol: '$',
+    },
+    BND: {
+        symbol: '$',
+    },
+    BOB: {
+        symbol: 'Bs',
+    },
+    BRL: {
+        symbol: 'R$',
+    },
+    BSD: {
+        symbol: '$',
+    },
+    BTC: {
+        symbol: 'Ƀ',
+    },
+    BTN: {
+        symbol: 'Nu.',
+    },
+    BWP: {
+        symbol: 'P',
+    },
+    BYR: {
+        symbol: 'р.',
+    },
+    BZD: {
+        symbol: 'BZ$',
+    },
+    CAD: {
+        symbol: 'C$',
+    },
+    CDF: {
+        symbol: 'FC',
+    },
+    CHF: {
+        symbol: 'CHF',
+    },
+    CLP: {
+        symbol: '$',
+    },
+    CNY: {
+        symbol: '¥',
+    },
+    COP: {
+        symbol: '$',
+    },
+    CRC: {
+        symbol: '₡',
+    },
+    CUC: {
+        symbol: 'CUC',
+    },
+    CUP: {
+        symbol: '$MN',
+    },
+    CVE: {
+        symbol: '$',
+    },
+    CZK: {
+        symbol: 'Kč',
+    },
+    DJF: {
+        symbol: 'Fdj',
+    },
+    DKK: {
+        symbol: 'kr.',
+    },
+    DOP: {
+        symbol: 'RD$',
+    },
+    DZD: {
+        symbol: 'د.ج.‏',
+    },
+    EGP: {
+        symbol: 'ج.م.‏',
+    },
+    ERN: {
+        symbol: 'Nfk',
+    },
+    ETB: {
+        symbol: 'ETB',
+    },
+    EUR: {
+        symbol: '€',
+    },
+    FJD: {
+        symbol: 'FJ$',
+    },
+    FKP: {
+        symbol: '£',
+    },
+    GBP: {
+        symbol: '£',
+    },
+    GEL: {
+        symbol: 'Lari',
+    },
+    GHS: {
+        symbol: '₵',
+    },
+    GIP: {
+        symbol: '£',
+    },
+    GMD: {
+        symbol: 'D',
+    },
+    GNF: {
+        symbol: 'FG',
+    },
+    GTQ: {
+        symbol: 'Q',
+    },
+    GYD: {
+        symbol: 'G$',
+    },
+    HKD: {
+        symbol: 'HK$',
+    },
+    HNL: {
+        symbol: 'L.',
+    },
+    HRK: {
+        symbol: 'kn',
+    },
+    HTG: {
+        symbol: 'G',
+    },
+    HUF: {
+        symbol: 'Ft',
+    },
+    IDR: {
+        symbol: 'Rp',
+    },
+    ILS: {
+        symbol: '₪',
+    },
+    INR: {
+        symbol: '₹',
+    },
+    IQD: {
+        symbol: 'د.ع.‏',
+    },
+    IRR: {
+        symbol: '﷼',
+    },
+    ISK: {
+        symbol: 'kr.',
+    },
+    JMD: {
+        symbol: 'J$',
+    },
+    JOD: {
+        symbol: 'د.ا.‏',
+    },
+    JPY: {
+        symbol: '¥',
+    },
+    KES: {
+        symbol: 'S',
+    },
+    KGS: {
+        symbol: 'сом',
+    },
+    KHR: {
+        symbol: '៛',
+    },
+    KMF: {
+        symbol: 'CF',
+    },
+    KPW: {
+        symbol: '₩',
+    },
+    KRW: {
+        symbol: '₩',
+    },
+    KWD: {
+        symbol: 'د.ك.‏',
+    },
+    KYD: {
+        symbol: '$',
+    },
+    KZT: {
+        symbol: '₸',
+    },
+    LAK: {
+        symbol: '₭',
+    },
+    LBP: {
+        symbol: 'ل.ل.‏',
+    },
+    LKR: {
+        symbol: '₨',
+    },
+    LRD: {
+        symbol: 'L$',
+    },
+    LSL: {
+        symbol: 'M',
+    },
+    LYD: {
+        symbol: 'د.ل.‏',
+    },
+    MAD: {
+        symbol: 'د.م.‏',
+    },
+    MDL: {
+        symbol: 'lei',
+    },
+    MGA: {
+        symbol: 'Ar',
+    },
+    MKD: {
+        symbol: 'ден.',
+    },
+    MMK: {
+        symbol: 'K',
+    },
+    MNT: {
+        symbol: '₮',
+    },
+    MOP: {
+        symbol: 'MOP$',
+    },
+    MRO: {
+        symbol: 'UM',
+    },
+    MTL: {
+        symbol: '₤',
+    },
+    MUR: {
+        symbol: '₨',
+    },
+    MVR: {
+        symbol: 'MVR',
+    },
+    MWK: {
+        symbol: 'MK',
+    },
+    MXN: {
+        symbol: 'MX$',
+    },
+    MYR: {
+        symbol: 'RM',
+    },
+    MZN: {
+        symbol: 'MT',
+    },
+    NAD: {
+        symbol: 'N$',
+    },
+    NGN: {
+        symbol: '₦',
+    },
+    NIO: {
+        symbol: 'C$',
+    },
+    NOK: {
+        symbol: 'kr',
+    },
+    NPR: {
+        symbol: '₨',
+    },
+    NZD: {
+        symbol: 'NZ$',
+    },
+    OMR: {
+        symbol: '﷼',
+    },
+    PAB: {
+        symbol: 'B/.',
+    },
+    PEN: {
+        symbol: 'S/.',
+    },
+    PGK: {
+        symbol: 'K',
+    },
+    PHP: {
+        symbol: '₱',
+    },
+    PKR: {
+        symbol: '₨',
+    },
+    PLN: {
+        symbol: 'zł',
+    },
+    PYG: {
+        symbol: '₲',
+    },
+    QAR: {
+        symbol: '﷼',
+    },
+    RON: {
+        symbol: 'lei',
+    },
+    RSD: {
+        symbol: 'Дин.',
+    },
+    RUB: {
+        symbol: '₽',
+    },
+    RWF: {
+        symbol: 'RWF',
+    },
+    SAR: {
+        symbol: '﷼',
+    },
+    SBD: {
+        symbol: 'S$',
+    },
+    SCR: {
+        symbol: '₨',
+    },
+    SDD: {
+        symbol: 'LSd',
+    },
+    SDG: {
+        symbol: '£‏',
+    },
+    SEK: {
+        symbol: 'kr',
+    },
+    SGD: {
+        symbol: 'S$',
+    },
+    SHP: {
+        symbol: '£',
+    },
+    SLL: {
+        symbol: 'Le',
+    },
+    SOS: {
+        symbol: 'S',
+    },
+    SRD: {
+        symbol: '$',
+    },
+    STD: {
+        symbol: 'Db',
+    },
+    SVC: {
+        symbol: '₡',
+    },
+    SYP: {
+        symbol: '£',
+    },
+    SZL: {
+        symbol: 'E',
+    },
+    THB: {
+        symbol: '฿',
+    },
+    TJS: {
+        symbol: 'TJS',
+    },
+    TMT: {
+        symbol: 'm',
+    },
+    TND: {
+        symbol: 'د.ت.‏',
+    },
+    TOP: {
+        symbol: 'T$',
+    },
+    TRY: {
+        symbol: 'TL',
+    },
+    TTD: {
+        symbol: 'TT$',
+    },
+    TVD: {
+        symbol: '$T',
+    },
+    TWD: {
+        symbol: 'NT$',
+    },
+    TZS: {
+        symbol: 'TSh',
+    },
+    UAH: {
+        symbol: '₴',
+    },
+    UGX: {
+        symbol: 'USh',
+    },
+    USD: {
+    // No override. Do what the locale thinks is best.
+    },
+    UYU: {
+        symbol: '$U',
+    },
+    UZS: {
+        symbol: 'сўм',
+    },
+    VEB: {
+        symbol: 'Bs.',
+    },
+    VEF: {
+        symbol: 'Bs. F.',
+    },
+    VND: {
+        symbol: '₫',
+    },
+    VUV: {
+        symbol: 'VT',
+    },
+    WST: {
+        symbol: 'WS$',
+    },
+    XAF: {
+        symbol: 'F',
+    },
+    XCD: {
+        symbol: '$',
+    },
+    XOF: {
+        symbol: 'F',
+    },
+    XPF: {
+        symbol: 'F',
+    },
+    YER: {
+        symbol: '﷼',
+    },
+    ZAR: {
+        symbol: 'R',
+    },
+    ZMW: {
+        symbol: 'ZK',
+    },
+    WON: {
+        symbol: '₩',
+    },
+};

package/dist/cjs/number-format-currency/index.cjs

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrencyObject = exports.numberFormatCurrency = void 0;
+const tslib_1 = require("tslib");
+const debug_1 = tslib_1.__importDefault(require("debug"));
+const constants_ts_1 = require("../constants.cjs");
+const get_cached_formatter_ts_1 = require("../get-cached-formatter.cjs");
+const currencies_ts_1 = require("./currencies.cjs");
+const debug = (0, debug_1.default)('number-formatters:number-format-currency');
+/**
+ * Retrieves the currency override for a given currency.
+ * If the currency is USD and the user is not in the US, it will return `US$`.
+ * @param  currency    - The currency to get the override for.
+ * @param  geoLocation - The geo location of the user.
+ * @return {CurrencyOverride | undefined} The currency override.
+ */
+function getCurrencyOverride(currency, geoLocation) {
+    if (currency === 'USD' && geoLocation && geoLocation !== '' && geoLocation !== 'US') {
+        return { symbol: 'US$' };
+    }
+    return currencies_ts_1.defaultCurrencyOverrides[currency];
+}
+/**
+ * Returns a valid currency code based on a shortlist of currency codes.
+ * Only currencies from the shortlist are allowed. Everything else will fall back to `FALLBACK_CURRENCY`.
+ * @param  currency    - The currency to get the valid currency for.
+ * @param  geoLocation - The geo location of the user.
+ * @return {string} The valid currency.
+ */
+function getValidCurrency(currency, geoLocation) {
+    if (!getCurrencyOverride(currency, geoLocation)) {
+        debug(`getValidCurrency was called with a non-existent currency "${currency}"; falling back to ${constants_ts_1.FALLBACK_CURRENCY}`);
+        return constants_ts_1.FALLBACK_CURRENCY;
+    }
+    return currency;
+}
+/**
+ * Returns a currency formatter for a given currency.
+ * @param  params                   - The parameters for the currency formatter.
+ * @param  params.number            - The number to format.
+ * @param  params.currency          - The currency to format.
+ * @param  params.browserSafeLocale - The browser safe locale.
+ * @param  params.forceLatin        - Whether to force the latin locale.
+ * @param  params.stripZeros        - Whether to strip zeros.
+ * @param  params.signForPositive   - Whether to show the sign for positive numbers.
+ * @return {Intl.NumberFormat} The currency formatter.
+ */
+function getCurrencyFormatter({ number, currency, browserSafeLocale, forceLatin = true, stripZeros, signForPositive, }) {
+    /**
+     * `numberingSystem` is an option to `Intl.NumberFormat` and is available
+     * in all major browsers according to
+     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+     * but is not part of the TypeScript types in `es2020`:
+     *
+     * https://github.com/microsoft/TypeScript/blob/cfd472f7aa5a2010a3115263bf457b30c5b489f3/src/lib/es2020.intl.d.ts#L272
+     *
+     * However, it is part of the TypeScript types in `es5`:
+     *
+     * https://github.com/microsoft/TypeScript/blob/cfd472f7aa5a2010a3115263bf457b30c5b489f3/src/lib/es5.d.ts#L4310
+     *
+     * Apparently calypso uses `es2020` so we cannot use that option here right
+     * now. Instead, we will use the unicode extension to the locale, documented
+     * here:
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numberingSystem#adding_a_numbering_system_via_the_locale_string
+     */
+    const locale = `${browserSafeLocale}${forceLatin ? '-u-nu-latn' : ''}`;
+    const numberFormatOptions = {
+        style: 'currency',
+        currency,
+        ...(stripZeros &&
+            Number.isInteger(number) && {
+            /**
+             * There's an option called `trailingZeroDisplay` but it does not yet work
+             * in FF so we have to strip zeros manually.
+             */
+            maximumFractionDigits: 0,
+            minimumFractionDigits: 0,
+        }),
+        ...(signForPositive && { signDisplay: 'exceptZero' }),
+    };
+    return (0, get_cached_formatter_ts_1.getCachedFormatter)({
+        locale,
+        options: numberFormatOptions,
+    });
+}
+/**
+ * Returns the precision for a given locale and currency.
+ * @param  browserSafeLocale - The browser safe locale.
+ * @param  currency          - The currency to get the precision for.
+ * @param  forceLatin        - Whether to force the latin locale.
+ * @return {number | undefined} The precision.
+ */
+function getPrecisionForLocaleAndCurrency(browserSafeLocale, currency, forceLatin) {
+    const formatter = getCurrencyFormatter({ number: 0, currency, browserSafeLocale, forceLatin });
+    /**
+     * For regular numbers, the default is 3 if neither `minimumFractionDigits` or `maximumFractionDigits` are set,
+     * otherwise the greatest betweem `minimumFractionDigits` and 3.
+     *
+     * For currencies, the default is dependent on the currency.
+     *
+     * This may also result in undefined, for several reasons:
+     * see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#significantdigitsfractiondigits_default_values
+     */
+    return formatter.resolvedOptions().maximumFractionDigits;
+}
+/**
+ * Scales a number to a specified precision and rounds it to that precision.
+ * It ensures that all currency values are consistently rounded to the desired precision,
+ * avoiding issues with floating-point arithmetic.
+ * @param  number            - The number to scale.
+ * @param  currencyPrecision - The precision to scale the number to.
+ * @return {number} The scaled number.
+ */
+function scaleNumberForPrecision(number, currencyPrecision) {
+    const scale = Math.pow(10, currencyPrecision);
+    return Math.round(number * scale) / scale;
+}
+/**
+ * Prepares a number for formatting.
+ * @param  number            - The number to prepare.
+ * @param  currencyPrecision - The precision to prepare the number for.
+ * @param  isSmallestUnit    - Whether the number is the smallest unit of a currency.
+ * @return {number} The prepared number.
+ */
+function prepareNumberForFormatting(number, 
+// currencyPrecision here must be the precision of the currency, regardless
+// of what precision is requested for display!
+currencyPrecision, isSmallestUnit) {
+    if (isNaN(number)) {
+        debug('formatCurrency was called with NaN');
+        return 0;
+    }
+    if (isSmallestUnit) {
+        if (!Number.isInteger(number)) {
+            debug('formatCurrency was called with isSmallestUnit and a float which will be rounded', number);
+        }
+        const smallestUnitDivisor = 10 ** currencyPrecision;
+        return scaleNumberForPrecision(Math.round(number) / smallestUnitDivisor, currencyPrecision);
+    }
+    return scaleNumberForPrecision(number, currencyPrecision);
+}
+/**
+ * Formats money with a given currency code.
+ *
+ * The currency will define the properties to use for this formatting, but
+ * those properties can be overridden using the options. Be careful when doing
+ * this.
+ *
+ * For currencies that include decimals, this will always return the amount
+ * with decimals included, even if those decimals are zeros. To exclude the
+ * zeros, use the `stripZeros` option. For example, the function will normally
+ * format `10.00` in `USD` as `$10.00` but when this option is true, it will
+ * return `$10` instead.
+ *
+ * Since rounding errors are common in floating point math, sometimes a price
+ * is provided as an integer in the smallest unit of a currency (eg: cents in
+ * USD or yen in JPY). Set the `isSmallestUnit` to change the function to
+ * operate on integer numbers instead. If this option is not set or false, the
+ * function will format the amount `1025` in `USD` as `$1,025.00`, but when the
+ * option is true, it will return `$10.25` instead.
+ *
+ * If the number is NaN, it will be treated as 0.
+ *
+ * If the currency code is not known, this will assume a default currency
+ * similar to USD.
+ *
+ * If `isSmallestUnit` is set and the number is not an integer, it will be
+ * rounded to an integer.
+ *
+ * @param  params                   - The parameters for the currency formatter.
+ * @param  params.number            - The number to format.
+ * @param  params.browserSafeLocale - The browser safe locale.
+ * @param  params.currency          - The currency to format.
+ * @param  params.stripZeros        - Whether to strip zeros.
+ * @param  params.isSmallestUnit    - Whether the number is the smallest unit of a currency.
+ * @param  params.signForPositive   - Whether to show the sign for positive numbers.
+ * @param  params.geoLocation       - The geo location of the user.
+ * @param  params.forceLatin        - Whether to force the latin locale.
+ * @return {string} A formatted string.
+ */
+const numberFormatCurrency = ({ number, browserSafeLocale, currency, stripZeros, isSmallestUnit, signForPositive, geoLocation, forceLatin, }) => {
+    const validCurrency = getValidCurrency(currency, geoLocation);
+    const currencyOverride = getCurrencyOverride(validCurrency, geoLocation);
+    const currencyPrecision = getPrecisionForLocaleAndCurrency(browserSafeLocale, validCurrency, forceLatin);
+    if (isSmallestUnit && typeof currencyPrecision === 'undefined') {
+        throw new Error(`Could not determine currency precision for ${validCurrency} in ${browserSafeLocale}`);
+    }
+    const numberAsFloat = prepareNumberForFormatting(number, currencyPrecision ?? 0, isSmallestUnit);
+    const formatter = getCurrencyFormatter({
+        number: numberAsFloat,
+        currency: validCurrency,
+        browserSafeLocale,
+        forceLatin,
+        stripZeros,
+        signForPositive,
+    });
+    const parts = formatter.formatToParts(numberAsFloat);
+    return parts.reduce((formatted, part) => {
+        switch (part.type) {
+            case 'currency':
+                if (currencyOverride?.symbol) {
+                    return formatted + currencyOverride.symbol;
+                }
+                return formatted + part.value;
+            default:
+                return formatted + part.value;
+        }
+    }, '');
+};
+exports.numberFormatCurrency = numberFormatCurrency;
+/**
+ * Returns a formatted price object which can be used to manually render a
+ * formatted currency (eg: if you wanted to render the currency symbol in a
+ * different font size).
+ *
+ * The currency will define the properties to use for this formatting, but
+ * those properties can be overridden using the options. Be careful when doing
+ * this.
+ *
+ * For currencies that include decimals, this will always return the amount
+ * with decimals included, even if those decimals are zeros. To exclude the
+ * zeros, use the `stripZeros` option. For example, the function will normally
+ * format `10.00` in `USD` as `$10.00` but when this option is true, it will
+ * return `$10` instead.
+ *
+ * Since rounding errors are common in floating point math, sometimes a price
+ * is provided as an integer in the smallest unit of a currency (eg: cents in
+ * USD or yen in JPY). Set the `isSmallestUnit` to change the function to
+ * operate on integer numbers instead. If this option is not set or false, the
+ * function will format the amount `1025` in `USD` as `$1,025.00`, but when the
+ * option is true, it will return `$10.25` instead.
+ *
+ * Note that the `integer` return value of this function is not a number, but a
+ * locale-formatted string which may include symbols like spaces, commas, or
+ * periods as group separators. Similarly, the `fraction` property is a string
+ * that contains the decimal separator.
+ *
+ * If the number is NaN, it will be treated as 0.
+ *
+ * If the currency code is not known, this will assume a default currency
+ * similar to USD.
+ *
+ * If `isSmallestUnit` is set and the number is not an integer, it will be
+ * rounded to an integer.
+ *
+ * @param  params                   - The parameters for the currency formatter.
+ * @param  params.number            - The number to format.
+ * @param  params.browserSafeLocale - The browser safe locale.
+ * @param  params.currency          - The currency to format.
+ * @param  params.stripZeros        - Whether to strip zeros.
+ * @param  params.isSmallestUnit    - Whether the number is the smallest unit of a currency.
+ * @param  params.signForPositive   - Whether to show the sign for positive numbers.
+ * @param  params.geoLocation       - The geo location of the user.
+ * @param  params.forceLatin        - Whether to force the latin locale.
+ * @return {CurrencyObject} A formatted string e.g. { symbol:'$', integer: '$99', fraction: '.99', sign: '-' }
+ */
+const getCurrencyObject = ({ number, browserSafeLocale, currency, stripZeros, isSmallestUnit, signForPositive, geoLocation, forceLatin, }) => {
+    const validCurrency = getValidCurrency(currency, geoLocation);
+    const currencyOverride = getCurrencyOverride(validCurrency, geoLocation);
+    const currencyPrecision = getPrecisionForLocaleAndCurrency(browserSafeLocale, validCurrency, forceLatin);
+    const numberAsFloat = prepareNumberForFormatting(number, currencyPrecision ?? 0, isSmallestUnit);
+    const formatter = getCurrencyFormatter({
+        number: numberAsFloat,
+        currency: validCurrency,
+        browserSafeLocale,
+        forceLatin,
+        stripZeros,
+        signForPositive,
+    });
+    const parts = formatter.formatToParts(numberAsFloat);
+    let sign = '';
+    let symbol = '$';
+    let symbolPosition = 'before';
+    let hasAmountBeenSet = false;
+    let hasDecimalBeenSet = false;
+    let integer = '';
+    let fraction = '';
+    parts.forEach(part => {
+        switch (part.type) {
+            case 'currency':
+                symbol = currencyOverride?.symbol ?? part.value;
+                if (hasAmountBeenSet) {
+                    symbolPosition = 'after';
+                }
+                return;
+            case 'group':
+                integer += part.value;
+                hasAmountBeenSet = true;
+                return;
+            case 'decimal':
+                fraction += part.value;
+                hasAmountBeenSet = true;
+                hasDecimalBeenSet = true;
+                return;
+            case 'integer':
+                integer += part.value;
+                hasAmountBeenSet = true;
+                return;
+            case 'fraction':
+                fraction += part.value;
+                hasAmountBeenSet = true;
+                hasDecimalBeenSet = true;
+                return;
+            case 'minusSign':
+                sign = '-';
+                return;
+            case 'plusSign':
+                sign = '+';
+        }
+    });
+    const hasNonZeroFraction = !Number.isInteger(numberAsFloat) && hasDecimalBeenSet;
+    return {
+        sign,
+        symbol,
+        symbolPosition,
+        integer,
+        fraction,
+        hasNonZeroFraction,
+    };
+};
+exports.getCurrencyObject = getCurrencyObject;

package/dist/cjs/number-format.cjs

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberFormatCompact = exports.numberFormat = void 0;
+const get_cached_formatter_ts_1 = require("./get-cached-formatter.cjs");
+/**
+ * Formats numbers using locale settings and/or passed options.
+ * @param  params                     - The parameters for the number formatter.
+ * @param  params.browserSafeLocale   - The browser safe locale.
+ * @param  params.decimals            - The number of decimal places to use.
+ * @param  params.forceLatin          - Whether to force the latin locale.
+ * @param  params.numberFormatOptions - The options for the number formatter.
+ * @return {Intl.NumberFormat} The number formatter.
+ */
+const numberFormat = ({ browserSafeLocale, decimals = 0, forceLatin = true, numberFormatOptions = {}, }) => {
+    /**
+     * `numberingSystem` is an option to `Intl.NumberFormat` and is available
+     * in all major browsers according to
+     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+     * but is not part of the TypeScript types in `es2020`:
+     *
+     * https://github.com/microsoft/TypeScript/blob/cfd472f7aa5a2010a3115263bf457b30c5b489f3/src/lib/es2020.intl.d.ts#L272
+     *
+     * However, it is part of the TypeScript types in `es5`:
+     *
+     * https://github.com/microsoft/TypeScript/blob/cfd472f7aa5a2010a3115263bf457b30c5b489f3/src/lib/es5.d.ts#L4310
+     *
+     * Apparently calypso uses `es2020` so we cannot use that option here right
+     * now. Instead, we will use the unicode extension to the locale, documented
+     * here:
+     *
+     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numberingSystem#adding_a_numbering_system_via_the_locale_string
+     */
+    const locale = `${browserSafeLocale}${forceLatin ? '-u-nu-latn' : ''}`;
+    const options = {
+        minimumFractionDigits: decimals, // minimumFractionDigits default is 0
+        maximumFractionDigits: decimals, // maximumFractionDigits default is the greater between minimumFractionDigits and 3
+        ...numberFormatOptions,
+    };
+    return (0, get_cached_formatter_ts_1.getCachedFormatter)({ locale, options });
+};
+exports.numberFormat = numberFormat;
+/**
+ * Convenience method for formatting numbers in a compact notation e.g. 1K, 1M, etc.
+ * Basically sets `notation: 'compact'` and `maximumFractionDigits: 1` in the options.
+ * Everything is overridable by passing the `numberFormatOptions` option.
+ * If you want more digits, pass `maximumFractionDigits: 2`.
+ * @param  params                     - The parameters for the number formatter.
+ * @param  params.numberFormatOptions - The options for the number formatter.
+ * @return {Intl.NumberFormat} The number formatter.
+ */
+const numberFormatCompact = ({ numberFormatOptions = {}, ...params }) => numberFormat({
+    ...params,
+    numberFormatOptions: {
+        notation: 'compact',
+        maximumFractionDigits: 1,
+        ...numberFormatOptions,
+    },
+});
+exports.numberFormatCompact = numberFormatCompact;

package/dist/cjs/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/{create-number-formatters.js → esm/create-number-formatters.js}

@@ -1,7 +1,7 @@
 import { getSettings } from '@wordpress/date';
-import { FALLBACK_LOCALE } from './constants.js';
-import { numberFormatCurrency, getCurrencyObject as getCurrencyObjectFromCurrencyFormatter, } from './number-format-currency/index.js';
-import { numberFormat, numberFormatCompact } from './number-format.js';
+import { FALLBACK_LOCALE } from "./constants.js";
+import { numberFormatCurrency, getCurrencyObject as getCurrencyObjectFromCurrencyFormatter, } from "./number-format-currency/index.js";
+import { numberFormat, numberFormatCompact } from "./number-format.js";
 /**
  * Creates a NumberFormatters instance that provides number and currency formatting functionality with locale awareness
  * @return {NumberFormatters} A NumberFormatters instance

package/dist/{get-cached-formatter.js → esm/get-cached-formatter.js}

@@ -1,5 +1,5 @@
 import debugFactory from 'debug';
-import { FALLBACK_LOCALE } from './constants.js';
+import { FALLBACK_LOCALE } from "./constants.js";
 const debug = debugFactory('number-formatters:get-cached-formatter');
 const formatterCache = new Map();
 /**

package/dist/{index.js → esm/index.js}

@@ -1,7 +1,6 @@
-import createNumberFormatters from './create-number-formatters.js';
+import createNumberFormatters from "./create-number-formatters.js";
 const defaultFormatter = createNumberFormatters();
 export const { setLocale, setGeoLocation, formatNumber, formatNumberCompact, formatCurrency, getCurrencyObject, } = defaultFormatter;
 export { createNumberFormatters };
-export * from './types.js';
 // We can optionally export the formatters individually if we want to use them in a more granular way.
 // export { numberFormat, numberFormatCompact, numberFormatCurrency, getCurrencyObject };

package/dist/{number-format-currency → esm/number-format-currency}/index.js

@@ -1,7 +1,7 @@
 import debugFactory from 'debug';
-import { FALLBACK_CURRENCY } from '../constants.js';
-import { getCachedFormatter } from '../get-cached-formatter.js';
-import { defaultCurrencyOverrides } from './currencies.js';
+import { FALLBACK_CURRENCY } from "../constants.js";
+import { getCachedFormatter } from "../get-cached-formatter.js";
+import { defaultCurrencyOverrides } from "./currencies.js";
 const debug = debugFactory('number-formatters:number-format-currency');
 /**
  * Retrieves the currency override for a given currency.

package/dist/{number-format.js → esm/number-format.js}

@@ -1,4 +1,4 @@
-import { getCachedFormatter } from './get-cached-formatter.js';
+import { getCachedFormatter } from "./get-cached-formatter.js";
 /**
  * Formats numbers using locale settings and/or passed options.
  * @param  params                     - The parameters for the number formatter.

package/dist/{create-number-formatters.d.ts → types/create-number-formatters.d.ts}

@@ -1,4 +1,4 @@
-import type { FormatCurrency, FormatNumber, GetCurrencyObject } from './types.js';
+import type { FormatCurrency, FormatNumber, GetCurrencyObject } from './types.ts';
 export interface NumberFormatters {
     /**
      * Sets the locale for number formatting

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+import createNumberFormatters from './create-number-formatters.ts';
+export declare const setLocale: (locale: string) => void, setGeoLocation: (geoLocation: string) => void, formatNumber: import("./types.ts").FormatNumber, formatNumberCompact: import("./types.ts").FormatNumber, formatCurrency: import("./types.ts").FormatCurrency, getCurrencyObject: import("./types.ts").GetCurrencyObject;
+export { createNumberFormatters };
+export type * from './types.ts';

package/dist/{number-format-currency → types/number-format-currency}/currencies.d.ts

@@ -1,2 +1,2 @@
-import type { CurrencyOverride } from '../types.js';
+import type { CurrencyOverride } from '../types.ts';
 export declare const defaultCurrencyOverrides: Record<string, CurrencyOverride>;

package/dist/{number-format-currency → types/number-format-currency}/index.d.ts

@@ -1,4 +1,4 @@
-import type { CurrencyObject, NumberFormatCurrencyParams } from '../types.js';
+import type { CurrencyObject, NumberFormatCurrencyParams } from '../types.ts';
 /**
  * Formats money with a given currency code.
  *

package/dist/{number-format.d.ts → types/number-format.d.ts}

@@ -1,4 +1,4 @@
-import type { NumberFormatParams } from './types.js';
+import type { NumberFormatParams } from './types.ts';
 /**
  * Formats numbers using locale settings and/or passed options.
  * @param  params                     - The parameters for the number formatter.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/number-formatters",
-	"version": "1.0.0-alpha.1",
+	"version": "1.0.0",
 	"description": "Number formatting utilities",
 	"author": "Automattic",
 	"license": "GPL-2.0-or-later",
@@ -14,30 +14,35 @@
 		"url": "https://github.com/Automattic/jetpack/labels/[JS Package] Number Formatters"
 	},
 	"dependencies": {
-		"@babel/runtime": "^7",
-		"@wordpress/date": "5.19.0",
-		"debug": "4.4.0"
+		"@wordpress/date": "^5.19.0",
+		"debug": "^4.4.0",
+		"tslib": "^2.5.0"
 	},
 	"devDependencies": {
 		"@babel/core": "7.26.10",
 		"@babel/preset-react": "7.26.3",
 		"@jest/globals": "29.4.3",
+		"@knighted/duel": "2.1.4",
 		"@types/jest": "29.5.14",
 		"jest": "29.7.0",
 		"jest-environment-jsdom": "29.7.0",
 		"typescript": "5.8.2"
 	},
 	"type": "module",
+	"main": "./dist/cjs/index.cjs",
+	"module": "./dist/esm/index.js",
+	"types": "./dist/types/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/index.d.ts",
-			"default": "./dist/index.js"
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/esm/index.js",
+			"require": "./dist/cjs/index.cjs"
 		}
 	},
 	"scripts": {
-		"build": "pnpm run clean && pnpm run compile-ts",
-		"clean": "rm -rf dist/",
-		"compile-ts": "tsc --pretty",
+		"build": "pnpm run clean && pnpm run build:ts",
+		"build:ts": "duel --dirs",
+		"clean": "rm -rf dist",
 		"test": "NODE_OPTIONS=--experimental-vm-modules jest",
 		"test-coverage": "pnpm run test --coverage",
 		"typecheck": "tsc --noEmit"

package/src/create-number-formatters.ts

@@ -1,11 +1,11 @@
 import { getSettings } from '@wordpress/date';
-import { FALLBACK_LOCALE } from './constants.js';
+import { FALLBACK_LOCALE } from './constants.ts';
 import {
 	numberFormatCurrency,
 	getCurrencyObject as getCurrencyObjectFromCurrencyFormatter,
-} from './number-format-currency/index.js';
-import { numberFormat, numberFormatCompact } from './number-format.js';
-import type { CurrencyObject, FormatCurrency, FormatNumber, GetCurrencyObject } from './types.js';
+} from './number-format-currency/index.ts';
+import { numberFormat, numberFormatCompact } from './number-format.ts';
+import type { CurrencyObject, FormatCurrency, FormatNumber, GetCurrencyObject } from './types.ts';
 
 // Since global is used inside createNumberFormatters, we need to declare it for TS
 declare const global: typeof globalThis;

package/src/get-cached-formatter.ts

@@ -1,5 +1,5 @@
 import debugFactory from 'debug';
-import { FALLBACK_LOCALE } from './constants.js';
+import { FALLBACK_LOCALE } from './constants.ts';
 
 const debug = debugFactory( 'number-formatters:get-cached-formatter' );
 

package/src/index.ts

@@ -1,4 +1,4 @@
-import createNumberFormatters from './create-number-formatters.js';
+import createNumberFormatters from './create-number-formatters.ts';
 
 const defaultFormatter = createNumberFormatters();
 
@@ -13,7 +13,7 @@ export const {
 
 export { createNumberFormatters };
 
-export * from './types.js';
+export type * from './types.ts';
 
 // We can optionally export the formatters individually if we want to use them in a more granular way.
 // export { numberFormat, numberFormatCompact, numberFormatCurrency, getCurrencyObject };

package/src/number-format-currency/currencies.ts

@@ -1,4 +1,4 @@
-import type { CurrencyOverride } from '../types.js';
+import type { CurrencyOverride } from '../types.ts';
 
 export const defaultCurrencyOverrides: Record< string, CurrencyOverride > = {
 	AED: {

package/src/number-format-currency/index.ts

@@ -1,8 +1,8 @@
 import debugFactory from 'debug';
-import { FALLBACK_CURRENCY } from '../constants.js';
-import { getCachedFormatter } from '../get-cached-formatter.js';
-import { defaultCurrencyOverrides } from './currencies.js';
-import type { CurrencyOverride, CurrencyObject, NumberFormatCurrencyParams } from '../types.js';
+import { FALLBACK_CURRENCY } from '../constants.ts';
+import { getCachedFormatter } from '../get-cached-formatter.ts';
+import { defaultCurrencyOverrides } from './currencies.ts';
+import type { CurrencyOverride, CurrencyObject, NumberFormatCurrencyParams } from '../types.ts';
 
 const debug = debugFactory( 'number-formatters:number-format-currency' );
 

package/src/number-format.ts

@@ -1,5 +1,5 @@
-import { getCachedFormatter } from './get-cached-formatter.js';
-import type { NumberFormatParams } from './types.js';
+import { getCachedFormatter } from './get-cached-formatter.ts';
+import type { NumberFormatParams } from './types.ts';
 
 /**
  * Formats numbers using locale settings and/or passed options.

package/dist/index.d.ts

@@ -1,4 +0,0 @@
-import createNumberFormatters from './create-number-formatters.js';
-export declare const setLocale: (locale: string) => void, setGeoLocation: (geoLocation: string) => void, formatNumber: import("./types.js").FormatNumber, formatNumberCompact: import("./types.js").FormatNumber, formatCurrency: import("./types.js").FormatCurrency, getCurrencyObject: import("./types.js").GetCurrencyObject;
-export { createNumberFormatters };
-export * from './types.js';