new feature, options: currencySign, currencyDisplay

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 Strictly follows [Semantic Versioning 2.0.0.](https://semver.org/)
 
+## v1.10.0
+`2022-10-06`\
+\
+:rocket: Features:
+- [`formatNumber()`](DOCUMENTATION.md#formatNumber), [`formatNumberToFixed()`](DOCUMENTATION.md#formatNumberToFixed), [`formatMoney()`](DOCUMENTATION.md#formatMoney) - accepts `currency` as numeric representation (e.g. `USD = 840`).
+```typescript
+formatMoney(1.532, { precision: 2, currency: 840 }, "pl-PL")
+```
+- [`formatNumber()`](DOCUMENTATION.md#formatNumber), [`formatNumberToFixed()`](DOCUMENTATION.md#formatNumberToFixed), [`formatMoney()`](DOCUMENTATION.md#formatMoney) - accepts new option `currencySign` (Safari >= `14.1`). Defaults: `currencySign: "standard"` when `currency` value is provided.
+```typescript
+formatMoney(-1.532, { precision: 2, currency: 840, currencySign: "accounting" })
+```
+- [`getCurrencySymbol()`](DOCUMENTATION.md#getCurrencySymbol) - accepts new option `currencyDisplay` (Safari >= `14.1`)
+```typescript
+getCurrencySymbol({ currency: "CAD", currencyDisplay: "narrowSymbol" }, "en")
+```
+
 ## v1.9.0
 `2022-10-05`\
 \

DOCUMENTATION.md

@@ -225,6 +225,9 @@ formatMoney(1.53588, { precision: 3, currency: "USD" }, "en"); // returns "$1.53
 formatMoney(1.53588, { precision: 3, currency: "USD", currencyDisplay: "code" }, "en"); // returns "USD 1.536"
 formatMoney(1.532, { precision: 2, currency: "PLN" }, "pl-PL"); // returns "1,53 zł"
 formatMoney(1.532, { precision: 2, currency: "USD" }, "pl-PL"); // returns "1,53 USD"
+formatMoney(1.532, { precision: 2, currency: "CAD" }, "en-US"); // returns "CA$1.53"
+formatMoney(1.532, { precision: 2, currency: "CAD", currencyDisplay: "narrowSymbol" }, "en-US"); // returns "$1.53"
+formatMoney(-1.53588, { precision: 3, currency: "USD", currencySign: "accounting" }, "en"); // returns "($1.536)"
 ```
 
 ### formatMonth()
@@ -252,6 +255,7 @@ arguments:
   - negativeZero (boolean): default `true` (current Intl default behavior)
   - currency (string): currency ISO Alpha 3 code (e.g. `"USD"`), default `undefined`
   - currencyDisplay (string): `"symbol" | "narrowSymbol" | "code" | "name"`; default `"symbol"` when `currency` is provided; see more info in the `Intl` documentation
+  - currencySign (string): `"standard" | "accounting"`; default `"standard"` when `currency` is provided; see more info in the `Intl` documentation
 - locale (optional, default: browser locale): BCP47 language tag/tags (`string` or `string[]`) or `Intl.Collator`
 
 ```typescript
@@ -336,6 +340,8 @@ import { getCurrencySymbol } from '@dnvgl/i18n';
 
 getCurrencySymbol("USD", "en-US"); // returns "$"
 getCurrencySymbol(840, "en-US"); // returns "$" (where 840 is the USD numeric code)
+getCurrencySymbol({ currency: "CAD" }, "en-US"); // returns "CA$"
+getCurrencySymbol({ currency: "CAD", currencyDisplay: "narrowSymbol" }, "en-US"); // returns "$"
 ```
 
 ### formatTime()
@@ -529,7 +535,7 @@ parseNumber("-1,62-sd3.454", true, "en-GB"); // returns undefined
 ```
 
 ### plural()
-String pattern as array or separated by characeter (default: `|`, can be customized by `separator` argument)
+String pattern as array or separated by character (default: `|`, can be customized by `separator` argument)
 ```typescript
 import { plural } from '@dnvgl/i18n';
 

__tests__/formatMoney.test.ts

@@ -19,14 +19,20 @@ describe('formatMoney', () => {
   test("using options", () => {
     expect(formatMoney(1.532, { precision: 2, currency: "PLN" }, "pl-PL")).toEqual(`1,53${IntlWhitespace}zł`);
     expect(formatMoney(1.532, { precision: 2, currency: "USD" }, "pl-PL")).toEqual(`1,53${IntlWhitespace}USD`);
+    expect(formatMoney(1.532, { precision: 2, currency: 840 }, "pl-PL")).toEqual(`1,53${IntlWhitespace}USD`);
     expect(formatMoney(1.53588, { precision: 3, currency: "USD" }, "en")).toEqual("$1.536");
+    expect(formatMoney(-1.53588, { precision: 3, currency: "USD", currencySign: "accounting" }, "en")).toEqual("($1.536)");
     expect(formatMoney(1.53588, { precision: 3, currency: "USD", currencyDisplay: "code" }, "en")).toEqual(`USD${IntlWhitespace}1.536`);
   });
 
   test("using partial options", () => {
     expect(formatMoney(1.53588, { }, "en")).toEqual("1.54");
     expect(formatMoney(1.53588, { precision: 3 }, "en")).toEqual("1.536");
     expect(formatMoney(1.53588, { currency: "USD" }, "en")).toEqual("$1.54");
+    expect(formatMoney(1.53588, { currency: "CAD" }, "en")).toEqual("CA$1.54");
+    expect(formatMoney(1.53588, { currency: "CAD", currencyDisplay: "narrowSymbol" }, "en")).toEqual("$1.54");
+    expect(formatMoney(1.53588, { currencyDisplay: "narrowSymbol" }, "en")).toEqual("1.54");
+    expect(formatMoney(-1.53588, { currencySign: "accounting" }, "en")).toEqual("-1.54");
     expect(formatMoney(1.53588, { currency: "USD", currencyDisplay: "code" }, "en")).toEqual(`USD${IntlWhitespace}1.54`);
   });
 });

__tests__/getCurrencySymbol.test.ts

@@ -1,4 +1,4 @@
-import { getCurrencySymbol } from "../src";
+import { CurrencySymbolOptions, getCurrencySymbol } from "../src";
 
 describe('getCurrencySymbol', () => {
   test.each([
@@ -9,10 +9,30 @@ describe('getCurrencySymbol', () => {
     [985, "pl", "zł"],
     [985, "en", "PLN"]
   ])('returns proper value for %p currency and %p locale', (currency, locale, expected) => {
-    for (var i =0; i < 1000; i++) {
-      getCurrencySymbol(currency, locale);
-    }
     const result = getCurrencySymbol(currency, locale);
     expect(result).toBe(expected);
   });
+
+  test.each([
+    [{ currency: "USD" }, "en", "$"],
+    [{ currency: "CAD" }, "en", "CA$"],
+    [{ currency: "CAD", currencyDisplay: "narrowSymbol" }, "en", "$"],
+    [{ currency: 840 }, "en", "$"],
+    [{ currency: "PLN" }, "pl", "zł"],
+    [{ currency: "PLN" }, "en", "PLN"],
+    [{ currency: 985 }, "pl", "zł"],
+    [{ currency: 985 }, "en", "PLN"]
+  ] as [CurrencySymbolOptions, string, string][])('returns proper value for %p options and %p locale', (currency, locale, expected) => {
+    const result = getCurrencySymbol(currency, locale);
+    expect(result).toBe(expected);
+  });
+
+  describe("given invalid parameters", () => {
+    it("fails to compile", () => {
+      // @ts-expect-error
+      () => getCurrencySymbol({ currencyDisplay: "narrowSymbol" }); // HINT: missing currency argument
+      // @ts-expect-error
+      () => getCurrencySymbol({ currencyDisplay: "narrowSymbol" }, "en"); // HINT: missing currency argument
+    });
+  });
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dnvgl/i18n",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "A set of functions to support multiple languages/cultures in a browser or Node.js",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

src/formatMoney.ts

@@ -18,7 +18,8 @@ export function formatMoney(value: number, options?: number | Partial<NumberForm
         useBankersRounding: defaultOptions.useBankersRounding, 
         precision: options.precision ?? defaultOptions.precision, 
         currency: options.currency,
-        currencyDisplay: options.currencyDisplay
+        currencyDisplay: options.currencyDisplay,
+        currencySign: options.currencySign
       }
       : defaultOptions
 

src/formatNumber.ts

@@ -1,3 +1,4 @@
+import { findIso4217Currency } from "./findIso4217Currency";
 import { createNumberFormat } from "./internal/createNumberFormat";
 import { roundUsingBankersMethod } from "./roundUsingBankersMethod";
 import { Locale } from "./types/locale";
@@ -23,14 +24,20 @@ export function formatNumber(value: number, options?: Partial<NumberFormat>
 function createFormatterOptions(opts?: Partial<NumberFormat>): Intl.NumberFormatOptions {
   const minimumFractionDigits = opts?.minPrecision,
     maximumFractionDigits = opts?.maxPrecision ?? 10,
-    style = opts?.currency ? "currency" : "decimal";
+    style = opts?.currency ? "currency" : "decimal",
+    currency = opts?.currency !== undefined
+      ? typeof opts.currency === "string"
+        ? opts.currency
+        : findIso4217Currency(opts.currency)?.alpha3Code
+      : undefined;
 
   return {
     style: style,
-    currency: opts?.currency,
+    currency: currency,
     currencyDisplay: style === "currency" 
       ? opts?.currencyDisplay ?? "symbol" 
       : undefined,
+    currencySign: opts?.currencySign,
     minimumFractionDigits: minimumFractionDigits,
     maximumFractionDigits: maximumFractionDigits,
     useGrouping:opts?.thousandsSeparator === false ? false : true

src/formatNumberToFixed.ts

@@ -17,6 +17,7 @@ export function formatNumberToFixed(value: number, options?: Partial<NumberForma
     negativeZero: isNumberArg ? undefined : options?.negativeZero,
     currency: isNumberArg ? undefined : options?.currency,
     currencyDisplay: isNumberArg ? undefined : options?.currencyDisplay,
+    currencySign: isNumberArg ? undefined : options?.currencySign
   };
 
   return formatNumber(value, formatOptions, locale);

src/getCurrencySymbol.ts

@@ -1,16 +1,34 @@
 import { findIso4217Currency } from "./findIso4217Currency";
 import { getSeparator } from "./internal/getSeparator";
+import { CurrencySymbolOptions } from "./types/currencySymbolOptions";
+import { IntlCurrencyDisplay } from "./types/intlCurrencyDisplay";
 import { Iso4217Alpha3Code, Iso4217NumericCode } from "./types/iso4217";
 import { Locale } from "./types/locale";
 
-export function getCurrencySymbol(currencyCode: Iso4217Alpha3Code | Iso4217NumericCode, locale?: Locale): string {
-  const code = typeof currencyCode === "string"
-    ? currencyCode
-    : findIso4217Currency(currencyCode)?.alpha3Code;
+export function getCurrencySymbol(currencyCode: Iso4217Alpha3Code | Iso4217NumericCode, locale?: Locale): string
+export function getCurrencySymbol(currencyCode: CurrencySymbolOptions, locale?: Locale): string
+export function getCurrencySymbol(options: Iso4217Alpha3Code | Iso4217NumericCode | CurrencySymbolOptions, locale?: Locale): string {
+  if (typeof options === "string") {
+    return getCurrencySymbolString(options, undefined, locale);
+  }
+
+  if (typeof options === "number") {
+    return getCurrencySymbolString(findIso4217Currency(options)?.alpha3Code, undefined, locale);
+  }
 
-  if (!code) {
+  const code = typeof options.currency === "string"
+    ? options.currency
+    : findIso4217Currency(options.currency)?.alpha3Code
+
+  return getCurrencySymbolString(code, options.currencyDisplay, locale);
+}
+
+function getCurrencySymbolString(currency?: Iso4217Alpha3Code, currencyDisplay?: IntlCurrencyDisplay, locale?: Locale): string {
+  if (!currency) {
     return "";
   }
 
-  return getSeparator(1, "currency", { style: "currency", currency: code, currencyDisplay: "symbol" }, locale);
+  const intlOptions = { style: "currency", currency: currency, currencyDisplay: currencyDisplay ?? "symbol" };
+
+  return getSeparator(1, "currency", intlOptions, locale);
 }

src/index.ts

@@ -64,11 +64,13 @@ export { NumberFormatBase } from './types/numberFormatBase';
 export { NumberFormatFixed } from './types/numberFormatFixed';
 export { NumberFormatMoney } from './types/numberFormatMoney';
 export { IntlCurrencyDisplay } from './types/intlCurrencyDisplay';
+export { IntlCurrencySign } from './types/intlCurrencySign';
 export { TransformationOptions } from './types/transformationOptions';
 export { TimeFormatPrecision } from './types/timeFormatPrecision';
 export { Locale, LocaleOrCollator } from './types/locale';
 export { DatePart } from './types/datePart';
 export { Iso3166Country, Iso3166Alpha2Code, Iso3166Alpha3Code, Iso3166NumericCode } from './types/iso3166';
 export { StateOfUsa, StateAlpha2Code } from './types/stateOfUsa';
 export { IbanParseOptions } from './types/ibanParseOptions';
-export { Iso4217Currency, Iso4217Alpha3Code, Iso4217NumericCode } from './types/iso4217';
+export { Iso4217Currency, Iso4217Alpha3Code, Iso4217NumericCode } from './types/iso4217';
+export { CurrencySymbolOptions } from './types/currencySymbolOptions';

src/types/currencySymbolOptions.ts

@@ -0,0 +1,7 @@
+import { IntlCurrencyDisplay } from "./intlCurrencyDisplay";
+import { Iso4217Alpha3Code, Iso4217NumericCode } from "./iso4217";
+
+export interface CurrencySymbolOptions {
+  currency: Iso4217Alpha3Code | Iso4217NumericCode;
+  currencyDisplay?: IntlCurrencyDisplay;
+}

src/types/intlCurrencySign.ts

@@ -0,0 +1 @@
+export type IntlCurrencySign = "standard" | "accounting";

src/types/numberFormatBase.ts

@@ -1,10 +1,12 @@
 import { IntlCurrencyDisplay } from "./intlCurrencyDisplay";
-import { Iso4217Alpha3Code } from "./iso4217";
+import { IntlCurrencySign } from "./intlCurrencySign";
+import { Iso4217Alpha3Code, Iso4217NumericCode } from "./iso4217";
 
 export interface NumberFormatBase {
   thousandsSeparator: boolean;
   useBankersRounding: boolean;
   negativeZero: boolean;
-  currency: Iso4217Alpha3Code;
+  currency: Iso4217Alpha3Code | Iso4217NumericCode;
   currencyDisplay: IntlCurrencyDisplay;
+  currencySign: IntlCurrencySign;
 }

src/types/numberFormatMoney.ts

@@ -1,8 +1,10 @@
 import { IntlCurrencyDisplay } from "./intlCurrencyDisplay";
-import { Iso4217Alpha3Code } from "./iso4217";
+import { IntlCurrencySign } from "./intlCurrencySign";
+import { Iso4217Alpha3Code, Iso4217NumericCode } from "./iso4217";
 
 export interface NumberFormatMoney {
   precision: number;
-  currency: Iso4217Alpha3Code;
+  currency: Iso4217Alpha3Code | Iso4217NumericCode;
   currencyDisplay: IntlCurrencyDisplay;
+  currencySign: IntlCurrencySign;
 }