subunit-money 2.0.1 → 2.1.0

package/README.md

@@ -13,9 +13,9 @@ const price = new Money('USD', '19.99')
 const tax = price.multiply(0.0825)
 const total = price.add(tax)
 
-console.log(total.toString()) // "21.63 USD"
-console.log(total.amount)     // "21.63" (string, safe for JSON/DB)
-console.log(total.toNumber()) // 21.63 (number, for calculations)
+console.log(total.toString()) // "21.64 USD"
+console.log(total.amount)     // "21.64" (string, safe for JSON/DB)
+console.log(total.toNumber()) // 21.64 (number, for calculations)
 ```
 
 ## Why Model Money as a Value Object?
@@ -28,6 +28,8 @@ Naive JavaScript math fails for monetary values in subtle but critical ways:
 
 **The Split Penny Problem**: Imagine charging tax ($1.649175) on 10 items. If you round per-item (legally required on receipts), that's $1.65 × 10 = $16.50. But if you defer rounding, 10 × $1.649175 = $16.49. That missing penny is a real problem. Money objects round immediately after multiplication to prevent this.
 
+**Banker's Rounding**: When a value is exactly halfway (like $0.545), should it round up or down? Simple "round half up" always rounds up, creating systematic bias—over millions of transactions, you're consistently overcharging. This library uses "round half to even" (banker's rounding): $0.545 rounds to $0.54 (4 is even), but $0.555 rounds to $0.56 (5 is odd, round to even 6). This eliminates bias and is the IEEE 754-2008 standard for financial calculations.
+
 This library uses BigInt internally to store currency in subunits (cents, satoshis, etc.), making all arithmetic exact.
 
 ## Features
@@ -205,7 +207,7 @@ try {
 - **Minimal surface area**: A value object should be just a value object
 - **Fail fast**: Errors thrown immediately, not silently propagated
 - **No localization**: Formatting for display is your app's concern
-- **No rounding rules**: Currency-specific rounding is application-specific
+- **Banker's rounding**: Uses IEEE 754-2008 round-half-to-even to eliminate systematic bias
 
 ## Why String Amounts?
 

package/dist/money-converter.js

@@ -18,7 +18,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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_rateService;
+var _MoneyConverter_instances, _MoneyConverter_rateService, _MoneyConverter_bankersRound;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MoneyConverter = void 0;
 const money_js_1 = require("./money.js");
@@ -37,6 +37,7 @@ const currency_js_1 = require("./currency.js");
  */
 class MoneyConverter {
     constructor(rateService) {
+        _MoneyConverter_instances.add(this);
         _MoneyConverter_rateService.set(this, void 0);
         __classPrivateFieldSet(this, _MoneyConverter_rateService, rateService, "f");
     }
@@ -52,14 +53,26 @@ class MoneyConverter {
         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 currencyDef = (0, currency_js_1.getCurrency)(targetCurrency);
-        const convertedAmount = Number(money.amount) * Number(rate.rate);
-        const rounded = convertedAmount.toFixed(currencyDef.decimalDigits);
-        return new money_js_1.Money(targetCurrency, rounded);
+        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.
@@ -136,4 +149,24 @@ class MoneyConverter {
     }
 }
 exports.MoneyConverter = MoneyConverter;
-_MoneyConverter_rateService = new WeakMap();
+_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

@@ -57,7 +57,15 @@ export declare class Money<C extends string = string> {
     subtract(other: Money<C>): Money<C>;
     /**
      * Multiply by a factor.
-     * Result is rounded to the currency's decimal places using banker's rounding.
+     *
+     * DESIGN: Rounds immediately after multiplication using banker's rounding
+     * (round half-to-even). This prevents the "split penny problem" where
+     * line-item rounding differs from deferred rounding:
+     *   Per-item: $1.65 tax × 10 items = $16.50 ✓ (matches receipt)
+     *   Deferred: 10 × $1.649175 = $16.49 ✗ (missing penny)
+     *
+     * For chained calculations without intermediate rounding, perform arithmetic
+     * in Number space first, then create a Money object with the final result.
      */
     multiply(factor: number): Money<C>;
     /**

package/dist/money.js

@@ -19,7 +19,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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 _Money_instances, _a, _Money_value, _Money_currencyDef, _Money_parseAmount, _Money_fromInternal, _Money_assertSameCurrency, _Money_getInternalValue, _Money_createFromInternal, _Money_formatInternalValue;
+var _Money_instances, _a, _Money_value, _Money_currencyDef, _Money_parseAmount, _Money_assertSameCurrency, _Money_getInternalValue, _Money_roundedDivide, _Money_createFromInternal, _Money_formatInternalValue;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Money = void 0;
 const errors_js_1 = require("./errors.js");
@@ -103,16 +103,24 @@ class Money {
     }
     /**
      * Multiply by a factor.
-     * Result is rounded to the currency's decimal places using banker's rounding.
+     *
+     * DESIGN: Rounds immediately after multiplication using banker's rounding
+     * (round half-to-even). This prevents the "split penny problem" where
+     * line-item rounding differs from deferred rounding:
+     *   Per-item: $1.65 tax × 10 items = $16.50 ✓ (matches receipt)
+     *   Deferred: 10 × $1.649175 = $16.49 ✗ (missing penny)
+     *
+     * For chained calculations without intermediate rounding, perform arithmetic
+     * in Number space first, then create a Money object with the final result.
      */
     multiply(factor) {
         if (typeof factor !== 'number' || !Number.isFinite(factor)) {
             throw new TypeError(`Factor must be a finite number, got: ${factor}`);
         }
-        // Convert factor to BigInt-compatible form
         const factorStr = factor.toFixed(INTERNAL_PRECISION);
         const factorBigInt = BigInt(factorStr.replace('.', ''));
-        const result = (__classPrivateFieldGet(this, _Money_value, "f") * factorBigInt) / PRECISION_MULTIPLIER;
+        const product = __classPrivateFieldGet(this, _Money_value, "f") * factorBigInt;
+        const result = __classPrivateFieldGet(_a, _a, "m", _Money_roundedDivide).call(_a, product, PRECISION_MULTIPLIER);
         return __classPrivateFieldGet(_a, _a, "m", _Money_createFromInternal).call(_a, result, this.currency, __classPrivateFieldGet(this, _Money_currencyDef, "f"));
     }
     /**
@@ -130,6 +138,11 @@ class Money {
         if (!Array.isArray(proportions) || proportions.length === 0) {
             throw new TypeError('Proportions must be a non-empty array');
         }
+        for (const p of proportions) {
+            if (typeof p !== 'number' || !Number.isFinite(p) || p < 0) {
+                throw new TypeError('All proportions must be non-negative finite numbers');
+            }
+        }
         const total = proportions.reduce((sum, p) => sum + p, 0);
         if (total <= 0) {
             throw new TypeError('Sum of proportions must be positive');
@@ -314,25 +327,32 @@ _a = Money, _Money_value = new WeakMap(), _Money_currencyDef = new WeakMap(), _M
     const paddedFrac = frac.padEnd(INTERNAL_PRECISION, '0');
     const combined = BigInt(whole + paddedFrac);
     return sign === '-' ? -combined : combined;
-}, _Money_fromInternal = function _Money_fromInternal(value, currency) {
-    const currencyDef = (0, currency_js_1.getCurrency)(currency);
-    if (!currencyDef) {
-        throw new errors_js_1.CurrencyUnknownError(currency);
-    }
-    // Create instance without parsing
-    const instance = Object.create(_a.prototype);
-    Object.defineProperty(instance, 'currency', { value: currency, enumerable: true });
-    Object.defineProperty(instance, '#value', { value });
-    Object.defineProperty(instance, '#currencyDef', { value: currencyDef });
-    instance['#value'] = value;
-    instance['#currencyDef'] = currencyDef;
-    return instance;
 }, _Money_assertSameCurrency = function _Money_assertSameCurrency(other) {
     if (this.currency !== other.currency) {
         throw new errors_js_1.CurrencyMismatchError(this.currency, other.currency);
     }
 }, _Money_getInternalValue = function _Money_getInternalValue() {
     return __classPrivateFieldGet(this, _Money_value, "f");
+}, _Money_roundedDivide = function _Money_roundedDivide(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;
 }, _Money_createFromInternal = function _Money_createFromInternal(value, currency, currencyDef) {
     const instance = Object.create(_a.prototype);
     // Use Object.defineProperties for proper initialization
@@ -346,7 +366,7 @@ _a = Money, _Money_value = new WeakMap(), _Money_currencyDef = new WeakMap(), _M
 }, _Money_formatInternalValue = function _Money_formatInternalValue(value, currencyDef) {
     const decimals = currencyDef.decimalDigits;
     const divisor = 10n ** BigInt(INTERNAL_PRECISION - decimals);
-    const adjusted = value / divisor;
+    const adjusted = __classPrivateFieldGet(_a, _a, "m", _Money_roundedDivide).call(_a, value, divisor);
     const isNegative = adjusted < 0n;
     const abs = isNegative ? -adjusted : adjusted;
     if (decimals === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subunit-money",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A type-safe value object for monetary amounts with currency conversion support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,18 +14,20 @@
   },
   "files": [
     "dist",
-    "currencymap.json"
+    "currencymap.json",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",
     "test": "node --import tsx --test test/*.test.ts",
     "lint": "tsc --noEmit",
-    "tag": "git tag v$(jq -r '.version' package.json)",
-    "prepare-release": "npm run build && git add dist && git commit -m \"Build $(jq -r '.version' package.json)\" && npm run tag",
-    "preversion": "npm run test && npm run lint",
-    "version": "npm run build && git add -A dist",
+    "check-clean": "git diff --quiet && git diff --cached --quiet",
+    "preversion": "npm run check-clean && npm test",
     "postversion": "git push && git push --tags",
-    "prepublishOnly": "npm run test && npm run build"
+    "prepublishOnly": "npm run check-clean && npm run build",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
   },
   "repository": {
     "type": "git",