@munchi_oy/core 2.0.0 → 2.0.2

package/index.ts

@@ -1,5 +1,7 @@
 export * from "./generated/index";
 export * from "./src/currency";
 export * from "./src/enums";
+export * from "./src/money";
+export * from "./src/region";
 export * from "./src/subcategory";
 export { VERSION as MUNCHI_CORE_VERSION } from "./src/version";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@munchi_oy/core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Munchi Core SDK - Core utilities and types",
   "license": "UNLICENSED",
   "publishConfig": {

package/src/currency.ts

@@ -1,20 +1,9 @@
-import { CurrencyCode } from "../generated";
-
-const currencyMinorUnits: Record<string, number> = {
-  [CurrencyCode.Eur]: 2,
-  [CurrencyCode.Aed]: 2,
-  [CurrencyCode.Usd]: 2,
-  [CurrencyCode.Gbp]: 2,
-  BHD: 3,
-  JPY: 0,
-};
+import type { CurrencyCode } from "../generated";
+import { minorUnitMultiplier } from "./money";
 
+/** @deprecated Use `minorUnitMultiplier`, `toMinor` and `fromMinor` from `./money`. */
 export const CurrencyRegistry = {
   getMultiplier(currencyCode: CurrencyCode | string): number {
-    const minorUnits = currencyMinorUnits[currencyCode.toUpperCase()];
-    if (typeof minorUnits !== "number") {
-      return 100;
-    }
-    return Math.round(10 ** minorUnits);
+    return minorUnitMultiplier(currencyCode);
   },
 };

package/src/money.test.ts

@@ -0,0 +1,158 @@
+import { CurrencyCode } from "../generated";
+import {
+  cashRound,
+  formatMoney,
+  fromMinor,
+  minorUnitDigits,
+  toMinor,
+} from "./money";
+
+describe("minorUnitDigits", () => {
+  it.each([
+    [CurrencyCode.Eur, 2],
+    [CurrencyCode.Sek, 2],
+    [CurrencyCode.Aed, 2],
+    [CurrencyCode.Isk, 0],
+    ["JPY", 0],
+    ["BHD", 3],
+    ["kwd", 3],
+    ["CLF", 4],
+    ["UYW", 4],
+  ])("gives %s %i decimals", (currency, digits) => {
+    expect(minorUnitDigits(currency)).toBe(digits);
+  });
+});
+
+describe("toMinor and fromMinor", () => {
+  it("converts a two-decimal price without float drift", () => {
+    expect(toMinor(19.99, CurrencyCode.Eur)).toBe(1999);
+  });
+
+  it("converts a zero-decimal currency one to one", () => {
+    expect(toMinor(1500, CurrencyCode.Isk)).toBe(1500);
+  });
+
+  it("converts a three-decimal currency in thousandths", () => {
+    expect(toMinor(1.234, "BHD")).toBe(1234);
+  });
+
+  it.each([
+    [1.005, CurrencyCode.Eur, 101],
+    [1.015, CurrencyCode.Eur, 102],
+    [2.5, "JPY", 3],
+    [1.0005, "KWD", 1001],
+    [1.00005, "CLF", 10001],
+  ])(
+    "rounds the half-way amount %d %s up to %i minor units",
+    (major, currency, minor) => {
+      expect(toMinor(major, currency)).toBe(minor);
+    },
+  );
+
+  it.each([
+    [-1.005, CurrencyCode.Eur, -100],
+    [-1.015, CurrencyCode.Eur, -101],
+    [-2.5, "JPY", -2],
+    [-1.0005, "KWD", -1000],
+    [-1.00005, "CLF", -10000],
+  ])(
+    "rounds the negative half-way amount %d %s toward +Infinity like Math.round, to %i",
+    (major, currency, minor) => {
+      expect(toMinor(major, currency)).toBe(minor);
+    },
+  );
+
+  it.each([
+    [1.006, CurrencyCode.Eur, 101],
+    [-1.006, CurrencyCode.Eur, -101],
+  ])(
+    "rounds %d %s past the half way to the nearer unit, %i",
+    (major, currency, minor) => {
+      expect(toMinor(major, currency)).toBe(minor);
+    },
+  );
+
+  it("converts zero to zero", () => {
+    expect(toMinor(0, CurrencyCode.Eur)).toBe(0);
+  });
+
+  it("converts amounts written in exponent notation", () => {
+    expect(toMinor(1e21, CurrencyCode.Eur)).toBe(1e23);
+  });
+
+  it("converts a tiny amount in exponent notation to zero minor units", () => {
+    expect(toMinor(1e-7, CurrencyCode.Eur)).toBe(0);
+  });
+
+  it("keeps a non-finite amount non-finite", () => {
+    expect(toMinor(Number.POSITIVE_INFINITY, CurrencyCode.Eur)).toBe(
+      Number.POSITIVE_INFINITY,
+    );
+  });
+
+  it("converts a four-decimal currency in ten-thousandths", () => {
+    expect(toMinor(1.2345, "CLF")).toBe(12345);
+  });
+
+  it("turns minor units back into the major amount", () => {
+    expect(fromMinor(1999, CurrencyCode.Eur)).toBe(19.99);
+  });
+});
+
+describe("formatMoney", () => {
+  it("puts the euro sign after the amount in Finnish", () => {
+    expect(
+      formatMoney({ amount: 1250, currency: CurrencyCode.Eur }, "fi-FI"),
+    ).toMatch(/^12,50\s€$/);
+  });
+
+  it("puts the pound sign before the amount in British English", () => {
+    expect(
+      formatMoney({ amount: 1250, currency: CurrencyCode.Gbp }, "en-GB"),
+    ).toBe("£12.50");
+  });
+
+  it("shows no decimals for a zero-decimal currency", () => {
+    expect(
+      formatMoney({ amount: 1500, currency: CurrencyCode.Isk }, "en-GB", {
+        currencyDisplay: "code",
+      }),
+    ).toMatch(/^ISK\s1,500$/);
+  });
+
+  it("shows three decimals for a three-decimal currency", () => {
+    expect(
+      formatMoney({ amount: 1234, currency: "BHD" }, "en-GB", {
+        currencyDisplay: "code",
+      }),
+    ).toMatch(/^BHD\s1\.234$/);
+  });
+});
+
+describe("cashRound", () => {
+  it.each([
+    [1002, 1000],
+    [1003, 1005],
+    [1007, 1005],
+    [1008, 1010],
+    [1005, 1005],
+  ])("rounds %i to %i with a five-cent increment", (amount, rounded) => {
+    expect(cashRound(amount, { increment: 5 }).roundedAmount).toBe(rounded);
+  });
+
+  it("reports the rounding difference", () => {
+    expect(cashRound(1003, { increment: 5 }).roundingDifference).toBe(2);
+  });
+
+  it("leaves the amount alone without cash rounding", () => {
+    expect(cashRound(1003, null)).toEqual({
+      actualAmount: 1003,
+      roundedAmount: 1003,
+      roundingDifference: 0,
+    });
+  });
+
+  it("leaves refunds and zero alone", () => {
+    expect(cashRound(-1003, { increment: 5 }).roundedAmount).toBe(-1003);
+  });
+});

package/src/money.ts

@@ -0,0 +1,125 @@
+import type { CurrencyCode } from "../generated";
+
+/** An amount in the currency's minor unit (cents for EUR), always an integer. */
+export interface Money {
+  amount: number;
+  currency: CurrencyCode | string;
+}
+
+export interface CashRounding {
+  /** Cash totals snap to a multiple of this many minor units (5 = 0.05 EUR). */
+  increment: number;
+}
+
+export interface CashRoundingResult {
+  actualAmount: number;
+  roundedAmount: number;
+  roundingDifference: number;
+}
+
+// ISO 4217 minor units that differ from 2. A table, not Intl, so every runtime (Hermes, Node, browsers) agrees.
+const MINOR_UNIT_DIGITS: Record<string, number> = {
+  BIF: 0,
+  CLP: 0,
+  DJF: 0,
+  GNF: 0,
+  ISK: 0,
+  JPY: 0,
+  KMF: 0,
+  KRW: 0,
+  PYG: 0,
+  RWF: 0,
+  UGX: 0,
+  UYI: 0,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0,
+  BHD: 3,
+  IQD: 3,
+  JOD: 3,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  TND: 3,
+  CLF: 4,
+  UYW: 4,
+};
+
+export function minorUnitDigits(currency: CurrencyCode | string): number {
+  return MINOR_UNIT_DIGITS[currency.toUpperCase()] ?? 2;
+}
+
+export function minorUnitMultiplier(currency: CurrencyCode | string): number {
+  return 10 ** minorUnitDigits(currency);
+}
+
+// Shifts the decimal point in the number's own decimal text, so 1.005 EUR is 100.5 cents and rounds to 101;
+// `1.005 * 100` is 100.49999999999999 in binary floating point. Ties round like Math.round (toward +Infinity).
+export function toMinor(
+  major: number,
+  currency: CurrencyCode | string,
+): number {
+  if (!Number.isFinite(major)) {
+    return Math.round(major * minorUnitMultiplier(currency));
+  }
+  const [mantissa, exponent = "0"] = String(major).split("e");
+  return Math.round(
+    Number(`${mantissa}e${Number(exponent) + minorUnitDigits(currency)}`),
+  );
+}
+
+export function fromMinor(
+  minor: number,
+  currency: CurrencyCode | string,
+): number {
+  return minor / minorUnitMultiplier(currency);
+}
+
+export interface FormatMoneyOptions {
+  currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
+  signDisplay?: "auto" | "always" | "exceptZero" | "never";
+}
+
+/** Formats with Intl in `locale` (e.g. "fi-FI", "en-FI"), so the symbol sits where that locale puts it. */
+export function formatMoney(
+  money: Money,
+  locale: string,
+  options: FormatMoneyOptions = {},
+): string {
+  const digits = minorUnitDigits(money.currency);
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency.toUpperCase(),
+    currencyDisplay: options.currencyDisplay ?? "symbol",
+    signDisplay: options.signDisplay ?? "auto",
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(fromMinor(money.amount, money.currency));
+}
+
+/** Rounds a cash total half up to the increment; `null` means no cash rounding. */
+export function cashRound(
+  amount: number,
+  rounding: CashRounding | null,
+): CashRoundingResult {
+  const increment = rounding?.increment ?? 0;
+  if (amount <= 0 || !Number.isFinite(amount) || increment <= 1) {
+    return {
+      actualAmount: amount,
+      roundedAmount: amount,
+      roundingDifference: 0,
+    };
+  }
+  const remainder = amount % increment;
+  const roundedAmount =
+    remainder * 2 < increment
+      ? amount - remainder
+      : amount + (increment - remainder);
+  return {
+    actualAmount: amount,
+    roundedAmount,
+    roundingDifference: roundedAmount - amount,
+  };
+}

package/src/region.test.ts

@@ -0,0 +1,80 @@
+import { cashRound } from "./money";
+import { countryQuirks, regionLocale } from "./region";
+
+describe("countryQuirks", () => {
+  it.each([
+    ["FI", 5],
+    ["EE", 5],
+    ["SE", 100],
+  ])("rounds cash in %s to %i minor units", (countryCode, increment) => {
+    expect(countryQuirks(countryCode).cashRounding).toEqual({ increment });
+  });
+
+  it.each(["DE", "US", "JP"])("does not round cash in %s", (countryCode) => {
+    expect(countryQuirks(countryCode).cashRounding).toBeNull();
+  });
+
+  it("feeds cash rounding straight into cashRound", () => {
+    expect(
+      cashRound(1003, countryQuirks("FI").cashRounding).roundedAmount,
+    ).toBe(1005);
+  });
+
+  it.each([
+    ["DE", ["de", "en"]],
+    ["FR", ["fr", "en"]],
+    ["JP", ["ja", "en"]],
+  ])(
+    "offers customers in %s the country's language, then English",
+    (countryCode, languages) => {
+      expect(countryQuirks(countryCode).customerLanguages).toEqual(languages);
+    },
+  );
+
+  it("offers English once where English is the country's language", () => {
+    expect(countryQuirks("US").customerLanguages).toEqual(["en"]);
+  });
+
+  it.each([
+    ["FI", ["fi", "sv", "en"]],
+    ["EE", ["et", "ru", "en"]],
+    ["ES", ["es", "ca", "en"]],
+  ])(
+    "offers customers in %s the languages listed for it",
+    (countryCode, languages) => {
+      expect(countryQuirks(countryCode).customerLanguages).toEqual(languages);
+    },
+  );
+
+  it("reads the country code in any case", () => {
+    expect(countryQuirks("fi")).toEqual(countryQuirks("FI"));
+  });
+
+  it.each([null, undefined, ""])(
+    "falls back to English and no rounding without a country (%p)",
+    (countryCode) => {
+      expect(countryQuirks(countryCode)).toEqual({
+        cashRounding: null,
+        customerLanguages: ["en"],
+      });
+    },
+  );
+
+  it("falls back to English for a code that is not a country", () => {
+    expect(countryQuirks("not-a-country").customerLanguages).toEqual(["en"]);
+  });
+});
+
+describe("regionLocale", () => {
+  it("combines the reader's language with the venue's country", () => {
+    expect(regionLocale("en", "FI")).toBe("en-FI");
+  });
+
+  it("drops a region the language already carries", () => {
+    expect(regionLocale("fi-FI", "FI")).toBe("fi-FI");
+  });
+
+  it("falls back to the bare language without a country", () => {
+    expect(regionLocale("sv", null)).toBe("sv");
+  });
+});

package/src/region.ts

@@ -0,0 +1,61 @@
+import type { CashRounding } from "./money";
+
+/** What can't be derived from a store's country with Intl. Every country is allowed; this only fills in local habits. */
+export interface CountryQuirks {
+  cashRounding: CashRounding | null;
+  /** Languages a customer-facing screen (kiosk, receipt) offers; the first is the default. */
+  customerLanguages: string[];
+}
+
+const QUIRKS: Readonly<Record<string, Partial<CountryQuirks>>> = {
+  FI: { cashRounding: { increment: 5 }, customerLanguages: ["fi", "sv", "en"] },
+  EE: { cashRounding: { increment: 5 }, customerLanguages: ["et", "ru", "en"] },
+  SE: { cashRounding: { increment: 100 } },
+  ES: { customerLanguages: ["es", "ca", "en"] },
+};
+
+// Intl.Locale is missing on some runtimes (older Hermes), and an unknown region throws.
+function mainLanguage(countryCode: string): string | undefined {
+  if (typeof Intl.Locale !== "function") {
+    return undefined;
+  }
+  try {
+    return new Intl.Locale(`und-${countryCode}`).maximize().language;
+  } catch {
+    return undefined;
+  }
+}
+
+export function countryQuirks(
+  countryCode: string | null | undefined,
+): CountryQuirks {
+  if (!countryCode) {
+    return { cashRounding: null, customerLanguages: ["en"] };
+  }
+  const code = countryCode.toUpperCase();
+  const quirks = QUIRKS[code] ?? {};
+  const language = mainLanguage(code);
+  return {
+    cashRounding: quirks.cashRounding ?? null,
+    customerLanguages:
+      quirks.customerLanguages ??
+      (language && language !== "und"
+        ? [...new Set([language, "en"])]
+        : ["en"]),
+  };
+}
+
+/** The locale to format numbers and dates in: the reader's language with the venue's country ("en" + "FI" → "en-FI"). */
+export function regionLocale(
+  language: string,
+  countryCode: string | null | undefined,
+): string {
+  const base = language.split("-")[0].toLowerCase();
+  if (!countryCode) {
+    return base;
+  }
+  const candidate = `${base}-${countryCode.toUpperCase()}`;
+  return Intl.NumberFormat.supportedLocalesOf([candidate]).length > 0
+    ? candidate
+    : base;
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated. Do not edit manually.
 // Run 'pnpm version:sync' to update this file.
-export const VERSION = "2.0.0";
+export const VERSION = "2.0.2";