@rinxun/numeric-calculator 1.0.7 → 1.0.9-beta.1

package/README.md

@@ -142,7 +142,7 @@ const result = new NC(-1000).divide(100, '20', 2).toPrecision(); // -1000/100/20
 
 
 
-<h4>inst.round(fractionDigits?: number)</h4>
+<h4>inst.round(fractionDigits?: number, options?: { snap?: boolean })</h4>
 
 ``` typescript
 const result = new NC().round(3); // 0
@@ -151,6 +151,15 @@ const result = new NC(7.65).times(16.5).round(2); // => 7.65 * 16.5 = 126.225
 const result = new NC(26.05).times(16.5).round(2); // => 26.05 * 16.5 = 429.825 ≈ 429.83
 ```
 
+`options.snap` (default `false`) makes rounding tolerant to binary floating-point representation dust. After plain float arithmetic upstream, a true `95.015` can arrive as `95.01499999999942`, and exact-decimal rounding of the *represented* value then rounds down, disagreeing with the true value. With `snap`, the amplified value is nudged by a few ULPs relative to its own magnitude before `Math.round`, so only values sitting exactly on a rounding boundary are affected — everything beyond a few ULPs of the boundary keeps its exact-decimal result, and there is no magic number to tune:
+
+``` typescript
+const dust = 2959.9649999999997; // true value 2959.965, distorted by float subtraction upstream
+const result = new NC(dust).round(2); // 2959.96 — exact decimal of the represented value
+const result = new NC(dust).round(2, { snap: true }); // 2959.97 — matches the true half-up value
+const result = new NC(719.6446).round(2, { snap: true }); // 719.64 — values beyond a few ULPs of the boundary are untouched
+```
+
 
 
 <h4>inst.toPrecision(precision?: number)</h4>
@@ -187,4 +196,4 @@ const result = new NC(10).plus(new NC().times(2, 4), '6').divide(new NC(12).minu
 
 <h2>Changelog</h2>
 
-If you have recently updated, please read the [changelog](https://github.com/rinxun/numeric-calculator/releases) for details of what has changed.
+If you have recently updated, please read the [changelog](https://github.com/rinxun/numeric-calculator/releases) for details of what has changed.

package/index.d.ts

@@ -3,6 +3,17 @@ declare type IConfig = {
     fractionDigits?: number;
     enableCheckBoundary?: boolean;
 };
+declare type IRoundOptions = {
+    /**
+     * @description when true, nudges the amplified value by a few ULPs relative
+     * to its own magnitude before rounding, so that binary floating-point
+     * representation dust does not flip values sitting exactly on a rounding
+     * boundary. Use it when the input may come from plain float arithmetic
+     * upstream, e.g. a true 95.015 arriving as 95.01499999999942. Defaults to
+     * false, which keeps the exact-decimal behavior of the represented value.
+     */
+    snap?: boolean;
+};
 declare type IOperand = Calculator | number | string;
 /**
  * @description Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue
@@ -134,8 +145,9 @@ declare class Calculator {
     /**
      *
      * @param {number} fractionDigits default to 2, should be in the range 0 - 20
+     * @param {IRoundOptions} options rounding options, see {@link IRoundOptions.snap}
      * @returns {number} rounded result
      */
-    round(fractionDigits?: number): number;
+    round(fractionDigits?: number, options?: IRoundOptions): number;
 }
 export default Calculator;

package/index.js

@@ -323,13 +323,24 @@ var Calculator = /** @class */ (function () {
     /**
      *
      * @param {number} fractionDigits default to 2, should be in the range 0 - 20
+     * @param {IRoundOptions} options rounding options, see {@link IRoundOptions.snap}
      * @returns {number} rounded result
      */
-    Calculator.prototype.round = function (fractionDigits) {
+    Calculator.prototype.round = function (fractionDigits, options) {
         var magnification = Math.pow(10, fractionDigits || this._fractionDigits || 2);
         var amplifyingResult = this.processTimes(this._VALUE || 0, magnification);
         this.checkBoundary(amplifyingResult);
-        return this.processDivide(Math.round(amplifyingResult), magnification);
+        // Round the magnitude, then restore the sign, so a negative value rounds as
+        // the mirror of its positive (-0.125 -> -0.13, like 0.125 -> 0.13) and the
+        // snap nudge moves it away from zero just as it does for positives.
+        var magnitude = Math.abs(amplifyingResult);
+        // Dust observed in real pipelines reaches a few dozen ULPs (each float op
+        // distorts by at most 0.5 ULP), so 64x headroom. This stays safely below
+        // half an amplified unit at any magnitude (it scales with the value), and
+        // assumes inputs are meaningful well beyond ULP precision.
+        var tolerance = (options === null || options === void 0 ? void 0 : options.snap) ? magnitude * Number.EPSILON * 64 : 0;
+        var rounded = Math.round(magnitude + tolerance);
+        return this.processDivide(amplifyingResult < 0 ? -rounded : rounded, magnification);
     };
     return Calculator;
 }());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rinxun/numeric-calculator",
-  "version": "1.0.7",
+  "version": "1.0.9-beta.1",
   "description": "Calculate addition, subtraction, multiplication, division precisely, for tackling the precision issue",
   "keywords": [
     "long",
@@ -37,7 +37,8 @@
     "url": "https://github.com/JandneMa"
   },
   "scripts": {
-    "build": "./node_modules/.bin/tsc"
+    "build": "./node_modules/.bin/tsc",
+    "test": "./node_modules/.bin/tsc > /dev/null && node --test tests/*.test.js"
   },
   "files": [
     "*.js",

package/tests/arithmetic.test.js

@@ -0,0 +1,397 @@
+/**
+ * Tests for plus, minus, times, divide, chaining, operand types, toFixed and
+ * toPrecision.
+ *
+ * Every expected value comes from exact decimal arithmetic on BigInt (see
+ * exact-decimal.js), never from the library itself. The library documents its
+ * results as precise to 15 significant digits (toPrecision() defaults to 15),
+ * so the theoretical result of an operation is the exact result rounded to 15
+ * significant digits, stored as the nearest double.
+ *
+ * Some 1.0.x limitations are kept as todo tests: they run and report on every
+ * run without failing it. Each todo names the cause.
+ *
+ * Run with `yarn test` (builds index.js first).
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Calculator = require("../index.js").default;
+const {
+  parseDecimal,
+  addDecimal,
+  subtractDecimal,
+  multiplyDecimal,
+  roundHalfAwayFromZero,
+  roundSignificant,
+  significantCandidates,
+  divideDecimal,
+  makeRandom,
+  randomDecimal,
+  expectAll,
+} = require("./exact-decimal");
+
+const PRECISION = 15;
+/**
+ * Theoretical public result of an exact decimal: rounded to 15 significant
+ * digits, as a double. Within one double step of a 15-digit tie either
+ * neighbour is accepted (see significantCandidates).
+ */
+const expected15 = (dec) => significantCandidates(dec, PRECISION).map(Number);
+/** Theoretical public result of the exact quotient a / b. */
+const expectedQuotient = (a, b) =>
+  significantCandidates(divideDecimal(parseDecimal(a), parseDecimal(b), PRECISION), PRECISION).map(Number);
+
+/** Random operand: below 10^7 with 0-4 decimals, so sums stay within 12 digits. */
+const operand = (random, allowNegative = true) =>
+  randomDecimal(random, 10000000, Math.floor(random() * 5), allowNegative);
+
+/** Random money amount: below 10^7 with 2 decimals. */
+const money = (random, allowNegative = true) =>
+  randomDecimal(random, 10000000, 2, allowNegative);
+
+/** n random pairs from `make`. */
+function* pairs(seed, n, make) {
+  const random = makeRandom(seed);
+  for (let i = 0; i < n; i++) yield { a: make(random), b: make(random) };
+}
+
+const N = 100000;
+
+/**
+ * Known 1.0.x limitations, used as `todo` reasons. Each is fixed by scaling
+ * operands to exact integers (Math.round) in processTimes/processDivide and by
+ * dividing once in processDivide; drop the todo when that lands.
+ */
+const KNOWN = {
+  scaling:
+    "1.0.x scales operands with a float multiply (4486513.64 * 100 = 448651363.99999994), " +
+    "so about 0.5-1.5% of results are off in the last digits",
+  divide:
+    "1.0.x rounds the quotient to 15 digits, scales it, and the caller rounds again, " +
+    "so a few quotients are off by one in the 15th digit",
+};
+
+// #region plus / minus
+test("plus: a + b equals the exact sum, operands of the same sign", () => {
+  const random = makeRandom(11);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      const sign = random() < 0.5 ? "-" : "";
+      yield { a: sign + operand(random, false), b: sign + operand(random, false) };
+    }
+  }
+  expectAll(cases(), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).plus(Number(b)).toPrecision(),
+    expected: expected15(addDecimal(parseDecimal(a), parseDecimal(b))),
+  }));
+});
+
+test("plus: a + b equals the exact sum, operands of any sign", { todo: KNOWN.scaling }, () => {
+  expectAll(pairs(12, N, operand), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).plus(Number(b)).toPrecision(),
+    expected: expected15(addDecimal(parseDecimal(a), parseDecimal(b))),
+  }));
+});
+
+test("minus: a - b equals the exact difference", { todo: KNOWN.scaling }, () => {
+  expectAll(pairs(13, N, operand), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).minus(Number(b)).toPrecision(),
+    expected: expected15(subtractDecimal(parseDecimal(a), parseDecimal(b))),
+  }));
+});
+
+test("minus: money a - b equals the exact difference", { todo: KNOWN.scaling }, () => {
+  expectAll(pairs(14, N, money), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).minus(Number(b)).toPrecision(),
+    expected: expected15(subtractDecimal(parseDecimal(a), parseDecimal(b))),
+  }));
+});
+
+test("plus/minus on money, then toFixed(2), equal the exact result", () => {
+  expectAll(pairs(15, N, money), ({ a, b }) => {
+    const exact = subtractDecimal(parseDecimal(a), parseDecimal(b));
+    return {
+      actual: new Calculator(Number(a)).minus(Number(b)).toFixed(2),
+      expected: roundHalfAwayFromZero(exact, 2).replace(/^-(0\.00)$/, "$1"),
+    };
+  });
+});
+
+test("plus: several operands at once equal the exact sum", { todo: KNOWN.scaling }, () => {
+  const random = makeRandom(16);
+  function* cases() {
+    for (let i = 0; i < N / 4; i++) {
+      yield { ops: Array.from({ length: 2 + Math.floor(random() * 5) }, () => money(random)) };
+    }
+  }
+  expectAll(cases(), ({ ops }) => ({
+    actual: new Calculator(Number(ops[0])).plus(...ops.slice(1).map(Number)).toPrecision(),
+    expected: expected15(ops.map(parseDecimal).reduce(addDecimal)),
+  }));
+});
+
+test("minus: x - x is 0 and x - 0 is x", () => {
+  const random = makeRandom(17);
+  for (let i = 0; i < 10000; i++) {
+    const x = Number(operand(random));
+    assert.equal(new Calculator(x).minus(x).toPrecision(), 0, `${x} - ${x}`);
+    assert.equal(new Calculator(x).minus(0).toPrecision(), x, `${x} - 0`);
+    assert.equal(new Calculator(x).plus(0).toPrecision(), x, `${x} + 0`);
+  }
+});
+
+test("plus is commutative: a + b equals b + a", () => {
+  expectAll(pairs(18, N, operand), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).plus(Number(b)).toPrecision(),
+    expected: new Calculator(Number(b)).plus(Number(a)).toPrecision(),
+  }));
+});
+// #endregion
+
+// #region times
+/**
+ * The library multiplies the operands as integers (1.25 * 0.5 -> 125 * 5), so
+ * results are exact only while that integer product stays a safe integer.
+ * Beyond it, enableCheckBoundary warns (tested below).
+ */
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const productIsSafe = (a, b) => {
+  const { unscaled } = multiplyDecimal(parseDecimal(a), parseDecimal(b));
+  return (unscaled < 0n ? -unscaled : unscaled) <= MAX_SAFE;
+};
+
+test("times: a * b equals the exact product, within the safe-integer range", { todo: KNOWN.scaling }, () => {
+  function* cases() {
+    for (const pair of pairs(21, N, operand)) if (productIsSafe(pair.a, pair.b)) yield pair;
+  }
+  expectAll(cases(), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).times(Number(b)).toPrecision(),
+    expected: expected15(multiplyDecimal(parseDecimal(a), parseDecimal(b))),
+  }));
+});
+
+test("enableCheckBoundary warns when the integer product leaves the safe range", (t) => {
+  const warn = t.mock.method(console, "warn", () => {});
+  new Calculator(4408410.0051, { enableCheckBoundary: true }).times(-8862149.1585);
+  assert.ok(warn.mock.callCount() > 0, "expected a boundary warning");
+  warn.mock.resetCalls();
+  new Calculator(1.25, { enableCheckBoundary: true }).times(0.5);
+  assert.equal(warn.mock.callCount(), 0, "no warning for a small product");
+});
+
+test("times: money * rate equals the exact product", () => {
+  const random = makeRandom(22);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      yield { a: money(random), r: randomDecimal(random, 100, 4) };
+    }
+  }
+  expectAll(cases(), ({ a, r }) => ({
+    actual: new Calculator(Number(a)).times(Number(r)).toPrecision(),
+    expected: expected15(multiplyDecimal(parseDecimal(a), parseDecimal(r))),
+  }));
+});
+
+test("times: small numbers written in exponent form", () => {
+  const random = makeRandom(23);
+  function* cases() {
+    for (let i = 0; i < N / 4; i++) {
+      // e.g. 1.234e-9 * 5.6e-7: mantissas with up to 4 digits, exponents -12..-5
+      const a = `${(1 + Math.floor(random() * 9999)) / 1000}e-${5 + Math.floor(random() * 8)}`;
+      const b = `${(1 + Math.floor(random() * 9999)) / 1000}e-${5 + Math.floor(random() * 8)}`;
+      yield { a, b };
+    }
+  }
+  const toDec = (str) => {
+    const [mantissa, exponent] = str.split("e");
+    const dec = parseDecimal(mantissa);
+    return { unscaled: dec.unscaled, scale: dec.scale - Number(exponent) };
+  };
+  expectAll(cases(), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).times(Number(b)).toPrecision(),
+    expected: expected15(multiplyDecimal(toDec(a), toDec(b))),
+  }));
+});
+
+test("times is commutative and has 1 as identity", () => {
+  expectAll(pairs(24, N, operand), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).times(Number(b)).toPrecision(),
+    expected: new Calculator(Number(b)).times(Number(a)).toPrecision(),
+  }));
+  const random = makeRandom(25);
+  for (let i = 0; i < 10000; i++) {
+    const x = Number(operand(random));
+    assert.equal(new Calculator(x).times(1).toPrecision(), x, `${x} * 1`);
+  }
+});
+// #endregion
+
+// #region divide
+test("divide: a / b equals the exact quotient rounded to 15 significant digits", { todo: KNOWN.divide }, () => {
+  const random = makeRandom(31);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      const a = operand(random);
+      let b = operand(random);
+      if (Number(b) === 0) b = "1";
+      yield { a, b };
+    }
+  }
+  expectAll(cases(), ({ a, b }) => ({
+    actual: new Calculator(Number(a)).divide(Number(b)).toPrecision(),
+    expected: expectedQuotient(a, b),
+  }));
+});
+
+test("divide: money / pay periods equals the exact quotient", () => {
+  const random = makeRandom(32);
+  const periods = ["1", "12", "24", "26", "52"];
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      yield { a: money(random), p: periods[Math.floor(random() * periods.length)] };
+    }
+  }
+  expectAll(cases(), ({ a, p }) => ({
+    actual: new Calculator(Number(a)).divide(Number(p)).toPrecision(),
+    expected: expectedQuotient(a, p),
+  }));
+});
+
+test("divide: (a * b) / b gives back a when the product is exact", () => {
+  const random = makeRandom(33);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      const a = money(random);
+      let b = randomDecimal(random, 1000, 2);
+      if (Number(b) === 0) b = "1.25";
+      const product = roundHalfAwayFromZero(multiplyDecimal(parseDecimal(a), parseDecimal(b)), 4);
+      yield { a, b, product };
+    }
+  }
+  expectAll(cases(), ({ a, b, product }) => ({
+    actual: new Calculator(Number(product)).divide(Number(b)).toPrecision(),
+    expected: Number(a),
+  }));
+});
+// #endregion
+
+// #region chaining and operands
+test("chained plus/minus/times equal the exact result", { todo: KNOWN.scaling }, () => {
+  const random = makeRandom(41);
+  function* cases() {
+    for (let i = 0; i < N / 2; i++) {
+      // (a + b) * r - c, all money except a 2-decimal rate below 10
+      yield { a: money(random), b: money(random), r: randomDecimal(random, 10, 2), c: money(random) };
+    }
+  }
+  expectAll(cases(), ({ a, b, r, c }) => {
+    const exact = subtractDecimal(
+      multiplyDecimal(addDecimal(parseDecimal(a), parseDecimal(b)), parseDecimal(r)),
+      parseDecimal(c)
+    );
+    return {
+      actual: new Calculator(Number(a)).plus(Number(b)).times(Number(r)).minus(Number(c)).toPrecision(),
+      expected: expected15(exact),
+    };
+  });
+});
+
+test("string, number and Calculator operands give the same result", () => {
+  const random = makeRandom(42);
+  for (let i = 0; i < 10000; i++) {
+    const a = operand(random);
+    const b = operand(random);
+    const fromNumbers = new Calculator(Number(a)).plus(Number(b)).toPrecision();
+    assert.equal(new Calculator(a).plus(b).toPrecision(), fromNumbers, `"${a}" + "${b}"`);
+    assert.equal(
+      new Calculator(new Calculator(a)).plus(new Calculator(b)).toPrecision(),
+      fromNumbers,
+      `Calculator(${a}) + Calculator(${b})`
+    );
+  }
+});
+
+test("the first operand can come from the operation when the constructor has none", () => {
+  assert.equal(new Calculator().plus(0.1, 0.2).toPrecision(), 0.3);
+  assert.equal(new Calculator().minus(1, 0.9).toPrecision(), 0.1);
+  assert.equal(new Calculator().times(0.1, 3).toPrecision(), 0.3);
+  assert.equal(new Calculator().divide(0.3, 0.1).toPrecision(), 3);
+});
+
+test("well-known float traps give the exact decimal result", () => {
+  const cases = [
+    { op: "plus", a: "0.1", b: "0.2", exact: "0.3" },
+    { op: "plus", a: "0.7", b: "0.1", exact: "0.8" },
+    { op: "minus", a: "1", b: "0.9", exact: "0.1" },
+    { op: "minus", a: "0.3", b: "0.1", exact: "0.2" },
+    { op: "times", a: "0.1", b: "3", exact: "0.3" },
+    { op: "times", a: "1.005", b: "1000", exact: "1005" },
+    { op: "times", a: "19.9", b: "100", exact: "1990" },
+    { op: "divide", a: "0.3", b: "0.1", exact: "3" },
+    { op: "divide", a: "0.69", b: "10", exact: "0.069" },
+  ];
+  expectAll(cases, ({ op, a, b, exact }) => ({
+    actual: new Calculator(Number(a))[op](Number(b)).toPrecision(),
+    expected: Number(exact),
+  }));
+});
+// #endregion
+
+// #region documented behaviour that is not arithmetic
+test("non-numeric string operands count as 0", () => {
+  assert.equal(new Calculator("abc").plus(5).toPrecision(), 5);
+  assert.equal(new Calculator(5).plus("abc").toPrecision(), 5);
+  assert.equal(new Calculator(5).times("abc").toPrecision(), 0);
+});
+
+test("times by 0 and divide by 0 both give 0", () => {
+  assert.equal(new Calculator(12.34).times(0).toPrecision(), 0);
+  assert.equal(new Calculator(12.34).divide(0).toPrecision(), 0);
+});
+// #endregion
+
+// #region toFixed / toPrecision
+test("toFixed(n): values not on a half match exact rounding", () => {
+  const random = makeRandom(51);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      const n = 1 + Math.floor(random() * 4);
+      const str = randomDecimal(random, 1000000, n + 1 + Math.floor(random() * 2));
+      const dec = parseDecimal(str);
+      const tail = dec.unscaled % 10n ** BigInt(dec.scale - n);
+      const half = 5n * 10n ** BigInt(dec.scale - n - 1);
+      if (tail === half || tail === -half) continue;
+      yield { str, n };
+    }
+  }
+  expectAll(cases(), ({ str, n }) => ({
+    actual: new Calculator(Number(str)).toFixed(n),
+    expected: roundHalfAwayFromZero(parseDecimal(str), n).replace(/^-(0\.0+)$/, "$1"),
+  }));
+});
+
+test("toFixed() pads to the configured fraction digits, default 2", () => {
+  assert.equal(new Calculator(3).toFixed(), "3.00");
+  assert.equal(new Calculator(3.1).toFixed(4), "3.1000");
+  assert.equal(new Calculator(3.1, { fractionDigits: 3 }).toFixed(), "3.100");
+});
+
+test("toPrecision(p): matches the exact value rounded to p significant digits, off a half", () => {
+  const random = makeRandom(52);
+  function* cases() {
+    for (let i = 0; i < N; i++) {
+      const p = 1 + Math.floor(random() * 12);
+      const str = operand(random);
+      const dec = parseDecimal(str);
+      // Skip exact halves at digit p; how they round depends on the stored double.
+      const digits = (dec.unscaled < 0n ? -dec.unscaled : dec.unscaled).toString();
+      if (digits.length > p && /^50*$/.test(digits.slice(p))) continue;
+      yield { str, p };
+    }
+  }
+  expectAll(cases(), ({ str, p }) => ({
+    actual: new Calculator(Number(str)).toPrecision(p),
+    expected: Number(roundSignificant(parseDecimal(str), p)),
+  }));
+});
+// #endregion

package/tests/exact-decimal.js

@@ -0,0 +1,214 @@
+/**
+ * Exact decimal arithmetic on BigInt, used as the theoretical reference in the
+ * tests. Nothing here calls the library, so expected values never come from the
+ * code under test.
+ */
+const assert = require("node:assert/strict");
+
+// #region Exact decimals
+/**
+ * An exact decimal number: value = unscaled / 10^scale, unscaled is a signed BigInt.
+ * @typedef {{ unscaled: bigint, scale: number }} Decimal
+ */
+
+const abs = (n) => (n < 0n ? -n : n);
+const pow10 = (n) => 10n ** BigInt(n);
+
+/** @returns {Decimal} */
+function parseDecimal(str) {
+  const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(str);
+  if (!match) throw new Error(`not a plain decimal: ${str}`);
+  const fraction = match[3] || "";
+  const magnitude = BigInt(match[2] + fraction);
+  return { unscaled: match[1] === "-" ? -magnitude : magnitude, scale: fraction.length };
+}
+
+/** Rescale to a larger scale without changing the value. */
+function rescale(dec, scale) {
+  return { unscaled: dec.unscaled * pow10(scale - dec.scale), scale };
+}
+
+/** @returns {Decimal} exact a + b */
+function addDecimal(a, b) {
+  const scale = Math.max(a.scale, b.scale);
+  return { unscaled: rescale(a, scale).unscaled + rescale(b, scale).unscaled, scale };
+}
+
+/** @returns {Decimal} exact a - b */
+function subtractDecimal(a, b) {
+  return addDecimal(a, { unscaled: -b.unscaled, scale: b.scale });
+}
+
+/** @returns {Decimal} exact a * b */
+function multiplyDecimal(a, b) {
+  return { unscaled: a.unscaled * b.unscaled, scale: a.scale + b.scale };
+}
+
+/** Decimal string for unscaled / 10^scale; scale may be negative. */
+function formatDecimal(unscaled, scale) {
+  const negative = unscaled < 0n;
+  let digits = abs(unscaled).toString();
+  if (scale <= 0) {
+    digits += "0".repeat(-scale);
+  } else {
+    digits = digits.padStart(scale + 1, "0");
+    digits = `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+  }
+  return (negative && unscaled !== 0n ? "-" : "") + digits;
+}
+
+/** Drop `drop` trailing digits of a non-negative integer, rounding half away from zero. */
+function dropDigitsHalfAway(magnitude, drop) {
+  if (drop <= 0) return magnitude * pow10(-drop);
+  const divisor = pow10(drop);
+  const quotient = magnitude / divisor;
+  return (magnitude % divisor) * 2n >= divisor ? quotient + 1n : quotient;
+}
+
+/** Round to n fraction digits, halves away from zero. Returns a decimal string. */
+function roundHalfAwayFromZero(dec, n) {
+  const sign = dec.unscaled < 0n ? -1n : 1n;
+  const magnitude = dropDigitsHalfAway(abs(dec.unscaled), dec.scale - n);
+  return formatDecimal(sign * magnitude, n);
+}
+
+/** Round to p significant digits, halves away from zero. Returns a decimal string. */
+function roundSignificant(dec, p) {
+  const magnitude = abs(dec.unscaled);
+  if (magnitude === 0n) return "0";
+  const drop = magnitude.toString().length - p;
+  if (drop <= 0) return formatDecimal(dec.unscaled, dec.scale);
+  const sign = dec.unscaled < 0n ? -1n : 1n;
+  return formatDecimal(sign * dropDigitsHalfAway(magnitude, drop), dec.scale - drop);
+}
+
+/**
+ * The values a double-based result may take when it claims p significant
+ * digits: the exact value rounded to p digits and, only when the exact value
+ * sits within one double step (2^-52 relative) of a p-digit tie, the other
+ * neighbour too. A double cannot tell which side of such a tie the exact value
+ * is on, so either answer is as good as the format allows.
+ * @returns {string[]} acceptable decimal strings, the nearest first
+ */
+function significantCandidates(dec, p) {
+  const magnitude = abs(dec.unscaled);
+  const drop = magnitude.toString().length - p;
+  const nearest = roundSignificant(dec, p);
+  if (magnitude === 0n || drop <= 0) return [nearest];
+  const unit = pow10(drop);
+  const remainder = magnitude % unit;
+  const distanceToTie = abs(remainder * 2n - unit); // in half-units
+  if (distanceToTie * 2n ** 52n > magnitude * 2n) return [nearest];
+  const sign = dec.unscaled < 0n ? -1n : 1n;
+  const down = formatDecimal(sign * (magnitude / unit), dec.scale - drop);
+  const up = formatDecimal(sign * (magnitude / unit + 1n), dec.scale - drop);
+  return [nearest, nearest === up ? down : up];
+}
+
+/** Exact a / b with p + 3 extra digits and a sticky digit, as a Decimal. */
+function divideDecimal(a, b, p) {
+  if (b.unscaled === 0n) throw new Error("division by zero");
+  const numerator = abs(a.unscaled) * pow10(b.scale);
+  const denominator = abs(b.unscaled) * pow10(a.scale);
+  const extra =
+    p + 3 + Math.max(0, denominator.toString().length - numerator.toString().length);
+  const scaled = numerator * pow10(extra);
+  const quotient = (scaled / denominator) * 10n + (scaled % denominator !== 0n ? 1n : 0n);
+  const negative = a.unscaled < 0n !== b.unscaled < 0n && a.unscaled !== 0n;
+  return { unscaled: negative ? -quotient : quotient, scale: extra + 1 };
+}
+
+/**
+ * a / b rounded to p significant digits (halves away from zero), computed from
+ * enough exact quotient digits plus a sticky bit, so it is correctly rounded.
+ */
+function divideSignificant(a, b, p) {
+  if (b.unscaled === 0n) throw new Error("division by zero");
+  const numerator = abs(a.unscaled) * pow10(b.scale);
+  const denominator = abs(b.unscaled) * pow10(a.scale);
+  const extra =
+    p + 3 + Math.max(0, denominator.toString().length - numerator.toString().length);
+  const scaled = numerator * pow10(extra);
+  let quotient = scaled / denominator;
+  // A non-zero remainder only matters to break an exact-looking half; append a
+  // sticky digit so a truncated ...5000 that is really above half rounds up.
+  const sticky = scaled % denominator !== 0n;
+  quotient = quotient * 10n + (sticky ? 1n : 0n);
+  const negative = a.unscaled < 0n !== b.unscaled < 0n && a.unscaled !== 0n;
+  return roundSignificant({ unscaled: negative ? -quotient : quotient, scale: extra + 1 }, p);
+}
+
+/** Number of significant digits of a decimal. */
+function significantDigits(dec) {
+  const magnitude = abs(dec.unscaled);
+  if (magnitude === 0n) return 1;
+  return magnitude.toString().replace(/0+$/, "").length || 1;
+}
+
+/** The double that stores a decimal string (the nearest double to it). */
+const toNumber = (str) => Number(str);
+// #endregion
+
+// #region Test helpers
+/** Seeded PRNG (mulberry32), so every run checks the same values. */
+function makeRandom(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Random decimal string: below `maxInt` before the point, exactly `decimals` after it. */
+function randomDecimal(random, maxInt, decimals, allowNegative = true) {
+  const intPart = Math.floor(random() * maxInt);
+  let fraction = "";
+  for (let i = 0; i < decimals; i++) fraction += Math.floor(random() * 10);
+  const sign = allowNegative && random() < 0.5 ? "-" : "";
+  return `${sign}${intPart}${decimals ? `.${fraction}` : ""}`;
+}
+
+/**
+ * Run `check` on every case and fail once with the first few mismatches, so a
+ * failure shows concrete inputs instead of only a count.
+ */
+function expectAll(cases, check) {
+  const failures = [];
+  let total = 0;
+  for (const c of cases) {
+    total++;
+    // `expected` is one value, or an array of acceptable values (nearest first).
+    const { actual, expected } = check(c);
+    const accepted = Array.isArray(expected) ? expected : [expected];
+    if (!accepted.some((e) => Object.is(actual, e))) {
+      failures.push({ ...c, actual, expected: accepted.length === 1 ? accepted[0] : accepted });
+    }
+  }
+  assert.ok(total > 0, "no cases were generated");
+  assert.deepEqual(
+    failures.slice(0, 10),
+    [],
+    `${failures.length} of ${total} cases differ from the exact result`
+  );
+}
+// #endregion
+
+module.exports = {
+  parseDecimal,
+  addDecimal,
+  subtractDecimal,
+  multiplyDecimal,
+  roundHalfAwayFromZero,
+  roundSignificant,
+  significantCandidates,
+  divideDecimal,
+  divideSignificant,
+  significantDigits,
+  toNumber,
+  makeRandom,
+  randomDecimal,
+  expectAll,
+};

package/tests/exact-decimal.test.js

@@ -0,0 +1,63 @@
+/**
+ * Checks the exact-decimal reference itself against values worked out by hand,
+ * since every other test trusts it.
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const E = require("./exact-decimal");
+
+const d = E.parseDecimal;
+const sig = (str, p) => E.roundSignificant(d(str), p);
+
+test("reference: exact add, subtract and multiply", () => {
+  assert.deepEqual(E.addDecimal(d("0.1"), d("0.2")), { unscaled: 3n, scale: 1 });
+  assert.deepEqual(E.subtractDecimal(d("1.5"), d("2.25")), { unscaled: -75n, scale: 2 });
+  assert.deepEqual(E.multiplyDecimal(d("1.2"), d("-0.05")), { unscaled: -60n, scale: 3 });
+  assert.deepEqual(E.addDecimal(d("-615403.718"), d("613501.153")), { unscaled: -1902565n, scale: 3 });
+});
+
+test("reference: rounding to fraction digits, halves away from zero", () => {
+  assert.equal(E.roundHalfAwayFromZero(d("1.005"), 2), "1.01");
+  assert.equal(E.roundHalfAwayFromZero(d("-1.005"), 2), "-1.01");
+  assert.equal(E.roundHalfAwayFromZero(d("1.0049"), 2), "1.00");
+  assert.equal(E.roundHalfAwayFromZero(d("-0.004"), 2), "0.00");
+  assert.equal(E.roundHalfAwayFromZero(d("2.5"), 0), "3");
+  assert.equal(E.roundHalfAwayFromZero(d("7"), 2), "7.00");
+});
+
+test("reference: rounding to significant digits", () => {
+  assert.equal(sig("123456", 3), "123000");
+  assert.equal(sig("0.00012345", 3), "0.000123");
+  assert.equal(sig("-2.5", 1), "-3");
+  assert.equal(Number(sig("9.9999", 3)), 10); // carries into a new digit
+  assert.equal(sig("0.3", 15), "0.3");
+  assert.equal(sig("0", 15), "0");
+});
+
+test("reference: division rounded to significant digits", () => {
+  const div = (a, b, p) => E.divideSignificant(d(a), d(b), p);
+  assert.equal(div("1", "3", 15), "0.333333333333333");
+  assert.equal(div("2", "3", 15), "0.666666666666667");
+  assert.equal(div("100", "7", 15), "14.2857142857143");
+  assert.equal(div("-1", "8", 2), "-0.13");
+  assert.equal(div("1", "-8", 2), "-0.13");
+  assert.equal(div("0.69", "10", 15), "0.0690000000000000");
+  assert.equal(div("0", "5", 15), "0");
+  // 1/16 = 0.0625 exactly: a true tie at 2 digits rounds away from zero.
+  assert.equal(div("1", "16", 3), "0.0625");
+  assert.equal(div("1", "16", 2), "0.063");
+  // 1/16.0001 is just below 0.0625, so it rounds down even though the digits start 0.0624999...
+  assert.equal(div("1", "16.0001", 2), "0.062");
+});
+
+test("reference: tie zone accepts both neighbours only within one double step", () => {
+  // 16 digits ending in 5: an exact tie at 15 digits, so both neighbours are accepted.
+  assert.deepEqual(E.significantCandidates(d("1234567890123.455"), 15), [
+    "1234567890123.46",
+    "1234567890123.45",
+  ]);
+  // Clearly below the tie: only the nearest.
+  assert.deepEqual(E.significantCandidates(d("1234567890123.454"), 15), ["1234567890123.45"]);
+  // Short values are exact: only themselves.
+  assert.deepEqual(E.significantCandidates(d("0.3"), 15), ["0.3"]);
+});

package/tests/round.test.js

@@ -0,0 +1,249 @@
+/**
+ * Tests for Calculator#round.
+ *
+ * Every expected value comes from exact decimal arithmetic on BigInt (see
+ * exact-decimal.js), never from the library itself. The
+ * rounding rule the reference implements is: round to `n` fraction digits,
+ * halves away from zero (0.125 -> 0.13, -0.125 -> -0.13).
+ *
+ * Run with `yarn test` (builds index.js first).
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const Calculator = require("../index.js").default;
+
+const {
+  parseDecimal,
+  addDecimal,
+  multiplyDecimal,
+  roundHalfAwayFromZero,
+  significantDigits,
+  makeRandom,
+  randomDecimal,
+  expectAll,
+} = require("./exact-decimal");
+
+/** The double the theoretical result is stored as (the nearest double to it). */
+function expectedRound(dec, n) {
+  return Number(roundHalfAwayFromZero(dec, n));
+}
+
+const round = (value, n, options) => new Calculator(value).round(n, options);
+const SNAP = { snap: true };
+
+test("with snap: every half cent from 0.005 to 1000.005 rounds away from zero, both signs", () => {
+  function* halfCents() {
+    for (let cents = 0; cents <= 100000; cents++) {
+      const str = `${(cents / 100).toFixed(2)}5`;
+      yield { str };
+      yield { str: `-${str}` };
+    }
+  }
+  expectAll(halfCents(), ({ str }) => ({
+    actual: round(Number(str), 2, SNAP),
+    expected: expectedRound(parseDecimal(str), 2),
+  }));
+});
+
+test("with snap: random decimals (up to 12 significant digits) match exact rounding", () => {
+  const random = makeRandom(1);
+  function* cases() {
+    for (let i = 0; i < 200000; i++) {
+      const n = 1 + Math.floor(random() * 4); // 1..4
+      const decimals = Math.floor(random() * 7); // 0..6, so some are already rounded
+      const str = randomDecimal(random, 1000000, Math.min(decimals, 12 - 7));
+      yield { str, n };
+    }
+  }
+  expectAll(cases(), ({ str, n }) => ({
+    actual: round(Number(str), n, SNAP),
+    expected: expectedRound(parseDecimal(str), n),
+  }));
+});
+
+test("with snap: float error from plain JS sums is removed (a + b rounds as the exact sum)", () => {
+  // Same-sign operands, so the float error stays within a few ULPs of the sum
+  // itself, which is what snap's allowance is sized for. See the todo test on
+  // cancellation below for opposite signs.
+  const random = makeRandom(2);
+  function* cases() {
+    for (let i = 0; i < 100000; i++) {
+      const a = randomDecimal(random, 1000000, 3, false);
+      const b = randomDecimal(random, 1000000, 3, false);
+      yield { a, b };
+      yield { a: `-${a}`, b: `-${b}` };
+    }
+  }
+  expectAll(cases(), ({ a, b }) => ({
+    actual: round(Number(a) + Number(b), 2, SNAP),
+    expected: expectedRound(addDecimal(parseDecimal(a), parseDecimal(b)), 2),
+  }));
+});
+
+test("with snap: float error from plain JS products is removed (a * b rounds as the exact product)", () => {
+  const random = makeRandom(3);
+  function* cases() {
+    for (let i = 0; i < 100000; i++) {
+      const a = randomDecimal(random, 100000, 2);
+      const b = randomDecimal(random, 100, 1);
+      yield { a, b };
+    }
+  }
+  expectAll(cases(), ({ a, b }) => {
+    const exact = multiplyDecimal(parseDecimal(a), parseDecimal(b));
+    assert.ok(significantDigits(exact) <= 12);
+    return {
+      actual: round(Number(a) * Number(b), 2, SNAP),
+      expected: expectedRound(exact, 2),
+    };
+  });
+});
+
+test("with snap: (t / m) * m in plain JS rounds as t, for half cents t", () => {
+  const random = makeRandom(4);
+  const divisors = [3, 7, 9, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47];
+  function* cases() {
+    for (let i = 0; i < 100000; i++) {
+      const cents = Math.floor(random() * 1000000);
+      const sign = random() < 0.5 ? "-" : "";
+      const t = `${sign}${(cents / 100).toFixed(2)}5`;
+      const m = divisors[Math.floor(random() * divisors.length)];
+      yield { t, m };
+    }
+  }
+  // Mathematically (t / m) * m === t; only the float evaluation is off.
+  expectAll(cases(), ({ t, m }) => ({
+    actual: round((Number(t) / m) * m, 2, SNAP),
+    expected: expectedRound(parseDecimal(t), 2),
+  }));
+});
+
+test("with snap: known values with float error from upstream arithmetic", () => {
+  const cases = [
+    // 3 * 0.075 in plain JS is 0.22499999999999998; the exact product is 0.225.
+    { value: 3 * 0.075, exact: "0.225" },
+    { value: -3 * 0.075, exact: "-0.225" },
+    // A garnishment withheld amount whose exact value is 602.015.
+    { value: 602.0149999999994, exact: "602.015" },
+    { value: -602.0149999999994, exact: "-602.015" },
+    { value: 95.01499999999942, exact: "95.015" },
+  ];
+  expectAll(cases, ({ value, exact }) => ({
+    actual: round(value, 2, SNAP),
+    expected: expectedRound(parseDecimal(exact), 2),
+  }));
+});
+
+test("without snap: values not on a half match exact rounding", () => {
+  const random = makeRandom(5);
+  function* cases() {
+    for (let i = 0; i < 200000; i++) {
+      const n = 1 + Math.floor(random() * 4); // 1..4
+      const str = randomDecimal(random, 1000000, n + 1 + Math.floor(random() * 2));
+      const dec = parseDecimal(str);
+      // Skip exact halves: whether 1.005 is a half depends on how it is stored.
+      const tail = dec.unscaled % 10n ** BigInt(dec.scale - n);
+      const half = 5n * 10n ** BigInt(dec.scale - n - 1);
+      if (tail === half || tail === -half) continue;
+      yield { str, n };
+    }
+  }
+  expectAll(cases(), ({ str, n }) => ({
+    actual: round(Number(str), n),
+    expected: expectedRound(parseDecimal(str), n),
+  }));
+});
+
+test("without snap: halves stored exactly in binary round away from zero", () => {
+  // k + j/8 and k + j/4 are exact doubles, so there is no ambiguity about the half.
+  function* cases() {
+    for (let k = 0; k <= 20000; k++) {
+      for (const fraction of ["125", "375", "625", "875"]) {
+        yield { str: `${k}.${fraction}`, n: 2 };
+        yield { str: `-${k}.${fraction}`, n: 2 };
+      }
+      for (const fraction of ["25", "75"]) {
+        yield { str: `${k}.${fraction}`, n: 1 };
+        yield { str: `-${k}.${fraction}`, n: 1 };
+      }
+    }
+  }
+  expectAll(cases(), ({ str, n }) => ({
+    actual: round(Number(str), n),
+    expected: expectedRound(parseDecimal(str), n),
+  }));
+});
+
+test("negative values round as the mirror of their positive value", () => {
+  // Rounding half away from zero is odd-symmetric: round(-x) = -round(x).
+  const random = makeRandom(6);
+  function* cases() {
+    for (let i = 0; i < 100000; i++) {
+      const n = 1 + Math.floor(random() * 4);
+      const str = randomDecimal(random, 1000000, Math.floor(random() * 7), false);
+      for (const options of [undefined, SNAP]) yield { str, n, options };
+    }
+  }
+  expectAll(cases(), ({ str, n, options }) => {
+    const positive = round(Number(str), n, options);
+    return { actual: round(-Number(str), n, options), expected: positive === 0 ? 0 : -positive };
+  });
+});
+
+test("rounding to zero gives 0, not -0", () => {
+  for (const value of [-0.004, -0.0049, -0.00001]) {
+    assert.ok(Object.is(round(value, 2), 0), `round(${value}, 2)`);
+    assert.ok(Object.is(round(value, 2, SNAP), 0), `round(${value}, 2, snap)`);
+  }
+});
+
+test("fractionDigits defaults to the configured value, which defaults to 2", () => {
+  assert.equal(new Calculator(2.3456).round(), expectedRound(parseDecimal("2.3456"), 2));
+  assert.equal(
+    new Calculator(2.3456, { fractionDigits: 3 }).round(),
+    expectedRound(parseDecimal("2.3456"), 3)
+  );
+});
+
+// Known limitations of 1.0.x, kept as todo tests so they show up in every run
+// without failing it.
+test(
+  "without snap: a decimal half that is not exact in binary rounds as written",
+  { todo: "round() scales with a float multiply (1.005 * 1000 = 1004.9999999999999); use { snap: true }" },
+  () => {
+    for (const str of ["1.005", "1.015", "4.015", "-1.005"]) {
+      assert.equal(round(Number(str), 2), expectedRound(parseDecimal(str), 2), str);
+    }
+  }
+);
+
+test(
+  "with snap: float error from cancellation (large a + large negative b) is removed",
+  {
+    todo:
+      "snap's allowance scales with the result, but the error of -615403.718 + 613501.153 " +
+      "scales with the operands, so it is about 25x too large; compute such values with NC instead",
+  },
+  () => {
+    const cases = [
+      { a: "-615403.718", b: "613501.153" }, // exact -1902.565
+      { a: "568756.460", b: "-565399.545" }, // exact 3356.915
+      { a: "-917513.753", b: "917501.658" }, // exact -12.095
+    ];
+    for (const { a, b } of cases) {
+      assert.equal(
+        round(Number(a) + Number(b), 2, SNAP),
+        expectedRound(addDecimal(parseDecimal(a), parseDecimal(b)), 2),
+        `${a} + ${b}`
+      );
+    }
+  }
+);
+
+test(
+  "round(0) rounds to an integer",
+  { todo: "fractionDigits 0 currently falls back to the default of 2" },
+  () => {
+    assert.equal(round(2.5, 0), expectedRound(parseDecimal("2.5"), 0));
+  }
+);