@ducatjs/money 0.0.0 → 0.2.0

package/dist/money.js

@@ -0,0 +1,703 @@
+import { currencyExponent } from './currency.js';
+import { formatScaled, parseDecimal, parsePlainDecimal, POW10, pow10n, ratio, normalizeMinor, } from './decimal.js';
+import { DEFAULT_ROUNDING, divideAndRound, divideAndRoundBigint, RoundingError, } from './rounding.js';
+// 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;
+/**
+ * @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 = 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 = (money, factor, policy) => policy[ROUND_PRODUCT](money, factor);
+/** Thrown when two amounts in different currencies are combined. */
+export class CurrencyMismatchError extends TypeError {
+    name = 'CurrencyMismatchError';
+    constructor(expected, actual) {
+        super(`Currency mismatch: ${expected} vs ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/**
+ * An immutable amount of money: an integer number of 10^-scale units of `currency`.
+ *
+ * `minor` is a JS number whenever it is a safe integer (|v| <= 2^53 - 1) and a bigint otherwise, so
+ * ordinary amounts never allocate a bigint, and huge or high-precision amounts never lose a digit.
+ * `scale` is normally the currency's ISO exponent (2 for EUR) but can be larger for sub-minor
+ * precision (unit prices, FX intermediates); `round()` brings it back.
+ *
+ * Instances are not frozen (Object.freeze costs 5-8x on construction in V8 and JSC; see bench/),
+ * but every field is readonly and no operation mutates. Create values with `money()` /
+ * `fromMinor()`.
+ *
+ * The class carries the core methods only. Opt-in modules (`@ducatjs/money/allocate`,
+ * `@ducatjs/money/tax`, `@ducatjs/money/format`, ...) add theirs when imported; see `extendMoney`.
+ */
+class Money {
+    /** @internal */
+    constructor(currency, minor, scale) {
+        this.currency = currency;
+        this.minor = minor;
+        this.scale = scale;
+    }
+    /** "12.34 EUR" */
+    toString() {
+        return `${formatScaled(this.minor, this.scale)} ${this.currency}`;
+    }
+    toJSON() {
+        return { amount: formatScaled(this.minor, this.scale), currency: this.currency };
+    }
+    /** Blocks `a + b`, `a > b`, `+a`: arithmetic and comparison must go through the library. */
+    [Symbol.toPrimitive](hint) {
+        if (hint === 'string') {
+            return this.toString();
+        }
+        throw new TypeError('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) {
+        return add(this, other);
+    }
+    /** this - other */
+    subtract(other) {
+        return subtract(this, other);
+    }
+    /**
+     * this * factor, rounded to this scale. `factor` is exact: integer, decimal string ('1.075'),
+     * bigint or ratio().
+     */
+    multiply(factor, rounding) {
+        return multiply(this, factor, rounding);
+    }
+    /** this / divisor, rounded to this scale (or to a policy's scale and increment) */
+    divide(divisor, rounding) {
+        return divide(this, divisor, rounding);
+    }
+    negate() {
+        return negate(this);
+    }
+    abs() {
+        return abs(this);
+    }
+    round(rounding, scale) {
+        // the free function handles both; the cast only picks its implementation signature
+        return round(this, rounding, scale);
+    }
+    /** Changes the scale; decreasing it rounds (default 'halfExpand'). */
+    toScale(scale, rounding) {
+        return toScale(this, scale, rounding);
+    }
+    // comparison
+    /** -1, 0 or 1; throws on currency mismatch */
+    compare(other) {
+        return compare(this, other);
+    }
+    /** same currency and value; a different currency is simply not equal */
+    equals(other) {
+        return equals(this, other);
+    }
+    lessThan(other) {
+        return compare(this, other) < 0;
+    }
+    lessThanOrEqual(other) {
+        return compare(this, other) <= 0;
+    }
+    greaterThan(other) {
+        return compare(this, other) > 0;
+    }
+    greaterThanOrEqual(other) {
+        return compare(this, other) >= 0;
+    }
+    isZero() {
+        return this.minor == 0;
+    }
+    isPositive() {
+        return this.minor > 0;
+    }
+    isNegative() {
+        return this.minor < 0;
+    }
+    sign() {
+        return sign(this);
+    }
+    min(...others) {
+        return min(this, ...others);
+    }
+    max(...others) {
+        return max(this, ...others);
+    }
+    clamp(lo, hi) {
+        return clamp(this, lo, hi);
+    }
+    /** Same currency, value and scale: 1.0 EUR is not identical to 1.00 EUR. */
+    identical(other) {
+        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(operation) {
+        return operation(this);
+    }
+    // output
+    /** The whole major units, truncated toward zero: 12 for 12.34 EUR, -12 for -12.34 EUR. */
+    majorPart() {
+        return majorPart(this);
+    }
+    /** The rest in 10^-scale units, with the amount's sign: 34 for 12.34 EUR, -34 for -12.34. */
+    minorPart() {
+        return minorPart(this);
+    }
+    /** Exact decimal string in major units: "12.34" */
+    toDecimal() {
+        return formatScaled(this.minor, this.scale);
+    }
+    /** Minor units as a bigint (BIGINT columns) */
+    toMinor() {
+        return toBigInt(this.minor);
+    }
+    /** Minor units as a number; throws beyond 2^53 */
+    toMinorNumber() {
+        return toMinorNumber(this);
+    }
+}
+/** Whether a value is a Money from this package. */
+export function isMoney(value) {
+    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(value, currency) {
+    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(money, currency) {
+    // 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.
+ */
+const methodOwners = new Map();
+/**
+ * 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'));
+/**
+ * Adds methods to every Money (this is how `@ducatjs/money/allocate`, `@ducatjs/money/format`, ...
+ * install theirs). Declare their types with `declare module '@ducatjs/money' { interface Money<C
+ * extends string> { ... } }`. The methods are non-enumerable, like class methods. A name that Money
+ * already has (one of its own methods, or one added by a different owner) throws, so two modules
+ * cannot silently fight over it.
+ */
+export function extendMoney(methods, options) {
+    const prototype = Money.prototype;
+    const owner = options?.owner;
+    for (const name of Object.keys(methods)) {
+        const method = methods[name];
+        if (RESERVED_NAMES.has(name)) {
+            throw new TypeError(`Money#${name} is reserved`);
+        }
+        // Replacing an existing method would silently change behaviour for every caller, unless it is
+        // the same function or the same owner installing its own methods again.
+        const previousOwner = methodOwners.get(name);
+        const isOwnReinstall = owner !== undefined && previousOwner === owner;
+        if (Object.hasOwn(prototype, name) && prototype[name] !== method && !isOwnReinstall) {
+            throw new TypeError(`Money#${name} is already defined`);
+        }
+        // Non-enumerable, like the class's own methods, so Object.keys and spreads see only the fields.
+        Object.defineProperty(prototype, name, {
+            value: method,
+            writable: true,
+            configurable: true,
+            enumerable: false,
+        });
+        if (owner !== undefined) {
+            methodOwners.set(name, owner);
+        }
+    }
+}
+/** @internal construct from a value that may be an unsafe bigint */
+export function make(currency, minor, scale) {
+    return new Money(currency, typeof minor === 'bigint' ? normalizeMinor(minor) : minor, scale);
+}
+const toBigInt = (minor) => (typeof minor === 'bigint' ? minor : BigInt(minor));
+/** v * 10^e exactly (e >= 0) */
+export function scaleUp(minor, exponent) {
+    if (exponent === 0) {
+        return minor;
+    }
+    if (typeof minor === 'number' && exponent <= 15) {
+        const scaled = minor * POW10[exponent];
+        if (scaled <= MAX_SAFE_MINOR && scaled >= -MAX_SAFE_MINOR) {
+            return scaled;
+        }
+    }
+    return normalizeMinor(toBigInt(minor) * pow10n(exponent));
+}
+/** v / 10^e rounded (e >= 0) */
+export function scaleDown(minor, exponent, mode) {
+    if (exponent === 0) {
+        return minor;
+    }
+    if (typeof minor === 'number' && exponent <= 15) {
+        return divideAndRound(minor, POW10[exponent], mode);
+    }
+    return normalizeMinor(divideAndRoundBigint(toBigInt(minor), pow10n(exponent), mode));
+}
+/**
+ * Creates money from an amount in major units.
+ *
+ *     money('12.34', 'EUR')   // exact decimal string: the recommended form
+ *     money(12, 'EUR')        // integers are major units: 12.00 EUR
+ *     money(12.34, 'EUR')     // non-integer numbers are read at their shortest decimal form ("12.34")
+ *     money(10n ** 30n, 'USD')
+ *
+ * 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.
+ */
+export function money(amount, currency, options) {
+    const scale = options?.scale ?? currencyExponent(currency);
+    if (typeof amount === 'string') {
+        const parsed = parsePlainDecimal(amount) ?? parseDecimal(amount);
+        return fromScaled(currency, parsed.digits, parsed.scale, scale, options?.rounding ?? 'unnecessary', amount);
+    }
+    if (typeof amount === 'number') {
+        if (Number.isSafeInteger(amount)) {
+            return make(currency, scaleUp(amount, scale), scale);
+        }
+        if (!Number.isFinite(amount)) {
+            throw new RangeError(`Invalid amount ${amount}`);
+        }
+        const parsed = parseDecimal(String(amount));
+        return fromScaled(currency, parsed.digits, parsed.scale, scale, options?.rounding ?? 'unnecessary', amount);
+    }
+    if (typeof amount === 'bigint') {
+        return make(currency, scaleUp(normalizeMinor(amount), scale), scale);
+    }
+    throw new TypeError(`Invalid amount ${String(amount)}`);
+}
+function fromScaled(currency, digits, from, to, mode, input) {
+    if (typeof digits === 'bigint') {
+        digits = normalizeMinor(digits);
+    }
+    if (from === to) {
+        return new Money(currency, digits, to);
+    }
+    if (from < to) {
+        return make(currency, scaleUp(digits, to - from), to);
+    }
+    try {
+        return make(currency, scaleDown(digits, from - to, mode), to);
+    }
+    catch (error) {
+        if (error instanceof RoundingError) {
+            throw new RoundingError(`${String(input)} has more than ${to} decimal places for ${currency}; pass { rounding } or { scale }`);
+        }
+        throw error;
+    }
+}
+/**
+ * Creates money from an integer count of minor units (cents): `fromMinor(1234, 'EUR')` is 12.34
+ * EUR. This is the form to read from a BIGINT column or a payment processor (but see
+ * `stripe`/`adyen` for processors whose exponent differs from ISO).
+ */
+export function fromMinor(minor, currency, scale) {
+    const resolvedScale = scale ?? currencyExponent(currency);
+    if (typeof minor === 'number') {
+        if (!Number.isSafeInteger(minor)) {
+            throw new RangeError(`Minor units must be a safe integer, got ${minor}; pass a bigint`);
+        }
+        return new Money(currency, minor + 0, resolvedScale);
+    }
+    if (typeof minor !== 'bigint') {
+        throw new TypeError(`Invalid minor units ${String(minor)}`);
+    }
+    return make(currency, minor, resolvedScale);
+}
+/** Zero in a currency, at its exponent (or `scale`). */
+export function zero(currency, scale) {
+    return new Money(currency, 0, scale ?? currencyExponent(currency));
+}
+// ---------------------------------------------------------------------------------------------
+// Arithmetic
+// ---------------------------------------------------------------------------------------------
+function mismatch(money, other) {
+    throw new CurrencyMismatchError(money.currency, other.currency);
+}
+function addUsingBigInt(money, other, sign) {
+    const scale = Math.max(money.scale, other.scale);
+    const left = toBigInt(scaleUp(money.minor, scale - money.scale));
+    const right = toBigInt(scaleUp(other.minor, scale - other.scale));
+    return make(money.currency, sign === 1 ? left + right : left - right, scale);
+}
+/**
+ * a + b. Mixing currencies is a type error for literal currency types and a runtime error
+ * otherwise.
+ */
+export function add(money, other) {
+    if (money.currency !== other.currency) {
+        mismatch(money, other);
+    }
+    const left = money.minor;
+    const right = other.minor;
+    if (typeof left === 'number' && typeof right === 'number' && money.scale === other.scale) {
+        // exact whenever |sum| <= MAX_SAFE_MINOR: both inputs are safe integers
+        const sum = left + right;
+        if (sum <= MAX_SAFE_MINOR && sum >= -MAX_SAFE_MINOR) {
+            return new Money(money.currency, sum, money.scale);
+        }
+    }
+    return addUsingBigInt(money, other, 1);
+}
+/** a - b */
+export function subtract(money, other) {
+    if (money.currency !== other.currency) {
+        mismatch(money, other);
+    }
+    const left = money.minor;
+    const right = other.minor;
+    if (typeof left === 'number' && typeof right === 'number' && money.scale === other.scale) {
+        const difference = left - right;
+        if (difference <= MAX_SAFE_MINOR && difference >= -MAX_SAFE_MINOR) {
+            return new Money(money.currency, difference + 0, money.scale);
+        }
+    }
+    return addUsingBigInt(money, other, -1);
+}
+/** Sum of a list (same currency; any scale). An empty list needs `currency` and returns zero. */
+export function sum(items, currency) {
+    const count = items.length;
+    if (count === 0) {
+        if (currency === undefined) {
+            throw new RangeError('sum() of an empty list needs a currency');
+        }
+        return zero(currency);
+    }
+    let total = items[0];
+    if (currency !== undefined && total.currency !== currency) {
+        throw new CurrencyMismatchError(currency, total.currency);
+    }
+    const itemCurrency = total.currency;
+    const scale = total.scale;
+    // Fast loop on plain numbers: each partial sum of safe integers is exact while it stays within
+    // MAX_SAFE_MINOR. It falls back to add() at the first bigint, scale change or overflow. NaN marks
+    // "no fast total".
+    let fastTotal = typeof total.minor === 'number' ? total.minor : NaN;
+    let i = 1;
+    for (; i < count && fastTotal === fastTotal; i++) {
+        const item = items[i];
+        if (item.currency !== itemCurrency) {
+            mismatch(total, item);
+        }
+        if (typeof item.minor !== 'number' || item.scale !== scale) {
+            break;
+        }
+        const next = fastTotal + item.minor;
+        if (!(next <= MAX_SAFE_MINOR && next >= -MAX_SAFE_MINOR)) {
+            break;
+        }
+        fastTotal = next;
+    }
+    if (fastTotal === fastTotal) {
+        total = new Money(itemCurrency, fastTotal, scale);
+    }
+    for (; i < count; i++) {
+        total = add(total, items[i]);
+    }
+    return total;
+}
+/** -money */
+export function negate(money) {
+    const minor = money.minor;
+    return new Money(money.currency, typeof minor === 'number' ? 0 - minor : normalizeMinor(-minor), money.scale);
+}
+/** |money| */
+export function abs(money) {
+    return money.minor < 0 ? negate(money) : money;
+}
+/**
+ * m * factor, rounded to m's scale. `factor` is exact: an integer, a decimal string ('1.075'), a
+ * bigint, or a `ratio()`. Rounding defaults to 'halfExpand' (ties away from zero); pass
+ * 'unnecessary' to throw instead.
+ */
+export function multiply(money, factor, rounding = DEFAULT_ROUNDING) {
+    const minor = money.minor;
+    // 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);
+        }
+    }
+    return multiplyByRatio(money, ratio(factor), rounding);
+}
+/** @internal m * r, rounded with a mode (at `scale`) or with a policy (at the policy's scale) */
+export function multiplyByRatio(money, factor, rounding, scale = money.scale) {
+    if (typeof rounding === 'function') {
+        return roundWithPolicy(money, factor, rounding);
+    }
+    const minor = money.minor;
+    if (typeof minor === 'number' &&
+        scale === money.scale &&
+        factor.n === factor.n &&
+        factor.d === factor.d) {
+        // exact when |product| <= MAX_SAFE_MINOR (both factors are safe integers)
+        const product = minor * factor.n;
+        if (product <= MAX_SAFE_MINOR && product >= -MAX_SAFE_MINOR) {
+            return new Money(money.currency, divideAndRound(product, factor.d, rounding), scale);
+        }
+    }
+    let numerator = toBigInt(minor) * factor.num;
+    let denominator = factor.den;
+    if (scale > money.scale) {
+        numerator *= pow10n(scale - money.scale);
+    }
+    else if (scale < money.scale) {
+        denominator *= pow10n(money.scale - scale);
+    }
+    return make(money.currency, divideAndRoundBigint(numerator, denominator, rounding), scale);
+}
+/** m / divisor, rounded to m's scale (default 'halfExpand'), or with a rounding policy. */
+export function divide(money, divisor, rounding = DEFAULT_ROUNDING) {
+    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);
+}
+export function round(money, rounding, scale) {
+    if (typeof rounding === 'function') {
+        return roundWithPolicy(money, ratio(1), rounding);
+    }
+    return toScale(money, scale ?? currencyExponent(money.currency), rounding);
+}
+/**
+ * Changes the scale; increasing it is always exact, decreasing it rounds (default 'halfExpand').
+ */
+export function toScale(money, scale, rounding = DEFAULT_ROUNDING) {
+    if (!Number.isInteger(scale) || scale < 0) {
+        throw new RangeError(`Invalid scale ${scale}`);
+    }
+    if (scale === money.scale) {
+        return money;
+    }
+    if (scale > money.scale) {
+        return make(money.currency, scaleUp(money.minor, scale - money.scale), scale);
+    }
+    return make(money.currency, scaleDown(money.minor, money.scale - scale, rounding), scale);
+}
+// ---------------------------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------------------------
+/** -1, 0 or 1. Throws on currency mismatch. Works across scales and number/bigint. */
+export function compare(money, other) {
+    if (money.currency !== other.currency) {
+        mismatch(money, other);
+    }
+    let left = money.minor;
+    let right = other.minor;
+    if (money.scale !== other.scale) {
+        const scale = Math.max(money.scale, other.scale);
+        left = scaleUp(left, scale - money.scale);
+        right = scaleUp(right, scale - other.scale);
+    }
+    // number < bigint comparisons are exact in JS
+    if (left < right) {
+        return -1;
+    }
+    return left > right ? 1 : 0;
+}
+/**
+ * Same currency and same value (1.0 EUR at scale 1 equals 1.00 EUR). Different currencies: false.
+ */
+export function equals(money, other) {
+    if (money.currency !== other.currency) {
+        return false;
+    }
+    if (money.scale === other.scale) {
+        // == compares number and bigint exactly
+        return money.minor == other.minor;
+    }
+    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, other) {
+    return (money.currency === other.currency && money.scale === other.scale && money.minor == other.minor);
+}
+/** money < other (same currency; any scale). */
+export const lessThan = (money, other) => compare(money, other) < 0;
+/** money <= other */
+export const lessThanOrEqual = (money, other) => compare(money, other) <= 0;
+/** money > other */
+export const greaterThan = (money, other) => compare(money, other) > 0;
+/** money >= other */
+export const greaterThanOrEqual = (money, other) => compare(money, other) >= 0;
+/** Whether the amount is zero. */
+export const isZero = (money) => money.minor == 0;
+/** Whether the amount is greater than zero. */
+export const isPositive = (money) => money.minor > 0;
+/** Whether the amount is less than zero. */
+export const isNegative = (money) => money.minor < 0;
+/** 1, 0 or -1 for positive, zero and negative amounts. */
+export const sign = (money) => {
+    if (money.minor > 0) {
+        return 1;
+    }
+    return money.minor < 0 ? -1 : 0;
+};
+/** The smallest of the amounts (same currency); the first one wins ties. */
+export function min(first, ...rest) {
+    let smallest = first;
+    for (const candidate of rest) {
+        if (compare(candidate, smallest) < 0) {
+            smallest = candidate;
+        }
+    }
+    return smallest;
+}
+/** The largest of the amounts (same currency); the first one wins ties. */
+export function max(first, ...rest) {
+    let largest = first;
+    for (const candidate of rest) {
+        if (compare(candidate, largest) > 0) {
+            largest = candidate;
+        }
+    }
+    return largest;
+}
+/** Limits m to [lo, hi]. */
+export function clamp(money, lo, hi) {
+    if (compare(lo, hi) > 0) {
+        throw new RangeError('clamp(): lo > hi');
+    }
+    if (compare(money, lo) < 0) {
+        return lo;
+    }
+    return compare(money, hi) > 0 ? hi : money;
+}
+// ---------------------------------------------------------------------------------------------
+// Serialisation primitives
+// ---------------------------------------------------------------------------------------------
+/**
+ * Exact decimal string in major units: "12.34", "-0.05", "1000" (JPY). For NUMERIC/DECIMAL columns.
+ */
+export function toDecimal(money) {
+    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) {
+    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) {
+    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) {
+    return toBigInt(money.minor);
+}
+/** Minor units as a number; throws if not a safe integer. */
+export function toMinorNumber(money) {
+    if (typeof money.minor === 'bigint') {
+        throw new RangeError(`${money} does not fit in a safe integer; use toMinor()`);
+    }
+    return money.minor;
+}
+/** Parses `{ amount: "12.34", currency: "EUR" }` (as produced by JSON.stringify(money)). */
+export function fromJSON(json, options) {
+    const parsed = typeof json === 'string' ? JSON.parse(json) : json;
+    if (parsed === null ||
+        typeof parsed !== 'object' ||
+        typeof parsed.amount !== 'string' ||
+        typeof parsed.currency !== 'string') {
+        throw new TypeError('Expected { amount: string, currency: string }');
+    }
+    return money(parsed.amount, parsed.currency, options);
+}
+export { ratio } from './decimal.js';
+//# sourceMappingURL=money.js.map