arbitrary-numbers 1.0.2 → 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
@@ -83,17 +95,20 @@ 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)
@@ -157,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.
@@ -166,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.
@@ -267,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.
@@ -351,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:
@@ -363,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.
@@ -583,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 |