@ducatjs/money 0.1.0 → 0.2.0

package/src/money.ts

@@ -32,6 +32,56 @@ export interface MoneyJSON<C extends string = string> {
   readonly currency: C;
 }
 
+/**
+ * A reusable rounding rule: a scale, an increment at that scale and a rounding mode, such as "CHF
+ * cash" (scale 2, increment 5, half up) or "4 decimals, half even". Build one with `roundingPolicy()`
+ * from `@ducatjs/money/policy` (or `cashPolicy()` from `@ducatjs/money/cash`) and pass it wherever
+ * a rounding mode is accepted: `m.multiply('1.075', policy)`, `m.round(policy)`. A policy is also
+ * a function that rounds an amount, so `m.with(policy)` and `amounts.map(policy)` work too.
+ *
+ * Policies are plain values passed explicitly; they are never stored on amounts or set globally.
+ */
+export interface RoundingPolicy {
+  /** Rounds `money` to this policy (exactly like `round(money, policy)`). */
+  <C extends string>(money: Money<C>): Money<C>;
+  /** Decimal places of the result; `undefined` means the currency's ISO exponent. */
+  readonly scale: number | undefined;
+  /** The result is a multiple of this many 10^-scale units (1 for plain rounding, 5 for 0.05). */
+  readonly increment: number;
+  /** How to round to the increment. */
+  readonly rounding: RoundingMode;
+  /** The one currency the policy is for, if any; other currencies throw `CurrencyMismatchError`. */
+  readonly currency: string | undefined;
+  /**
+   * @internal money × factor, rounded once to this policy, under a key only this copy of the
+   * package can build. The core calls it for every operation given a policy, so the policy code
+   * stays out of bundles that never build one.
+   */
+  readonly [ROUND_PRODUCT]: <C extends string>(money: Money<C>, factor: Ratio) => Money<C>;
+}
+
+/**
+ * @internal The key a policy's rounding function is stored under. Module-private, so only
+ * `roundingPolicy` from this copy of the package makes values the core accepts as policies: a
+ * lookalike function, or a policy from a second installed copy (whose results would be that copy's
+ * Money), is rejected with a TypeError, as `isMoney` rejects the other copy's Money.
+ */
+export const ROUND_PRODUCT: unique symbol = Symbol();
+
+/**
+ * @internal money × factor rounded by a policy. Anything not built by `roundingPolicy` lacks the
+ * private key, so calling it throws a TypeError; that is the whole check, kept this small because
+ * it is in every bundle.
+ */
+export const roundWithPolicy = <C extends string>(
+  money: Money<C>,
+  factor: Ratio,
+  policy: RoundingPolicy,
+): Money<C> => policy[ROUND_PRODUCT](money, factor);
+
+/** What rounding parameters accept: a mode such as `'halfEven'`, or a `RoundingPolicy`. */
+export type RoundingInput = RoundingMode | RoundingPolicy;
+
 /** Thrown when two amounts in different currencies are combined. */
 export class CurrencyMismatchError extends TypeError {
   override name = 'CurrencyMismatchError';
@@ -103,11 +153,11 @@ class Money<C extends string = string> {
    * this * factor, rounded to this scale. `factor` is exact: integer, decimal string ('1.075'),
    * bigint or ratio().
    */
-  multiply(factor: Factor, rounding?: RoundingMode): Money<C> {
+  multiply(factor: Factor, rounding?: RoundingInput): Money<C> {
     return multiply(this, factor, rounding);
   }
-  /** this / divisor, rounded to this scale */
-  divide(divisor: Factor, rounding?: RoundingMode): Money<C> {
+  /** this / divisor, rounded to this scale (or to a policy's scale and increment) */
+  divide(divisor: Factor, rounding?: RoundingInput): Money<C> {
     return divide(this, divisor, rounding);
   }
   negate(): Money<C> {
@@ -116,9 +166,12 @@ class Money<C extends string = string> {
   abs(): Money<C> {
     return abs(this);
   }
-  /** Rounds to the currency's exponent (or `scale`). */
-  round(rounding: RoundingMode, scale?: number): Money<C> {
-    return round(this, rounding, scale);
+  /** Rounds to the currency's exponent (or `scale`), or to a rounding policy. */
+  round(rounding: RoundingMode, scale?: number): Money<C>;
+  round(policy: RoundingPolicy): Money<C>;
+  round(rounding: RoundingInput, scale?: number): Money<C> {
+    // the free function handles both; the cast only picks its implementation signature
+    return round(this, rounding as RoundingMode, scale);
   }
   /** Changes the scale; decreasing it rounds (default 'halfExpand'). */
   toScale(scale: number, rounding?: RoundingMode): Money<C> {
@@ -167,7 +220,27 @@ class Money<C extends string = string> {
     return clamp(this, lo, hi);
   }
 
+  /** Same currency, value and scale: 1.0 EUR is not identical to 1.00 EUR. */
+  identical(other: Money): boolean {
+    return identical(this, other);
+  }
+  /**
+   * Applies `operation` to this amount and returns its result, so a rounding policy or a
+   * conversion reads as one step in a chain: `price.multiply('1.075').with(toCash)`.
+   */
+  with<R>(operation: (money: Money<C>) => R): R {
+    return operation(this);
+  }
+
   // output
+  /** The whole major units, truncated toward zero: 12 for 12.34 EUR, -12 for -12.34 EUR. */
+  majorPart(): number | bigint {
+    return majorPart(this);
+  }
+  /** The rest in 10^-scale units, with the amount's sign: 34 for 12.34 EUR, -34 for -12.34. */
+  minorPart(): number | bigint {
+    return minorPart(this);
+  }
   /** Exact decimal string in major units: "12.34" */
   toDecimal(): string {
     return formatScaled(this.minor, this.scale);
@@ -188,6 +261,33 @@ export function isMoney(value: unknown): value is Money {
   return value instanceof Money;
 }
 
+/**
+ * Whether a value is a Money in `currency`. It narrows a currency known only at run time
+ * (`Money<string>`, or `unknown`) to the literal type:
+ *
+ *     if (isMoneyIn(price, 'EUR')) { price.add(money('1', 'EUR')) }
+ */
+export function isMoneyIn<C extends CurrencyInput>(value: unknown, currency: C): value is Money<C> {
+  return value instanceof Money && value.currency === currency;
+}
+
+/**
+ * Narrows `money` to `Money<C>`, or throws a `CurrencyMismatchError` if it is in another
+ * currency. Use it where a different currency is a bug rather than a branch.
+ */
+export function assertCurrency<C extends CurrencyInput>(
+  money: Money,
+  currency: C,
+): asserts money is Money<C> {
+  // A non-Money would otherwise pass when it happens to have a matching `currency` field.
+  if (!(money instanceof Money)) {
+    throw new TypeError(`Expected Money, got ${typeof money}`);
+  }
+  if (money.currency !== currency) {
+    throw new CurrencyMismatchError(currency, money.currency);
+  }
+}
+
 /**
  * Which module installed each added method, so a second copy of the same module can replace its
  * own.
@@ -546,10 +646,16 @@ export function abs<C extends string>(money: Money<C>): Money<C> {
 export function multiply<C extends string>(
   money: Money<C>,
   factor: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): Money<C> {
   const minor = money.minor;
-  if (typeof factor === 'number' && Number.isSafeInteger(factor) && typeof minor === 'number') {
+  // An integer product is exact at this scale, but a policy may ask for another scale or increment.
+  if (
+    typeof factor === 'number' &&
+    Number.isSafeInteger(factor) &&
+    typeof minor === 'number' &&
+    typeof rounding === 'string'
+  ) {
     const product = minor * factor;
     if (product <= MAX_SAFE_MINOR && product >= -MAX_SAFE_MINOR) {
       return new Money(money.currency, product + 0, money.scale);
@@ -558,13 +664,16 @@ export function multiply<C extends string>(
   return multiplyByRatio(money, ratio(factor), rounding);
 }
 
-/** @internal m * r, rounded */
+/** @internal m * r, rounded with a mode (at `scale`) or with a policy (at the policy's scale) */
 export function multiplyByRatio<C extends string>(
   money: Money<C>,
   factor: Ratio,
-  rounding: RoundingMode,
+  rounding: RoundingInput,
   scale = money.scale,
 ): Money<C> {
+  if (typeof rounding === 'function') {
+    return roundWithPolicy(money, factor, rounding);
+  }
   const minor = money.minor;
   if (
     typeof minor === 'number' &&
@@ -588,16 +697,55 @@ export function multiplyByRatio<C extends string>(
   return make(money.currency, divideAndRoundBigint(numerator, denominator, rounding), scale);
 }
 
-/** m / divisor, rounded to m's scale (default 'halfExpand'). */
+/** m / divisor, rounded to m's scale (default 'halfExpand'), or with a rounding policy. */
 export function divide<C extends string>(
   money: Money<C>,
   divisor: Factor,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
 ): Money<C> {
   const divisorRatio = ratio(divisor);
   if (divisorRatio.num === 0n) {
     throw new RangeError('Division by zero');
   }
+
+  // Fast path: m / (n/d) = m·d / n, rounded once by the same kernel the ratio path uses. Building
+  // the inverse ratio d/n would cost bigint arithmetic and a gcd on every call; the divisor's own
+  // ratio is cached for small integers and strings. Why it is exact:
+  // - makeRatio guarantees d > 0 and n/d in lowest terms, so m·d / n is the same fraction the
+  //   inverse ratio d/n would give, and only n's sign needs handling;
+  // - `x === x` is false only for NaN, which is how a Ratio marks a part that is not a safe
+  //   integer, so both parts are safe integers here;
+  // - m and d are safe integers, so a float product beyond 2^53 - 1 cannot round back down into
+  //   the safe range: the bound check below rejects every inexact product;
+  // - divideAndRound corrects its float quotient exactly (and takes the bigint kernel itself when
+  //   dividend + divisor exceeds the safe range).
+  // A rounding policy (a function, not a mode string) must not take this path: it rounds to its own
+  // scale and increment.
+  const minor = money.minor;
+  const numerator = divisorRatio.n;
+  const denominator = divisorRatio.d;
+  if (
+    typeof minor === 'number' &&
+    typeof rounding === 'string' &&
+    numerator === numerator &&
+    denominator === denominator
+  ) {
+    let dividend = minor * denominator;
+    if (dividend <= MAX_SAFE_MINOR && dividend >= -MAX_SAFE_MINOR) {
+      // divideAndRound needs a positive divisor: (−p)/(−n) is the same quotient
+      let positiveDivisor = numerator;
+      if (numerator < 0) {
+        dividend = 0 - dividend;
+        positiveDivisor = 0 - numerator;
+      }
+      return new Money(
+        money.currency,
+        divideAndRound(dividend, positiveDivisor, rounding),
+        money.scale,
+      );
+    }
+  }
+
   return multiplyByRatio(money, ratio(divisorRatio.den, divisorRatio.num), rounding);
 }
 
@@ -609,7 +757,17 @@ export function round<C extends string>(
   money: Money<C>,
   rounding: RoundingMode,
   scale?: number,
+): Money<C>;
+/** Rounds to a policy's scale and increment: `round(money('10.03', 'CHF'), cashPolicy('CHF'))`. */
+export function round<C extends string>(money: Money<C>, policy: RoundingPolicy): Money<C>;
+export function round<C extends string>(
+  money: Money<C>,
+  rounding: RoundingInput,
+  scale?: number,
 ): Money<C> {
+  if (typeof rounding === 'function') {
+    return roundWithPolicy(money, ratio(1), rounding);
+  }
   return toScale(money, scale ?? currencyExponent(money.currency), rounding);
 }
 
@@ -670,6 +828,17 @@ export function equals(money: Money, other: Money): boolean {
   return compare(money, other) === 0;
 }
 
+/**
+ * Same currency, same value *and* same scale, with number and bigint minor units counted as equal.
+ * `equals` treats 1.0 EUR (scale 1) and 1.00 EUR as equal; `identical` does not. For round-trip
+ * tests, where the scale must survive too.
+ */
+export function identical(money: Money, other: Money): boolean {
+  return (
+    money.currency === other.currency && money.scale === other.scale && money.minor == other.minor
+  );
+}
+
 /** money < other (same currency; any scale). */
 export const lessThan = <C extends string>(money: Money<C>, other: Money<NoInfer<C>>): boolean =>
   compare(money, other) < 0;
@@ -747,6 +916,35 @@ export function toDecimal(money: Money): string {
   return formatScaled(money.minor, money.scale);
 }
 
+/**
+ * The whole major units, truncated toward zero: 12 for 12.34 EUR and -12 for -12.34 EUR. A number
+ * while it is a safe integer, a bigint beyond, like `minor`.
+ */
+export function majorPart(money: Money): number | bigint {
+  const minor = money.minor;
+  if (typeof minor === 'number' && money.scale <= 15) {
+    // Taking the remainder out first leaves an exact multiple, so the division is exact. `+ 0`
+    // turns -0 into 0.
+    const unit = POW10[money.scale]!;
+    return (minor - (minor % unit)) / unit + 0;
+  }
+  // bigint division truncates toward zero, like the fast path
+  return normalizeMinor(toBigInt(minor) / pow10n(money.scale));
+}
+
+/**
+ * What is left after `majorPart`, in 10^-scale units and with the amount's sign: 34 for 12.34
+ * EUR, -34 for -12.34 EUR, 5 for 1.005 EUR at scale 3.
+ */
+export function minorPart(money: Money): number | bigint {
+  const minor = money.minor;
+  if (typeof minor === 'number' && money.scale <= 15) {
+    // % on safe integers is exact and keeps the dividend's sign; `+ 0` turns -0 into 0.
+    return (minor % POW10[money.scale]!) + 0;
+  }
+  return normalizeMinor(toBigInt(minor) % pow10n(money.scale));
+}
+
 /** Minor units as a bigint (always safe; use for BIGINT columns). */
 export function toMinor(money: Money): bigint {
   return toBigInt(money.minor);