@automattic/number-formatters 1.0.0-alpha.1

package/dist/create-number-formatters.d.ts

@@ -0,0 +1,124 @@
+import type { FormatCurrency, FormatNumber, GetCurrencyObject } from './types.js';
+export interface NumberFormatters {
+    /**
+     * Sets the locale for number formatting
+     * @param locale - The locale to use for formatting
+     */
+    setLocale(locale: string): void;
+    /**
+     * Sets the user's geo location for currency formatting if available
+     * @param geoLocation - The geo location to use for formatting
+     */
+    setGeoLocation(geoLocation: string): void;
+    /**
+     * Formats numbers using locale settings and/or passed options.
+     * @param  number                     - The number to format.
+     * @param  params                     - The parameters for the formatter.
+     * @param  params.decimals            - The number of decimal places to display.
+     * @param  params.forceLatin          - Whether to force the Latin script.
+     * @param  params.numberFormatOptions - Additional options to pass to the formatter.
+     * @return {string} Formatted number as string, or original number as string if formatting fails.
+     */
+    formatNumber: FormatNumber;
+    /**
+     * Formats numbers using locale settings and/or passed options, with a compact notation.
+     * 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  number                     - The number to format.
+     * @param  params                     - The parameters for the formatter.
+     * @param  params.decimals            - The number of decimal places to display.
+     * @param  params.forceLatin          - Whether to force the Latin script.
+     * @param  params.numberFormatOptions - Additional options to pass to the formatter.
+     * @return {string} Formatted number as string, or original number as string if formatting fails.
+     */
+    formatNumberCompact: FormatNumber;
+    /**
+     * 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  number                  - The number to format.
+     * @param  currency                - The currency to format.
+     * @param  options                 - The options for the formatter.
+     * @param  options.stripZeros      - Whether to strip zeros.
+     * @param  options.isSmallestUnit  - Whether the number is the smallest unit of a currency.
+     * @param  options.signForPositive - Whether to show the sign for positive numbers.
+     * @param  options.forceLatin      - Whether to force the latin locale.
+     * @return {string} A formatted string.
+     */
+    formatCurrency: FormatCurrency;
+    /**
+     * 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  number                  - The number to format.
+     * @param  currency                - The currency to format.
+     * @param  options                 - The options for the formatter.
+     * @param  options.stripZeros      - Whether to strip zeros.
+     * @param  options.isSmallestUnit  - Whether the number is the smallest unit of a currency.
+     * @param  options.signForPositive - Whether to show the sign for positive numbers.
+     * @param  options.forceLatin      - Whether to force the latin locale.
+     * @return {CurrencyObject} A formatted price object.
+     */
+    getCurrencyObject: GetCurrencyObject;
+}
+/**
+ * Creates a NumberFormatters instance that provides number and currency formatting functionality with locale awareness
+ * @return {NumberFormatters} A NumberFormatters instance
+ */
+declare function createNumberFormatters(): NumberFormatters;
+export default createNumberFormatters;

package/dist/create-number-formatters.js

@@ -0,0 +1,101 @@
+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';
+/**
+ * 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 }, } = getSettings();
+        return (localeState ??
+            (localeFromUserSettings || global?.window?.navigator?.language) ??
+            FALLBACK_LOCALE).split('_')[0];
+    };
+    const setGeoLocation = (geoLocation) => {
+        geoLocationState = geoLocation;
+    };
+    const formatNumber = (number, { decimals = 0, forceLatin = true, numberFormatOptions = {} } = {}) => {
+        try {
+            const formatter = 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 = 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 numberFormatCurrency({
+            number,
+            currency,
+            browserSafeLocale: getBrowserSafeLocale(),
+            stripZeros,
+            isSmallestUnit,
+            signForPositive,
+            geoLocation: geoLocationState,
+            forceLatin,
+        });
+    };
+    const getCurrencyObject = (number, currency, { stripZeros = false, isSmallestUnit = false, signForPositive = false, forceLatin = true } = {}) => {
+        return getCurrencyObjectFromCurrencyFormatter({
+            number,
+            currency,
+            browserSafeLocale: getBrowserSafeLocale(),
+            stripZeros,
+            isSmallestUnit,
+            signForPositive,
+            geoLocation: geoLocationState,
+            forceLatin,
+        });
+    };
+    return {
+        setLocale,
+        setGeoLocation,
+        formatNumber,
+        formatNumberCompact,
+        formatCurrency,
+        getCurrencyObject,
+    };
+}
+export default createNumberFormatters;

package/dist/get-cached-formatter.d.ts

@@ -0,0 +1,17 @@
+interface Params {
+    locale: string;
+    options?: Intl.NumberFormatOptions;
+    fallbackLocale?: string;
+    retries?: number;
+}
+/**
+ * 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.
+ */
+export declare function getCachedFormatter({ locale, fallbackLocale, options, retries, }: Params): Intl.NumberFormat;
+export {};

package/dist/get-cached-formatter.js

@@ -0,0 +1,32 @@
+import debugFactory from 'debug';
+import { FALLBACK_LOCALE } from './constants.js';
+const debug = debugFactory('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.
+ */
+export function getCachedFormatter({ locale, fallbackLocale = 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/index.d.ts

@@ -0,0 +1,4 @@
+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';

package/dist/index.js

@@ -0,0 +1,7 @@
+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/currencies.d.ts

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