arbitrary-numbers 1.0.2 → 2.0.0

package/README.md

@@ -10,15 +10,71 @@
   [![Zero dependencies](https://img.shields.io/badge/dependencies-zero-6366f1?labelColor=0c0c0e)](package.json)
 </div>
 
-`arbitrary-numbers` fills a specific gap: JavaScript's `Number` type silently loses precision above `Number.MAX_SAFE_INTEGER`, and `BigInt` can't represent decimals, so working with extremely large or small magnitudes often requires manual scaling into very large integers.
+**arbitrary-numbers** is a fast, TypeScript-first big-number library for idle games and incremental simulators. It stores numbers as `coefficient × 10^exponent`, mutates in-place for zero allocation on the hot path, and ships with notation plugins and serialization built in.
 
-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.
+```
+gold.add(income).sub(cost).mul(multiplier)   // mutates gold, returns gold — zero allocations
+```
+
+- **Mutable by default** — no allocations on the steady-state path
+- **Opt-in immutability** — `.freeze()` returns a `FrozenArbitraryNumber` that throws on any mutation
+- **Fused operations** — `mulAdd`, `subMul`, `mulDiv`, … compute two steps in one normalisation pass
+- **Reusable formulas** — define a pipeline once, `apply()` to any value
+- **Notation plugins** — scientific, unit (K/M/B/T), letter (a/b/c), or write your own in 5 lines
+- **Save/load built-in** — `toJSON()` / `fromJSON()` for idle-game persistence
+- **Zero dependencies**
+
+---
+
+## Table of contents
+
+- [How it compares](#how-it-compares)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [The mutable API](#the-mutable-api)
+- [Creating numbers](#creating-numbers)
+- [Arithmetic](#arithmetic)
+- [Fused operations](#fused-operations)
+- [Reusable formulas](#reusable-formulas)
+- [Frozen numbers](#frozen-numbers)
+- [Comparison and predicates](#comparison-and-predicates)
+- [Rounding and math](#rounding-and-math)
+- [Display and notation](#display-and-notation)
+- [Custom notation plugins](#custom-notation-plugins)
+- [Serialization](#serialization)
+- [Precision control](#precision-control)
+- [Utilities](#utilities)
+- [Errors](#errors)
+- [Idle game example](#idle-game-example)
+- [Performance](#performance)
+- [Migration from v1](#migration-from-v1)
+
+---
+
+## How it compares
+
+| Library | Pick when |
+|---|---|
+| **arbitrary-numbers** | You want TypeScript types, mutable-fast arithmetic, fused ops, notation plugins, and serialization |
+| `break_infinity.js` | Community ecosystem matters most — widely used, battle-tested, but JS-only and immutable |
+| `break_eternity.js` | You genuinely need values beyond `10^(10^15)` |
+| `decimal.js` | You need arbitrary *precision* (financial math, exact decimals) — not just range |
+
+Performance on Node 22.16, Intel i5-13600KF:
+
+| Operation | arbitrary-numbers v2 | break_infinity.js | break_eternity.js | decimal.js |
+|---|---|---|---|---|
+| `add` / `sub` | **~13 ns** | ~28–32 ns | ~150–195 ns | ~134–163 ns |
+| `mul` | **~11 ns** | ~15 ns | ~159 ns | ~380 ns |
+| `div` | **~12 ns** | ~39–47 ns | ~200–249 ns | ~469–843 ns |
+| `sqrt()` | **~11 ns** | ~14 ns | ~32 ns | ~4591 ns |
+| `compareTo` | **~3.6 ns** | ~4.8 ns | ~20 ns | ~79 ns |
+| `clone()` | **~6.7 ns** | ~61 ns | ~73 ns | ~260 ns |
+| `sumArray(50)` | **~156 ns total** | no equivalent | no equivalent | no equivalent |
 
-- **Immutable by default** — every operation returns a new instance, no surprise mutations
-- **Fused operations** (`mulAdd`, `subMul`, ...) — 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
-- **Zero dependencies** — nothing to audit, nothing to break
+Full breakdown: [`benchmarks/COMPETITOR_BENCHMARKS.md`](benchmarks/COMPETITOR_BENCHMARKS.md).
+
+---
 
 ## Install
 
@@ -28,565 +84,614 @@ npm install arbitrary-numbers
 
 Requires TypeScript `"strict": true`.
 
+---
+
 ## Quick start
 
 ```typescript
-import { an, chain, formula, unitNotation } from "arbitrary-numbers";
+import { an, formula, unitNotation, letterNotation, scientificNotation } from "arbitrary-numbers";
+
+// JS overflows — arbitrary-numbers doesn't
+Number("1e500")    // Infinity
+an(1, 500)         // 1.00e+500  — tracked exactly
+
+// Mutable chaining — all three ops mutate gold, no allocations
+const gold   = an(7.5, 12);   // 7,500,000,000,000
+const income = an(2.5, 9);
+const cost   = an(1.0, 9);
+gold.add(income).sub(cost);
+
+// clone() when you need to keep the original
+const before = gold.clone();
+gold.mul(an(1.1, 0));
+// before is unchanged
+
+// Notation plugins — swap at any call site
+an(3.2, 15).toString(scientificNotation)  // "3.20e+15"
+an(3.2, 15).toString(unitNotation)        // "3.20 Qa"
+an(3.2, 15).toString(letterNotation)      // "3.20e"
+
+// Reusable formula — define once, apply to many values
+const tick = formula().mulAdd(an(1.08, 0), an(2.5, 6));
+tick.applyInPlace(gold);   // hot path — mutates gold in-place
+const result = tick.apply(gold);  // apply() clones first, gold unchanged
+```
 
-// JavaScript range limits
-const jsHuge = Number("1e500");  // Infinity
-const jsTiny = Number("1e-500"); // 0
+---
 
-// Arbitrary range in both directions
-const huge = an(1, 500);
-const tiny = an(1, -500);
+## The mutable API
 
-// 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();
+**Every arithmetic method mutates `this` and returns `this`.** This is the single most important thing to understand.
 
-// Reusable per-tick formula: gold = (gold * 1.08) + 2_500_000
-const tick = formula("tick").mulAdd(an(1.08), an(2.5, 6));
+```typescript
+const a = an(3, 6);  // 3,000,000
+const b = an(1, 3);  //     1,000
 
-let gold = an(7.5, 12);
-for (let i = 0; i < 3; i += 1) {
-    gold = tick.apply(gold);
-}
+a.add(b);   // a is now 3,001,000 — b is unchanged
+```
 
-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()}`);
+Chain operations naturally:
 
-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)}`);
+```typescript
+gold.add(income).sub(cost).mul(multiplier);  // all ops mutate gold
 ```
 
-Example output when running this in a repository checkout (for example with `npx tsx examples/quickstart.ts`):
+Use `clone()` to branch:
+
+```typescript
+const snapshot = gold.clone();
+gold.add(income);
+// snapshot is still the old value
+```
 
-```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
+**Static methods allocate, instance methods mutate:**
 
-=== Game math helpers ===
-Damage (chain + fused subMul)  -> 4.59 Qa
-Gold after 3 ticks (formula)   -> 9.45 T
+```typescript
+ArbitraryNumber.add(a, b)  // returns a NEW instance — a and b are unchanged
+a.add(b)                   // mutates a, returns a
 ```
 
-## Table of contents
+Watch out for aliasing:
 
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Table of contents](#table-of-contents)
-- [Creating numbers](#creating-numbers)
-- [Arithmetic](#arithmetic)
-- [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)
-- [Display and formatting](#display-and-formatting)
-  - [scientificNotation (default)](#scientificnotation-default)
-  - [unitNotation - K, M, B, T...](#unitnotation---k-m-b-t)
-  - [AlphabetNotation - a, b, c... aa, ab...](#alphabetnotation---a-b-c-aa-ab)
-- [Precision control](#precision-control)
-- [Errors](#errors)
-- [Utilities](#utilities)
-  - [ArbitraryNumberOps - mixed `number | ArbitraryNumber` input](#arbitrarynumberops---mixed-number--arbitrarynumber-input)
-  - [ArbitraryNumberGuard - type guards](#arbitrarynumberguard---type-guards)
-  - [ArbitraryNumberHelpers - game and simulation patterns](#arbitrarynumberhelpers---game-and-simulation-patterns)
-- [Writing a custom plugin](#writing-a-custom-plugin)
-- [Idle game example](#idle-game-example)
-- [Performance](#performance)
+```typescript
+const total = gold;        // alias — NOT a copy
+total.add(income);         // mutates gold too!
+
+const total = gold.clone(); // correct — independent copy
+total.add(income);          // gold is unchanged
+```
+
+---
 
 ## Creating numbers
 
 ```typescript
 import { ArbitraryNumber, an } from "arbitrary-numbers";
 
-// From a coefficient and exponent
-new ArbitraryNumber(1.5, 3)   // 1,500       { coefficient: 1.5, exponent: 3 }
-new ArbitraryNumber(15, 3)    // 15,000  ->  { coefficient: 1.5, exponent: 4 }  (normalised)
-new ArbitraryNumber(0, 99)    // Zero    ->  { coefficient: 0,   exponent: 0 }
+new ArbitraryNumber(1.5, 3)    // 1,500        { coefficient: 1.5, exponent: 3 }
+new ArbitraryNumber(15, 3)     // normalised → { coefficient: 1.5, exponent: 4 }
+new ArbitraryNumber(0, 99)     // zero     →  { coefficient: 0,   exponent: 0 }
 
-// From a plain JS number
 ArbitraryNumber.from(1_500_000)  // { coefficient: 1.5, exponent: 6 }
 ArbitraryNumber.from(0.003)      // { coefficient: 3,   exponent: -3 }
 
-// Shorthand
-an(1.5, 6)      // same as new ArbitraryNumber(1.5, 6)
-an.from(1_500)  // same as ArbitraryNumber.from(1500)
+an(1.5, 6)       // shorthand for new ArbitraryNumber(1.5, 6)
+an.from(1_500)   // shorthand for ArbitraryNumber.from(1500)
 
-// Static constants
-ArbitraryNumber.Zero  // 0
-ArbitraryNumber.One   // 1
-ArbitraryNumber.Ten   // 10
+an(1.5, 6).clone()  // fresh mutable copy
 ```
 
-Inputs must be finite. `NaN`, `Infinity`, and `-Infinity` throw `ArbitraryNumberInputError`:
+Non-finite inputs throw `ArbitraryNumberInputError`:
 
 ```typescript
-ArbitraryNumber.from(Infinity)     // throws ArbitraryNumberInputError  { value: Infinity }
-new ArbitraryNumber(NaN, 0)        // throws ArbitraryNumberInputError  { value: NaN }
-new ArbitraryNumber(1, Infinity)   // throws ArbitraryNumberInputError  { value: Infinity }
+ArbitraryNumber.from(Infinity)   // throws
+new ArbitraryNumber(NaN, 0)      // throws
 ```
 
+---
+
 ## Arithmetic
 
-All methods return a new `ArbitraryNumber`. Instances are immutable.
+All instance methods mutate `this` and return `this`. Static methods return a new instance.
 
 ```typescript
-const a = an(3, 6);  // 3,000,000
-const b = an(1, 3);  //     1,000
+const a = an(3, 6);
+const b = an(1, 3);
+
+// instance — mutates a
+a.add(b)    a.sub(b)    a.mul(b)    a.div(b)
+a.pow(2)    a.negate()  a.abs()
+
+// static — new instance, a and b unchanged
+ArbitraryNumber.add(a, b)
+ArbitraryNumber.sub(a, b)
+ArbitraryNumber.mul(a, b)
+ArbitraryNumber.div(a, b)
+```
+
+Negative numbers are fully supported — the sign lives in the coefficient:
 
-a.add(b)    // 3,001,000
-a.sub(b)    // 2,999,000
-a.mul(b)    // 3,000,000,000
-a.div(b)    // 3,000
-a.pow(2)    // 9 * 10^12
-a.negate()  // -3,000,000
-a.abs()     //  3,000,000
+```typescript
+const debt = an(-5, 6);   // -5,000,000
+debt.clone().abs()         //  5,000,000
+debt.clone().negate()      //  5,000,000
+debt.sign()                // -1
+debt.isNegative()          // true
 ```
 
+---
+
 ## 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.
+Fused methods compute a two-step expression in one normalisation pass — fewer intermediate steps, one less allocation compared to chaining two separate ops.
 
 ```typescript
-// (gold * rate) + bonus  in one pass, ~1.5x faster than chained
-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
-
-// Sum an array in one pass, ~9x faster than .reduce((a, b) => a.add(b))
-const total = ArbitraryNumber.sumArray(incomeSources);
+gold.mulAdd(rate, bonus)          // (gold × rate) + bonus
+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(dt, cost)       // (production × dt) / cost
 ```
 
-## Fluent builder - `chain()`
+Operands are only read, never mutated. Only `this` changes.
 
-`chain()` wraps an `ArbitraryNumber` in a thin accumulator. Each method mutates the accumulated value and returns `this`. No expression tree, no deferred execution.
+Batch operations that avoid intermediate instances entirely:
 
 ```typescript
-import { chain } from "arbitrary-numbers";
-
-const damage = chain(base)
-    .subMul(armour, mitigation)  // (base - armour) * mitigation, fused
-    .add(flat)
-    .floor()
-    .done();                     // returns the ArbitraryNumber result
+ArbitraryNumber.sumArray(sources)        // sum of an array — ~3.1 ns/element
+ArbitraryNumber.productArray(multipliers)  // product of an array
 ```
 
-All fused ops are available on the builder, so complex formulas do not sacrifice performance.
-
-Available methods: `add`, `sub`, `mul`, `div`, `pow`, `mulAdd`, `addMul`, `mulSub`, `subMul`, `divAdd`, `abs`, `neg`, `sqrt`, `floor`, `ceil`, `round`, `done`.
+---
 
-## Reusable formulas - `formula()`
+## Reusable formulas
 
-`formula()` builds a deferred pipeline. Unlike `chain()`, a formula stores its operations and runs them only when `apply()` is called, so the same formula can be applied to any number of values.
+`formula()` builds a chainable pipeline. Steps are stored as closures and replayed on each application.
 
 ```typescript
 import { formula, an } from "arbitrary-numbers";
 
-const armorReduction = formula("Armor Reduction")
-    .subMul(armor, an(7.5, -1))  // (base - armor) * 0.75
+// Build once
+const armorReduction = formula()
+    .subMul(armor, an(0.75, 0))  // (base − armor) × 0.75
     .floor();
 
+// apply() — clones the input, returns a new instance
 const physDamage = armorReduction.apply(physBase);
 const magDamage  = armorReduction.apply(magBase);
+
+// applyInPlace() — mutates the passed instance directly (hot path, no clone)
+armorReduction.applyInPlace(enemyAtk);
 ```
 
-Each step returns a new `AnFormula`, leaving the original unchanged. Branching is safe:
+Compose with `then()`:
 
 ```typescript
-const base      = formula().mul(an(2));
-const withFloor = base.floor();  // new formula, base is unchanged
-const withCeil  = base.ceil();   // another branch from the same base
+const withCrit = armorReduction.then(formula().mul(critMult).ceil());
+const result   = withCrit.apply(baseDamage);
 ```
 
-Compose two formulas in sequence with `then()`:
+Type a formula as a property:
 
 ```typescript
-const critBonus = formula("Crit Bonus").mul(an(1.5)).ceil();
-const full      = armorReduction.then(critBonus);
-const result    = full.apply(baseDamage);
+import type { AnFormula } from "arbitrary-numbers";
+
+class DamageSystem {
+    private readonly formula: AnFormula;
+    constructor(armor: ArbitraryNumber) {
+        this.formula = formula().subMul(armor, an(0.75, 0)).floor();
+    }
+    calculate(base: ArbitraryNumber): ArbitraryNumber {
+        return this.formula.apply(base);
+    }
+}
 ```
 
-Available methods: `add`, `sub`, `mul`, `div`, `pow`, `mulAdd`, `addMul`, `mulSub`, `subMul`, `divAdd`, `abs`, `neg`, `sqrt`, `floor`, `ceil`, `round`, `then`, `named`, `apply`.
+---
 
-### chain() vs formula()
+## Frozen numbers
 
-| | `chain(value)` | `formula(name?)` |
-|---|---|---|
-| Execution | Immediate | Deferred, runs on `apply()` |
-| Input | Fixed at construction | Provided at `apply()` |
-| Reusable | No, one-shot | Yes, any number of times |
-| Composable | No | Yes, via `then()` |
-| Builder style | Stateful accumulator | Immutable, each step returns a new instance |
-| Terminal | `.done()` | `.apply(value)` |
+`.freeze()` returns a `FrozenArbitraryNumber` — identical API, but every mutating method throws `ArbitraryNumberMutationError`.
+
+```typescript
+import { ArbitraryNumber, FrozenArbitraryNumber } from "arbitrary-numbers";
+
+const base = an(1.5, 6).freeze();
+base.add(an(1));  // throws ArbitraryNumberMutationError: "add"
+
+// Escape with clone()
+const mutable = base.clone();  // plain ArbitraryNumber, fully mutable
+mutable.add(an(1));  // ok
+```
+
+The three static constants are frozen — use `an(0)` / `an(1)` / `an(10)` when you need a mutable starting point:
+
+```typescript
+ArbitraryNumber.Zero  // FrozenArbitraryNumber — read only
+ArbitraryNumber.One   // FrozenArbitraryNumber — read only
+ArbitraryNumber.Ten   // FrozenArbitraryNumber — read only
+
+ArbitraryNumber.Zero.add(income)  // throws!
+an(0).add(income)                 // ok
+```
+
+---
 
 ## Comparison and predicates
 
+These never mutate.
+
 ```typescript
 const a = an(1, 4);  // 10,000
 const b = an(9, 3);  //  9,000
 
-a.compareTo(b)           //  1  (compatible with Array.sort)
+a.compareTo(b)           //  1   (compatible with Array.sort)
 a.greaterThan(b)         // true
 a.lessThan(b)            // false
 a.greaterThanOrEqual(b)  // true
-a.lessThanOrEqual(b)     // false
 a.equals(b)              // false
 
-a.isZero()               // false
-a.isPositive()           // true
-a.isNegative()           // false
-a.isInteger()            // true
-a.sign()                 //  1  (-1 | 0 | 1)
+a.isZero()      // false
+a.isPositive()  // true
+a.isNegative()  // false
+a.isInteger()   // true
+a.sign()        //  1   (-1 | 0 | 1)
 
-ArbitraryNumber.min(a, b)                      // b   (9,000)
-ArbitraryNumber.max(a, b)                      // a   (10,000)
-ArbitraryNumber.clamp(an(5, 5), a, an(1, 5))  // an(1, 5)  (clamped to max)
-ArbitraryNumber.lerp(a, b, 0.5)               // 9,500
+ArbitraryNumber.min(a, b)              // b  (returns the input reference — no clone)
+ArbitraryNumber.max(a, b)             // a
+ArbitraryNumber.clamp(an(5, 5), a, b)  // b  (clamped to max)
+ArbitraryNumber.lerp(a, b, 0.5)        // new instance — midpoint
 ```
 
-## Rounding and math
+`min`, `max`, `clamp` return one of the original references — they do not clone.
 
-```typescript
-const n = an(1.75, 0);  // 1.75
+---
 
-n.floor()   // 1
-n.ceil()    // 2
-n.round()   // 2
-
-an(4, 0).sqrt()              // 2       (1.18x faster than .pow(0.5))
-an(1, 4).sqrt()              // 100
-an(-4, 0).sqrt()             // throws ArbitraryNumberDomainError
+## Rounding and math
 
-an(1, 3).log10()             // 3
-an(1.5, 3).log10()           // 3.176...
-ArbitraryNumber.Zero.log10() // throws ArbitraryNumberDomainError
+These mutate `this` and return `this`.
 
-an(1.5, 3).toNumber()        // 1500
-an(1, 400).toNumber()        // Infinity  (exponent beyond float64 range)
+```typescript
+an(1.75, 0).clone().floor()   //  1
+an(1.75, 0).clone().ceil()    //  2
+an(1.75, 0).clone().round()   //  2
+an(1.75, 0).clone().trunc()   //  1
+an(-1.75, 0).clone().floor()  // -2  (toward −∞)
+an(-1.75, 0).clone().trunc()  // -1  (toward 0)
+
+an(4, 0).clone().sqrt()   // 2
+an(8, 0).clone().cbrt()   // 2
+an(-27, 0).clone().cbrt() // -3   (cube root supports negatives)
+
+an(1, 3).log10()           //  3
+an(1024, 0).log(2)         // 10
+an(Math.E, 0).ln()         //  ≈ 1
+ArbitraryNumber.exp10(6)   // 1e6  (new instance)
+
+an(1, 400).toNumber()      // Infinity  (beyond float64)
 ```
 
-## Display and formatting
+---
 
-`toString(plugin?, decimals?)` accepts any `NotationPlugin`. Three plugins are included.
+## Display and notation
 
-### scientificNotation (default)
+`toString(plugin?, decimals?)` accepts any `NotationPlugin`. Three are included:
 
 ```typescript
-import { scientificNotation } from "arbitrary-numbers";
+import {
+    scientificNotation,   // default
+    unitNotation,         // K / M / B / T / Qa …
+    letterNotation,       // a / b / c … aa / ab …
+} from "arbitrary-numbers";
 
-an(1.5, 3).toString()                      // "1.50e+3"
-an(1.5, 3).toString(scientificNotation, 4) // "1.5000e+3"
-an(1.5, 0).toString()                      // "1.50"
+const n = an(3.2, 15);  // 3,200,000,000,000,000
+
+n.toString()                         // "3.20e+15"   (scientificNotation)
+n.toString(scientificNotation, 4)    // "3.2000e+15"
+n.toString(unitNotation)             // "3.20 Qa"
+n.toString(letterNotation)           // "3.20e"
 ```
 
-### unitNotation - K, M, B, T...
+**Unit notation** comes with two built-in unit lists:
 
 ```typescript
-import { unitNotation, UnitNotation, COMPACT_UNITS, letterNotation } from "arbitrary-numbers";
+import { UnitNotation, CLASSIC_UNITS, COMPACT_UNITS, letterNotation } from "arbitrary-numbers";
 
-an(1.5, 3).toString(unitNotation)  // "1.50 K"
-an(3.2, 6).toString(unitNotation)  // "3.20 M"
-an(1.0, 9).toString(unitNotation)  // "1.00 B"
+// CLASSIC_UNITS: K, M, B, T, Qa, Qi … Ct (centillion)
+// COMPACT_UNITS: k, M, B, T, Qa, Qi … No
+// fallback kicks in for values beyond the list
 
-// Custom unit list with a fallback for values beyond the list
-const custom = new UnitNotation({ units: COMPACT_UNITS, fallback: letterNotation });
+const display = new UnitNotation({ units: CLASSIC_UNITS, fallback: letterNotation });
+an(3.2, 6).toString(display)    // "3.20 M"
+an(3.2, 303).toString(display)  // "3.20 Ct"
+an(3.2, 400).toString(display)  // "3.20e" (falls back to letterNotation)
 ```
 
-### AlphabetNotation - a, b, c... aa, ab...
+**Letter notation** — suffixes never run out (`a`–`z`, then `aa`–`zz`, then `aaa`, …):
 
 ```typescript
-import { letterNotation, AlphabetNotation, alphabetSuffix } from "arbitrary-numbers";
-
 an(1.5, 3).toString(letterNotation)   // "1.50a"
 an(1.5, 6).toString(letterNotation)   // "1.50b"
 an(1.5, 78).toString(letterNotation)  // "1.50z"
 an(1.5, 81).toString(letterNotation)  // "1.50aa"
 ```
 
-Suffixes never run out: `a-z`, then `aa-zz`, then `aaa`, and so on.
+---
+
+## Custom notation plugins
 
-Pass a custom alphabet for any suffix sequence:
+Any object with `format(coefficient, exponent, decimals)` is a valid plugin — you have complete control over how numbers render:
 
 ```typescript
-const excelNotation = new AlphabetNotation({ alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ" });
+import type { NotationPlugin } from "arbitrary-numbers";
+
+// Simple inline plugin — no class needed
+const romanTiers: NotationPlugin = {
+    format(coefficient, exponent, decimals) {
+        const tiers = ["", "K", "M", "B", "T", "Qa", "Qi"];
+        const tier  = Math.floor(exponent / 3);
+        const value = coefficient * 10 ** (exponent - tier * 3);
+        return `${value.toFixed(decimals)}${tiers[tier] ?? `e+${tier * 3}`}`;
+    },
+};
 
-an(1.5, 3).toString(excelNotation)   // "1.50A"
-an(1.5, 78).toString(excelNotation)  // "1.50Z"
-an(1.5, 81).toString(excelNotation)  // "1.50AA"
+an(1.5, 3).toString(romanTiers)   // "1.50K"
+an(1.5, 6).toString(romanTiers)   // "1.50M"
+an(1.5, 21).toString(romanTiers)  // "1.50e+21"
 ```
 
-`alphabetSuffix(tier, alphabet?)` exposes the suffix algorithm as a standalone function:
+For tier-based suffix patterns, extend `SuffixNotationBase` — it handles the `coefficient × 10^(exponent mod 3)` scaling for you and lets you focus on just the suffix:
 
 ```typescript
-import { alphabetSuffix } from "arbitrary-numbers";
+import { SuffixNotationBase } from "arbitrary-numbers";
 
-alphabetSuffix(1)                                // "a"
-alphabetSuffix(27)                               // "aa"
-alphabetSuffix(27, "ABCDEFGHIJKLMNOPQRSTUVWXYZ") // "AA"
-```
+class GameNotation extends SuffixNotationBase {
+    // Any suffix scheme you want — Japanese units, emoji, roman numerals, …
+    private static readonly TIERS = ["", "万", "億", "兆", "京", "垓"];
+    getSuffix(tier: number): string {
+        return GameNotation.TIERS[tier] ?? `e+${tier * 3}`;
+    }
+}
 
-## Precision control
+const jp = new GameNotation({ separator: "" });
+an(1.5, 3).toString(jp)   // "1.50万"
+an(3.2, 6).toString(jp)   // "3.20億"
+```
 
-When two numbers differ in exponent by more than `PrecisionCutoff` (default `15`), the smaller operand is silently discarded because its contribution is below floating-point resolution:
+The `AlphabetNotation` class (backing `letterNotation`) is also customisable:
 
 ```typescript
-const huge = an(1, 20);  // 10^20
-const tiny = an(1, 3);   // 1,000
+import { AlphabetNotation, alphabetSuffix } from "arbitrary-numbers";
 
-huge.add(tiny)  // returns huge unchanged
+const excelColumns = new AlphabetNotation({ alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ" });
+an(1.5, 3).toString(excelColumns)   // "1.50A"
+an(1.5, 78).toString(excelColumns)  // "1.50Z"
+an(1.5, 81).toString(excelColumns)  // "1.50AA"
+
+// The suffix algorithm is also available standalone
+alphabetSuffix(1)   // "a"
+alphabetSuffix(27)  // "aa"
 ```
 
-Override globally or for a single scoped block:
+---
+
+## Serialization
+
+Three paths for idle-game save files:
 
 ```typescript
-ArbitraryNumber.PrecisionCutoff = 50;  // global
+const gold = an(1.5, 6);
 
-// Scoped - PrecisionCutoff is restored after fn, even on throw
-const result = ArbitraryNumber.withPrecision(50, () => a.add(b));
-```
+// JSON — recommended, compact keys (c/e), stable across versions
+gold.toJSON()                      // { c: 1.5, e: 6 }
+JSON.stringify(gold)               // '{"c":1.5,"e":6}'
+ArbitraryNumber.fromJSON({ c: 1.5, e: 6 })  // restores
 
-## Errors
+// Pipe string — for URL params, cookies
+gold.toRawString()                 // "1.5|6"
+ArbitraryNumber.parse("1.5|6")    // restores
 
-All errors thrown by the library extend `ArbitraryNumberError`, so you can distinguish them from your own errors.
+// parse() accepts multiple input formats
+ArbitraryNumber.parse("1.5e+6")   // scientific
+ArbitraryNumber.parse("1500000")  // plain decimal
+ArbitraryNumber.parse("-0.003")   // negative
+```
+
+Save-every-60s pattern:
 
 ```typescript
-import {
-    ArbitraryNumberError,
-    ArbitraryNumberInputError,
-    ArbitraryNumberDomainError,
-} from "arbitrary-numbers";
+// Save
+function save(state: GameState): string {
+    return JSON.stringify({
+        gold: state.gold.toJSON(),
+        gps:  state.gps.toJSON(),
+    });
+}
 
-try {
-    an(1).div(an(0));
-} catch (e) {
-    if (e instanceof ArbitraryNumberDomainError) {
-        console.log(e.context);  // { dividend: 1 }
-    }
+// Load
+function load(json: string): GameState {
+    const raw = JSON.parse(json);
+    return {
+        gold: ArbitraryNumber.fromJSON(raw.gold),
+        gps:  ArbitraryNumber.fromJSON(raw.gps),
+    };
 }
+
+setInterval(() => localStorage.setItem("save", save(state)), 60_000);
 ```
 
-| Class | Thrown when | Extra property |
-|---|---|---|
-| `ArbitraryNumberInputError` | Non-finite input to a constructor or factory | `.value: number` |
-| `ArbitraryNumberDomainError` | Mathematically undefined operation | `.context: Record<string, number>` |
+---
 
-## Utilities
+## Precision control
 
-### ArbitraryNumberOps - mixed `number | ArbitraryNumber` input
+When two numbers differ in exponent by more than `defaults.scaleCutoff` (default `15`), the smaller operand is discarded — its contribution is below float64 resolution:
 
 ```typescript
-import { ArbitraryNumberOps as ops } from "arbitrary-numbers";
+const huge = an(1, 20);  // 10^20
+const tiny = an(1, 3);   //  1,000
 
-ops.from(1_500_000)          // { coefficient: 1.5, exponent: 6 }
-ops.add(1500, an(2, 3))      // 3,500
-ops.mul(an(2, 0), 5)         // 10
-ops.compare(5000, an(1, 4))  // -1  (5000 < 10,000)
-ops.clamp(500, 1000, 2000)   // 1,000
+huge.clone().add(tiny)  // unchanged — tiny is negligible at this scale
 ```
 
-### ArbitraryNumberGuard - type guards
+Override globally or in a scoped block:
 
 ```typescript
-import { ArbitraryNumberGuard as guard } from "arbitrary-numbers";
+ArbitraryNumber.defaults.scaleCutoff = 50;  // global
 
-guard.isArbitraryNumber(value)   // true when value instanceof ArbitraryNumber
-guard.isNormalizedNumber(value)  // true when value has numeric coefficient and exponent
-guard.isZero(value)              // true when value is ArbitraryNumber with coefficient 0
+// Scoped — restored after fn, even on throw
+const result = ArbitraryNumber.withPrecision(50, () => a.clone().add(b));
 ```
 
-### ArbitraryNumberHelpers - game and simulation patterns
+---
+
+## Utilities
+
+### ArbitraryNumberGuard — type guards
 
 ```typescript
-import { ArbitraryNumberHelpers as helpers } from "arbitrary-numbers";
+import { ArbitraryNumberGuard as guard } from "arbitrary-numbers";
 
-helpers.meetsOrExceeds(gold, upgradeCost)             // true when gold >= upgradeCost
-helpers.wholeMultipleCount(gold, upgradeCost)          // how many upgrades can you afford?
-helpers.subtractWithFloor(health, damage)              // max(health - damage, 0)
-helpers.subtractWithFloor(health, damage, minHealth)   // max(health - damage, minHealth)
+guard.isArbitraryNumber(value)    // true when value instanceof ArbitraryNumber
+guard.isNormalizedNumber(value)   // true when value has numeric coefficient + exponent
+guard.isZero(value)               // true when value is an ArbitraryNumber with coefficient 0
 ```
 
-All helpers accept `number | ArbitraryNumber` as input.
+### ArbitraryNumberHelpers — game patterns
 
-## Writing a custom plugin
+```typescript
+import { ArbitraryNumberHelpers as helpers } from "arbitrary-numbers";
 
-Any object with a `format(coefficient, exponent, decimals)` method is a valid `NotationPlugin`:
+helpers.meetsOrExceeds(gold, cost)              // gold >= cost
+helpers.wholeMultipleCount(gold, cost)          // how many can you afford?
+helpers.subtractWithFloor(health, damage)       // max(health − damage, 0)
+helpers.subtractWithFloor(health, damage, min)  // max(health − damage, min)
+```
 
-```typescript
-import type { NotationPlugin } from "arbitrary-numbers";
+All helpers accept `number | ArbitraryNumber` and never mutate their arguments.
 
-const emojiNotation: NotationPlugin = {
-    format(coefficient, exponent, decimals) {
-        const tiers = ["", "K", "M", "B", "T", "Qa", "Qi"];
-        const tier    = Math.floor(exponent / 3);
-        const display = coefficient * 10 ** (exponent - tier * 3);
-        return `${display.toFixed(decimals)}${tiers[tier] ?? `e+${tier * 3}`}`;
-    },
-};
+---
 
-an(1.5, 3).toString(emojiNotation)  // "1.50K"
-an(1.5, 6).toString(emojiNotation)  // "1.50M"
-```
+## Errors
 
-For tier-based suffix patterns, extend `SuffixNotationBase`, which handles all coefficient and remainder math:
+All errors extend `ArbitraryNumberError`.
+
+| Class | Thrown when |
+|---|---|
+| `ArbitraryNumberInputError` | Non-finite input (NaN, Infinity) to constructor or factory. `.value: number` |
+| `ArbitraryNumberDomainError` | Mathematically undefined operation (div by zero, sqrt of negative). `.context: Record<string, number>` |
+| `ArbitraryNumberMutationError` | Mutating method called on a frozen instance |
 
 ```typescript
-import { SuffixNotationBase } from "arbitrary-numbers";
+import { ArbitraryNumberDomainError } from "arbitrary-numbers";
 
-class TierNotation extends SuffixNotationBase {
-    private static readonly TIERS = ["", "K", "M", "B", "T", "Qa", "Qi"];
-    getSuffix(tier: number): string {
-        return TierNotation.TIERS[tier] ?? `e+${tier * 3}`;
+try {
+    an(1).div(an(0));
+} catch (e) {
+    if (e instanceof ArbitraryNumberDomainError) {
+        console.log(e.context);  // { dividend: 1 }
     }
 }
-
-an(3.2, 6).toString(new TierNotation({ separator: " " }))  // "3.20 M"
 ```
 
+---
+
 ## Idle game example
 
-A self-contained simulation showing hyper-growth, fused ops, helpers, and where plain JS `number` overflows while `ArbitraryNumber` keeps working.
+Full source: [`examples/idle-game.ts`](examples/idle-game.ts)
 
 ```typescript
 import {
-    an, chain,
-    UnitNotation,
-    CLASSIC_UNITS,
-    letterNotation,
+    an,
+    UnitNotation, CLASSIC_UNITS, letterNotation, scientificNotation,
     ArbitraryNumberHelpers as helpers,
 } from "arbitrary-numbers";
-import type { ArbitraryNumber } from "arbitrary-numbers";
 
-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 display = new UnitNotation({ units: CLASSIC_UNITS, fallback: letterNotation });
+const fmt = (v) => v.exponent > 300
+    ? v.toString(scientificNotation)
+    : v.toString(display);
 
-const display = new UnitNotation({
-    units: CLASSIC_UNITS,
-    fallback: letterNotation,
-});
+let gold        = an(1, 0);
+let gps         = an(1, 0);
+let upgradeCost = an(1, 2);
+let upgrades    = 0;
 
-function fmt(value: ArbitraryNumber, decimals = 2): string {
-    return value.toString(display, decimals);
-}
+for (let t = 1; t <= 350; t++) {
+    gold.mulAdd(an(1, 1), gps);  // gold = (gold × 10) + gps — fused, zero alloc
 
-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)}`,
-    );
+    if (upgrades < 25 && helpers.meetsOrExceeds(gold, upgradeCost)) {
+        gold.sub(upgradeCost);
+        gps.mul(an(1, 3));
+        upgradeCost.mul(an(1, 6));
+        upgrades++;
+    }
 }
+```
 
-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)}`,
-        );
-    }
+Output (selected lines):
 
-    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)}`);
-    }
+```
+=== Idle game simulation (350 ticks) ===
+start  gold=1.00  gps=1.00  upgradeCost=100.00
+
+[t=  2] UPGRADE # 1  gps       1.00 →     1.00 K   next cost: 1.00e+8
+[t=  8] UPGRADE # 2  gps     1.00 K →     1.00 M   next cost: 1.00e+14
+[t= 15] UPGRADE # 3  gps     1.00 M →     1.00 B   next cost: 1.00e+20
+...
+[t= 67] UPGRADE #11  gps    1.00 No →    1.00 Dc   next cost: 1.00e+68
+[t= 70] snapshot  AN:        112.22 Vg   JS: 1.12e+65
+[t= 80] UPGRADE #13  gps   1.00 UDc →   1.00 DDc   next cost: 1.00e+80
+...
+[t=140] snapshot  AN:             1.21   JS: 1.21e+129
+[t=280] snapshot  AN:             1.22   JS: 1.22e+267
+[t=350] snapshot  AN:        1.22e+337   JS: Infinity  ← beyond float64 max!
+
+=== Final state ===
+Upgrades bought : 25
+Final gold (AN) : 1.22e+337
+Gold as JS num  : Infinity
+```
 
-    if (t % 120 === 0) {
-        snapshot(t);
-    }
-}
+JS overflows at `~1e308`. ArbitraryNumber keeps tracking the exact value.
 
-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:
-
-```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.
-```
+> **Note on `UnitNotation` display:** `CLASSIC_UNITS` only defines specific named illion tiers (K, M, B, T … Ct). Values at exponents between named tiers will show as a plain decimal. For fully continuous display across all exponents, use `letterNotation` or `scientificNotation` as the primary formatter.
+
+---
 
 ## Performance
 
-Benchmarks are in [`benchmarks/`](benchmarks/). Competitor comparison: [`benchmarks/COMPETITOR_BENCHMARKS.md`](benchmarks/COMPETITOR_BENCHMARKS.md).
+Benchmarks: [`benchmarks/`](benchmarks/). Competitor comparison: [`benchmarks/COMPETITOR_BENCHMARKS.md`](benchmarks/COMPETITOR_BENCHMARKS.md).
 
-Quick reference (Node 22.16, Intel i5-13600KF):
+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 |
+| Operation | v2.0 | v1.1 |
+|---|---|---|
+| `new ArbitraryNumber(c, e)` | ~15.6 ns | ~13.5 ns |
+| `clone()` | **~6.7 ns** | ~13.5 ns |
+| `add` / `sub` | **~13 ns** | ~270 ns |
+| `mul` / `div` | **~11–12 ns** | ~255 ns |
+| `sqrt()` | **~11 ns** | ~252 ns |
+| `compareTo` | ~3.6 ns | ~3 ns |
+| `sumArray(50)` | **~156 ns** (~3.1 ns/elem) | N/A |
+
+v2 arithmetic is **20× faster than v1** — the v1 `Object.create` path cost ~250 ns per result regardless of the math. v2 mutates in-place: steady-state ops are pure float arithmetic with zero allocation.
+
+---
+
+## Migration from v1
+
+| v1 | v2 | Notes |
+|---|---|---|
+| `a.add(b)` → new instance | `a.add(b)` → mutates `a` | **Breaking.** Use `a.clone().add(b)` to keep old semantics. |
+| `chain(a).add(b).done()` | `a.add(b)` | `chain` removed — direct chaining is native. |
+| `formula(fn).apply(a)` | `formula().step1().step2().apply(a)` | Builder pattern replaces the callback. |
+| `ArbitraryNumber.PrecisionCutoff` | `ArbitraryNumber.defaults.scaleCutoff` | Renamed + namespaced. |
+| `ops.add(x, y)` | `ArbitraryNumber.add(x, y)` | Static on main class. |
+| `ArbitraryNumberOps` export | removed | — |
+| `ArbitraryNumberArithmetic` export | removed | — |
+| `NormalizedNumber` export | removed | — |
+| `AnChain`, `chain()` export | removed | — |
+| `a.toRaw()` | `a.toRawString()` | Renamed for clarity. |
+| `a.freeze()` | new | Returns `FrozenArbitraryNumber`. |
+| `ArbitraryNumber.Zero.add(...)` | throws `ArbitraryNumberMutationError` | Use `an(0).add(...)`. |