@classytic/primitives 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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`)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.31.1",
+  "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",