@automattic/number-formatters 1.0.0-alpha.1

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

@@ -0,0 +1,317 @@
+import debugFactory from 'debug';
+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.
+ * 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 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 ${FALLBACK_CURRENCY}`);
+        return 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 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;
+        }
+    }, '');
+};
+/**
+ * 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,
+    };
+};
+export { numberFormatCurrency, getCurrencyObject };

package/dist/number-format.d.ts

@@ -0,0 +1,22 @@
+import type { NumberFormatParams } from './types.js';
+/**
+ * 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.
+ */
+declare const numberFormat: ({ browserSafeLocale, decimals, forceLatin, numberFormatOptions, }: NumberFormatParams) => Intl.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.
+ */
+declare const numberFormatCompact: typeof numberFormat;
+export { numberFormat, numberFormatCompact };

package/dist/number-format.js

@@ -0,0 +1,55 @@
+import { getCachedFormatter } from './get-cached-formatter.js';
+/**
+ * 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 getCachedFormatter({ locale, options });
+};
+/**
+ * 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,
+    },
+});
+export { numberFormat, numberFormatCompact };

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+export interface NumberFormatParams {
+    /**
+     * Browser-safe locale string that works with Intl.NumberFormat e.g. 'en-US' (not 'en_US').
+     */
+    browserSafeLocale: string;
+    /**
+     * Number of decimal places to use.
+     * This is just convenience over setting `minimumFractionDigits`, `maximumFractionDigits` to the same value.
+     * ( default = 0 )
+     */
+    decimals?: number;
+    /**
+     * Whether to use latin numbers by default ( default = true ).
+     */
+    forceLatin?: boolean;
+    /**
+     * `Intl.NumberFormat` options to pass through.
+     * `minimumFractionDigits` & `maximumFractionDigits` will override `decimals` if set.
+     */
+    numberFormatOptions?: Intl.NumberFormatOptions;
+}
+export interface CurrencyOverride {
+    symbol?: string;
+}
+export interface NumberFormatCurrencyParams {
+    /**
+     * Number to format.
+     */
+    number: number;
+    /**
+     * Browser-safe locale string that works with Intl.NumberFormat e.g. 'en-US' (not 'en_US').
+     */
+    browserSafeLocale: string;
+    /**
+     * Currency code.
+     */
+    currency: string;
+    /**
+     * Whether to use latin numbers by default ( default = true ).
+     */
+    forceLatin?: boolean;
+    /**
+     * The user's geo location if available.
+     */
+    geoLocation?: string;
+    /**
+     * Forces any decimal zeros to be hidden if set.
+     *
+     * 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.
+     *
+     * For currencies without decimals (eg: JPY), this has no effect.
+     */
+    stripZeros?: boolean;
+    /**
+     * Changes function to treat number as an integer in the currency's smallest unit.
+     *
+     * 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). If this option is 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.
+     */
+    isSmallestUnit?: boolean;
+    /**
+     * If the number is greater than 0, setting this to true will include its
+     * sign (eg: `+$35.00`). Has no effect on negative numbers or 0.
+     */
+    signForPositive?: boolean;
+}
+export interface CurrencyObject {
+    /**
+     * The negative sign for the price, if it is negative, or the positive sign
+     * if `signForPositive` is set.
+     */
+    sign: '-' | '+' | '';
+    /**
+     * The currency symbol for the formatted price.
+     *
+     * Note that the symbol's position depends on the `symbolPosition` property,
+     * and keep RTL locales in mind.
+     */
+    symbol: string;
+    /**
+     * The position of the currency symbol relative to the formatted price.
+     */
+    symbolPosition: 'before' | 'after';
+    /**
+     * The section of the formatted price before the decimal.
+     *
+     * Note that this is not a number, but a locale-formatted string which may
+     * include symbols like spaces, commas, or periods as group separators.
+     */
+    integer: string;
+    /**
+     * The section of the formatted price after and including the decimal.
+     *
+     * Note that this is not a number, but a locale-formatted string which may
+     * include symbols like spaces, commas, or periods as the decimal separator.
+     */
+    fraction: string;
+    /**
+     * True if the formatted number has a non-0 decimal part.
+     */
+    hasNonZeroFraction: boolean;
+}
+export type FormatNumber = (number: number, options?: Omit<NumberFormatParams, 'browserSafeLocale'>) => string;
+export type FormatCurrency = (number: number, currency: string, options?: Omit<NumberFormatCurrencyParams, 'number' | 'currency' | 'browserSafeLocale' | 'geoLocation'>) => string;
+export type GetCurrencyObject = (number: number, currency: string, options?: Omit<NumberFormatCurrencyParams, 'number' | 'currency' | 'browserSafeLocale' | 'geoLocation'>) => CurrencyObject;

package/dist/types.js

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

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@automattic/number-formatters",
+	"version": "1.0.0-alpha.1",
+	"description": "Number formatting utilities",
+	"author": "Automattic",
+	"license": "GPL-2.0-or-later",
+	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/number-formatters/#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Automattic/jetpack.git",
+		"directory": "projects/js-packages/number-formatters"
+	},
+	"bugs": {
+		"url": "https://github.com/Automattic/jetpack/labels/[JS Package] Number Formatters"
+	},
+	"dependencies": {
+		"@babel/runtime": "^7",
+		"@wordpress/date": "5.19.0",
+		"debug": "4.4.0"
+	},
+	"devDependencies": {
+		"@babel/core": "7.26.10",
+		"@babel/preset-react": "7.26.3",
+		"@jest/globals": "29.4.3",
+		"@types/jest": "29.5.14",
+		"jest": "29.7.0",
+		"jest-environment-jsdom": "29.7.0",
+		"typescript": "5.8.2"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "pnpm run clean && pnpm run compile-ts",
+		"clean": "rm -rf dist/",
+		"compile-ts": "tsc --pretty",
+		"test": "NODE_OPTIONS=--experimental-vm-modules jest",
+		"test-coverage": "pnpm run test --coverage",
+		"typecheck": "tsc --noEmit"
+	}
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const FALLBACK_LOCALE = 'en';
+export const FALLBACK_CURRENCY = 'USD';