@ducatjs/money 0.0.0 → 0.1.0

package/src/allocate.ts

@@ -0,0 +1,393 @@
+import { parseDecimal, pow10n, normalizeMinor } from './decimal.js';
+import {
+  CurrencyMismatchError,
+  compare,
+  make,
+  negate,
+  scaleUp,
+  subtract,
+  toScale,
+  type Money,
+} from './money.js';
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Where the indivisible remainder (always fewer minor units than there are non-zero buckets for
+ * the spreading strategies) goes:
+ * - 'largest'  largest-remainder (Hamilton) method: units go to the buckets with the biggest
+ *              fractional part, ties to the earlier bucket. The default; minimises error per bucket.
+ * - 'first'    one unit each to the first buckets (with non-zero weight)
+ * - 'last'     one unit each to the last buckets
+ * - 'toFirst'  the whole remainder to the first bucket
+ * - 'toLast'   the whole remainder to the last bucket
+ */
+export type Remainder = 'largest' | 'first' | 'last' | 'toFirst' | 'toLast';
+
+/** Options for `allocate` and `split`: where the indivisible remainder goes. */
+export interface AllocateOptions {
+  readonly remainder?: Remainder;
+}
+
+/** A ratio weight: a non-negative integer, bigint or decimal string ('33.3'). */
+export type Weight = number | bigint | string;
+
+function weightsToBig(ws: readonly Weight[]): bigint[] {
+  return weightsScaled(ws).ws;
+}
+
+function weightsScaled(ws: readonly Weight[]): { ws: bigint[]; scale: number } {
+  let scale = 0;
+  const parsed = ws.map((weight) => {
+    if (typeof weight === 'bigint') {
+      return { digits: weight, scale: 0 };
+    }
+    if (typeof weight === 'number' && Number.isSafeInteger(weight)) {
+      return { digits: BigInt(weight), scale: 0 };
+    }
+    const item = parseDecimal(String(weight));
+    return item;
+  });
+  for (const item of parsed) {
+    if (item.digits < 0n) {
+      throw new RangeError('Allocation weights must not be negative');
+    }
+    if (item.scale > scale) {
+      scale = item.scale;
+    }
+  }
+  return { ws: parsed.map((item) => item.digits * pow10n(scale - item.scale)), scale };
+}
+
+/**
+ * Distributes `rem` extra units among the buckets; `frac` are the per-bucket remainders (for
+ * 'largest').
+ */
+function distribute<T extends number | bigint>(
+  shares: T[],
+  rem: number,
+  weights: readonly (number | bigint)[],
+  frac: readonly (number | bigint)[] | null,
+  mode: Remainder,
+  one: T,
+): void {
+  if (rem === 0) {
+    return;
+  }
+  const count = shares.length;
+  const eligible: number[] = [];
+  for (let i = 0; i < count; i++) {
+    if (weights[i]! > 0) {
+      eligible.push(i);
+    }
+  }
+  const plus = (i: number, k: number) => {
+    shares[i] = (
+      typeof one === 'number' ? (shares[i] as number) + k : (shares[i] as bigint) + BigInt(k)
+    ) as T;
+  };
+  switch (mode) {
+    case 'toFirst':
+      return plus(eligible[0]!, rem);
+    case 'toLast':
+      return plus(eligible[eligible.length - 1]!, rem);
+    case 'first':
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[k]!, 1);
+      }
+      return;
+    case 'last':
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[eligible.length - 1 - k]!, 1);
+      }
+      return;
+    case 'largest': {
+      const remainders = frac!;
+      // Largest remainder first; equal remainders keep bucket order.
+      eligible.sort((left, right) => {
+        if (remainders[left]! !== remainders[right]!) {
+          return remainders[left]! > remainders[right]! ? -1 : 1;
+        }
+        return left - right;
+      });
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[k]!, 1);
+      }
+      return;
+    }
+  }
+  throw new RangeError(`Unknown remainder strategy "${String(mode)}"`);
+}
+
+/**
+ * Splits `m` into parts proportional to `weights`. Exact: the parts always sum to `m`, and zero
+ * weights get zero. With 'largest' each part is less than one minor unit from its exact share; with
+ * 'first' and 'last', at most one unit. Negative amounts are allocated as the negation of the
+ * positive allocation. These properties are proved for a Lean model of this function
+ * (proofs/Ducat/Allocate.lean), and test/allocate.oracle.test.ts checks this code against that
+ * model.
+ *
+ *     allocate(money('100', 'EUR'), [1, 1, 1])        // 33.34, 33.33, 33.33
+ *     allocate(money('0.05', 'EUR'), ['70', '30'])    // 0.04, 0.01
+ */
+export function allocate<C extends string>(
+  money: Money<C>,
+  weights: readonly Weight[],
+  options?: AllocateOptions,
+): Money<C>[] {
+  const count = weights.length;
+  if (count === 0) {
+    throw new RangeError('allocate() needs at least one weight');
+  }
+  const mode = options?.remainder ?? 'largest';
+  if (money.minor < 0) {
+    return allocate(negate(money), weights, options).map(negate);
+  }
+  const minor = money.minor;
+
+  // fast path: integer weights whose products with the amount fit exactly in a double
+  if (typeof minor === 'number') {
+    let total = 0;
+    let maxWeight = 0;
+    let ok = true;
+    for (let i = 0; i < count; i++) {
+      const weight = weights[i];
+      if (typeof weight !== 'number' || !(weight >= 0) || !Number.isSafeInteger(weight)) {
+        ok = false;
+        break;
+      }
+      total += weight;
+      if (weight > maxWeight) {
+        maxWeight = weight;
+      }
+    }
+    if (ok && total > 0 && total <= MAX_SAFE_MINOR && minor * maxWeight <= MAX_SAFE_MINOR - total) {
+      const ws = weights as readonly number[];
+      const shares = new Array<number>(count);
+      const frac = new Array<number>(count);
+      let rem = minor;
+      for (let i = 0; i < count; i++) {
+        const product = minor * ws[i]!;
+        let quotient = Math.floor(product / total);
+        let remainder = product - quotient * total;
+        if (remainder < 0) {
+          quotient -= 1;
+          remainder += total;
+        } else if (remainder >= total) {
+          quotient += 1;
+          remainder -= total;
+        } // float-quotient fix-up
+        shares[i] = quotient;
+        frac[i] = remainder;
+        rem -= quotient;
+      }
+      if (rem > 0) {
+        if (mode === 'largest' && count <= 32) {
+          // selection instead of sort: rem < number of non-zero weights, n small
+          for (; rem > 0; rem--) {
+            let best = -1;
+            for (let i = 0; i < count; i++) {
+              if (ws[i]! > 0 && frac[i]! >= 0 && (best < 0 || frac[i]! > frac[best]!)) {
+                best = i;
+              }
+            }
+            shares[best]! += 1;
+            frac[best] = -1;
+          }
+        } else {
+          distribute(shares, rem, ws, frac, mode, 1);
+        }
+      }
+      const out = new Array<Money<C>>(count);
+      for (let i = 0; i < count; i++) {
+        out[i] = make(money.currency, shares[i]!, money.scale);
+      }
+      return out;
+    }
+  }
+
+  const ws = weightsToBig(weights);
+  let total = 0n;
+  for (const weight of ws) {
+    total += weight;
+  }
+  if (total === 0n) {
+    throw new RangeError('Allocation weights must not all be zero');
+  }
+  const xb = BigInt(minor);
+  const shares: bigint[] = new Array(count);
+  const frac: bigint[] = new Array(count);
+  let assigned = 0n;
+  for (let i = 0; i < count; i++) {
+    const product = xb * ws[i]!;
+    shares[i] = product / total;
+    frac[i] = product % total;
+    assigned += shares[i]!;
+  }
+  distribute(shares, Number(xb - assigned), ws, frac, mode, 1n);
+  return shares.map((share) => make(money.currency, share, money.scale));
+}
+
+/** Splits into `count` equal parts; the remainder goes per `remainder` (default 'first'). */
+export function split<C extends string>(
+  money: Money<C>,
+  count: number,
+  options?: AllocateOptions,
+): Money<C>[] {
+  if (!Number.isSafeInteger(count) || count < 1) {
+    throw new RangeError(`Invalid count ${count}`);
+  }
+  const weights = new Array<number>(count).fill(1);
+  return allocate(money, weights, { remainder: options?.remainder ?? 'first' });
+}
+
+/**
+ * Options for `instalments`: where the remainder goes, and an optional unit every regular
+ * instalment is a multiple of.
+ */
+export interface InstalmentOptions<C extends string> {
+  /** Where the remainder goes: default 'toFirst' (first instalment absorbs it). */
+  readonly remainder?: Exclude<Remainder, 'largest'>;
+  /** Make every regular instalment a multiple of this (e.g. money('1', 'EUR') for whole euros). */
+  readonly unit?: Money<C>;
+}
+
+/**
+ * Instalment plan: `count` equal payments, one of which absorbs the remainder.
+ *
+ *     instalments(money('100', 'EUR'), 3)                                   // 33.34, 33.33, 33.33
+ *     instalments(money('100', 'EUR'), 3, { remainder: 'toLast' })          // 33.33, 33.33, 33.34
+ *     instalments(money('100', 'EUR'), 3, { unit: money('1', 'EUR') })      // 34.00, 33.00, 33.00
+ */
+export function instalments<C extends string>(
+  total: Money<C>,
+  count: number,
+  options?: InstalmentOptions<NoInfer<C>>,
+): Money<C>[] {
+  if (!Number.isSafeInteger(count) || count < 1) {
+    throw new RangeError(`Invalid count ${count}`);
+  }
+  const mode = options?.remainder ?? 'toFirst';
+  const unit = options?.unit;
+  if (!unit) {
+    return allocate(total, new Array<number>(count).fill(1), { remainder: mode });
+  }
+  if (unit.currency !== total.currency) {
+    throw new CurrencyMismatchError(total.currency, unit.currency);
+  }
+  if (!(unit.minor > 0)) {
+    throw new RangeError('unit must be positive');
+  }
+  const scale = Math.max(total.scale, unit.scale);
+  const scaledTotal = toScale(total, scale);
+  const unitMinor = BigInt(scaleUp(unit.minor, scale - unit.scale));
+  const neg = scaledTotal.minor < 0;
+  const tv = BigInt(scaledTotal.minor) * (neg ? -1n : 1n);
+  const per = (tv / (unitMinor * BigInt(count))) * unitMinor;
+  const parts = new Array<bigint>(count).fill(per);
+  let left = tv - per * BigInt(count);
+  // spread whole units first (for 'first'/'last'), then the sub-unit leftover
+  if (mode === 'first' || mode === 'last') {
+    for (let k = 0; left >= unitMinor; k++, left -= unitMinor) {
+      parts[mode === 'first' ? k : count - 1 - k]! += unitMinor;
+    }
+  }
+  parts[mode === 'toLast' || mode === 'last' ? count - 1 : 0]! += left;
+  return parts.map((part) => make(total.currency, neg ? -part : part, scale));
+}
+
+/** One tranche of a `schedule`: a fixed amount, a (capped) percentage, or the rest. */
+export type Tranche<C extends string> =
+  | { readonly amount: Money<C> }
+  | { readonly percent: Weight; readonly cap?: Money<C> }
+  | { readonly rest: true };
+
+/**
+ * A payment schedule mixing fixed amounts, percentages of the total (optionally capped) and one
+ * `rest` tranche that receives whatever is left. Percent tranches are computed together with
+ * largest-remainder allocation, so no rounding mode is needed and the schedule is exact.
+ * Throws if the tranches cannot add up to exactly `total`.
+ *
+ *     schedule(money('1000', 'EUR'), [{ percent: 30 }, { amount: money('200', 'EUR') }, { rest: true }])
+ *     // 300.00, 200.00, 500.00
+ */
+export function schedule<C extends string>(
+  total: Money<C>,
+  tranches: readonly Tranche<NoInfer<C>>[],
+): Money<C>[] {
+  const pctIdx: number[] = [];
+  const pcts: Weight[] = [];
+  let restIdx = -1;
+  tranches.forEach((tranche, i) => {
+    if ('percent' in tranche) {
+      pctIdx.push(i);
+      pcts.push(tranche.percent);
+    } else if ('rest' in tranche) {
+      if (restIdx >= 0) {
+        throw new RangeError('schedule() allows only one rest tranche');
+      }
+      restIdx = i;
+    }
+  });
+  const out: (Money<C> | undefined)[] = new Array(tranches.length);
+  let left = total;
+  if (pcts.length) {
+    const { ws, scale } = weightsScaled(pcts);
+    let sum = 0n;
+    for (const weight of ws) {
+      sum += weight;
+    }
+    const hundred = 100n * pow10n(scale);
+    if (sum > hundred) {
+      throw new RangeError('schedule() percentages exceed 100');
+    }
+    const parts = allocate(
+      total,
+      [...ws, hundred - sum].map((weight) => normalizeMinor(weight)),
+    );
+    pctIdx.forEach((trancheIndex, k) => {
+      let part = parts[k]!;
+      const cap = (tranches[trancheIndex] as { cap?: Money<C> }).cap;
+      if (cap && compare(part, cap) > 0) {
+        part = cap;
+      }
+      out[trancheIndex] = part;
+      left = subtract(left, part);
+    });
+  }
+  tranches.forEach((tranche, i) => {
+    if ('amount' in tranche) {
+      out[i] = tranche.amount;
+      left = subtract(left, tranche.amount);
+    }
+  });
+  if (left.minor < 0) {
+    throw new RangeError(`schedule() tranches exceed the total by ${negate(left)}`);
+  }
+  if (restIdx >= 0) {
+    out[restIdx] = left;
+  } else if (left.minor != 0) {
+    throw new RangeError(`schedule() leaves ${left} unassigned; add { rest: true }`);
+  }
+  return out as Money<C>[];
+}
+
+/** Splits into tranches of at most `max` each: chunk(EUR 1000, EUR 300) -> 300, 300, 300, 100. */
+export function chunk<C extends string>(total: Money<C>, max: Money<NoInfer<C>>): Money<C>[] {
+  if (!(max.minor > 0)) {
+    throw new RangeError('chunk() max must be positive');
+  }
+  if (total.minor < 0) {
+    throw new RangeError('chunk() total must not be negative');
+  }
+  const out: Money<C>[] = [];
+  let left = total;
+  while (compare(left, max) > 0) {
+    out.push(max as Money<C>);
+    left = subtract(left, max);
+  }
+  if (left.minor > 0 || out.length === 0) {
+    out.push(left);
+  }
+  return out;
+}

package/src/bag.ts

@@ -0,0 +1,170 @@
+// Mixed-currency amounts: a bag of per-currency totals, converted and rounded once when a single
+// total is needed, and a cross-currency comparator through one base currency (a total preorder, so
+// sorting is well defined).
+import { exact, sumExact, type ExactMoney } from './exact.js';
+import { add, type Money } from './money.js';
+import { rateOf, type RateProvider, type RateQuery } from './provider.js';
+import type { Rate } from './rate.js';
+import type { RoundingMode } from './rounding.js';
+
+/** Options for MoneyBag#total. */
+export interface TotalOptions {
+  readonly asOf?: string | Date;
+  /** Result scale (default: the target currency's exponent). */
+  readonly scale?: number;
+}
+
+function queryFor(asOf: string | Date | undefined): RateQuery | undefined {
+  if (asOf === undefined) {
+    return undefined;
+  }
+  return { asOf };
+}
+
+/** Per-currency totals of `items`, in first-seen order. */
+export function sumByCurrency(items: Iterable<Money>): Map<string, Money> {
+  const totals = new Map<string, Money>();
+  for (const money of items) {
+    const previous = totals.get(money.currency);
+    if (previous === undefined) {
+      totals.set(money.currency, money);
+    } else {
+      totals.set(money.currency, add(previous, money));
+    }
+  }
+  return totals;
+}
+
+/** An immutable set of per-currency totals: `bag(eur10, usd5, eur2).get('EUR')` is EUR 12. */
+export class MoneyBag {
+  readonly #totals: ReadonlyMap<string, Money>;
+
+  /** @internal use bag() */
+  constructor(totals: ReadonlyMap<string, Money>) {
+    // Copied, so a caller who keeps the Map can't change an immutable bag.
+    this.#totals = new Map(totals);
+  }
+
+  /** A new bag with `items` added. */
+  add(...items: Money[]): MoneyBag {
+    return new MoneyBag(sumByCurrency([...this.#totals.values(), ...items]));
+  }
+
+  /** The total in `currency`, or undefined when the bag has none. */
+  get<C extends string>(currency: C): Money<C> | undefined {
+    return this.#totals.get(currency) as Money<C> | undefined;
+  }
+
+  /** The currencies held, in first-seen order. */
+  currencies(): string[] {
+    return [...this.#totals.keys()];
+  }
+
+  /** The per-currency totals, in first-seen order. */
+  values(): Money[] {
+    return [...this.#totals.values()];
+  }
+
+  /** Every entry converted exactly into `to` and summed. Nothing is rounded. */
+  exactTotal<To extends string>(
+    to: To,
+    provider: RateProvider,
+    options?: Pick<TotalOptions, 'asOf'>,
+  ): ExactMoney<To> {
+    const query = queryFor(options?.asOf);
+    const parts: ExactMoney<To>[] = [];
+    for (const money of this.#totals.values()) {
+      if (money.currency === to) {
+        parts.push(exact(money as Money<To>));
+      } else {
+        const rate = rateOf(provider, money.currency, to, query);
+        parts.push(exact(money).convert(rate));
+      }
+    }
+    return sumExact(parts, to);
+  }
+
+  /** The total in `to`, rounded once: `bag.total('EUR', fx, 'halfEven')`. */
+  total<To extends string>(
+    to: To,
+    provider: RateProvider,
+    rounding: RoundingMode,
+    options?: TotalOptions,
+  ): Money<To> {
+    return this.exactTotal(to, provider, options).round(rounding, options?.scale);
+  }
+
+  /** The totals as a list of Money JSON values. */
+  toJSON(): unknown[] {
+    return this.values().map((money) => money.toJSON());
+  }
+}
+
+/** A bag of the per-currency totals of `items`. */
+export function bag(...items: Money[]): MoneyBag {
+  return new MoneyBag(sumByCurrency(items));
+}
+
+/** Options for comparator(). */
+export interface ComparatorOptions {
+  /** Every amount is compared as its exact value in this currency. */
+  readonly base: string;
+  readonly asOf?: string | Date;
+}
+
+/** Converts amounts exactly into `options.base`, looking each currency's rate up once. */
+function baseConverter(
+  provider: RateProvider,
+  options: ComparatorOptions,
+): (money: Money) => ExactMoney {
+  const base = options.base;
+  const query = queryFor(options.asOf);
+  const ratesToBase = new Map<string, Rate>();
+
+  return (money) => {
+    if (money.currency === base) {
+      return exact(money);
+    }
+    let rate = ratesToBase.get(money.currency);
+    if (rate === undefined) {
+      rate = rateOf(provider, money.currency, base, query);
+      ratesToBase.set(money.currency, rate);
+    }
+    return exact(money).convert(rate);
+  };
+}
+
+/**
+ * Compares amounts in any currencies through one base currency, exactly (no rounding, so rounding
+ * makes no ties). One rate per currency makes it a total preorder, so `list.sort(comparator(fx, {
+ * base: 'USD' }))` is consistent. Pairwise conversion with bid/ask or slightly inconsistent mids is
+ * not, and Array#sort's result then differs between engines. Rates are looked up once per currency,
+ * lazily: a missing rate throws from inside `sort`, after the list may already be partly reordered.
+ * `sortByValue` looks every rate up first.
+ */
+export function comparator(
+  provider: RateProvider,
+  options: ComparatorOptions,
+): (money: Money, other: Money) => -1 | 0 | 1 {
+  const inBase = baseConverter(provider, options);
+  return (money, other) => inBase(money).compare(inBase(other));
+}
+
+/**
+ * A new array of `items` in ascending order of their value in `options.base`, as `comparator`
+ * orders them. Every amount is converted before sorting, so a missing rate throws
+ * RateUnavailableError before anything is reordered, and each amount is converted only once.
+ *
+ *     sortByValue([jpy100, gbp1, usd1], fx, { base: 'EUR' })   // [jpy100, usd1, gbp1]
+ */
+export function sortByValue<Item extends Money>(
+  items: Iterable<Item>,
+  provider: RateProvider,
+  options: ComparatorOptions,
+): Item[] {
+  const inBase = baseConverter(provider, options);
+  const keyed = Array.from(items, (item) => ({ item, value: inBase(item) }));
+  // Array#sort is stable, so equal values keep their input order.
+  keyed.sort((first, second) => first.value.compare(second.value));
+  return keyed.map((entry) => entry.item);
+}

package/src/braintree.ts

@@ -0,0 +1,71 @@
+/**
+ * Braintree's amount view (https://developer.paypal.com/braintree/docs/reference/general/currencies,
+ * encoded in data/braintree.json). `amount` is a decimal string in major units, "formatted like
+ * '10' or '10.00'":
+ * - zero-decimal currencies can't include decimals: BIF CLP DJF GNF ISK JPY KMF KRW LAK PYG RWF UGX
+ *   VND VUV XAF XOF XPF (LAK has 2 in ISO 4217);
+ * - the others take their ISO decimals ("10.00"). No three-decimal currency is listed.
+ * Amounts must be greater than zero, refunds and credits included.
+ */
+import { BRAINTREE_EXPONENTS } from './generated/braintree.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorDecimal, toProcessorDecimal } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { BRAINTREE_EXPONENTS };
+
+/** "Can only contain numbers and one decimal point (e.g. x.xx)". */
+const AMOUNT_PATTERN = /^[0-9]+(\.[0-9]+)?$/;
+
+/** The number of decimals Braintree takes for a currency (JPY 0, LAK 0, USD 2). */
+export function braintreeExponent(currency: string): number {
+  const exponent = BRAINTREE_EXPONENTS[currency.toUpperCase()];
+  if (exponent === undefined) {
+    throw new RangeError(`${currency} is not a Braintree currency`);
+  }
+  return exponent;
+}
+
+/** Whether Braintree lists the currency (case-insensitive). */
+export function isBraintreeCurrency(currency: string): boolean {
+  return BRAINTREE_EXPONENTS[currency.toUpperCase()] !== undefined;
+}
+
+/** Options for the Braintree amount: how to round when Braintree needs a coarser amount. */
+export interface BraintreeAmountOptions {
+  /**
+   * How to round when Braintree needs fewer decimals than the value has (default 'unnecessary':
+   * throw).
+   */
+  readonly rounding?: RoundingMode;
+}
+
+/**
+ * The exact `amount` string: toBraintree(money('10', 'USD')) === '10.00', JPY 100 -> '100'.
+ * Braintree has no currency field on a transaction: the merchant account sets it.
+ * Throws a RangeError for zero or negative amounts.
+ */
+export function toBraintree(money: Money, options?: BraintreeAmountOptions): string {
+  const rounding = options?.rounding ?? 'unnecessary';
+
+  // 81531 "Amount must be greater than zero"; 81501: credits are positive too ("x.xx, not -x.xx").
+  return toProcessorDecimal(
+    'Braintree',
+    money,
+    braintreeExponent(money.currency),
+    rounding,
+    'positive',
+  );
+}
+
+/** Reads a Braintree amount string exactly: fromBraintree('10.00', 'USD'). */
+export function fromBraintree<C extends CurrencyInput>(
+  amount: string,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+
+  // Validates the currency before parsing, so an unlisted currency is the error reported.
+  braintreeExponent(code);
+  return fromProcessorDecimal('Braintree', amount, code, AMOUNT_PATTERN);
+}