@ducatjs/money 0.0.0 → 0.1.0

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/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `@ducatjs/money`: the core. Money with construction, arithmetic, rounding, comparison and
+ * serialisation as methods (`price.add(fee).multiply('1.075')`), plus the ISO 4217 exponents.
+ * The same operations as plain functions (`add(price, fee)`) are in `@ducatjs/money/fn`. Allocation, tax, conversion, cash rounding,
+ * formatting, parsing and the processor and database views are opt-in modules
+ * (`@ducatjs/money/allocate`, `@ducatjs/money/tax`, ...; `@ducatjs/money/all` for everything).
+ */
+export {
+  money,
+  fromMinor,
+  zero,
+  fromJSON,
+  isMoney,
+  extendMoney,
+  type ExtendMoneyOptions,
+  sum,
+  ratio,
+  CurrencyMismatchError,
+  type Money,
+  type MoneyJSON,
+  type MoneyOptions,
+  type CurrencyInput,
+  type Factor,
+  type Ratio,
+} from './money.js';
+export { DEFAULT_ROUNDING, Rounding, RoundingError, type RoundingMode } from './rounding.js';
+export {
+  currencyExponent,
+  defineCurrency,
+  isCurrency,
+  ISO_EXPONENTS,
+  ISO_4217_PUBLISHED,
+  ISO_NON_MONETARY,
+  type CurrencyCode,
+  type IsoCurrencyCode,
+  type CustomCurrencies,
+} from './currency.js';

package/src/klarna.ts

@@ -0,0 +1,54 @@
+/**
+ * Klarna's amount view (Klarna Payments and Order Management; https://docs.klarna.com/acquirer/klarna/get-started/integration-resilience/data-types/,
+ * encoded in data/klarna.json). Amounts (`order_amount`, `unit_price`, `total_amount`, ...) are
+ * integers "in minor units according to the ISO 4217 standard", in the one local currency of each
+ * purchase country: 25 EUR -> 2500, 1000 HUF -> 100000 (fillér; PayPal sends HUF without decimals).
+ */
+import { KLARNA_EXPONENTS } from './generated/klarna.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorAmount, toProcessorAmount } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { KLARNA_EXPONENTS };
+
+/** The ISO 4217 exponent of a Klarna purchase currency; throws for any other currency. */
+export function klarnaExponent(currency: string): number {
+  const exponent = KLARNA_EXPONENTS[currency.toUpperCase()];
+  if (exponent === undefined) {
+    throw new RangeError(`${currency} is not a Klarna purchase currency`);
+  }
+  return exponent;
+}
+
+/** Whether the currency is one of Klarna's purchase currencies (case-insensitive). */
+export function isKlarnaCurrency(currency: string): boolean {
+  return KLARNA_EXPONENTS[currency.toUpperCase()] !== undefined;
+}
+
+/** Options for the Klarna amount: how to round when Klarna needs a coarser amount. */
+export interface KlarnaAmountOptions {
+  /**
+   * How to round when the value has more decimals than the currency (default 'unnecessary': throw).
+   */
+  readonly rounding?: RoundingMode;
+}
+
+/**
+ * The integer to send in any Klarna amount field: toKlarna(money('25', 'EUR')) === 2500.
+ * A bare number, because Klarna gives the currency once per order (`purchase_currency`).
+ * Negative amounts pass through: discount order lines are negative ("Negative when type is
+ * discount"), though `order_amount` itself must be non-negative.
+ */
+export function toKlarna(money: Money, options?: KlarnaAmountOptions): number {
+  const rounding = options?.rounding ?? 'unnecessary';
+  return toProcessorAmount('Klarna', money, klarnaExponent(money.currency), 1, rounding);
+}
+
+/** Reads a Klarna amount field: fromKlarna(2500, 'EUR') is 25.00 EUR. */
+export function fromKlarna<C extends CurrencyInput>(
+  amount: number | bigint,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+  return fromProcessorAmount('Klarna', amount, code, klarnaExponent(code));
+}