arbitrary-numbers 1.0.1 → 1.1.0

package/README.md

@@ -15,11 +15,23 @@
 Numbers are stored as a normalized `coefficient × 10^exponent` pair. That makes arithmetic across wildly different scales fast and predictable — exactly what idle games and simulations need when values span from `1` to `10^300` in the same loop.
 
 - **Immutable by default** — every operation returns a new instance, no surprise mutations
-- **Fused operations** (`mulAdd`, `subMul`, ...) — reduce allocations in hot loops
+- **Fused operations** (`mulAdd`, `subMul`, `mulDiv`, ...) — reduce allocations in hot loops
 - **Formula pipelines** — define an expression once, apply it to any number of values
 - **Pluggable display** — swap between scientific, unit (K/M/B/T), and letter notation without touching game logic
+- **Save / load built-in** — `toJSON()` / `fromJSON()` / `parse()` for idle-game persistence
 - **Zero dependencies** — nothing to audit, nothing to break
 
+## How it compares
+
+| Library | Strengths | Limitations | Pick when |
+|---|---|---|---|
+| **arbitrary-numbers** | TypeScript-first, fused ops, `mulDiv`, pluggable notation, serialization, zero deps | Newer; coefficient is always float64 | You want types, ergonomics, and notation flexibility |
+| `break_infinity.js` | Very fast, large incremental-game community, battle-tested | JS only, no types, plugin system is bolt-on | Max speed and community examples matter most |
+| `break_eternity.js` | Handles super-exponent range up to `e(9e15)` | Heavier, more complex API | You genuinely need values beyond `10^(10^15)` |
+| `decimal.js` | Arbitrary *precision* (not just range) | 4–14× slower for game math | Financial math, exact decimal arithmetic |
+
+`arbitrary-numbers` stores coefficients as float64, giving ~15 significant digits of precision — the same as a plain JS `number`. If you need exact decimal arithmetic, use `decimal.js`. If you need exponents beyond ~10^(10^15), use `break_eternity`.
+
 ## Install
 
 ```sh
@@ -33,46 +45,70 @@ Requires TypeScript `"strict": true`.
 ```typescript
 import { an, chain, formula, unitNotation } from "arbitrary-numbers";
 
-// Exact at any scale, no overflow or silent precision loss
-const base  = an(1, 9);  // 1,000,000,000
-const armor = an(2, 6);  //     2,000,000
-let   gold  = an(5, 6);  //     5,000,000
+// JavaScript range limits
+const jsHuge = Number("1e500");  // Infinity
+const jsTiny = Number("1e-500"); // 0
 
-// Damage formula: (base - armor) * 0.75
-const damage = chain(base)
-    .subMul(armor, an(7.5, -1))
+// Arbitrary range in both directions
+const huge = an(1, 500);
+const tiny = an(1, -500);
+
+// One-off pipeline with chain(): (6.2e15 - 8.5e13) * 0.75
+const damage = chain(an(6.2, 15))
+    .subMul(an(8.5, 13), an(7.5, -1))
     .floor()
     .done();
 
-damage.toString(unitNotation)  // "748.50 M"
+// Reusable per-tick formula: gold = (gold * 1.08) + 2_500_000
+const tick = formula("tick").mulAdd(an(1.08), an(2.5, 6));
 
-// Per-tick update: fused op, one allocation instead of two
-gold = gold.mulAdd(an(1.05), an(1, 4));  // (gold * 1.05) + 10,000
+let gold = an(7.5, 12);
+for (let i = 0; i < 3; i += 1) {
+    gold = tick.apply(gold);
+}
 
-// Reusable formula pipeline applied to multiple values
-const applyArmor = formula("Armor").subMul(armor, an(7.5, -1)).floor();
-const physDamage = applyArmor.apply(base);
-const magDamage  = applyArmor.apply(an(8, 8));
+console.log("=== Range limits (JS vs arbitrary-numbers) ===");
+console.log(`JS Number('1e500')  -> ${jsHuge}`);
+console.log(`AN an(1, 500)       -> ${huge.toString()}`);
+console.log(`JS Number('1e-500') -> ${jsTiny}`);
+console.log(`AN an(1, -500)      -> ${tiny.toString()}`);
 
-// Formatting adapts at every scale automatically
-an(1.5, 3).toString(unitNotation)  // "1.50 K"
-an(1.5, 6).toString(unitNotation)  // "1.50 M"
-an(1.5, 9).toString(unitNotation)  // "1.50 B"
+console.log("");
+console.log("=== Game math helpers ===");
+console.log(`Damage (chain + fused subMul)  -> ${damage.toString(unitNotation)}`);
+console.log(`Gold after 3 ticks (formula)   -> ${gold.toString(unitNotation)}`);
+```
+
+Example output when running this in a repository checkout (for example with `npx tsx examples/quickstart.ts`):
+
+```text
+=== Range limits (JS vs arbitrary-numbers) ===
+JS Number('1e500')  -> Infinity
+AN an(1, 500)       -> 1.00e+500
+JS Number('1e-500') -> 0
+AN an(1, -500)      -> 1.00e-500
+
+=== Game math helpers ===
+Damage (chain + fused subMul)  -> 4.59 Qa
+Gold after 3 ticks (formula)   -> 9.45 T
 ```
 
 ## Table of contents
 
+- [How it compares](#how-it-compares)
 - [Install](#install)
 - [Quick start](#quick-start)
 - [Table of contents](#table-of-contents)
 - [Creating numbers](#creating-numbers)
 - [Arithmetic](#arithmetic)
+- [Negative numbers](#negative-numbers)
 - [Fused operations](#fused-operations)
 - [Fluent builder - `chain()`](#fluent-builder---chain)
 - [Reusable formulas - `formula()`](#reusable-formulas---formula)
   - [chain() vs formula()](#chain-vs-formula)
 - [Comparison and predicates](#comparison-and-predicates)
 - [Rounding and math](#rounding-and-math)
+- [Serialization and save-load](#serialization-and-save-load)
 - [Display and formatting](#display-and-formatting)
   - [scientificNotation (default)](#scientificnotation-default)
   - [unitNotation - K, M, B, T...](#unitnotation---k-m-b-t)
@@ -136,6 +172,30 @@ a.negate()  // -3,000,000
 a.abs()     //  3,000,000
 ```
 
+## Negative numbers
+
+All operations support negative coefficients. The sign is carried in the coefficient — the exponent is always the magnitude.
+
+```typescript
+const debt   = an(-5, 6);   // -5,000,000
+const income = an(2, 6);    //  2,000,000
+
+debt.add(income)     // -3,000,000
+debt.abs()           //  5,000,000
+debt.negate()        //  5,000,000
+debt.sign()          // -1
+debt.isNegative()    // true
+
+// Notation plugins preserve the sign
+import { unitNotation, letterNotation, scientificNotation } from "arbitrary-numbers";
+
+an(-1.5, 6).toString(scientificNotation) // "-1.50e+6"
+an(-1.5, 6).toString(unitNotation)       // "-1.50 M"
+an(-1.5, 6).toString(letterNotation)     // "-1.50b"
+```
+
+Negative numbers are less common in idle games (resources can't go below zero), but they are useful for delta-income tracking, balance sheets, and damage-over-time effects. All arithmetic, comparison, rounding, and formatting methods handle negatives correctly across the full exponent range.
+
 ## Fused operations
 
 Fused methods compute a two-step expression in one normalisation pass, saving one intermediate allocation per call. Use them in per-tick update loops.
@@ -145,15 +205,21 @@ Fused methods compute a two-step expression in one normalisation pass, saving on
 gold = gold.mulAdd(prestigeRate, prestigeBonus);
 
 // Other fused pairs
-base.addMul(bonus, multiplier);   // (base + bonus) * multiplier
-income.mulSub(rate, upkeep);      // (income * rate) - upkeep
-raw.subMul(reduction, boost);     // (raw - reduction) * boost
-damage.divAdd(speed, flat);       // (damage / speed) + flat
+base.addMul(bonus, multiplier);          // (base + bonus) * multiplier
+income.mulSub(rate, upkeep);             // (income * rate) - upkeep
+raw.subMul(reduction, boost);            // (raw - reduction) * boost
+damage.divAdd(speed, flat);              // (damage / speed) + flat
+production.mulDiv(deltaTime, cost);      // (production * deltaTime) / cost
 
 // Sum an array in one pass, ~9x faster than .reduce((a, b) => a.add(b))
 const total = ArbitraryNumber.sumArray(incomeSources);
+
+// Multiply all elements in one pass
+const product = ArbitraryNumber.productArray(multipliers);
 ```
 
+`mulDiv` is the idle-tick workhorse: `(production * deltaTime) / cost` without allocating an intermediate value for the product.
+
 ## Fluent builder - `chain()`
 
 `chain()` wraps an `ArbitraryNumber` in a thin accumulator. Each method mutates the accumulated value and returns `this`. No expression tree, no deferred execution.
@@ -246,22 +312,112 @@ ArbitraryNumber.lerp(a, b, 0.5)               // 9,500
 ```typescript
 const n = an(1.75, 0);  // 1.75
 
-n.floor()   // 1
-n.ceil()    // 2
-n.round()   // 2
+n.floor()   //  1  (toward -∞)
+n.ceil()    //  2  (toward +∞)
+n.round()   //  2  (half-up)
+n.trunc()   //  1  (toward 0)
+
+an(-1.75, 0).floor()  // -2  (toward -∞)
+an(-1.75, 0).trunc()  // -1  (toward 0, unlike floor)
 
 an(4, 0).sqrt()              // 2       (1.18x faster than .pow(0.5))
 an(1, 4).sqrt()              // 100
 an(-4, 0).sqrt()             // throws ArbitraryNumberDomainError
 
+an(8, 0).cbrt()              // 2
+an(1, 9).cbrt()              // 1e3  (= 1,000)
+an(-27, 0).cbrt()            // -3   (cube root supports negatives)
+
 an(1, 3).log10()             // 3
 an(1.5, 3).log10()           // 3.176...
+an(1024, 0).log(2)           // 10
+an(Math.E, 0).ln()           // ≈ 1
+
+ArbitraryNumber.exp10(6)     // 1e6  (inverse of log10)
+ArbitraryNumber.exp10(3.5)   // ≈ 3162.3
+
 ArbitraryNumber.Zero.log10() // throws ArbitraryNumberDomainError
 
 an(1.5, 3).toNumber()        // 1500
 an(1, 400).toNumber()        // Infinity  (exponent beyond float64 range)
+
+// Batch operations
+ArbitraryNumber.productArray([an(2), an(3), an(4)])    // 24
+ArbitraryNumber.maxOfArray([an(1), an(3), an(2)])      // an(3)
+ArbitraryNumber.minOfArray([an(3), an(1), an(2)])      // an(1)
+```
+
+## Serialization and save-load
+
+Idle games need to persist numbers across sessions. `arbitrary-numbers` provides three serialization paths:
+
+### JSON (recommended for save files)
+
+```typescript
+import { ArbitraryNumber, an } from "arbitrary-numbers";
+
+const gold = an(1.5, 6);
+
+// Serialize — produces { c: number, e: number }
+const blob = gold.toJSON();           // { c: 1.5, e: 6 }
+const json = JSON.stringify(gold);    // '{"c":1.5,"e":6}'
+
+// Deserialize
+const restored = ArbitraryNumber.fromJSON(JSON.parse(json));
+restored.equals(gold);  // true
+```
+
+`toJSON()` uses short keys (`c`/`e`) to keep save blobs small. The shape is stable — renaming internal fields will never silently break your saves.
+
+### Compact string (URL params, cookies)
+
+```typescript
+const raw = gold.toRaw();             // "1.5|6"
+const restored = ArbitraryNumber.parse("1.5|6");
+restored.equals(gold);  // true
+```
+
+### Parsing arbitrary strings
+
+`ArbitraryNumber.parse()` accepts multiple formats:
+
+```typescript
+ArbitraryNumber.parse("1.5|6")      // pipe format  (exact round-trip)
+ArbitraryNumber.parse("1.5e+6")     // scientific notation
+ArbitraryNumber.parse("1500000")    // plain decimal
+ArbitraryNumber.parse("-0.003")     // negative decimal
+ArbitraryNumber.parse("1.5E6")      // uppercase E
 ```
 
+Unrecognised or non-finite strings throw `ArbitraryNumberInputError`.
+
+### Save-every-60s pattern
+
+```typescript
+// Save
+function saveGame(state: GameState): string {
+    return JSON.stringify({
+        gold: state.gold.toJSON(),
+        gps:  state.gps.toJSON(),
+        tick: state.tick,
+    });
+}
+
+// Load
+function loadGame(json: string): GameState {
+    const raw = JSON.parse(json);
+    return {
+        gold: ArbitraryNumber.fromJSON(raw.gold),
+        gps:  ArbitraryNumber.fromJSON(raw.gps),
+        tick: raw.tick,
+    };
+}
+
+setInterval(() => localStorage.setItem("save", saveGame(state)), 60_000);
+```
+
+> **Precision note:** `toJSON()` / `fromJSON()` round-trip is exact. `toRaw()` / `parse()` with the pipe format is also exact. Parsing a number from a notation string (e.g. `"1.50 M"`) is not provided — it would be lossy because the suffix format discards precision beyond `decimals`.
+
 ## Display and formatting
 
 `toString(plugin?, decimals?)` accepts any `NotationPlugin`. Three plugins are included.
@@ -330,7 +486,7 @@ When two numbers differ in exponent by more than `PrecisionCutoff` (default `15`
 const huge = an(1, 20);  // 10^20
 const tiny = an(1, 3);   // 1,000
 
-huge.add(tiny)  // returns huge unchanged
+huge.add(tiny)  // returns huge unchanged — tiny is negligible at 10^20 scale
 ```
 
 Override globally or for a single scoped block:
@@ -342,6 +498,34 @@ ArbitraryNumber.PrecisionCutoff = 50;  // global
 const result = ArbitraryNumber.withPrecision(50, () => a.add(b));
 ```
 
+### When things drift — precision troubleshooting
+
+**"Why doesn't `a.add(b).sub(b).equals(a)` return true when `b` is much larger than `a`?"**
+
+```typescript
+const a = an(1, 3);   // 1,000
+const b = an(1, 20);  // 10^20
+
+a.add(b)              // returns b — a is negligible, discarded
+a.add(b).sub(b)       // returns b.sub(b) = 0, not a
+a.add(b).sub(b).equals(a)  // false — a was lost when added to b
+```
+
+This is the fundamental float64 limitation: `1,000 + 10^20 = 10^20` in any number system with ~15 significant digits. `arbitrary-numbers` does not hide this — it is exact for the scale at which each value is stored.
+
+**Game patterns and their typical precision needs:**
+
+| Pattern | Exponent diff | Precision loss |
+|---|---|---|
+| Same-tier resources (gold + gold) | 0–3 | None |
+| Upgrade costs vs balance | 0–8 | None |
+| Prestige multipliers | 15–25 | < 0.0001% |
+| Idle accumulation over time | 20–50 | ~0.1% (acceptable for display) |
+
+If exact addition across large exponent gaps matters (e.g. financial ledger), raise `PrecisionCutoff` to `50` and use `withPrecision`.
+
+> **Warning:** `PrecisionCutoff` is a global static. Changing it affects all arithmetic library-wide, including in async callbacks that run concurrently. Use `withPrecision` for scoped overrides.
+
 ## Errors
 
 All errors thrown by the library extend `ArbitraryNumberError`, so you can distinguish them from your own errors.
@@ -441,67 +625,117 @@ an(3.2, 6).toString(new TierNotation({ separator: " " }))  // "3.20 M"
 
 ## Idle game example
 
-A self-contained simulation showing `an()`, fused ops, `chain()`, helpers, and `unitNotation` working together.
+A self-contained simulation showing hyper-growth, fused ops, helpers, and where plain JS `number` overflows while `ArbitraryNumber` keeps working.
 
 ```typescript
 import {
-    ArbitraryNumber, an, chain,
-    unitNotation, ArbitraryNumberHelpers as helpers,
+    an, chain,
+    UnitNotation,
+    CLASSIC_UNITS,
+    letterNotation,
+    ArbitraryNumberHelpers as helpers,
 } from "arbitrary-numbers";
+import type { ArbitraryNumber } from "arbitrary-numbers";
 
-let gold       = ArbitraryNumber.Zero;
-let goldPerSec = an(1);
+let gold = an(5, 6);      // 5,000,000
+let gps = an(2, 5);       // 200,000 per tick
+let reactorCost = an(1, 9);
+let reactors = 0;
 
-const UPGRADES = [
-    { label: "Copper Pick  ", cost: an(50),    mult: an(5)    },
-    { label: "Iron Mine    ", cost: an(1, 3),  mult: an(20)   },
-    { label: "Gold Refinery", cost: an(5, 6),  mult: an(1, 4) },
-] as const;
+const display = new UnitNotation({
+    units: CLASSIC_UNITS,
+    fallback: letterNotation,
+});
 
-function tick(): void {
-    gold = gold.add(goldPerSec);
+function fmt(value: ArbitraryNumber, decimals = 2): string {
+    return value.toString(display, decimals);
 }
 
-function tryBuyAll(): void {
-    for (const u of UPGRADES) {
-        if (!helpers.meetsOrExceeds(gold, u.cost)) continue;
-        gold       = gold.sub(u.cost);
-        goldPerSec = goldPerSec.mul(u.mult);
-        console.log(`  bought ${u.label}  GPS: ${goldPerSec.toString(unitNotation)}`);
-    }
+function snapshot(tick: number): void {
+    console.log(
+        `[t=${String(tick).padStart(4)}] SNAPSHOT  `
+        + `gold=${fmt(gold, 2).padStart(12)}  gps=${fmt(gps, 2).padStart(12)}`,
+    );
 }
 
-function prestige(multiplier: ArbitraryNumber): void {
-    goldPerSec = chain(goldPerSec)
-        .mulAdd(multiplier, an(1))  // (gps * mult) + 1, fused
-        .floor()
-        .done();
-    console.log(`  prestige!  new GPS: ${goldPerSec.toString(unitNotation)}`);
-}
+console.log("=== Hyper-growth idle loop (720 ticks) ===");
+console.log(`start gold=${fmt(gold)}  gps=${fmt(gps)}  reactorCost=${fmt(reactorCost)}`);
+
+for (let t = 1; t <= 720; t += 1) {
+    // Core growth: gold = (gold * 1.12) + gps
+    gold = gold.mulAdd(an(1.12), gps);
+
+    if (t % 60 === 0 && helpers.meetsOrExceeds(gold, reactorCost)) {
+        const before = gps;
+        gold = gold.sub(reactorCost);
+        gps = chain(gps).mul(an(1, 25)).floor().done();
+        reactorCost = reactorCost.mul(an(8));
+        reactors += 1;
+
+        console.log(
+            `[t=${String(t).padStart(4)}] REACTOR   #${String(reactors).padStart(2)}  `
+            + `gps ${fmt(before)} -> ${fmt(gps)}  `
+            + `nextCost=${fmt(reactorCost)}`,
+        );
+    }
 
-for (let t = 1; t <= 1_000_000; t++) {
-    tick();
-    if (t % 10 === 0)      tryBuyAll();
-    if (t === 51_000)      prestige(an(1.5));
-    if (t % 250_000 === 0) {
-        const g   = gold.toString(unitNotation, 3);
-        const gps = goldPerSec.toString(unitNotation, 3);
-        console.log(`[t=${String(t).padStart(9)}]  gold: ${g.padStart(12)}  gps: ${gps}`);
+    if (t === 240 || t === 480) {
+        const before = gps;
+        gps = chain(gps)
+            .mul(an(1, 4))
+            .add(an(7.5, 6))
+            .floor()
+            .done();
+        console.log(`[t=${String(t).padStart(4)}] PRESTIGE  gps ${fmt(before)} -> ${fmt(gps)}`);
+    }
+
+    if (t % 120 === 0) {
+        snapshot(t);
     }
 }
+
+console.log("\n=== Final scale check ===");
+console.log(`reactors bought: ${reactors}`);
+console.log(`final gold (unit+letter): ${fmt(gold)}`);
+console.log(`final gps  (unit+letter): ${fmt(gps)}`);
+console.log(`final gold as JS Number: ${gold.toNumber()}`);
+console.log(`final gps as JS Number : ${gps.toNumber()}`);
+console.log("If JS shows Infinity while unit+letter output stays finite, the library is doing its job.");
 ```
 
 Output:
 
-```
-  bought Copper Pick    GPS: 5.00
-  bought Iron Mine      GPS: 100.00
-  bought Gold Refinery  GPS: 1.00 M
-  prestige!  new GPS: 1.50 M
-[t=  250000]  gold:  199.750 B  gps: 1.500 M
-[t=  500000]  gold:  574.750 B  gps: 1.500 M
-[t=  750000]  gold:  949.750 B  gps: 1.500 M
-[t= 1000000]  gold:    1.325 T  gps: 1.500 M
+```text
+=== Hyper-growth idle loop (720 ticks) ===
+start gold=5.00 M  gps=200.00 K  reactorCost=1.00 B
+[t=  60] REACTOR   # 1  gps 200.00 K -> 2.00 No  nextCost=8.00 B
+[t= 120] REACTOR   # 2  gps 2.00 No -> 20.00 SpDc  nextCost=64.00 B
+[t= 120] SNAPSHOT  gold=    14.94 Dc  gps=  20.00 SpDc
+[t= 180] REACTOR   # 3  gps 20.00 SpDc -> 200.00 QiVg  nextCost=512.00 B
+[t= 240] REACTOR   # 4  gps 200.00 QiVg -> 2.00 ai  nextCost=4.10 T
+[t= 240] PRESTIGE  gps 2.00 ai -> 20.00 aj
+[t= 240] SNAPSHOT  gold=   1.49 SpVg  gps=    20.00 aj
+[t= 300] REACTOR   # 5  gps 20.00 aj -> 200.00 ar  nextCost=32.77 T
+[t= 360] REACTOR   # 6  gps 200.00 ar -> 2.00 ba  nextCost=262.14 T
+[t= 360] SNAPSHOT  gold=     1.49 at  gps=     2.00 ba
+[t= 420] REACTOR   # 7  gps 2.00 ba -> 20.00 bi  nextCost=2.10 Qa
+[t= 480] REACTOR   # 8  gps 20.00 bi -> 200.00 bq  nextCost=16.78 Qa
+[t= 480] PRESTIGE  gps 200.00 bq -> 2.00 bs
+[t= 480] SNAPSHOT  gold=   149.43 bj  gps=     2.00 bs
+[t= 540] REACTOR   # 9  gps 2.00 bs -> 20.00 ca  nextCost=134.22 Qa
+[t= 600] REACTOR   #10  gps 20.00 ca -> 200.00 ci  nextCost=1.07 Qi
+[t= 600] SNAPSHOT  gold=   149.43 cb  gps=   200.00 ci
+[t= 660] REACTOR   #11  gps 200.00 ci -> 2.00 cr  nextCost=8.59 Qi
+[t= 720] REACTOR   #12  gps 2.00 cr -> 20.00 cz  nextCost=68.72 Qi
+[t= 720] SNAPSHOT  gold=    14.94 cs  gps=    20.00 cz
+
+=== Final scale check ===
+reactors bought: 12
+final gold (unit+letter): 14.94 cs
+final gps  (unit+letter): 20.00 cz
+final gold as JS Number: 1.494328222485101e+292
+final gps as JS Number : Infinity
+If JS shows Infinity while unit+letter output stays finite, the library is doing its job.
 ```
 
 ## Performance
@@ -512,10 +746,10 @@ Quick reference (Node 22.16, Intel i5-13600KF):
 
 | Operation | Time |
 |---|---|
-| `add` / `sub` (typical) | ~20-28 ns |
-| `mul` / `div` | ~10-11 ns |
-| Fused ops (`mulAdd`, `mulSub`, ...) | ~27-29 ns, 1.5-1.6x faster than chained |
-| `sumArray(50 items)` | ~200 ns, 8.4-8.7x faster than `.reduce` |
-| `compareTo` (same exponent) | ~0.6 ns |
-| `sqrt()` | ~10 ns |
-| `pow(0.5)` | ~7 ns |
+| `add` / `sub` (typical) | ~270-275 ns |
+| `mul` / `div` | ~250-255 ns |
+| Fused ops (`mulAdd`, `mulSub`, ...) | ~275 ns, ~1.9x faster than chained |
+| `sumArray(50 items)` | ~435 ns, ~31x faster than `.reduce` |
+| `compareTo` (same exponent) | ~3 ns |
+| `sqrt()` | ~252 ns |
+| `pow(0.5)` | ~20 ns |