subunit-money 3.0.0 → 3.2.0

package/dist/exchange-rate-service.js

@@ -1,174 +0,0 @@
-"use strict";
-/**
- * Exchange Rate Service - Central authority for currency conversion rates.
- *
- * Design principles:
- * - Rates are stored as strings to preserve precision
- * - Timestamps track when rates were set
- * - Optional source tracking for audit trails
- * - Inverse rates can be auto-generated or explicitly set
- */
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _ExchangeRateService_instances, _ExchangeRateService_rates, _ExchangeRateService_key;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExchangeRateService = void 0;
-/**
- * Service for managing exchange rates between currencies.
- *
- * @example
- * const rates = new ExchangeRateService()
- * rates.setRate('USD', 'EUR', 0.92, 'ECB')
- * rates.getRate('USD', 'EUR') // { from: 'USD', to: 'EUR', rate: '0.92', ... }
- */
-class ExchangeRateService {
-    constructor() {
-        _ExchangeRateService_instances.add(this);
-        _ExchangeRateService_rates.set(this, new Map()
-        /**
-         * Create a rate key for storage.
-         */
-        );
-    }
-    /**
-     * Set an exchange rate.
-     *
-     * @param from - Source currency code
-     * @param to - Target currency code
-     * @param rate - Exchange rate (1 unit of 'from' = rate units of 'to')
-     * @param source - Optional source identifier (e.g., 'ECB', 'Coinbase')
-     * @param autoInverse - If true, automatically create inverse rate (default: true)
-     */
-    setRate(from, to, rate, source, autoInverse = true) {
-        const rateStr = typeof rate === 'number' ? rate.toPrecision(15) : rate;
-        __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").set(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to), {
-            from,
-            to,
-            rate: rateStr,
-            timestamp: new Date(),
-            source,
-        });
-        // Auto-create inverse rate if requested and not already explicitly set
-        if (autoInverse) {
-            const inverseKey = __classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, to, from);
-            if (!__classPrivateFieldGet(this, _ExchangeRateService_rates, "f").has(inverseKey)) {
-                const inverseRate = 1 / Number(rateStr);
-                __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").set(inverseKey, {
-                    from: to,
-                    to: from,
-                    rate: inverseRate.toPrecision(15),
-                    timestamp: new Date(),
-                    source: source ? `${source} (inverse)` : '(inverse)',
-                });
-            }
-        }
-    }
-    /**
-     * Get an exchange rate.
-     *
-     * @param from - Source currency code
-     * @param to - Target currency code
-     * @returns The exchange rate, or undefined if not set
-     */
-    getRate(from, to) {
-        // Same currency = rate of 1
-        if (from === to) {
-            return {
-                from,
-                to,
-                rate: '1',
-                timestamp: new Date(),
-                source: '(identity)',
-            };
-        }
-        return __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").get(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
-    }
-    /**
-     * Check if a rate exists.
-     */
-    hasRate(from, to) {
-        return from === to || __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").has(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
-    }
-    /**
-     * Remove a rate.
-     */
-    removeRate(from, to) {
-        return __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").delete(__classPrivateFieldGet(this, _ExchangeRateService_instances, "m", _ExchangeRateService_key).call(this, from, to));
-    }
-    /**
-     * Get both forward and reverse rates, with discrepancy analysis.
-     * Useful for detecting rate inconsistencies.
-     *
-     * @param currencyA - First currency
-     * @param currencyB - Second currency
-     * @returns Rate pair with discrepancy, or undefined if either rate is missing
-     */
-    getRatePair(currencyA, currencyB) {
-        const forward = this.getRate(currencyA, currencyB);
-        const reverse = this.getRate(currencyB, currencyA);
-        if (!forward || !reverse) {
-            return undefined;
-        }
-        // Calculate discrepancy: how far is forward * reverse from 1.0?
-        const product = Number(forward.rate) * Number(reverse.rate);
-        const discrepancy = Math.abs(1 - product);
-        return { forward, reverse, discrepancy };
-    }
-    /**
-     * Get all rates for a specific base currency.
-     *
-     * @param base - The base currency code
-     * @returns Array of rates from this currency
-     */
-    getRatesFrom(base) {
-        const rates = [];
-        for (const rate of __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").values()) {
-            if (rate.from === base) {
-                rates.push(rate);
-            }
-        }
-        return rates.sort((a, b) => a.to.localeCompare(b.to));
-    }
-    /**
-     * Get all registered rates.
-     */
-    getAllRates() {
-        return Array.from(__classPrivateFieldGet(this, _ExchangeRateService_rates, "f").values()).sort((a, b) => {
-            const fromCompare = a.from.localeCompare(b.from);
-            return fromCompare !== 0 ? fromCompare : a.to.localeCompare(b.to);
-        });
-    }
-    /**
-     * Clear all rates.
-     */
-    clear() {
-        __classPrivateFieldGet(this, _ExchangeRateService_rates, "f").clear();
-    }
-    /**
-     * Load rates from a simple object.
-     *
-     * @param rates - Object where keys are "FROM:TO" and values are rates
-     * @param source - Optional source identifier
-     *
-     * @example
-     * service.loadRates({
-     *   'USD:EUR': 0.92,
-     *   'USD:GBP': 0.79,
-     * }, 'daily-update')
-     */
-    loadRates(rates, source) {
-        for (const [key, rate] of Object.entries(rates)) {
-            const [from, to] = key.split(':');
-            if (from && to) {
-                this.setRate(from, to, rate, source, false); // Don't auto-inverse when batch loading
-            }
-        }
-    }
-}
-exports.ExchangeRateService = ExchangeRateService;
-_ExchangeRateService_rates = new WeakMap(), _ExchangeRateService_instances = new WeakSet(), _ExchangeRateService_key = function _ExchangeRateService_key(from, to) {
-    return `${from}:${to}`;
-};

package/dist/money-converter.d.ts

@@ -1,82 +0,0 @@
-/**
- * Money Converter - Safe cross-currency operations.
- *
- * Bridges Money objects with ExchangeRateService to enable:
- * - Currency conversion
- * - Multi-currency arithmetic
- * - Percentage calculations across currencies
- */
-import { Money } from './money.js';
-import { ExchangeRateService } from './exchange-rate-service.js';
-/**
- * Converter for performing operations between different currencies.
- *
- * @example
- * const rates = new ExchangeRateService()
- * rates.setRate('USD', 'EUR', 0.92)
- *
- * const converter = new MoneyConverter(rates)
- * const euros = converter.convert(new Money('USD', '100'), 'EUR')
- * console.log(euros.toString()) // "92.00 EUR"
- */
-export declare class MoneyConverter {
-    #private;
-    constructor(rateService: ExchangeRateService);
-    /**
-     * Convert a Money amount to another currency.
-     *
-     * @param money - The amount to convert
-     * @param targetCurrency - The target currency code
-     * @returns A new Money in the target currency
-     * @throws {ExchangeRateError} If no rate is available
-     */
-    convert<From extends string, To extends string>(money: Money<From>, targetCurrency: To): Money<To>;
-    /**
-     * Add two Money amounts, converting as needed.
-     *
-     * @param a - First amount
-     * @param b - Second amount
-     * @param resultCurrency - Currency for the result (must be one of the input currencies)
-     * @returns Sum in the result currency
-     */
-    add<A extends string, B extends string, R extends A | B>(a: Money<A>, b: Money<B>, resultCurrency: R): Money<R>;
-    /**
-     * Subtract two Money amounts, converting as needed.
-     *
-     * @param a - Amount to subtract from
-     * @param b - Amount to subtract
-     * @param resultCurrency - Currency for the result
-     * @returns Difference in the result currency
-     */
-    subtract<A extends string, B extends string, R extends A | B>(a: Money<A>, b: Money<B>, resultCurrency: R): Money<R>;
-    /**
-     * Calculate what percentage one amount is of another.
-     * Converts both to the same currency before comparison.
-     *
-     * @param part - The partial amount
-     * @param whole - The whole amount
-     * @returns Percentage as a number (e.g., 25 for 25%)
-     */
-    percentageOf<A extends string, B extends string>(part: Money<A>, whole: Money<B>): number;
-    /**
-     * Sum multiple Money amounts, converting all to a target currency.
-     *
-     * @param amounts - Array of Money objects (can be different currencies)
-     * @param targetCurrency - Currency for the result
-     * @returns Total in the target currency
-     */
-    sum<C extends string>(amounts: Money<string>[], targetCurrency: C): Money<C>;
-    /**
-     * Compare two Money amounts across currencies.
-     * Returns negative if a < b, zero if equal, positive if a > b.
-     *
-     * @param a - First amount
-     * @param b - Second amount
-     * @returns Comparison result
-     */
-    compare<A extends string, B extends string>(a: Money<A>, b: Money<B>): -1 | 0 | 1;
-    /**
-     * Get the exchange rate service (for direct rate access).
-     */
-    get rateService(): ExchangeRateService;
-}

package/dist/money-converter.js

@@ -1,172 +0,0 @@
-"use strict";
-/**
- * Money Converter - Safe cross-currency operations.
- *
- * Bridges Money objects with ExchangeRateService to enable:
- * - Currency conversion
- * - Multi-currency arithmetic
- * - Percentage calculations across currencies
- */
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _MoneyConverter_instances, _MoneyConverter_rateService, _MoneyConverter_bankersRound;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MoneyConverter = void 0;
-const money_js_1 = require("./money.js");
-const errors_js_1 = require("./errors.js");
-const currency_js_1 = require("./currency.js");
-/**
- * Converter for performing operations between different currencies.
- *
- * @example
- * const rates = new ExchangeRateService()
- * rates.setRate('USD', 'EUR', 0.92)
- *
- * const converter = new MoneyConverter(rates)
- * const euros = converter.convert(new Money('USD', '100'), 'EUR')
- * console.log(euros.toString()) // "92.00 EUR"
- */
-class MoneyConverter {
-    constructor(rateService) {
-        _MoneyConverter_instances.add(this);
-        _MoneyConverter_rateService.set(this, void 0);
-        __classPrivateFieldSet(this, _MoneyConverter_rateService, rateService, "f");
-    }
-    /**
-     * Convert a Money amount to another currency.
-     *
-     * @param money - The amount to convert
-     * @param targetCurrency - The target currency code
-     * @returns A new Money in the target currency
-     * @throws {ExchangeRateError} If no rate is available
-     */
-    convert(money, targetCurrency) {
-        if (money.currency === targetCurrency) {
-            return money;
-        }
-        const currencyDef = (0, currency_js_1.getCurrency)(targetCurrency);
-        if (!currencyDef) {
-            throw new errors_js_1.CurrencyUnknownError(targetCurrency);
-        }
-        const rate = __classPrivateFieldGet(this, _MoneyConverter_rateService, "f").getRate(money.currency, targetCurrency);
-        if (!rate) {
-            throw new errors_js_1.ExchangeRateError(money.currency, targetCurrency);
-        }
-        const sourceCurrencyDef = (0, currency_js_1.getCurrency)(money.currency);
-        const sourceSubunits = money.toSubunits();
-        const sourceMultiplier = 10n ** BigInt(sourceCurrencyDef.decimalDigits);
-        const targetMultiplier = 10n ** BigInt(currencyDef.decimalDigits);
-        const RATE_PRECISION = 15n;
-        const rateMultiplier = 10n ** RATE_PRECISION;
-        const rateValue = Number(rate.rate);
-        const rateBigInt = BigInt(Math.round(rateValue * Number(rateMultiplier)));
-        const product = sourceSubunits * rateBigInt * targetMultiplier;
-        const divisor = rateMultiplier * sourceMultiplier;
-        const targetSubunits = __classPrivateFieldGet(this, _MoneyConverter_instances, "m", _MoneyConverter_bankersRound).call(this, product, divisor);
-        return money_js_1.Money.fromSubunits(targetSubunits, targetCurrency);
-    }
-    /**
-     * Add two Money amounts, converting as needed.
-     *
-     * @param a - First amount
-     * @param b - Second amount
-     * @param resultCurrency - Currency for the result (must be one of the input currencies)
-     * @returns Sum in the result currency
-     */
-    add(a, b, resultCurrency) {
-        const aConverted = this.convert(a, resultCurrency);
-        const bConverted = this.convert(b, resultCurrency);
-        return aConverted.add(bConverted);
-    }
-    /**
-     * Subtract two Money amounts, converting as needed.
-     *
-     * @param a - Amount to subtract from
-     * @param b - Amount to subtract
-     * @param resultCurrency - Currency for the result
-     * @returns Difference in the result currency
-     */
-    subtract(a, b, resultCurrency) {
-        const aConverted = this.convert(a, resultCurrency);
-        const bConverted = this.convert(b, resultCurrency);
-        return aConverted.subtract(bConverted);
-    }
-    /**
-     * Calculate what percentage one amount is of another.
-     * Converts both to the same currency before comparison.
-     *
-     * @param part - The partial amount
-     * @param whole - The whole amount
-     * @returns Percentage as a number (e.g., 25 for 25%)
-     */
-    percentageOf(part, whole) {
-        // Convert both to the 'whole' currency for comparison
-        const partConverted = this.convert(part, whole.currency);
-        return (partConverted.toNumber() / whole.toNumber()) * 100;
-    }
-    /**
-     * Sum multiple Money amounts, converting all to a target currency.
-     *
-     * @param amounts - Array of Money objects (can be different currencies)
-     * @param targetCurrency - Currency for the result
-     * @returns Total in the target currency
-     */
-    sum(amounts, targetCurrency) {
-        let total = money_js_1.Money.zero(targetCurrency);
-        for (const amount of amounts) {
-            const converted = this.convert(amount, targetCurrency);
-            total = total.add(converted);
-        }
-        return total;
-    }
-    /**
-     * Compare two Money amounts across currencies.
-     * Returns negative if a < b, zero if equal, positive if a > b.
-     *
-     * @param a - First amount
-     * @param b - Second amount
-     * @returns Comparison result
-     */
-    compare(a, b) {
-        // Convert b to a's currency for comparison
-        const bConverted = this.convert(b, a.currency);
-        return money_js_1.Money.compare(a, bConverted);
-    }
-    /**
-     * Get the exchange rate service (for direct rate access).
-     */
-    get rateService() {
-        return __classPrivateFieldGet(this, _MoneyConverter_rateService, "f");
-    }
-}
-exports.MoneyConverter = MoneyConverter;
-_MoneyConverter_rateService = new WeakMap(), _MoneyConverter_instances = new WeakSet(), _MoneyConverter_bankersRound = function _MoneyConverter_bankersRound(numerator, denominator) {
-    if (denominator === 1n)
-        return numerator;
-    const quotient = numerator / denominator;
-    const remainder = numerator % denominator;
-    if (remainder === 0n)
-        return quotient;
-    const halfDenominator = denominator / 2n;
-    const absRemainder = remainder < 0n ? -remainder : remainder;
-    if (absRemainder > halfDenominator) {
-        return numerator < 0n ? quotient - 1n : quotient + 1n;
-    }
-    if (absRemainder === halfDenominator) {
-        const isQuotientEven = quotient % 2n === 0n;
-        if (isQuotientEven) {
-            return quotient;
-        }
-        return numerator < 0n ? quotient - 1n : quotient + 1n;
-    }
-    return quotient;
-};

package/dist/money.d.ts

@@ -1,146 +0,0 @@
-/**
- * Money - An immutable value object for monetary amounts.
- *
- * Design principles:
- * - Immutable: all operations return new instances
- * - Type-safe: currency mismatches are caught at compile time (when possible) and runtime
- * - Precise: uses BigInt internally to avoid floating-point errors
- * - String-based API: amounts are strings to preserve precision in JSON/DB round-trips
- */
-/**
- * Serialized form of a Money object, safe for JSON.
- */
-export interface MoneyObject<C extends string = string> {
-    currency: C;
-    amount: string;
-}
-/**
- * Money class - represents a monetary amount in a specific currency.
- *
- * @typeParam C - The currency code type (enables compile-time currency checking)
- *
- * @example
- * const price = new Money('USD', '19.99')
- * const tax = price.multiply(0.08)
- * const total = price.add(tax)
- * console.log(total.amount) // "21.59"
- */
-export declare class Money<C extends string = string> {
-    #private;
-    readonly currency: C;
-    /**
-     * Create a new Money instance.
-     *
-     * @param currency - ISO 4217 currency code (must be registered)
-     * @param amount - The amount as a number or string
-     * @throws {CurrencyUnknownError} If the currency is not registered
-     * @throws {AmountError} If the amount is not a valid number
-     * @throws {SubunitError} If the amount has more decimals than the currency allows
-     */
-    constructor(currency: C, amount: number | string);
-    /**
-     * The amount as a formatted string with correct decimal places.
-     * @example
-     * new Money('USD', 19.9).amount // "19.90"
-     * new Money('JPY', 1000).amount // "1000"
-     */
-    get amount(): string;
-    /**
-     * Add another Money amount.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    add(other: Money<C>): Money<C>;
-    /**
-     * Subtract another Money amount.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    subtract(other: Money<C>): Money<C>;
-    /**
-     * Multiply by a factor.
-     *
-     * DESIGN: Rounds immediately after multiplication using banker's rounding
-     * (round half-to-even). This prevents the "split penny problem".
-     */
-    multiply(factor: number): Money<C>;
-    /**
-     * Allocate this amount proportionally.
-     * Handles remainder distribution to avoid losing pennies.
-     *
-     * @param proportions - Array of proportions (e.g., [1, 1, 1] for three-way split)
-     * @returns Array of Money objects that sum to the original amount
-     */
-    allocate(proportions: number[]): Money<C>[];
-    /**
-     * Check if this amount equals another.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    equalTo(other: Money<C>): boolean;
-    /**
-     * Check if this amount is greater than another.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    greaterThan(other: Money<C>): boolean;
-    /**
-     * Check if this amount is less than another.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    lessThan(other: Money<C>): boolean;
-    /**
-     * Check if this amount is greater than or equal to another.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    greaterThanOrEqual(other: Money<C>): boolean;
-    /**
-     * Check if this amount is less than or equal to another.
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    lessThanOrEqual(other: Money<C>): boolean;
-    /**
-     * Check if this amount is zero.
-     */
-    isZero(): boolean;
-    /**
-     * Check if this amount is positive (greater than zero).
-     */
-    isPositive(): boolean;
-    /**
-     * Check if this amount is negative (less than zero).
-     */
-    isNegative(): boolean;
-    /**
-     * Convert to a plain object (safe for JSON).
-     */
-    toJSON(): MoneyObject<C>;
-    /**
-     * Convert to string representation.
-     */
-    toString(): string;
-    /**
-     * Get the amount as a number (may lose precision for large values).
-     * Use with caution - prefer string-based operations.
-     */
-    toNumber(): number;
-    /**
-     * Get the amount in subunits (e.g., cents for USD).
-     * Useful for database storage (Stripe-style integer storage).
-     */
-    toSubunits(): bigint;
-    /**
-     * Create a Money instance from a plain object.
-     */
-    static fromObject<C extends string>(obj: MoneyObject<C>): Money<C>;
-    /**
-     * Create a Money instance from subunits (e.g., cents).
-     * Useful for loading from database (Stripe-style integer storage).
-     */
-    static fromSubunits<C extends string>(subunits: bigint | number, currency: C): Money<C>;
-    /**
-     * Compare two Money objects (for use with Array.sort).
-     * @throws {CurrencyMismatchError} If currencies don't match
-     */
-    static compare<C extends string>(a: Money<C>, b: Money<C>): -1 | 0 | 1;
-    /**
-     * Create a zero amount in the specified currency.
-     */
-    static zero<C extends string>(currency: C): Money<C>;
-}