@ducatjs/money 0.0.0 → 0.2.0

package/src/generated/iso4217.ts

@@ -0,0 +1,179 @@
+// GENERATED by scripts/gen-currencies.mjs from data/iso4217-list-one.xml. Do not edit by hand.
+/* eslint-disable */
+
+/** Publication date of the ISO 4217 List One snapshot the table was generated from. */
+export const ISO_4217_PUBLISHED = "2026-09-17";
+
+/** ISO 4217 minor-unit exponent for every active code that has one (165 codes). */
+export const ISO_EXPONENTS = {
+  AED: 2,
+  AFN: 2,
+  ALL: 2,
+  AMD: 2,
+  AOA: 2,
+  ARS: 2,
+  AUD: 2,
+  AWG: 2,
+  AZN: 2,
+  BAM: 2,
+  BBD: 2,
+  BDT: 2,
+  BHD: 3,
+  BIF: 0,
+  BMD: 2,
+  BND: 2,
+  BOB: 2,
+  BOV: 2,
+  BRL: 2,
+  BSD: 2,
+  BTN: 2,
+  BWP: 2,
+  BYN: 2,
+  BZD: 2,
+  CAD: 2,
+  CDF: 2,
+  CHE: 2,
+  CHF: 2,
+  CHW: 2,
+  CLF: 4,
+  CLP: 0,
+  CNY: 2,
+  COP: 2,
+  COU: 2,
+  CRC: 2,
+  CUP: 2,
+  CVE: 2,
+  CZK: 2,
+  DJF: 0,
+  DKK: 2,
+  DOP: 2,
+  DZD: 2,
+  EGP: 2,
+  ERN: 2,
+  ETB: 2,
+  EUR: 2,
+  FJD: 2,
+  FKP: 2,
+  GBP: 2,
+  GEL: 2,
+  GHS: 2,
+  GIP: 2,
+  GMD: 2,
+  GNF: 0,
+  GTQ: 2,
+  GYD: 2,
+  HKD: 2,
+  HNL: 2,
+  HTG: 2,
+  HUF: 2,
+  IDR: 2,
+  ILS: 2,
+  INR: 2,
+  IQD: 3,
+  IRR: 2,
+  ISK: 0,
+  JMD: 2,
+  JOD: 3,
+  JPY: 0,
+  KES: 2,
+  KGS: 2,
+  KHR: 2,
+  KMF: 0,
+  KPW: 2,
+  KRW: 0,
+  KWD: 3,
+  KYD: 2,
+  KZT: 2,
+  LAK: 2,
+  LBP: 2,
+  LKR: 2,
+  LRD: 2,
+  LSL: 2,
+  LYD: 3,
+  MAD: 2,
+  MDL: 2,
+  MGA: 2,
+  MKD: 2,
+  MMK: 2,
+  MNT: 2,
+  MOP: 2,
+  MRU: 2,
+  MUR: 2,
+  MVR: 2,
+  MWK: 2,
+  MXN: 2,
+  MXV: 2,
+  MYR: 2,
+  MZN: 2,
+  NAD: 2,
+  NGN: 2,
+  NIO: 2,
+  NOK: 2,
+  NPR: 2,
+  NZD: 2,
+  OMR: 3,
+  PAB: 2,
+  PEN: 2,
+  PGK: 2,
+  PHP: 2,
+  PKR: 2,
+  PLN: 2,
+  PYG: 0,
+  QAR: 2,
+  RON: 2,
+  RSD: 2,
+  RUB: 2,
+  RWF: 0,
+  SAR: 2,
+  SBD: 2,
+  SCR: 2,
+  SDG: 2,
+  SEK: 2,
+  SGD: 2,
+  SHP: 2,
+  SLE: 2,
+  SOS: 2,
+  SRD: 2,
+  SSP: 2,
+  STN: 2,
+  SVC: 2,
+  SYP: 2,
+  SZL: 2,
+  THB: 2,
+  TJS: 2,
+  TMT: 2,
+  TND: 3,
+  TOP: 2,
+  TRY: 2,
+  TTD: 2,
+  TWD: 2,
+  TZS: 2,
+  UAH: 2,
+  UGX: 0,
+  USD: 2,
+  USN: 2,
+  UYI: 0,
+  UYU: 2,
+  UYW: 4,
+  UZS: 2,
+  VED: 2,
+  VES: 2,
+  VND: 0,
+  VUV: 0,
+  WST: 2,
+  XAD: 2,
+  XAF: 0,
+  XCD: 2,
+  XCG: 2,
+  XOF: 0,
+  XPF: 0,
+  YER: 2,
+  ZAR: 2,
+  ZMW: 2,
+  ZWG: 2,
+} as const;
+
+export type IsoCurrencyCode = keyof typeof ISO_EXPONENTS;
+
+/** Active codes whose minor unit is "N.A." (precious metals, SDR, testing): not monetary, not in ISO_EXPONENTS. */
+export const ISO_NON_MONETARY = ["XAG","XAU","XBA","XBB","XBC","XBD","XDR","XPD","XPT","XSU","XTS","XUA","XXX"] as const;

package/src/generated/kernel.ts

@@ -0,0 +1,230 @@
+// lean-sources sha256:69cb179d69b98bf06518e6abae249369e163ca9ac7c318064680c59920517601 content sha256:dc3d761f86eb9b865b2cfa6a6dba6e6b3853afdab3ec5c8811415f9942c6231c
+// GENERATED from proofs/Ducat/Rounding.lean by `pnpm gen:kernel`. Do not edit.
+import { RoundingError } from '../rounding-error.js';
+import type { RoundingMode } from '../rounding.js';
+
+const ROUNDING_NECESSARY = 'Rounding necessary: the result is not exact; pass a rounding mode';
+
+/**
+ * `dividend / divisor` rounded with `mode`; `divisor` must be positive.
+ *
+ * Each `case` is printed from the Lean kernel for that mode, which is proved correct in
+ * proofs/Ducat/Rounding.lean: `kernel_sound` (the result satisfies the specification `Rounds`),
+ * `rounds_unique` (only one value does) and `kernel_fails_iff` (it throws only for 'unnecessary' on an
+ * inexact division), hence `kernel_correct`. Unknown modes throw a RangeError.
+ */
+export function divideAndRoundBigint(
+  dividend: bigint,
+  divisor: bigint,
+  mode: RoundingMode,
+): bigint {
+  const quotient = dividend / divisor;
+  const remainder = dividend - quotient * divisor;
+  return roundTruncatedQuotientBigint(dividend, divisor, quotient, remainder, mode);
+}
+
+/**
+ * Rounds the truncated `quotient` of `dividend / divisor` (with `remainder = dividend - quotient * divisor`)
+ * with `mode`; `divisor` must be positive.
+ *
+ * Each `case` is printed from the Lean kernel for that mode, which is proved correct in
+ * proofs/Ducat/Rounding.lean: `kernel_sound` (the result satisfies the specification `Rounds`),
+ * `rounds_unique` (only one value does) and `kernel_fails_iff` (it throws only for 'unnecessary' on an
+ * inexact division), hence `kernel_correct`. Unknown modes throw a RangeError.
+ */
+function roundTruncatedQuotientBigint(
+  dividend: bigint,
+  divisor: bigint,
+  quotient: bigint,
+  remainder: bigint,
+  mode: RoundingMode,
+): bigint {
+  if (remainder === 0n) {
+    return quotient;
+  }
+  const twiceRemainder = remainder < 0n ? -2n * remainder : 2n * remainder;
+
+  switch (mode) {
+    // rounds to the nearest integer, ties away from zero
+    case 'halfExpand': {
+      if (divisor <= twiceRemainder) {
+        if (dividend < 0n) {
+          return quotient - 1n;
+        }
+        return quotient + 1n;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties to the even neighbour
+    case 'halfEven': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && quotient % 2n !== 0n)) {
+        if (dividend < 0n) {
+          return quotient - 1n;
+        }
+        return quotient + 1n;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards zero
+    case 'halfTrunc': {
+      if (divisor < twiceRemainder) {
+        if (dividend < 0n) {
+          return quotient - 1n;
+        }
+        return quotient + 1n;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards +infinity
+    case 'halfCeil': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && !(dividend < 0n))) {
+        if (dividend < 0n) {
+          return quotient - 1n;
+        }
+        return quotient + 1n;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards -infinity
+    case 'halfFloor': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && dividend < 0n)) {
+        if (dividend < 0n) {
+          return quotient - 1n;
+        }
+        return quotient + 1n;
+      }
+      return quotient;
+    }
+    // rounds towards zero
+    case 'trunc': {
+      return quotient;
+    }
+    // rounds away from zero
+    case 'expand': {
+      if (dividend < 0n) {
+        return quotient - 1n;
+      }
+      return quotient + 1n;
+    }
+    // rounds towards +infinity
+    case 'ceil': {
+      if (dividend < 0n) {
+        return quotient;
+      }
+      return quotient + 1n;
+    }
+    // rounds towards -infinity
+    case 'floor': {
+      if (!(dividend < 0n)) {
+        return quotient;
+      }
+      return quotient - 1n;
+    }
+    // rounds not at all: throws RoundingError unless the division is exact
+    case 'unnecessary': {
+      throw new RoundingError(ROUNDING_NECESSARY);
+    }
+  }
+  throw new RangeError(`Unknown rounding mode "${String(mode)}"`);
+}
+
+/**
+ * The same switch over `number`: rounds the truncated `quotient` of `dividend / divisor`, where
+ * `remainder = dividend - quotient * divisor` exactly and `divisor` is positive. Every input must be a safe
+ * integer. This copy is not proved; test/kernel.test.ts compares it with the `bigint` one.
+ */
+export function roundTruncatedQuotient(
+  dividend: number,
+  divisor: number,
+  quotient: number,
+  remainder: number,
+  mode: RoundingMode,
+): number {
+  if (remainder === 0) {
+    return quotient;
+  }
+  const twiceRemainder = remainder < 0 ? -2 * remainder : 2 * remainder;
+
+  switch (mode) {
+    // rounds to the nearest integer, ties away from zero
+    case 'halfExpand': {
+      if (divisor <= twiceRemainder) {
+        if (dividend < 0) {
+          return quotient - 1;
+        }
+        return quotient + 1;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties to the even neighbour
+    case 'halfEven': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && quotient % 2 !== 0)) {
+        if (dividend < 0) {
+          return quotient - 1;
+        }
+        return quotient + 1;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards zero
+    case 'halfTrunc': {
+      if (divisor < twiceRemainder) {
+        if (dividend < 0) {
+          return quotient - 1;
+        }
+        return quotient + 1;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards +infinity
+    case 'halfCeil': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && !(dividend < 0))) {
+        if (dividend < 0) {
+          return quotient - 1;
+        }
+        return quotient + 1;
+      }
+      return quotient;
+    }
+    // rounds to the nearest integer, ties towards -infinity
+    case 'halfFloor': {
+      if (divisor < twiceRemainder || (twiceRemainder === divisor && dividend < 0)) {
+        if (dividend < 0) {
+          return quotient - 1;
+        }
+        return quotient + 1;
+      }
+      return quotient;
+    }
+    // rounds towards zero
+    case 'trunc': {
+      return quotient;
+    }
+    // rounds away from zero
+    case 'expand': {
+      if (dividend < 0) {
+        return quotient - 1;
+      }
+      return quotient + 1;
+    }
+    // rounds towards +infinity
+    case 'ceil': {
+      if (dividend < 0) {
+        return quotient;
+      }
+      return quotient + 1;
+    }
+    // rounds towards -infinity
+    case 'floor': {
+      if (!(dividend < 0)) {
+        return quotient;
+      }
+      return quotient - 1;
+    }
+    // rounds not at all: throws RoundingError unless the division is exact
+    case 'unnecessary': {
+      throw new RoundingError(ROUNDING_NECESSARY);
+    }
+  }
+  throw new RangeError(`Unknown rounding mode "${String(mode)}"`);
+}

package/src/generated/klarna.ts

@@ -0,0 +1,21 @@
+// GENERATED by scripts/gen-currencies.mjs from data/klarna.json (https://docs.klarna.com/acquirer/klarna/get-started/integration-resilience/data-types/, retrieved 2026-11-07). Do not edit by hand.
+/* eslint-disable */
+
+/** Klarna purchase currencies and their ISO 4217 exponents (amounts are integer minor units). */
+export const KLARNA_EXPONENTS: Readonly<Record<string, number>> = {
+  AUD: 2,
+  CAD: 2,
+  CHF: 2,
+  CZK: 2,
+  DKK: 2,
+  EUR: 2,
+  GBP: 2,
+  HUF: 2,
+  MXN: 2,
+  NOK: 2,
+  NZD: 2,
+  PLN: 2,
+  RON: 2,
+  SEK: 2,
+  USD: 2,
+};

package/src/generated/paypal.ts

@@ -0,0 +1,31 @@
+// GENERATED by scripts/gen-currencies.mjs from data/paypal.json (https://developer.paypal.com/api/rest/reference/currency-codes/, retrieved 2026-11-07). Do not edit by hand.
+/* eslint-disable */
+
+/** PayPal decimals per currency (`value` is a decimal string). HUF, JPY and TWD take none. */
+export const PAYPAL_EXPONENTS: Readonly<Record<string, number>> = {
+  AUD: 2,
+  BRL: 2,
+  CAD: 2,
+  CHF: 2,
+  CNY: 2,
+  CZK: 2,
+  DKK: 2,
+  EUR: 2,
+  GBP: 2,
+  HKD: 2,
+  HUF: 0,
+  ILS: 2,
+  JPY: 0,
+  MXN: 2,
+  MYR: 2,
+  NOK: 2,
+  NZD: 2,
+  PHP: 2,
+  PLN: 2,
+  RUB: 2,
+  SEK: 2,
+  SGD: 2,
+  THB: 2,
+  TWD: 0,
+  USD: 2,
+};

package/src/generated/stripe.ts

@@ -0,0 +1,150 @@
+// GENERATED by scripts/gen-currencies.mjs from data/stripe.json (https://docs.stripe.com/currencies, retrieved 2026-11-07). Do not edit by hand.
+/* eslint-disable */
+
+/**
+ * Stripe presentment currencies: [API exponent, charge amount multiple, payout amount multiple].
+ * A multiple of 100 means "send a two-decimal value whose decimal part is always 00" (ISK, UGX)
+ * or, for payouts only, whole units (HUF, TWD). A multiple of 10 is the three-decimal rule
+ * (last digit must be 0).
+ */
+export const STRIPE_RULES: Readonly<Record<string, readonly [exponent: number, chargeMultiple: number, payoutMultiple: number]>> = {
+  AED: [2,1,1],
+  AFN: [2,1,1],
+  ALL: [2,1,1],
+  AMD: [2,1,1],
+  ANG: [2,1,1],
+  AOA: [2,1,1],
+  ARS: [2,1,1],
+  AUD: [2,1,1],
+  AWG: [2,1,1],
+  AZN: [2,1,1],
+  BAM: [2,1,1],
+  BBD: [2,1,1],
+  BDT: [2,1,1],
+  BHD: [3,10,10],
+  BIF: [0,1,1],
+  BMD: [2,1,1],
+  BND: [2,1,1],
+  BOB: [2,1,1],
+  BRL: [2,1,1],
+  BSD: [2,1,1],
+  BWP: [2,1,1],
+  BYN: [2,1,1],
+  BZD: [2,1,1],
+  CAD: [2,1,1],
+  CDF: [2,1,1],
+  CHF: [2,1,1],
+  CLP: [0,1,1],
+  CNY: [2,1,1],
+  COP: [2,1,1],
+  CRC: [2,1,1],
+  CVE: [2,1,1],
+  CZK: [2,1,1],
+  DJF: [0,1,1],
+  DKK: [2,1,1],
+  DOP: [2,1,1],
+  DZD: [2,1,1],
+  EGP: [2,1,1],
+  ETB: [2,1,1],
+  EUR: [2,1,1],
+  FJD: [2,1,1],
+  FKP: [2,1,1],
+  GBP: [2,1,1],
+  GEL: [2,1,1],
+  GIP: [2,1,1],
+  GMD: [2,1,1],
+  GNF: [0,1,1],
+  GTQ: [2,1,1],
+  GYD: [2,1,1],
+  HKD: [2,1,1],
+  HNL: [2,1,1],
+  HTG: [2,1,1],
+  HUF: [2,1,100],
+  IDR: [2,1,1],
+  ILS: [2,1,1],
+  INR: [2,1,1],
+  ISK: [2,100,100],
+  JMD: [2,1,1],
+  JOD: [3,10,10],
+  JPY: [0,1,1],
+  KES: [2,1,1],
+  KGS: [2,1,1],
+  KHR: [2,1,1],
+  KMF: [0,1,1],
+  KRW: [0,1,1],
+  KWD: [3,10,10],
+  KYD: [2,1,1],
+  KZT: [2,1,1],
+  LAK: [2,1,1],
+  LBP: [2,1,1],
+  LKR: [2,1,1],
+  LRD: [2,1,1],
+  LSL: [2,1,1],
+  MAD: [2,1,1],
+  MDL: [2,1,1],
+  MGA: [0,1,1],
+  MKD: [2,1,1],
+  MMK: [2,1,1],
+  MNT: [2,1,1],
+  MOP: [2,1,1],
+  MUR: [2,1,1],
+  MVR: [2,1,1],
+  MWK: [2,1,1],
+  MXN: [2,1,1],
+  MYR: [2,1,1],
+  MZN: [2,1,1],
+  NAD: [2,1,1],
+  NGN: [2,1,1],
+  NIO: [2,1,1],
+  NOK: [2,1,1],
+  NPR: [2,1,1],
+  NZD: [2,1,1],
+  OMR: [3,10,10],
+  PAB: [2,1,1],
+  PEN: [2,1,1],
+  PGK: [2,1,1],
+  PHP: [2,1,1],
+  PKR: [2,1,1],
+  PLN: [2,1,1],
+  PYG: [0,1,1],
+  QAR: [2,1,1],
+  RON: [2,1,1],
+  RSD: [2,1,1],
+  RUB: [2,1,1],
+  RWF: [0,1,1],
+  SAR: [2,1,1],
+  SBD: [2,1,1],
+  SCR: [2,1,1],
+  SEK: [2,1,1],
+  SGD: [2,1,1],
+  SHP: [2,1,1],
+  SLE: [2,1,1],
+  SOS: [2,1,1],
+  SRD: [2,1,1],
+  STD: [2,1,1],
+  SZL: [2,1,1],
+  THB: [2,1,1],
+  TJS: [2,1,1],
+  TND: [3,10,10],
+  TOP: [2,1,1],
+  TRY: [2,1,1],
+  TTD: [2,1,1],
+  TWD: [2,1,100],
+  TZS: [2,1,1],
+  UAH: [2,1,1],
+  UGX: [2,100,100],
+  USD: [2,1,1],
+  UYU: [2,1,1],
+  UZS: [2,1,1],
+  VND: [0,1,1],
+  VUV: [0,1,1],
+  WST: [2,1,1],
+  XAF: [0,1,1],
+  XCD: [2,1,1],
+  XCG: [2,1,1],
+  XOF: [0,1,1],
+  XPF: [0,1,1],
+  YER: [2,1,1],
+  ZAR: [2,1,1],
+  ZMW: [2,1,1],
+};

package/src/historic.ts

@@ -0,0 +1,77 @@
+/**
+ * `@ducatjs/money/historic`: withdrawn ISO 4217 codes and a few non-ISO ones, with the exponent
+ * each had and, for ISO codes, the month ISO withdrew it. Nothing is registered until you ask, so
+ * the core registry stays ISO 4217 as currently published:
+ *
+ *     defineHistoricCurrencies(['HRK', 'BGN']);
+ *     money('100', 'HRK'); // 100.00 HRK
+ *     historicCurrency('HRK')?.withdrawn; // '2023-01'
+ */
+import { defineCurrency } from './currency.js';
+import { HISTORIC_CURRENCY_TABLE, ISO_4217_LIST_THREE_PUBLISHED } from './generated/historic.js';
+
+export { ISO_4217_LIST_THREE_PUBLISHED };
+
+/** A code in the historic table. */
+export type HistoricCurrencyCode = keyof typeof HISTORIC_CURRENCY_TABLE;
+
+/**
+ * Every historic code, for the `CurrencyCode` type:
+ *
+ *     declare module '@ducatjs/money' {
+ *       interface CustomCurrencies extends HistoricCurrencies {}
+ *     }
+ */
+export type HistoricCurrencies = { readonly [Code in HistoricCurrencyCode]: true };
+
+/** One entry of the historic table. */
+export interface HistoricCurrency {
+  readonly code: HistoricCurrencyCode;
+  /** The name ISO 4217 List Three gives it (for non-ISO codes, a descriptive name). */
+  readonly name: string;
+  /** Its minor-unit exponent while it was current: what stored minor units of it mean. */
+  readonly exponent: number;
+  /** The ISO 4217 numeric code; absent for codes that were never ISO (CNH). */
+  readonly numeric?: string;
+  /**
+   * The year and month ISO 4217 withdrew it ('2023-01'), from List Three. A code withdrawn
+   * country by country has the last date. Absent for codes that were never ISO.
+   */
+  readonly withdrawn?: string;
+}
+
+const table: Readonly<Record<string, Omit<HistoricCurrency, 'code'>>> = HISTORIC_CURRENCY_TABLE;
+
+/** The table entry for a code, or undefined for a code that isn't in it. */
+export function historicCurrency(code: string): HistoricCurrency | undefined {
+  // own properties only, so 'toString' and friends are not currencies
+  if (!Object.hasOwn(table, code)) {
+    return undefined;
+  }
+  return { code: code as HistoricCurrencyCode, ...table[code]! };
+}
+
+/** Every entry of the table, by code. */
+export function historicCurrencies(): HistoricCurrency[] {
+  return Object.keys(table).map((code) => historicCurrency(code)!);
+}
+
+/**
+ * Registers historic codes with `defineCurrency`, so Money can hold them: all of them, or only
+ * `codes`. Registering one again is harmless; a code already defined with another exponent throws,
+ * as `defineCurrency` does.
+ */
+export function defineHistoricCurrencies(codes?: readonly HistoricCurrencyCode[]): void {
+  const selected: readonly string[] = codes ?? Object.keys(table);
+
+  // check every code first, so a typo registers nothing
+  for (const code of selected) {
+    if (!Object.hasOwn(table, code)) {
+      throw new RangeError(`${code} is not in the historic currency table`);
+    }
+  }
+
+  for (const code of selected) {
+    defineCurrency(code, table[code]!.exponent);
+  }
+}