@classytic/primitives 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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.32.0 — 2026-10-12
+
+### Added — `./quantity`: the step and running-sum helpers every package was copying
+
+Seven packages (order, cart, catalog, invoice, bd-tax, commerce-ui, pos-ui) each carried their own copy of the quantity grid; the pieces the grid did not yet offer are now here, so a consumer imports instead of copying.
+- `isQuantityStep(step)` — a guard for a usable step (a positive number on the grid, at least one grid unit). True exactly when `quantityStepToGrid` accepts it, pinned by a property test. For untrusted input (a stored `quantityStep`, a request body), where a throw is the wrong answer.
+- `isOnStepStrict(quantity, step)` — is the quantity ON the grid and a whole multiple of a valid step? STRICT and total: junk, an off-grid quantity or an invalid step is `false`, never a throw and never a snap. `isOnStep` is unchanged (it snaps first and throws on a bad step; its docs now say so and point here).
+- `addQuantity(a, b)` / `subtractQuantity(a, b)` — arithmetic on the grid, so a running sum never drifts (`1.2 + 1.15` is `2.35`). Zero is `0`, never `-0`. A non-finite operand throws `QuantityError`, as everywhere in the grid.
+
+## 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/quantity.d.mts

@@ -28,11 +28,32 @@ declare function snapQuantity(quantity: number, step?: number, mode?: RoundingMo
  * boundary, where a 7th decimal is a caller error rather than float drift.
  */
 declare function isOnQuantityGrid(value: number): boolean;
-/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+/**
+ * Is `quantity` a whole multiple of `step`, within half a grid unit? Snaps `quantity` first and THROWS
+ * ({@link QuantityError}) on a non-finite quantity or an invalid step. Use {@link isOnStepStrict} where a
+ * malformed input must answer `false` instead.
+ */
 declare function isOnStep(quantity: number, step: number): boolean;
+/**
+ * Is `step` a usable quantity step: a positive number on the grid, at least one grid unit? True exactly
+ * when {@link quantityStepToGrid} accepts it. A guard for untrusted input (a stored `quantityStep`, a
+ * request body) where a throw is the wrong answer.
+ */
+declare function isQuantityStep(step: unknown): step is number;
+/**
+ * Is `quantity` ON the grid and a whole multiple of a valid `step`? STRICT and total: an off-grid or
+ * non-finite quantity, or an invalid step, is `false` — never a throw and never a snap (`2.3500004`
+ * is off the 0.001 step here, on it for {@link isOnStep}). The check for an input boundary, such as a
+ * line quantity against the line's step.
+ */
+declare function isOnStepStrict(quantity: number, step: number): boolean;
+/** `a + b` on the grid, so a running sum never drifts (`1.2 + 1.15` is 2.35, not 2.3499…). */
+declare function addQuantity(a: number, b: number): number;
+/** `a − b` on the grid, so a running balance never drifts. */
+declare function subtractQuantity(a: number, b: number): number;
 /** Compare two quantities on the grid: equal when they snap to the same grid unit. */
 declare function compareQuantity(a: number, b: number): -1 | 0 | 1;
 /** `compareQuantity(a, b) === 0`. */
 declare function quantitiesEqual(a: number, b: number): boolean;
 //#endregion
-export { QUANTITY_SCALE, QuantityError, QuantityErrorCode, type RoundingMode, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };
+export { QUANTITY_SCALE, QuantityError, QuantityErrorCode, type RoundingMode, addQuantity, compareQuantity, isOnQuantityGrid, isOnStep, isOnStepStrict, isQuantityStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity, subtractQuantity };

package/dist/quantity.mjs

@@ -70,10 +70,39 @@ function isOnQuantityGrid(value) {
 	const grid = Math.round(scaled);
 	return Number.isSafeInteger(grid) && Math.abs(grid - scaled) <= 1e-9 * Math.max(1, Math.abs(scaled));
 }
-/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+/**
+* Is `quantity` a whole multiple of `step`, within half a grid unit? Snaps `quantity` first and THROWS
+* ({@link QuantityError}) on a non-finite quantity or an invalid step. Use {@link isOnStepStrict} where a
+* malformed input must answer `false` instead.
+*/
 function isOnStep(quantity, step) {
 	return quantityToGrid(quantity) % quantityStepToGrid(step) === 0n;
 }
+/**
+* Is `step` a usable quantity step: a positive number on the grid, at least one grid unit? True exactly
+* when {@link quantityStepToGrid} accepts it. A guard for untrusted input (a stored `quantityStep`, a
+* request body) where a throw is the wrong answer.
+*/
+function isQuantityStep(step) {
+	return typeof step === "number" && Number.isFinite(step) && step > 0 && isOnQuantityGrid(step) && quantityToGrid(step) > 0n;
+}
+/**
+* Is `quantity` ON the grid and a whole multiple of a valid `step`? STRICT and total: an off-grid or
+* non-finite quantity, or an invalid step, is `false` — never a throw and never a snap (`2.3500004`
+* is off the 0.001 step here, on it for {@link isOnStep}). The check for an input boundary, such as a
+* line quantity against the line's step.
+*/
+function isOnStepStrict(quantity, step) {
+	return isOnQuantityGrid(quantity) && isQuantityStep(step) && isOnStep(quantity, step);
+}
+/** `a + b` on the grid, so a running sum never drifts (`1.2 + 1.15` is 2.35, not 2.3499…). */
+function addQuantity(a, b) {
+	return gridToNumber(quantityToGrid(a) + quantityToGrid(b));
+}
+/** `a − b` on the grid, so a running balance never drifts. */
+function subtractQuantity(a, b) {
+	return gridToNumber(quantityToGrid(a) - quantityToGrid(b));
+}
 /** Compare two quantities on the grid: equal when they snap to the same grid unit. */
 function compareQuantity(a, b) {
 	const ga = quantityToGrid(a);
@@ -85,4 +114,4 @@ function quantitiesEqual(a, b) {
 	return compareQuantity(a, b) === 0;
 }
 //#endregion
-export { QUANTITY_SCALE, QuantityError, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };
+export { QUANTITY_SCALE, QuantityError, addQuantity, compareQuantity, isOnQuantityGrid, isOnStep, isOnStepStrict, isQuantityStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity, subtractQuantity };

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.32.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",