@ducatjs/money 0.2.1 → 0.3.0

package/src/money.ts

@@ -1,6 +1,8 @@
 import { currencyExponent, type CurrencyCode } from './currency.js';
 import {
   formatScaled,
+  faithfulDecimal,
+  checkScale,
   parseDecimal,
   parsePlainDecimal,
   POW10,
@@ -21,6 +23,13 @@ import {
 // A module-local constant, not an import: the hot loops (sum, add) read it on every iteration, and
 // V8 reads an imported binding through an extra indirection.
 const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+// MAX_DECIMAL_SCALE from decimal.ts, kept local: the scale checks below run on every toScale and on
+// every fromMinor with a scale, where an imported constant (or a call into decimal.ts) costs a
+// lookup. test/scale-validation.test.ts checks the two stay equal.
+const MAX_SCALE = 1000;
+
+/** A valid scale: an integer from 0 to MAX_SCALE (`>>> 0` changes negatives, fractions and NaN). */
+const isValidScale = (scale: number): boolean => scale >>> 0 === scale && scale <= MAX_SCALE;
 
 /** Currency codes accepted by constructors: known codes autocomplete, any string is allowed. */
 export type CurrencyInput = CurrencyCode | (string & {});
@@ -135,124 +144,6 @@ class Money<C extends string = string> {
       'Money cannot be converted to a number; use add(), compare(), toDecimal() etc.',
     );
   }
-
-  // Methods. Each one is a thin wrapper over the free function of the same name (also exported), so
-  // `a.add(b)` and `add(a, b)` are the same code. Operands are Money only: a bare number is never
-  // guessed to mean major or minor units.
-
-  // arithmetic
-  /** this + other (same currency; any scale) */
-  add(other: Money<C>): Money<C> {
-    return add(this, other);
-  }
-  /** this - other */
-  subtract(other: Money<C>): Money<C> {
-    return subtract(this, other);
-  }
-  /**
-   * this * factor, rounded to this scale. `factor` is exact: integer, decimal string ('1.075'),
-   * bigint or ratio().
-   */
-  multiply(factor: Factor, rounding?: RoundingInput): Money<C> {
-    return multiply(this, factor, rounding);
-  }
-  /** 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> {
-    return negate(this);
-  }
-  abs(): Money<C> {
-    return abs(this);
-  }
-  /** 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> {
-    return toScale(this, scale, rounding);
-  }
-  // comparison
-  /** -1, 0 or 1; throws on currency mismatch */
-  compare(other: Money<C>): -1 | 0 | 1 {
-    return compare(this, other);
-  }
-  /** same currency and value; a different currency is simply not equal */
-  equals(other: Money): boolean {
-    return equals(this, other);
-  }
-  lessThan(other: Money<C>): boolean {
-    return compare(this, other) < 0;
-  }
-  lessThanOrEqual(other: Money<C>): boolean {
-    return compare(this, other) <= 0;
-  }
-  greaterThan(other: Money<C>): boolean {
-    return compare(this, other) > 0;
-  }
-  greaterThanOrEqual(other: Money<C>): boolean {
-    return compare(this, other) >= 0;
-  }
-  isZero(): boolean {
-    return this.minor == 0;
-  }
-  isPositive(): boolean {
-    return this.minor > 0;
-  }
-  isNegative(): boolean {
-    return this.minor < 0;
-  }
-  sign(): -1 | 0 | 1 {
-    return sign(this);
-  }
-  min(...others: Money<C>[]): Money<C> {
-    return min(this, ...others);
-  }
-  max(...others: Money<C>[]): Money<C> {
-    return max(this, ...others);
-  }
-  clamp(lo: Money<C>, hi: Money<C>): Money<C> {
-    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);
-  }
-  /** Minor units as a bigint (BIGINT columns) */
-  toMinor(): bigint {
-    return toBigInt(this.minor);
-  }
-  /** Minor units as a number; throws beyond 2^53 */
-  toMinorNumber(): number {
-    return toMinorNumber(this);
-  }
 }
 export type { Money };
 
@@ -292,14 +183,16 @@ export function assertCurrency<C extends CurrencyInput>(
  * Which module installed each added method, so a second copy of the same module can replace its
  * own.
  */
-const methodOwners = new Map<string, string>();
+const methodOwners = /* @__PURE__ */ new Map<string, string>();
 
 /**
  * Names `extendMoney` refuses: the ones every object inherits, whose meaning other code relies on.
  * `toLocaleString` is allowed, since a formatting module may want to provide it.
  */
-const RESERVED_NAMES = new Set(
-  Object.getOwnPropertyNames(Object.prototype).filter((name) => name !== 'toLocaleString'),
+const RESERVED_NAMES = /* @__PURE__ */ new Set(
+  /* @__PURE__ */ Object.getOwnPropertyNames(Object.prototype).filter(
+    (name) => name !== 'toLocaleString',
+  ),
 );
 
 /** Options for `extendMoney`. */
@@ -355,6 +248,33 @@ export function extendMoney(
   }
 }
 
+// the names installCoreMethods has installed, so loading it again replaces its own methods only
+const coreMethodNames = /* @__PURE__ */ new Set<string>();
+
+/**
+ * @internal Installs the core methods (src/plugins/core.ts) on Money.prototype, non-enumerable like
+ * class methods. Kept apart from `extendMoney`, whose name checks the methods bundle doesn't need.
+ */
+export function installCoreMethods(methods: Record<string, unknown>): void {
+  // A program that imports only /fn can extendMoney a core name; the root entry must not then
+  // replace it silently. Reinstalling the core methods themselves (core.js loaded again, as hot
+  // reload does) is fine. Every name is checked before any is installed, so a throw changes nothing.
+  for (const name in methods) {
+    if (Object.hasOwn(Money.prototype, name) && !coreMethodNames.has(name)) {
+      throw new TypeError(`Money#${name} was defined before the core methods were installed`);
+    }
+  }
+  for (const name in methods) {
+    coreMethodNames.add(name);
+    Object.defineProperty(Money.prototype, name, {
+      value: methods[name],
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+}
+
 /** @internal construct from a value that may be an unsafe bigint */
 export function make<C extends string>(
   currency: C,
@@ -366,6 +286,9 @@ export function make<C extends string>(
 
 const toBigInt = (minor: number | bigint) => (typeof minor === 'bigint' ? minor : BigInt(minor));
 
+// scaleUp and scaleDown have a copy in src/scale.ts, for Fixed, which must not load this module;
+// test/fixed.test.ts checks that the copies agree.
+
 /** v * 10^e exactly (e >= 0) */
 export function scaleUp(minor: number | bigint, exponent: number): number | bigint {
   if (exponent === 0) {
@@ -415,15 +338,20 @@ export interface MoneyOptions {
  *     money(12.34, 'EUR')     // non-integer numbers are read at their shortest decimal form ("12.34")
  *     money(10n ** 30n, 'USD')
  *
+ * A string is an optional sign, ASCII digits, optionally a point with digits after it, and
+ * optionally an exponent (`'1.5e3'`); `'.5'`, `'5.'`, grouping and surrounding whitespace throw a
+ * SyntaxError (use `parse()` for text as people write it).
+ *
  * Throws if the amount has more decimals than the currency (or `scale`) unless `rounding` is given,
- * so `money(0.1 + 0.2, 'EUR')` throws rather than silently becoming 0.30.
+ * so `money(0.1 + 0.2, 'EUR')` throws rather than silently becoming 0.30. Without `rounding`, a
+ * number whose shortest form has more than 15 significant digits throws a RangeError too.
  */
 export function money<C extends CurrencyInput>(
   amount: string | number | bigint,
   currency: C,
   options?: MoneyOptions,
 ): Money<C> {
-  const scale = options?.scale ?? currencyExponent(currency);
+  const scale = resolveScale(currency, options?.scale);
   if (typeof amount === 'string') {
     const parsed = parsePlainDecimal(amount) ?? parseDecimal(amount);
     return fromScaled(
@@ -442,15 +370,22 @@ export function money<C extends CurrencyInput>(
     if (!Number.isFinite(amount)) {
       throw new RangeError(`Invalid amount ${amount}`);
     }
+    const rounding = options?.rounding;
     const parsed = parseDecimal(String(amount));
-    return fromScaled(
+    const result = fromScaled(
       currency,
       parsed.digits,
       parsed.scale,
       scale,
-      options?.rounding ?? 'unnecessary',
+      rounding ?? 'unnecessary',
       amount,
     );
+    // Only an explicit rounding mode says a float's extra digits may be dropped. Checked after
+    // fromScaled, so 0.1 + 0.2 at EUR's scale is still a RoundingError for its decimals.
+    if (rounding === undefined) {
+      faithfulDecimal(amount, 'pass a string, or { rounding }');
+    }
+    return result;
   }
   if (typeof amount === 'bigint') {
     return make(currency, scaleUp(normalizeMinor(amount), scale), scale);
@@ -497,10 +432,15 @@ export function fromMinor<C extends CurrencyInput>(
   currency: C,
   scale?: number,
 ): Money<C> {
-  const resolvedScale = scale ?? currencyExponent(currency);
+  const resolvedScale = resolveScale(currency, scale);
   if (typeof minor === 'number') {
     if (!Number.isSafeInteger(minor)) {
-      throw new RangeError(`Minor units must be a safe integer, got ${minor}; pass a bigint`);
+      // A bigint only helps an integer too large to be safe; a fraction needs a different fix.
+      throw new RangeError(
+        Number.isInteger(minor)
+          ? `Minor units must be a safe integer, got ${minor}; pass a bigint`
+          : `Minor units must be an integer, got ${minor}`,
+      );
     }
     return new Money(currency, minor + 0, resolvedScale);
   }
@@ -512,7 +452,19 @@ export function fromMinor<C extends CurrencyInput>(
 
 /** Zero in a currency, at its exponent (or `scale`). */
 export function zero<C extends CurrencyInput>(currency: C, scale?: number): Money<C> {
-  return new Money(currency, 0, scale ?? currencyExponent(currency));
+  return new Money(currency, 0, resolveScale(currency, scale));
+}
+
+/**
+ * @internal The scale to build a value at: `scale`, or the currency's exponent. The currency is
+ * looked up either way, because an explicit scale doesn't make an unknown code valid.
+ */
+export function resolveScale(currency: string, scale: number | undefined): number {
+  const exponent = currencyExponent(currency);
+  if (scale === undefined || isValidScale(scale)) {
+    return scale ?? exponent;
+  }
+  return checkScale(scale); // throws the shared message
 }
 
 // ---------------------------------------------------------------------------------------------
@@ -520,6 +472,10 @@ export function zero<C extends CurrencyInput>(currency: C, scale?: number): Mone
 // ---------------------------------------------------------------------------------------------
 
 function mismatch(money: Money, other: Money): never {
+  // only reached on the error path, so this check costs correct calls nothing
+  if (!((other as unknown) instanceof Money)) {
+    throw new TypeError(`Expected Money, got ${typeof other}`);
+  }
   throw new CurrencyMismatchError(money.currency, other.currency);
 }
 
@@ -568,10 +524,10 @@ export function subtract<C extends string>(money: Money<C>, other: Money<NoInfer
 
 type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
 /**
- * Rejects arrays whose element type mixes several literal currencies, e.g. (Money<'EUR'> |
- * Money<'USD'>)[].
+ * @internal Rejects arrays whose element type mixes several literal currencies, e.g. (Money<'EUR'>
+ * | Money<'USD'>)[].
  */
-type SingleCurrency<C extends string> =
+export type SingleCurrency<C extends string> =
   true extends IsUnion<C> ? { readonly 'mixed currencies are not allowed': C } : unknown;
 
 /** Sum of a list (same currency; any scale). An empty list needs `currency` and returns zero. */
@@ -721,6 +677,8 @@ export function divide<C extends string>(
   //   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.
+  // divideSafeByRatio in rounding.ts is the same steps as a function, for Fixed; a call here costs
+  // about 4% on the divide benchmarks. test/divide.test.ts checks that the two copies agree.
   const minor = money.minor;
   const numerator = divisorRatio.n;
   const denominator = divisorRatio.d;
@@ -751,7 +709,8 @@ export function divide<C extends string>(
 
 /**
  * Rounds to the currency's exponent (or `scale`): `round(money('1.005', 'EUR', {scale: 3}),
- * 'halfEven')`.
+ * 'halfEven')`. A scale is never negative: round to tens or hundreds with an increment
+ * (`roundingPolicy({ scale: 0, increment: 100 })`, or `roundToIncrement` from `/cash`).
  */
 export function round<C extends string>(
   money: Money<C>,
@@ -773,18 +732,21 @@ export function round<C extends string>(
 
 /**
  * Changes the scale; increasing it is always exact, decreasing it rounds (default 'halfExpand').
+ * Scales are integers from 0 to 1000; for tens or hundreds, use an increment (a rounding policy, or
+ * `roundToIncrement` from `/cash`).
  */
 export function toScale<C extends string>(
   money: Money<C>,
   scale: number,
   rounding: RoundingMode = DEFAULT_ROUNDING,
 ): Money<C> {
-  if (!Number.isInteger(scale) || scale < 0) {
-    throw new RangeError(`Invalid scale ${scale}`);
-  }
+  // a value's own scale is always valid, so this needs no check
   if (scale === money.scale) {
     return money;
   }
+  if (!isValidScale(scale)) {
+    checkScale(scale); // throws the shared message
+  }
   if (scale > money.scale) {
     return make(money.currency, scaleUp(money.minor, scale - money.scale), scale);
   }
@@ -945,17 +907,53 @@ export function minorPart(money: Money): number | bigint {
   return normalizeMinor(toBigInt(minor) % pow10n(money.scale));
 }
 
-/** Minor units as a bigint (always safe; use for BIGINT columns). */
+/**
+ * Units of the currency's minor unit (cents for EUR) as a bigint, for BIGINT columns and APIs that
+ * take ISO 4217 minor units. Exact at any scale: 1.5 EUR at scale 1 is 150n, and 12.340 EUR at
+ * scale 3 is 1234n. Throws RoundingError when the amount has non-zero digits below the minor unit
+ * (12.345 EUR); round() it first. For units of the value's own scale, use `toScaledUnits`.
+ */
 export function toMinor(money: Money): bigint {
-  return toBigInt(money.minor);
+  const shift = currencyExponent(money.currency) - money.scale;
+  const scaled = toBigInt(money.minor);
+
+  // At or below the exponent, scaling up is exact.
+  if (shift >= 0) {
+    return scaled * pow10n(shift);
+  }
+
+  // Above it, the conversion is exact only when the extra digits are all zero.
+  const divisor = pow10n(-shift);
+  if (scaled % divisor !== 0n) {
+    throw new RoundingError(`${money} has digits below the minor unit; round() it first`);
+  }
+  return scaled / divisor;
 }
 
-/** Minor units as a number; throws if not a safe integer. */
+/**
+ * Like `toMinor`, as a number. Throws RoundingError for digits below the minor unit, and a
+ * RangeError when the result isn't a safe integer.
+ */
 export function toMinorNumber(money: Money): number {
-  if (typeof money.minor === 'bigint') {
+  // The common case, a number at the currency's exponent, needs no conversion.
+  if (typeof money.minor === 'number' && money.scale === currencyExponent(money.currency)) {
+    return money.minor;
+  }
+
+  const minor = normalizeMinor(toMinor(money));
+  if (typeof minor === 'bigint') {
     throw new RangeError(`${money} does not fit in a safe integer; use toMinor()`);
   }
-  return money.minor;
+  return minor;
+}
+
+/**
+ * The amount in units of 10^-scale, as a bigint: 12340n for 12.340 EUR at scale 3. Store it
+ * together with the scale (as the scale-column helpers do); for the currency's minor units, use
+ * `toMinor`.
+ */
+export function toScaledUnits(money: Money): bigint {
+  return toBigInt(money.minor);
 }
 
 /** Parses `{ amount: "12.34", currency: "EUR" }` (as produced by JSON.stringify(money)). */

package/src/parse.ts

@@ -7,7 +7,7 @@ interface Symbols {
   /** The locale's group sizes, looked up the first time a group separator is seen. */
   groupSizes?: readonly GroupSizes[];
 }
-const symCache = new Map<string, Symbols>();
+const symCache = /* @__PURE__ */ new Map<string, Symbols>();
 
 /**
  * The group and decimal separators `format()` uses for this locale and currency. They come from a
@@ -215,12 +215,12 @@ export interface ParseMoneyOptions<C extends string = string> extends MoneyOptio
   readonly lenient?: boolean;
 }
 
-const symbolTables = new Map<string, Map<string, Set<string>>>();
-const groupSizeCache = new Map<string, GroupSizes[]>();
+const symbolTables = /* @__PURE__ */ new Map<string, Map<string, Set<string>>>();
+const groupSizeCache = /* @__PURE__ */ new Map<string, GroupSizes[]>();
 
 /** The size of the last group, and of the groups before it: [3, 3] for 1,234,567, [3, 2] for 12,34,567. */
 type GroupSizes = readonly [number, number];
-const supportedLocales = new Map<string, boolean>();
+const supportedLocales = /* @__PURE__ */ new Map<string, boolean>();
 
 /** Strips what surrounds a symbol in formatted output: spaces, no-break spaces and bidi marks. */
 const normalizeSymbol = (text: string) => text.replace(/[\s\p{Z}\p{Cf}]/gu, '');
@@ -321,15 +321,15 @@ function meaningsOf(
   piece: string,
   locale: string,
   candidates: ReadonlySet<string> | undefined,
-  symbols: Readonly<Record<string, string>> | undefined,
+  customSymbols: Readonly<Record<string, string>> | undefined,
 ): string[] {
   const isCandidate = (code: string) =>
     candidates === undefined ? defaultCandidates().includes(code) : candidates.has(code);
   if (/^[A-Z]{3}$/.test(piece) && isCandidate(piece)) {
     return [piece];
   }
-  if (symbols !== undefined && Object.hasOwn(symbols, piece)) {
-    return [symbols[piece]!];
+  if (customSymbols !== undefined && Object.hasOwn(customSymbols, piece)) {
+    return [customSymbols[piece]!];
   }
   // The locale's own symbols first, then English ones (US$, CA$, A$...), which many texts use.
   for (const source of [locale, ...ENGLISH_SYMBOL_LOCALES]) {

package/src/plugins/adyen.ts

@@ -1,4 +1,6 @@
 /** `@ducatjs/money/adyen`: Adyen's minor-unit view. Importing this module adds `toAdyen`. */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { toAdyen } from '../adyen.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/all.ts

@@ -1,4 +1,6 @@
 /** `@ducatjs/money/all`: core plus every opt-in module, with all methods installed. */
+// the core methods directly, not only through the root entry, so no bundler can drop them
+import './core.js';
 export * from '../index.js';
 // The core Money methods as plain functions too, as in /fn: /all is everything.
 export {
@@ -29,10 +31,13 @@ export {
   toDecimal,
   toMinor,
   toMinorNumber,
+  toScaledUnits,
 } from '../money.js';
 export { roundingPolicy, isoPolicy, assertScale, type RoundingPolicyOptions } from '../policy.js';
 export * from './allocate.js';
 export * from './tax.js';
+export * from '../pricing.js';
+export * from './math.js';
 export * from './convert.js';
 export * from './exact.js';
 export * from '../ecb.js';
@@ -45,6 +50,19 @@ export * from '../stripe-fx.js';
 export * from '../adyen-fx.js';
 export * from './cash.js';
 export * from '../historic.js';
+export * from '../crypto.js';
+export * from '../currencies.js';
+export * from '../wire.js';
+export * from '../words.js';
+export * from '../words/de.js';
+export * from '../words/en.js';
+export * from '../words/es.js';
+export * from '../words/fr.js';
+export * from '../words/it.js';
+export * from '../words/nl.js';
+export * from '../words/pt.js';
+export * from '../territories.js';
+export * from '../finance.js';
 export * from './format.js';
 export * from '../parse.js';
 export * from './stripe.js';
@@ -54,4 +72,4 @@ export * from './paypal.js';
 export * from './braintree.js';
 export * from './klarna.js';
 export * from './prisma.js';
-export * from './fixed.js';
+export * from './fixed-money.js';

package/src/plugins/allocate.ts

@@ -3,6 +3,8 @@
  * methods below to every Money; the free functions are exported too (and from `@ducatjs/money/fn`,
  * which changes no prototypes).
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import {
   allocate,
   chunk,

package/src/plugins/braintree.ts

@@ -1,6 +1,8 @@
 /**
  * `@ducatjs/money/braintree`: Braintree's amount view. Importing this module adds `toBraintree`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { toBraintree, type BraintreeAmountOptions } from '../braintree.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/cash.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/cash`: cash rounding (cash tenders only; card payments are never rounded) and
  * rounding to an increment. Importing this module adds the methods below.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { cashRound, roundToIncrement, type CashRoundOptions } from '../cash.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/checkout.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/checkout`: Checkout.com's amount view. Importing this module adds `toCheckout`
  * and `toCheckoutAmount`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { toCheckout, toCheckoutAmount, type CheckoutAmountOptions } from '../checkout.js';
 import type { Money } from '../index.js';
 import { extendMoney } from '../money.js';

package/src/plugins/convert.ts

@@ -2,6 +2,8 @@
  * `@ducatjs/money/convert`: currency conversion at exact rates. Importing this module adds
  * `Money#convert`.
  */
+// every ISO 4217 code, as for every entry except /fn
+import './iso.js';
 import { convert } from '../convert.js';
 import type { Factor } from '../decimal.js';
 import type { Money } from '../index.js';