@classytic/primitives 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.31.1 — 2026-10-11
+
+### Fixed — `convertWithSnapshot` is exact (`./currency`)
+- The conversion was computed in floating point (`minor / sourceFactor × rate × baseFactor`) and then
+  rounded, so a result that lands EXACTLY on a rounding boundary could round the wrong way. USD 5.30 at
+  110.15 is exactly 583.795 BDT; the float product was 583.79499…, giving 58379 paisa instead of 58380.
+  Over 1..99,999 cents the float form was off by one minor unit for 134 amounts at 110.15, 1,455 at 117.35
+  and 1,379 at 122.35.
+- The rate is now read as the decimal it prints as (`String(rate)`, exponent form included) and the
+  conversion is done in BigInt, rounded once. Signature and rounding modes are unchanged
+  (`half-away-from-zero` default, `floor`, `ceil`).
+- What changes: only results that were wrong. Under `half-away-from-zero`, amounts whose exact value is a
+  half-way point now round away from zero (one minor unit up in magnitude). Under `floor` / `ceil`, amounts
+  whose exact value is an integer are no longer nudged one unit off it (USD 2.20 at 110.15 `ceil` was 24234,
+  now 24233). A negative amount that rounds to zero now returns `0`, not `-0`. Every other result is
+  identical (checked against the float form across ~10.9M amount × rate × currency-pair × mode cases).
+- `convertWithSnapshot` now throws `TypeError` for a non-integer `source.amount` (a `Money` invariant that
+  `money()` already enforces), rather than converting a fractional minor unit.
+- `reverseWithSnapshot` is unchanged.
+
 ## 0.31.0 — 2026-10-11
 
 ### Added — `./quantity`: the 6-decimal quantity grid for fractional stock and sale quantities

package/dist/bank-transaction.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/bank-transaction.d.ts
 /**
  * The other side of a bank transaction. All fields optional — different

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-C9iLWiWR.mjs";
+import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-BGPS_Ena.mjs";
 export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, CurrencyMismatchError, FxRounding, FxSnapshot, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -1,3 +1,4 @@
+import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
 //#region src/money/currency.ts
 /**
 * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
@@ -179,6 +180,34 @@ function roundMinor(raw, mode) {
 	if (mode === "ceil") return Math.ceil(raw);
 	return Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1);
 }
+/** `numerator / denominator` (denominator > 0) landed exactly by `mode`. */
+function divideMinor(numerator, denominator, mode) {
+	if (mode === "half-away-from-zero") return roundedDiv(numerator, denominator, "half-up");
+	const quotient = numerator / denominator;
+	if (numerator % denominator === 0n) return quotient;
+	if (mode === "floor") return numerator < 0n ? quotient - 1n : quotient;
+	return numerator < 0n ? quotient : quotient + 1n;
+}
+const DECIMAL_NUMBER = /^(-?)(\d+)(?:\.(\d+))?(?:e([+-]\d+))?$/;
+/**
+* A finite number as the exact decimal its shortest round-trip string names:
+* `110.15` → `{ int: 11015n, scale: 2 }`, so `110.15` means 110.15, not the
+* binary double nearest to it.
+*/
+function decimalOf(value) {
+	const match = DECIMAL_NUMBER.exec(String(value));
+	if (match === null) throw new TypeError(`Cannot read ${value} as a decimal`);
+	const [, sign, whole, fraction = "", exponent = "0"] = match;
+	const digits = BigInt(`${sign}${whole}${fraction}`);
+	const power = Number(exponent) - fraction.length;
+	return power >= 0 ? {
+		int: digits * 10n ** BigInt(power),
+		scale: 0
+	} : {
+		int: digits,
+		scale: -power
+	};
+}
 /**
 * Apply an {@link FxSnapshot} to a source-currency amount.
 *
@@ -198,12 +227,23 @@ function roundMinor(raw, mode) {
 * (USD has 2, JPY has 0). The conversion therefore goes
 * `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
 * off by 100× for any pair whose exponents differ.
+*
+* ## Exact, rounded once
+*
+* The rate is read as the decimal it prints as and the product is computed in
+* BigInt: `minor × rate × baseFactor / sourceFactor`, rounded once. A float
+* product misses exact half-way points (USD 5.30 × 110.15 = 583.795 BDT
+* computes as 583.79499…), so it rounded to 58379 paisa instead of 58380.
 */
 function convertWithSnapshot(source, fx, options = {}) {
 	if (source.currency !== fx.sourceCurrency) throw new CurrencyMismatchError(source.currency, fx.sourceCurrency);
 	if (!Number.isFinite(fx.rate)) throw new TypeError(`FxSnapshot.rate must be finite, got ${fx.rate}`);
+	if (!Number.isInteger(source.amount)) throw new TypeError(`Money.amount must be an integer in minor units, got ${source.amount}`);
+	const rate = decimalOf(fx.rate);
+	const numerator = BigInt(source.amount) * rate.int * BigInt(minorUnitFactor(fx.baseCurrency));
+	const denominator = BigInt(minorUnitFactor(fx.sourceCurrency)) * 10n ** BigInt(rate.scale);
 	return {
-		amount: roundMinor(source.amount / minorUnitFactor(fx.sourceCurrency) * fx.rate * minorUnitFactor(fx.baseCurrency), options.rounding ?? "half-away-from-zero"),
+		amount: Number(divideMinor(numerator, denominator, options.rounding ?? "half-away-from-zero")),
 		currency: currencyCode(fx.baseCurrency)
 	};
 }

package/dist/monetization.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/monetization.d.ts
 /**
  * A map of currency code → {@link Money} for explicit per-currency pricing.

package/dist/{money-C9iLWiWR.d.mts → money-BGPS_Ena.d.mts}

@@ -172,6 +172,13 @@ type FxRounding = 'half-away-from-zero' | 'floor' | 'ceil';
  * (USD has 2, JPY has 0). The conversion therefore goes
  * `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
  * off by 100× for any pair whose exponents differ.
+ *
+ * ## Exact, rounded once
+ *
+ * The rate is read as the decimal it prints as and the product is computed in
+ * BigInt: `minor × rate × baseFactor / sourceFactor`, rounded once. A float
+ * product misses exact half-way points (USD 5.30 × 110.15 = 583.795 BDT
+ * computes as 583.79499…), so it rounded to 58379 paisa instead of 58380.
  */
 declare function convertWithSnapshot(source: Money, fx: FxSnapshot, options?: {
   rounding?: FxRounding;

package/dist/money.d.mts

@@ -1,2 +1,2 @@
-import { C as CashDestination, S as CASH_DESTINATIONS, T as isCashDestination, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, k as CurrencyMismatchError, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, w as cashDestinationLabel, x as toMajor, y as subtractMoney } from "./money-C9iLWiWR.mjs";
+import { C as CashDestination, S as CASH_DESTINATIONS, T as isCashDestination, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, k as CurrencyMismatchError, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, w as cashDestinationLabel, x as toMajor, y as subtractMoney } from "./money-BGPS_Ena.mjs";
 export { CASH_DESTINATIONS, type CashDestination, CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, cashDestinationLabel, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isCashDestination, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

package/dist/payment-events.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 import { ProviderUnknownCause } from "./payment-gateway.mjs";
 //#region src/events/payment-events.d.ts

package/dist/payment-gateway.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 //#region src/money/payment-gateway.d.ts
 /**

package/dist/proration.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/proration.d.ts
 /**
  * How to count days within a period.

package/dist/unit-cost-rate.d.mts

@@ -1,4 +1,4 @@
-import { O as CurrencyCode, t as MinorUnits } from "./money-C9iLWiWR.mjs";
+import { O as CurrencyCode, t as MinorUnits } from "./money-BGPS_Ena.mjs";
 import { t as RoundingMode } from "./rounded-div-D7lyJXt8.mjs";
 //#region src/money/unit-cost-rate.d.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */

package/dist/unit-cost-rate.mjs

@@ -1,5 +1,5 @@
-import { t as MinorUnits } from "./money-BBOARE5f.mjs";
 import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
+import { t as MinorUnits } from "./money-BBOARE5f.mjs";
 //#region src/money/unit-cost-rate.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
 const RATE_SCALE = 1e6;

package/dist/usage-pricing.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 import { UsageRating } from "./monetization.mjs";
 //#region src/money/usage-pricing.d.ts
 /** What ONE unit of a sale line measured: `{ value: 2.3, unit: 'kg' }`. `unit` must equal the rating's `unitLabel`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",