arbitrary-numbers 1.0.0

package/dist/index.js

@@ -0,0 +1,1484 @@
+// src/plugin/ScientificNotation.ts
+var ScientificNotation = class {
+  /**
+   * Formats a normalised value as `"<coefficient>e±<exponent>"`.
+   *
+   * @param coefficient - The significand in `[1, 10)` or `0`.
+   * @param exponent - The power of 10.
+   * @param decimals - Number of decimal places in the output.
+   * @returns The formatted string.
+   */
+  format(coefficient, exponent, decimals) {
+    if (exponent === 0) return coefficient.toFixed(decimals);
+    const sign = exponent < 0 ? "-" : "+";
+    return `${coefficient.toFixed(decimals)}e${sign}${Math.abs(exponent)}`;
+  }
+};
+var scientificNotation = new ScientificNotation();
+
+// src/constants/pow10.ts
+var POW10 = [
+  1,
+  10,
+  100,
+  1e3,
+  1e4,
+  1e5,
+  1e6,
+  1e7,
+  1e8,
+  1e9,
+  1e10,
+  1e11,
+  1e12,
+  1e13,
+  1e14,
+  1e15
+];
+function pow10(n) {
+  return n >= 0 && n < 16 ? POW10[n] : Math.pow(10, n);
+}
+
+// src/errors.ts
+var ArbitraryNumberError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArbitraryNumberError";
+  }
+};
+var ArbitraryNumberInputError = class extends ArbitraryNumberError {
+  constructor(message, value) {
+    super(message);
+    this.name = "ArbitraryNumberInputError";
+    this.value = value;
+  }
+};
+var ArbitraryNumberDomainError = class extends ArbitraryNumberError {
+  constructor(message, context) {
+    super(message);
+    this.name = "ArbitraryNumberDomainError";
+    this.context = context;
+  }
+};
+
+// src/core/ArbitraryNumber.ts
+var _ArbitraryNumber = class _ArbitraryNumber {
+  /**
+   * Creates an `ArbitraryNumber` from a plain JavaScript `number`.
+   *
+   * Prefer this over `new ArbitraryNumber(value, 0)` when working with
+   * ordinary numeric literals - it reads clearly at the call site and
+   * validates the input.
+   *
+   * @example
+   * ArbitraryNumber.from(1500);   // { coefficient: 1.5, exponent: 3 }
+   * ArbitraryNumber.from(0.005);  // { coefficient: 5,   exponent: -3 }
+   * ArbitraryNumber.from(0);      // ArbitraryNumber.Zero
+   *
+   * @param value - Any finite number.
+   * @throws `"ArbitraryNumber.from: value must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
+   */
+  static from(value) {
+    if (!isFinite(value)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.from: value must be finite", value);
+    }
+    return new _ArbitraryNumber(value, 0);
+  }
+  /**
+   * Constructs a new `ArbitraryNumber` and immediately normalises it so that
+   * `1 <= |coefficient| < 10` (or `coefficient === 0`).
+   *
+   * @example
+   * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
+   *
+   * @param coefficient - The significand. Must be a finite number; will be normalised.
+   * @param exponent - The power of 10. Must be a finite number.
+   * @throws `"ArbitraryNumber: coefficient must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
+   * @throws `"ArbitraryNumber: exponent must be finite"` for non-finite exponents.
+   */
+  constructor(coefficient, exponent) {
+    if (coefficient === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return;
+    }
+    if (!isFinite(coefficient)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber: coefficient must be finite", coefficient);
+    }
+    if (!isFinite(exponent)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber: exponent must be finite", exponent);
+    }
+    const abs = Math.abs(coefficient);
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) {
+      this.coefficient = 0;
+      this.exponent = 0;
+      return;
+    }
+    this.coefficient = coefficient / scale;
+    this.exponent = exponent + shift;
+  }
+  /**
+   * @internal Fast-path factory for already-normalised values.
+   *
+   * Uses Object.create() to bypass the constructor (zero normalisation cost).
+   * Only valid when |coefficient| is already in [1, 10) and exponent is correct.
+   * Do NOT use for unnormalised inputs - call new ArbitraryNumber(c, e) instead.
+   */
+  static createNormalized(coefficient, exponent) {
+    const n = Object.create(_ArbitraryNumber.prototype);
+    n.coefficient = coefficient;
+    n.exponent = exponent;
+    return n;
+  }
+  /**
+   * Normalises raw (coefficient, exponent) into a new ArbitraryNumber.
+   *
+   * INVARIANT: all ArbitraryNumber values must have coefficient in [1, 10).
+   * Algorithm: shift = floor(log10(|c|)); scale c by 10^-shift; adjust exponent.
+   * Cost: one Math.log10 call (~3-4 ns). This is the fundamental cost floor - logarithm
+   * is the only way to compute magnitude in JavaScript.
+   */
+  static normalizeFrom(c, e) {
+    if (c === 0) return _ArbitraryNumber.Zero;
+    const abs = Math.abs(c);
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) return _ArbitraryNumber.Zero;
+    return _ArbitraryNumber.createNormalized(c / scale, e + shift);
+  }
+  /**
+   * Returns `this + other`.
+   *
+   * When the exponent difference exceeds {@link PrecisionCutoff}, the smaller
+   * operand has no effect and the larger is returned as-is.
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 3).add(new ArbitraryNumber(2.5, 3)); // 4*10^3
+   */
+  add(other) {
+    if (this.coefficient === 0) return other;
+    if (other.coefficient === 0) return this;
+    const diff = this.exponent - other.exponent;
+    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
+    if (diff < -_ArbitraryNumber.PrecisionCutoff) return other;
+    let c;
+    let e;
+    if (diff >= 0) {
+      c = this.coefficient + other.coefficient / pow10(diff);
+      e = this.exponent;
+    } else {
+      c = other.coefficient + this.coefficient / pow10(-diff);
+      e = other.exponent;
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Returns `this - other`.
+   *
+   * @example
+   * new ArbitraryNumber(3.5, 3).sub(new ArbitraryNumber(1.5, 3)); // 2*10^3
+   */
+  sub(other) {
+    if (other.coefficient === 0) return this;
+    const negC = -other.coefficient;
+    if (this.coefficient === 0) return _ArbitraryNumber.createNormalized(negC, other.exponent);
+    const diff = this.exponent - other.exponent;
+    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
+    if (diff < -_ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(negC, other.exponent);
+    let c;
+    let e;
+    if (diff >= 0) {
+      c = this.coefficient + negC / pow10(diff);
+      e = this.exponent;
+    } else {
+      c = negC + this.coefficient / pow10(-diff);
+      e = other.exponent;
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Returns `this * other`.
+   *
+   * @example
+   * new ArbitraryNumber(2, 3).mul(new ArbitraryNumber(3, 4)); // 6*10^7
+   */
+  mul(other) {
+    if (this.coefficient === 0 || other.coefficient === 0) return _ArbitraryNumber.Zero;
+    const c = this.coefficient * other.coefficient;
+    const e = this.exponent + other.exponent;
+    const absC = c < 0 ? -c : c;
+    if (absC >= 10) return _ArbitraryNumber.createNormalized(c / 10, e + 1);
+    return _ArbitraryNumber.createNormalized(c, e);
+  }
+  /**
+   * Returns `this / other`.
+   *
+   * @example
+   * new ArbitraryNumber(6, 7).div(new ArbitraryNumber(3, 4)); // 2*10^3
+   *
+   * @throws `"Division by zero"` when `other` is zero.
+   */
+  div(other) {
+    if (other.coefficient === 0) throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    const c = this.coefficient / other.coefficient;
+    const e = this.exponent - other.exponent;
+    if (c === 0) return _ArbitraryNumber.Zero;
+    const absC = c < 0 ? -c : c;
+    if (absC < 1) return _ArbitraryNumber.createNormalized(c * 10, e - 1);
+    return _ArbitraryNumber.createNormalized(c, e);
+  }
+  /**
+   * Returns the arithmetic negation of this number (`-this`).
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 3).negate(); // -1.5*10^3
+   */
+  negate() {
+    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
+    return _ArbitraryNumber.createNormalized(-this.coefficient, this.exponent);
+  }
+  /**
+   * Returns the absolute value of this number (`|this|`).
+   *
+   * Returns `this` unchanged when the number is already non-negative.
+   *
+   * @example
+   * new ArbitraryNumber(-1.5, 3).abs(); // 1.5*10^3
+   */
+  abs() {
+    if (this.coefficient >= 0) return this;
+    return _ArbitraryNumber.createNormalized(-this.coefficient, this.exponent);
+  }
+  /**
+   * Returns `this^n`.
+   *
+   * Supports integer, fractional, and negative exponents.
+   * `x^0` always returns {@link One}, including `0^0` (by convention).
+   *
+   * @example
+   * new ArbitraryNumber(2, 3).pow(2);  // 4*10^6
+   * new ArbitraryNumber(2, 0).pow(-1); // 5*10^-1  (= 0.5)
+   *
+   * @param n - The exponent to raise this number to.
+   * @throws `"Zero cannot be raised to a negative power"` when this is zero and `n < 0`.
+   */
+  pow(n) {
+    if (n === 0) {
+      return _ArbitraryNumber.One;
+    }
+    if (this.coefficient === 0) {
+      if (n < 0) {
+        throw new ArbitraryNumberDomainError("Zero cannot be raised to a negative power", { exponent: n });
+      }
+      return _ArbitraryNumber.Zero;
+    }
+    if (this.coefficient < 0 && !Number.isInteger(n)) {
+      throw new ArbitraryNumberDomainError("ArbitraryNumber.pow: fractional exponent of a negative base is not supported", { base: this.toNumber(), exponent: n });
+    }
+    const rawExp = this.exponent * n;
+    const intExp = Math.floor(rawExp);
+    const fracExp = rawExp - intExp;
+    return new _ArbitraryNumber(
+      Math.pow(this.coefficient, n) * pow10(fracExp),
+      intExp
+    );
+  }
+  /**
+   * Fused multiply-add: `(this * multiplier) + addend`.
+   *
+   * Faster than `.mul(multiplier).add(addend)` because it avoids allocating an
+   * intermediate ArbitraryNumber for the product. One normalisation pass total.
+   *
+   * Common pattern - prestige loop: `value = value.mulAdd(prestigeMultiplier, prestigeBoost)`
+   *
+   * @example
+   * // Equivalent to value.mul(mult).add(boost) but ~35-50% faster
+   * const prestiged = currentValue.mulAdd(multiplier, boost);
+   */
+  mulAdd(multiplier, addend) {
+    if (this.coefficient === 0 || multiplier.coefficient === 0) return addend;
+    let cp = this.coefficient * multiplier.coefficient;
+    let ep = this.exponent + multiplier.exponent;
+    const absCp = cp < 0 ? -cp : cp;
+    if (absCp >= 10) {
+      cp /= 10;
+      ep += 1;
+    }
+    if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
+    const diff = ep - addend.exponent;
+    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
+    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    let c, e;
+    if (diff >= 0) {
+      c = cp + addend.coefficient / pow10(diff);
+      e = ep;
+    } else {
+      c = addend.coefficient + cp / pow10(-diff);
+      e = addend.exponent;
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Fused add-multiply: `(this + addend) * multiplier`.
+   *
+   * Faster than `.add(addend).mul(multiplier)` because it avoids allocating an
+   * intermediate ArbitraryNumber for the sum. One normalisation pass total.
+   *
+   * Common pattern - upgrade calculation: `newValue = baseValue.addMul(bonus, multiplier)`
+   *
+   * @example
+   * // Equivalent to base.add(bonus).mul(multiplier) but ~20-25% faster
+   * const upgraded = baseValue.addMul(bonus, multiplier);
+   */
+  addMul(addend, multiplier) {
+    if (multiplier.coefficient === 0) return _ArbitraryNumber.Zero;
+    let cs, es;
+    if (this.coefficient === 0 && addend.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.coefficient === 0) {
+      cs = addend.coefficient;
+      es = addend.exponent;
+    } else if (addend.coefficient === 0) {
+      cs = this.coefficient;
+      es = this.exponent;
+    } else {
+      const diff = this.exponent - addend.exponent;
+      if (diff > _ArbitraryNumber.PrecisionCutoff) {
+        cs = this.coefficient;
+        es = this.exponent;
+      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+        cs = addend.coefficient;
+        es = addend.exponent;
+      } else {
+        if (diff >= 0) {
+          cs = this.coefficient + addend.coefficient / pow10(diff);
+          es = this.exponent;
+        } else {
+          cs = addend.coefficient + this.coefficient / pow10(-diff);
+          es = addend.exponent;
+        }
+        if (cs === 0) return _ArbitraryNumber.Zero;
+        const abs = Math.abs(cs);
+        const shift = Math.floor(Math.log10(abs));
+        const scale = pow10(shift);
+        if (scale === 0) return _ArbitraryNumber.Zero;
+        cs /= scale;
+        es += shift;
+      }
+    }
+    let cp = cs * multiplier.coefficient;
+    const ep = es + multiplier.exponent;
+    const absCp = cp < 0 ? -cp : cp;
+    if (absCp >= 10) {
+      cp /= 10;
+      return _ArbitraryNumber.createNormalized(cp, ep + 1);
+    }
+    return _ArbitraryNumber.createNormalized(cp, ep);
+  }
+  /**
+   * Fused multiply-subtract: `(this * multiplier) - subtrahend`.
+   *
+   * Avoids one intermediate allocation vs `.mul(multiplier).sub(subtrahend)`.
+   *
+   * Common pattern - resource drain: `income.mulSub(rate, upkeepCost)`
+   */
+  mulSub(multiplier, subtrahend) {
+    if (this.coefficient === 0 || multiplier.coefficient === 0) {
+      if (subtrahend.coefficient === 0) return _ArbitraryNumber.Zero;
+      return _ArbitraryNumber.createNormalized(-subtrahend.coefficient, subtrahend.exponent);
+    }
+    let cp = this.coefficient * multiplier.coefficient;
+    let ep = this.exponent + multiplier.exponent;
+    const absCp = cp < 0 ? -cp : cp;
+    if (absCp >= 10) {
+      cp /= 10;
+      ep += 1;
+    }
+    if (subtrahend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
+    const diff = ep - subtrahend.exponent;
+    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
+    if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+      return _ArbitraryNumber.createNormalized(-subtrahend.coefficient, subtrahend.exponent);
+    }
+    let c, e;
+    if (diff >= 0) {
+      c = cp - subtrahend.coefficient / pow10(diff);
+      e = ep;
+    } else {
+      c = -subtrahend.coefficient + cp / pow10(-diff);
+      e = subtrahend.exponent;
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Fused subtract-multiply: `(this - subtrahend) * multiplier`.
+   *
+   * Avoids one intermediate allocation vs `.sub(subtrahend).mul(multiplier)`.
+   *
+   * Common pattern - upgrade after penalty: `health.subMul(damage, multiplier)`
+   */
+  subMul(subtrahend, multiplier) {
+    if (multiplier.coefficient === 0) return _ArbitraryNumber.Zero;
+    let cs, es;
+    if (this.coefficient === 0 && subtrahend.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.coefficient === 0) {
+      cs = -subtrahend.coefficient;
+      es = subtrahend.exponent;
+    } else if (subtrahend.coefficient === 0) {
+      cs = this.coefficient;
+      es = this.exponent;
+    } else {
+      const diff = this.exponent - subtrahend.exponent;
+      if (diff > _ArbitraryNumber.PrecisionCutoff) {
+        cs = this.coefficient;
+        es = this.exponent;
+      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+        cs = -subtrahend.coefficient;
+        es = subtrahend.exponent;
+      } else {
+        if (diff >= 0) {
+          cs = this.coefficient - subtrahend.coefficient / pow10(diff);
+          es = this.exponent;
+        } else {
+          cs = -subtrahend.coefficient + this.coefficient / pow10(-diff);
+          es = subtrahend.exponent;
+        }
+        if (cs === 0) return _ArbitraryNumber.Zero;
+        const abs = Math.abs(cs);
+        const shift = Math.floor(Math.log10(abs));
+        const scale = pow10(shift);
+        if (scale === 0) return _ArbitraryNumber.Zero;
+        cs /= scale;
+        es += shift;
+      }
+    }
+    let cp = cs * multiplier.coefficient;
+    const ep = es + multiplier.exponent;
+    const absCp = cp < 0 ? -cp : cp;
+    if (absCp >= 10) {
+      cp /= 10;
+      return _ArbitraryNumber.createNormalized(cp, ep + 1);
+    }
+    return _ArbitraryNumber.createNormalized(cp, ep);
+  }
+  /**
+   * Fused divide-add: `(this / divisor) + addend`.
+   *
+   * Avoids one intermediate allocation vs `.div(divisor).add(addend)`.
+   *
+   * Common pattern - efficiency bonus: `damage.divAdd(armor, flat)`
+   *
+   * @throws `"Division by zero"` when divisor is zero.
+   */
+  divAdd(divisor, addend) {
+    if (divisor.coefficient === 0) throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    if (this.coefficient === 0) return addend;
+    let cd = this.coefficient / divisor.coefficient;
+    let ed = this.exponent - divisor.exponent;
+    const absC = cd < 0 ? -cd : cd;
+    if (absC < 1) {
+      cd *= 10;
+      ed -= 1;
+    }
+    if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cd, ed);
+    const diff = ed - addend.exponent;
+    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cd, ed);
+    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    let c, e;
+    if (diff >= 0) {
+      c = cd + addend.coefficient / pow10(diff);
+      e = ed;
+    } else {
+      c = addend.coefficient + cd / pow10(-diff);
+      e = addend.exponent;
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
+   *
+   * **Why it's fast:** standard chained `.add()` normalises after every element (N log10 calls).
+   * `sumArray` aligns all coefficients to the largest exponent (pivot), sums them,
+   * then normalises once - regardless of array size.
+   *
+   * For 50 elements: chained add ~ 50 log10 calls + 50 allocations;
+   * sumArray ~ 50 divisions + 1 log10 call + 1 allocation -> ~9* faster.
+   *
+   * Common pattern - income aggregation: `total = ArbitraryNumber.sumArray(incomeSourcesPerTick)`
+   *
+   * @example
+   * const total = ArbitraryNumber.sumArray(incomeSources); // far faster than .reduce((a, b) => a.add(b))
+   *
+   * @param numbers - Array to sum. Empty array returns {@link Zero}. Single element returned as-is.
+   */
+  static sumArray(numbers) {
+    const len = numbers.length;
+    if (len === 0) return _ArbitraryNumber.Zero;
+    if (len === 1) return numbers[0];
+    let pivotExp = numbers[0].exponent;
+    for (let i = 1; i < len; i++) {
+      const n = numbers[i];
+      if (n.exponent > pivotExp) pivotExp = n.exponent;
+    }
+    let total = 0;
+    for (let i = 0; i < len; i++) {
+      const n = numbers[i];
+      if (n.coefficient === 0) continue;
+      const diff = pivotExp - n.exponent;
+      if (diff > _ArbitraryNumber.PrecisionCutoff) continue;
+      total += n.coefficient / pow10(diff);
+    }
+    if (total === 0) return _ArbitraryNumber.Zero;
+    const abs = Math.abs(total);
+    const shift = Math.floor(Math.log10(abs));
+    const scale = pow10(shift);
+    if (scale === 0) return _ArbitraryNumber.Zero;
+    return _ArbitraryNumber.createNormalized(total / scale, pivotExp + shift);
+  }
+  /**
+   * Compares this number to `other`.
+   *
+   * @returns `1` if `this > other`, `-1` if `this < other`, `0` if equal.
+   *
+   * @example
+   * new ArbitraryNumber(1, 4).compareTo(new ArbitraryNumber(9, 3)); // 1  (10000 > 9000)
+   * new ArbitraryNumber(-1, 4).compareTo(new ArbitraryNumber(1, 3)); // -1 (-10000 < 1000)
+   */
+  compareTo(other) {
+    const thisNegative = this.coefficient < 0;
+    const otherNegative = other.coefficient < 0;
+    if (thisNegative !== otherNegative) {
+      return thisNegative ? -1 : 1;
+    }
+    if (this.exponent !== other.exponent) {
+      if (this.coefficient === 0) return otherNegative ? 1 : -1;
+      if (other.coefficient === 0) return thisNegative ? -1 : 1;
+      const thisExponentIsHigher = this.exponent > other.exponent;
+      return thisNegative ? thisExponentIsHigher ? -1 : 1 : thisExponentIsHigher ? 1 : -1;
+    }
+    if (this.coefficient !== other.coefficient) {
+      return this.coefficient > other.coefficient ? 1 : -1;
+    }
+    return 0;
+  }
+  /** Returns `true` if `this > other`. */
+  greaterThan(other) {
+    return this.compareTo(other) > 0;
+  }
+  /** Returns `true` if `this < other`. */
+  lessThan(other) {
+    return this.compareTo(other) < 0;
+  }
+  /** Returns `true` if `this >= other`. */
+  greaterThanOrEqual(other) {
+    return this.compareTo(other) >= 0;
+  }
+  /** Returns `true` if `this <= other`. */
+  lessThanOrEqual(other) {
+    return this.compareTo(other) <= 0;
+  }
+  /** Returns `true` if `this === other` in value. */
+  equals(other) {
+    return this.compareTo(other) === 0;
+  }
+  /**
+   * Returns the largest integer less than or equal to this number (floor toward -Infinity).
+   *
+   * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
+   * and are returned unchanged.
+   *
+   * @example
+   * new ArbitraryNumber(1.7, 0).floor();  // 1
+   * new ArbitraryNumber(-1.7, 0).floor(); // -2
+   */
+  floor() {
+    if (this.coefficient === 0) {
+      return _ArbitraryNumber.Zero;
+    }
+    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) {
+      return this;
+    }
+    if (this.exponent < 0) {
+      return this.coefficient >= 0 ? _ArbitraryNumber.Zero : new _ArbitraryNumber(-1, 0);
+    }
+    return new _ArbitraryNumber(Math.floor(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Returns the smallest integer greater than or equal to this number (ceil toward +Infinity).
+   *
+   * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
+   * and are returned unchanged.
+   *
+   * @example
+   * new ArbitraryNumber(1.2, 0).ceil();  // 2
+   * new ArbitraryNumber(-1.7, 0).ceil(); // -1
+   */
+  ceil() {
+    if (this.coefficient === 0) {
+      return _ArbitraryNumber.Zero;
+    }
+    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) {
+      return this;
+    }
+    if (this.exponent < 0) {
+      return this.coefficient > 0 ? _ArbitraryNumber.One : _ArbitraryNumber.Zero;
+    }
+    return new _ArbitraryNumber(Math.ceil(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Clamps `value` to the inclusive range `[min, max]`.
+   *
+   * @example
+   * ArbitraryNumber.clamp(new ArbitraryNumber(5, 2), new ArbitraryNumber(1, 3), new ArbitraryNumber(2, 3)); // 1*10^3  (500 clamped to [1000, 2000])
+   *
+   * @param value - The value to clamp.
+   * @param min - Lower bound (inclusive).
+   * @param max - Upper bound (inclusive).
+   */
+  static clamp(value, min, max) {
+    if (value.lessThan(min)) return min;
+    if (value.greaterThan(max)) return max;
+    return value;
+  }
+  /**
+   * Returns the smaller of `a` and `b`.
+   * @example ArbitraryNumber.min(a, b)
+   */
+  static min(a, b) {
+    return a.lessThan(b) ? a : b;
+  }
+  /**
+   * Returns the larger of `a` and `b`.
+   * @example ArbitraryNumber.max(a, b)
+   */
+  static max(a, b) {
+    return a.greaterThan(b) ? a : b;
+  }
+  /**
+   * Linear interpolation: `a + (b - a) * t` where `t in [0, 1]` is a plain number.
+   *
+   * Used for smooth animations and tweening in game UIs.
+   * `t = 0` returns `a`; `t = 1` returns `b`.
+   *
+   * @param t - Interpolation factor as a plain `number`. Values outside [0, 1] are allowed (extrapolation).
+   * @example
+   * ArbitraryNumber.lerp(an(100), an(200), 0.5); // 150
+   */
+  static lerp(a, b, t) {
+    if (t === 0) return a;
+    if (t === 1) return b;
+    return a.add(b.sub(a).mul(_ArbitraryNumber.from(t)));
+  }
+  /**
+   * Runs `fn` with `PrecisionCutoff` temporarily set to `cutoff`, then restores the previous value.
+   *
+   * Useful when one section of code needs different precision than the rest.
+   *
+   * @example
+   * // Run financial calculation with higher precision
+   * const result = ArbitraryNumber.withPrecision(50, () => a.add(b));
+   */
+  static withPrecision(cutoff, fn) {
+    const prev = _ArbitraryNumber.PrecisionCutoff;
+    _ArbitraryNumber.PrecisionCutoff = cutoff;
+    try {
+      return fn();
+    } finally {
+      _ArbitraryNumber.PrecisionCutoff = prev;
+    }
+  }
+  /**
+   * Returns `log10(this)` as a plain JavaScript `number`.
+   *
+   * Because the number is stored as `c * 10^e`, this is computed exactly as
+   * `log10(c) + e` - no precision loss from the exponent.
+   *
+   * @example
+   * new ArbitraryNumber(1, 6).log10();    // 6
+   * new ArbitraryNumber(1.5, 3).log10();  // log10(1.5) + 3  ~ 3.176
+   *
+   * @throws `"Logarithm of zero is undefined"` when this is zero.
+   * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+   */
+  log10() {
+    if (this.coefficient === 0) {
+      throw new ArbitraryNumberDomainError("Logarithm of zero is undefined", { value: 0 });
+    }
+    if (this.coefficient < 0) {
+      throw new ArbitraryNumberDomainError("Logarithm of a negative number is undefined", { value: this.toNumber() });
+    }
+    return Math.log10(this.coefficient) + this.exponent;
+  }
+  /**
+   * Returns √this.
+   *
+   * Computed as pure coefficient math - no `Math.log10` call. Cost: one `Math.sqrt`.
+   * For even exponents: `sqrt(c) * 10^(e/2)`.
+   * For odd exponents: `sqrt(c * 10) * 10^((e-1)/2)`.
+   *
+   * @throws `"Square root of negative number"` when this is negative.
+   * @example
+   * new ArbitraryNumber(4, 0).sqrt();   // 2
+   * new ArbitraryNumber(1, 4).sqrt();   // 1*10^2  (= 100)
+   */
+  sqrt() {
+    if (this.coefficient < 0) throw new ArbitraryNumberDomainError("Square root of negative number", { value: this.toNumber() });
+    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.exponent % 2 !== 0) {
+      return _ArbitraryNumber.createNormalized(Math.sqrt(this.coefficient * 10), (this.exponent - 1) / 2);
+    }
+    return _ArbitraryNumber.createNormalized(Math.sqrt(this.coefficient), this.exponent / 2);
+  }
+  /**
+   * Returns the nearest integer value (rounds half-up).
+   *
+   * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
+   * and are returned unchanged.
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 0).round();  // 2
+   * new ArbitraryNumber(1.4, 0).round();  // 1
+   * new ArbitraryNumber(-1.5, 0).round(); // -1 (half-up toward positive infinity)
+   */
+  round() {
+    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) return this;
+    if (this.exponent < 0) {
+      if (this.exponent <= -2) return _ArbitraryNumber.Zero;
+      const rounded = Math.round(this.coefficient * 0.1);
+      return rounded === 0 ? _ArbitraryNumber.Zero : new _ArbitraryNumber(rounded, 0);
+    }
+    return new _ArbitraryNumber(Math.round(this.coefficient * pow10(this.exponent)), 0);
+  }
+  /**
+   * Returns `1` if positive, `-1` if negative, `0` if zero.
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 3).sign();  // 1
+   * new ArbitraryNumber(-1.5, 3).sign(); // -1
+   * ArbitraryNumber.Zero.sign();         // 0
+   */
+  sign() {
+    return Math.sign(this.coefficient);
+  }
+  /**
+   * Converts to a plain JavaScript `number`.
+   *
+   * Precision is limited to float64 (~15 significant digits).
+   * Returns `Infinity` for exponents beyond the float64 range (>=308).
+   * Returns `0` for exponents below the float64 range (<=-324).
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 3).toNumber();  // 1500
+   * new ArbitraryNumber(1, 400).toNumber();  // Infinity
+   */
+  toNumber() {
+    return this.coefficient * pow10(this.exponent);
+  }
+  /** Returns `true` when this number is zero. */
+  isZero() {
+    return this.coefficient === 0;
+  }
+  /** Returns `true` when this number is strictly positive. */
+  isPositive() {
+    return this.coefficient > 0;
+  }
+  /** Returns `true` when this number is strictly negative. */
+  isNegative() {
+    return this.coefficient < 0;
+  }
+  /**
+   * Returns `true` when this number has no fractional part.
+   * Numbers with `exponent >= PrecisionCutoff` are always considered integers.
+   */
+  isInteger() {
+    if (this.coefficient === 0) return true;
+    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) return true;
+    if (this.exponent < 0) return false;
+    return Number.isInteger(this.coefficient * pow10(this.exponent));
+  }
+  /**
+   * Formats this number as a string using the given notation plugin.
+   *
+   * Defaults to {@link scientificNotation} when no plugin is provided.
+   * `decimals` controls the number of decimal places passed to the plugin and defaults to `2`.
+   *
+   * @example
+   * new ArbitraryNumber(1.5, 3).toString();                  // "1.50e+3"
+   * new ArbitraryNumber(1.5, 3).toString(unitNotation);       // "1.50 K"
+   * new ArbitraryNumber(1.5, 3).toString(unitNotation, 4);    // "1.5000 K"
+   *
+   * @param notation - The formatting plugin to use.
+   * @param decimals - Number of decimal places to render. Defaults to `2`.
+   */
+  toString(notation = scientificNotation, decimals = 2) {
+    return notation.format(this.coefficient, this.exponent, decimals);
+  }
+};
+/**
+ * Precision cutoff: exponent-difference threshold below which the smaller operand
+ * is negligible and silently skipped during addition/subtraction.
+ *
+ * When |exponent_diff| > PrecisionCutoff, the smaller operand contributes less than
+ * 10^-PrecisionCutoff of the result - below float64 coefficient precision for the default of 15.
+ *
+ * Default: 15 (matches float64 coefficient precision of ~15.95 significant digits).
+ * Game patterns: diffs 0-8 (exact), prestige 15-25 (loss <0.0001%), idle 20-50 (~0.1% loss).
+ *
+ * Override globally via assignment, or use {@link withPrecision} for a scoped block.
+ */
+_ArbitraryNumber.PrecisionCutoff = 15;
+/** The additive identity: `0`. */
+_ArbitraryNumber.Zero = new _ArbitraryNumber(0, 0);
+/** The multiplicative identity: `1`. */
+_ArbitraryNumber.One = new _ArbitraryNumber(1, 0);
+/** `10`. */
+_ArbitraryNumber.Ten = new _ArbitraryNumber(1, 1);
+var ArbitraryNumber = _ArbitraryNumber;
+
+// src/core/an.ts
+var createAn = ((coefficient, exponent = 0) => new ArbitraryNumber(coefficient, exponent));
+createAn.from = (value) => ArbitraryNumber.from(value);
+var an = createAn;
+
+// src/core/AnChain.ts
+var AnChain = class _AnChain {
+  constructor(start) {
+    this.value = start;
+  }
+  // ── Construction ────────────────────────────────────────────────────
+  /** Creates an `AnChain` from an `ArbitraryNumber` or a plain `number`. */
+  static from(value) {
+    if (value instanceof ArbitraryNumber) return new _AnChain(value);
+    return new _AnChain(ArbitraryNumber.from(value));
+  }
+  // ── Arithmetic ───────────────────────────────────────────────────────
+  /** Adds `other` to the accumulated value. */
+  add(other) {
+    this.value = this.value.add(other);
+    return this;
+  }
+  /** Subtracts `other` from the accumulated value. */
+  sub(other) {
+    this.value = this.value.sub(other);
+    return this;
+  }
+  /** Multiplies the accumulated value by `other`. */
+  mul(other) {
+    this.value = this.value.mul(other);
+    return this;
+  }
+  /** Divides the accumulated value by `other`. */
+  div(other) {
+    this.value = this.value.div(other);
+    return this;
+  }
+  /** Raises the accumulated value to `exp`. */
+  pow(exp) {
+    this.value = this.value.pow(exp);
+    return this;
+  }
+  // ── Fused (avoids one intermediate allocation per call) ──────────────
+  /** `(this * mult) + add` */
+  mulAdd(mult, add) {
+    this.value = this.value.mulAdd(mult, add);
+    return this;
+  }
+  /** `(this + add) * mult` */
+  addMul(add, mult) {
+    this.value = this.value.addMul(add, mult);
+    return this;
+  }
+  /** `(this * mult) - sub` */
+  mulSub(mult, sub) {
+    this.value = this.value.mulSub(mult, sub);
+    return this;
+  }
+  /** `(this - sub) * mult` */
+  subMul(sub, mult) {
+    this.value = this.value.subMul(sub, mult);
+    return this;
+  }
+  /** `(this / div) + add` */
+  divAdd(div, add) {
+    this.value = this.value.divAdd(div, add);
+    return this;
+  }
+  // ── Unary ────────────────────────────────────────────────────────────
+  /** Absolute value. */
+  abs() {
+    this.value = this.value.abs();
+    return this;
+  }
+  /** Negates the accumulated value. */
+  neg() {
+    this.value = this.value.negate();
+    return this;
+  }
+  /** Square root of the accumulated value. */
+  sqrt() {
+    this.value = this.value.sqrt();
+    return this;
+  }
+  /** Rounds down to the nearest integer. */
+  floor() {
+    this.value = this.value.floor();
+    return this;
+  }
+  /** Rounds up to the nearest integer. */
+  ceil() {
+    this.value = this.value.ceil();
+    return this;
+  }
+  /** Rounds to the nearest integer. */
+  round() {
+    this.value = this.value.round();
+    return this;
+  }
+  // ── Terminal ─────────────────────────────────────────────────────────
+  /** Returns the accumulated `ArbitraryNumber` result. */
+  done() {
+    return this.value;
+  }
+};
+function chain(value) {
+  return AnChain.from(value);
+}
+
+// src/core/AnFormula.ts
+var AnFormula = class _AnFormula {
+  /**
+   * Prefer the {@link formula} factory function over calling this directly.
+   */
+  constructor(name, steps = []) {
+    this._name = name;
+    this.steps = steps;
+  }
+  /** The name passed to {@link formula}, if any. */
+  get name() {
+    return this._name;
+  }
+  /**
+   * Returns a copy of this formula with a new name, leaving the original unchanged.
+   *
+   * @param name - The new name.
+   * @example
+   * const base  = formula().mul(an(2));
+   * const named = base.named("Double");
+   * named.name   // "Double"
+   * base.name    // undefined
+   */
+  named(name) {
+    return new _AnFormula(name, this.steps);
+  }
+  // ── Private helper ────────────────────────────────────────────────────────
+  step(fn) {
+    return new _AnFormula(this._name, [...this.steps, fn]);
+  }
+  // ── Arithmetic ────────────────────────────────────────────────────────────
+  /** Appends `+ other` to the pipeline. */
+  add(other) {
+    return this.step((v) => v.add(other));
+  }
+  /** Appends `- other` to the pipeline. */
+  sub(other) {
+    return this.step((v) => v.sub(other));
+  }
+  /** Appends `* other` to the pipeline. */
+  mul(other) {
+    return this.step((v) => v.mul(other));
+  }
+  /** Appends `/ other` to the pipeline. */
+  div(other) {
+    return this.step((v) => v.div(other));
+  }
+  /** Appends `^ exp` to the pipeline. */
+  pow(exp) {
+    return this.step((v) => v.pow(exp));
+  }
+  // ── Fused (avoids one intermediate allocation per call) ───────────────────
+  /** Appends `(value * mult) + add` to the pipeline. */
+  mulAdd(mult, add) {
+    return this.step((v) => v.mulAdd(mult, add));
+  }
+  /** Appends `(value + add) * mult` to the pipeline. */
+  addMul(add, mult) {
+    return this.step((v) => v.addMul(add, mult));
+  }
+  /** Appends `(value * mult) - sub` to the pipeline. */
+  mulSub(mult, sub) {
+    return this.step((v) => v.mulSub(mult, sub));
+  }
+  /** Appends `(value - sub) * mult` to the pipeline. */
+  subMul(sub, mult) {
+    return this.step((v) => v.subMul(sub, mult));
+  }
+  /** Appends `(value / div) + add` to the pipeline. */
+  divAdd(div, add) {
+    return this.step((v) => v.divAdd(div, add));
+  }
+  // ── Unary ─────────────────────────────────────────────────────────────────
+  /** Appends `abs()` to the pipeline. */
+  abs() {
+    return this.step((v) => v.abs());
+  }
+  /** Appends `neg()` to the pipeline. */
+  neg() {
+    return this.step((v) => v.negate());
+  }
+  /** Appends `sqrt()` to the pipeline. */
+  sqrt() {
+    return this.step((v) => v.sqrt());
+  }
+  /** Appends `floor()` to the pipeline. */
+  floor() {
+    return this.step((v) => v.floor());
+  }
+  /** Appends `ceil()` to the pipeline. */
+  ceil() {
+    return this.step((v) => v.ceil());
+  }
+  /** Appends `round()` to the pipeline. */
+  round() {
+    return this.step((v) => v.round());
+  }
+  // ── Composition ───────────────────────────────────────────────────────────
+  /**
+   * Returns a new formula that first applies `this`, then applies `next`.
+   *
+   * Neither operand is mutated.
+   *
+   * @param next - The formula to apply after `this`.
+   * @example
+   * const full   = armorReduction.then(critBonus);
+   * const result = full.apply(baseDamage);
+   */
+  then(next) {
+    return new _AnFormula(this._name, [...this.steps, ...next.steps]);
+  }
+  // ── Terminal ──────────────────────────────────────────────────────────────
+  /**
+   * Runs this formula's pipeline against `value` and returns the result.
+   *
+   * The formula itself is unchanged - call `apply` as many times as needed.
+   *
+   * @param value - The starting value. Plain `number` is coerced via `ArbitraryNumber.from`.
+   * @throws `"ArbitraryNumber.from: value must be finite"` when a plain `number` is non-finite.
+   * @example
+   * const damage = damageFormula.apply(baseDamage);
+   * const scaled = damageFormula.apply(boostedBase);
+   */
+  apply(value) {
+    let result = value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
+    for (const step of this.steps) {
+      result = step(result);
+    }
+    return result;
+  }
+};
+function formula(name) {
+  return new AnFormula(name, []);
+}
+
+// src/plugin/SuffixNotationBase.ts
+var SuffixNotationBase = class {
+  /**
+   * @param options - Plugin options. `separator` defaults to `""`.
+   */
+  constructor(options = { separator: "" }) {
+    /** Lookup for remainder values 0, 1, 2 (exponent mod 3). */
+    this.displayScale = [1, 10, 100];
+    this.separator = options.separator ?? "";
+  }
+  /**
+   * Formats the number by combining the scaled coefficient with the suffix returned
+   * by {@link getSuffix}. When `getSuffix` returns an empty string, the separator is
+   * omitted and only the plain value is returned.
+   *
+   * @param coefficient - The significand in `[1, 10)` or `0`.
+   * @param exponent - The power of 10.
+   * @param decimals - Number of decimal places in the output.
+   * @returns The formatted string.
+   */
+  format(coefficient, exponent, decimals) {
+    if (exponent < 0) {
+      return (coefficient * Math.pow(10, exponent)).toFixed(decimals);
+    }
+    const tier = Math.floor(exponent / 3);
+    const remainder = exponent - tier * 3;
+    const displayC = coefficient * this.displayScale[remainder];
+    const suffix = this.getSuffix(tier);
+    if (!suffix) return displayC.toFixed(decimals);
+    return `${displayC.toFixed(decimals)}${this.separator}${suffix}`;
+  }
+};
+
+// src/plugin/AlphabetNotation.ts
+function alphabetSuffix(tier, alphabet = "abcdefghijklmnopqrstuvwxyz") {
+  if (alphabet.length === 0) throw new ArbitraryNumberInputError("alphabet must not be empty", alphabet);
+  if (tier <= 0) return "";
+  const index = tier - 1;
+  let length = 1;
+  let capacity = alphabet.length;
+  let offset = 0;
+  while (index >= offset + capacity) {
+    offset += capacity;
+    length++;
+    capacity = alphabet.length ** length;
+  }
+  let remaining = index - offset;
+  const chars = new Array(length);
+  for (let i = length - 1; i >= 0; i--) {
+    chars[i] = alphabet[remaining % alphabet.length];
+    remaining = Math.floor(remaining / alphabet.length);
+  }
+  return chars.join("");
+}
+var AlphabetNotation = class extends SuffixNotationBase {
+  /**
+   * @param options - Plugin options. `alphabet` defaults to `"abcdefghijklmnopqrstuvwxyz"`.
+   *   `separator` defaults to `""` (no space between the number and suffix).
+   */
+  constructor(options = {}) {
+    super(options);
+    this.defaultSuffix = "";
+    this.suffixCache = /* @__PURE__ */ new Map();
+    this.alphabet = options.alphabet ?? "abcdefghijklmnopqrstuvwxyz";
+  }
+  /**
+   * Returns the suffix label for the given tier.
+   *
+   * Tier 0 returns `""` - no suffix for values below 10^3.
+   * Tier 1 -> first alphabet symbol, tier N -> last, tier N+1 -> first two-symbol combination.
+   *
+   * Results are cached after the first call per tier.
+   *
+   * @param tier - The exponent tier (`floor(exponent / 3)`), >= 0.
+   * @returns The suffix string, or `""` for tier 0.
+   */
+  getSuffix(tier) {
+    if (tier === 0) {
+      return this.defaultSuffix;
+    }
+    const cached = this.suffixCache.get(tier);
+    if (cached !== void 0) return cached;
+    const result = alphabetSuffix(tier, this.alphabet);
+    this.suffixCache.set(tier, result);
+    return result;
+  }
+};
+var letterNotation = new AlphabetNotation();
+
+// src/constants/units.ts
+var CLASSIC_UNITS = (() => {
+  const u = [
+    void 0,
+    // tier  0: exponent  0-2  (no unit)
+    { symbol: "K", name: "Thousand" },
+    // tier  1: exponent  3
+    { symbol: "M", name: "Million" },
+    // tier  2: exponent  6
+    { symbol: "B", name: "Billion" },
+    // tier  3: exponent  9
+    { symbol: "T", name: "Trillion" },
+    // tier  4: exponent 12
+    { symbol: "Qa", name: "Quadrillion" },
+    // tier  5: exponent 15
+    { symbol: "Qi", name: "Quintillion" },
+    // tier  6: exponent 18
+    { symbol: "Sx", name: "Sextillion" },
+    // tier  7: exponent 21
+    { symbol: "Sp", name: "Septillion" },
+    // tier  8: exponent 24
+    { symbol: "Oc", name: "Octillion" },
+    // tier  9: exponent 27
+    { symbol: "No", name: "Nonillion" },
+    // tier 10: exponent 30
+    { symbol: "Dc", name: "Decillion" },
+    // tier 11: exponent 33
+    { symbol: "UDc", name: "Undecillion" },
+    // tier 12: exponent 36
+    { symbol: "DDc", name: "Duodecillion" },
+    // tier 13: exponent 39
+    { symbol: "TDc", name: "Tredecillion" },
+    // tier 14: exponent 42
+    { symbol: "QaDc", name: "Quattuordecillion" },
+    // tier 15: exponent 45
+    { symbol: "QiDc", name: "Quindecillion" },
+    // tier 16: exponent 48
+    { symbol: "SxDc", name: "Sexdecillion" },
+    // tier 17: exponent 51
+    { symbol: "SpDc", name: "Septendecillion" },
+    // tier 18: exponent 54
+    { symbol: "OcDc", name: "Octodecillion" },
+    // tier 19: exponent 57
+    { symbol: "NoDc", name: "Novemdecillion" },
+    // tier 20: exponent 60
+    { symbol: "Vg", name: "Vigintillion" },
+    // tier 21: exponent 63
+    { symbol: "UVg", name: "Unvigintillion" },
+    // tier 22: exponent 66
+    { symbol: "DVg", name: "Duovigintillion" },
+    // tier 23: exponent 69
+    { symbol: "TVg", name: "Trevigintillion" },
+    // tier 24: exponent 72
+    { symbol: "QaVg", name: "Quattuorvigintillion" },
+    // tier 25: exponent 75
+    { symbol: "QiVg", name: "Quinvigintillion" },
+    // tier 26: exponent 78
+    { symbol: "SxVg", name: "Sexvigintillion" },
+    // tier 27: exponent 81
+    { symbol: "SpVg", name: "Septenvigintillion" },
+    // tier 28: exponent 84
+    { symbol: "OcVg", name: "Octovigintillion" },
+    // tier 29: exponent 87
+    { symbol: "NoVg", name: "Novemvigintillion" },
+    // tier 30: exponent 90
+    { symbol: "Tg", name: "Trigintillion" },
+    // tier 31: exponent 93
+    { symbol: "UTg", name: "Untrigintillion" },
+    // tier 32: exponent 96
+    { symbol: "DTg", name: "Duotrigintillion" }
+    // tier 33: exponent 99
+    // tiers 34-100: undefined - fallback fires for these exponents
+  ];
+  u[101] = { symbol: "Ct", name: "Centillion" };
+  return Object.freeze(u);
+})();
+var COMPACT_UNITS = Object.freeze([
+  void 0,
+  // tier  0: exponent 0-2  (no unit)
+  { symbol: "k" },
+  // tier  1: exponent  3
+  { symbol: "M" },
+  // tier  2: exponent  6
+  { symbol: "B" },
+  // tier  3: exponent  9
+  { symbol: "T" },
+  // tier  4: exponent 12
+  { symbol: "Qa" },
+  // tier  5: exponent 15
+  { symbol: "Qi" },
+  // tier  6: exponent 18
+  { symbol: "Sx" },
+  // tier  7: exponent 21
+  { symbol: "Sp" },
+  // tier  8: exponent 24
+  { symbol: "Oc" },
+  // tier  9: exponent 27
+  { symbol: "No" }
+  // tier 10: exponent 30
+]);
+
+// src/plugin/UnitNotation.ts
+var UnitNotation = class extends SuffixNotationBase {
+  /**
+   * @param options - Tier-indexed unit array, optional suffix fallback plugin, and separator.
+   *   `separator` defaults to `" "` (a space between number and unit symbol).
+   */
+  constructor(options) {
+    super({ separator: " ", ...options });
+    this.units = options.units;
+    this.fallback = options.fallback;
+  }
+  /**
+   * Returns the suffix for the given tier: the own unit symbol if defined,
+   * otherwise the fallback's suffix, otherwise `""`.
+   *
+   * @param tier - The exponent tier (`Math.floor(exponent / 3)`).
+   * @returns The suffix string, or `""` if neither own units nor fallback cover this tier.
+   */
+  getSuffix(tier) {
+    return this.units[tier]?.symbol ?? this.fallback?.getSuffix(tier) ?? "";
+  }
+};
+var unitNotation = new UnitNotation({
+  units: CLASSIC_UNITS,
+  fallback: letterNotation
+});
+
+// src/utility/ArbitraryNumberGuard.ts
+var ArbitraryNumberGuard = class _ArbitraryNumberGuard {
+  /**
+   * Returns `true` if `obj` is an instance of {@link ArbitraryNumber}.
+   *
+   * @param obj - The value to test.
+   * @returns `true` when `obj instanceof ArbitraryNumber`.
+   */
+  static isArbitraryNumber(obj) {
+    return obj instanceof ArbitraryNumber;
+  }
+  /**
+   * Returns `true` if `obj` has the shape of a {@link NormalizedNumber}
+   * (i.e. has numeric `coefficient` and `exponent` properties).
+   *
+   * Note: both `ArbitraryNumber` instances and plain objects with the right
+   * shape will pass this check. Use {@link isArbitraryNumber} when you need
+   * to distinguish between the two.
+   *
+   * @param obj - The value to test.
+   * @returns `true` when `obj` has `typeof coefficient === "number"` and
+   *   `typeof exponent === "number"`.
+   */
+  static isNormalizedNumber(obj) {
+    return obj != null && typeof obj?.coefficient === "number" && typeof obj?.exponent === "number";
+  }
+  /**
+   * Returns `true` if `obj` is an {@link ArbitraryNumber} with a value of zero.
+   *
+   * @param obj - The value to test.
+   * @returns `true` when `obj` is an `ArbitraryNumber` and its `coefficient` is `0`.
+   */
+  static isZero(obj) {
+    return _ArbitraryNumberGuard.isArbitraryNumber(obj) && obj.coefficient === 0;
+  }
+};
+
+// src/utility/ArbitraryNumberOps.ts
+var ArbitraryNumberOps = class _ArbitraryNumberOps {
+  /**
+   * Converts `value` to an `ArbitraryNumber`, returning it unchanged if it already is one.
+   *
+   * @param value - A plain `number` or an existing `ArbitraryNumber`.
+   * @returns The corresponding `ArbitraryNumber`.
+   */
+  static from(value) {
+    return value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
+  }
+  /**
+   * Returns `left + right`, coercing both operands as needed.
+   *
+   * @param left - The augend.
+   * @param right - The addend.
+   * @example
+   * ops.add(1500, 2500) // ArbitraryNumber (4000)
+   */
+  static add(left, right) {
+    return _ArbitraryNumberOps.from(left).add(_ArbitraryNumberOps.from(right));
+  }
+  /**
+   * Returns `left - right`, coercing both operands as needed.
+   *
+   * @param left - The minuend.
+   * @param right - The subtrahend.
+   * @example
+   * ops.sub(5000, 1500) // ArbitraryNumber (3500)
+   */
+  static sub(left, right) {
+    return _ArbitraryNumberOps.from(left).sub(_ArbitraryNumberOps.from(right));
+  }
+  /**
+   * Returns `left * right`, coercing both operands as needed.
+   *
+   * @param left - The multiplicand.
+   * @param right - The multiplier.
+   * @example
+   * ops.mul(an(1, 3), 5) // ArbitraryNumber (5000)
+   */
+  static mul(left, right) {
+    return _ArbitraryNumberOps.from(left).mul(_ArbitraryNumberOps.from(right));
+  }
+  /**
+   * Returns `left / right`, coercing both operands as needed.
+   *
+   * @param left - The dividend.
+   * @param right - The divisor.
+   * @throws `"Division by zero"` when `right` is zero.
+   * @example
+   * ops.div(an(1, 6), 1000) // ArbitraryNumber (1000)
+   */
+  static div(left, right) {
+    return _ArbitraryNumberOps.from(left).div(_ArbitraryNumberOps.from(right));
+  }
+  /**
+   * Compares `left` to `right`.
+   *
+   * @param left - The left operand.
+   * @param right - The right operand.
+   * @returns `1` if `left > right`, `-1` if `left < right`, `0` if equal.
+   * @example
+   * ops.compare(5000, 1500) // 1
+   */
+  static compare(left, right) {
+    return _ArbitraryNumberOps.from(left).compareTo(_ArbitraryNumberOps.from(right));
+  }
+  /**
+   * Clamps `value` to the inclusive range `[min, max]`, coercing all inputs as needed.
+   *
+   * @param value - The value to clamp.
+   * @param min - The lower bound (inclusive).
+   * @param max - The upper bound (inclusive).
+   * @example
+   * ops.clamp(500, 1000, 2000) // ArbitraryNumber (1000)  - below min, returns min
+   */
+  static clamp(value, min, max) {
+    return ArbitraryNumber.clamp(
+      _ArbitraryNumberOps.from(value),
+      _ArbitraryNumberOps.from(min),
+      _ArbitraryNumberOps.from(max)
+    );
+  }
+};
+
+// src/utility/ArbitraryNumberHelpers.ts
+var ArbitraryNumberHelpers = class _ArbitraryNumberHelpers {
+  static coerce(value) {
+    return ArbitraryNumberOps.from(value);
+  }
+  /**
+   * Returns `true` when `value >= threshold`.
+   *
+   * @param value - The value to test.
+   * @param threshold - The minimum required value.
+   * @returns `true` when `value >= threshold`.
+   * @example
+   * ArbitraryNumberHelpers.meetsOrExceeds(gold, upgradeCost)
+   */
+  static meetsOrExceeds(value, threshold) {
+    return _ArbitraryNumberHelpers.coerce(value).greaterThanOrEqual(_ArbitraryNumberHelpers.coerce(threshold));
+  }
+  /**
+   * Returns the largest whole multiple count of `step` that fits into `total`.
+   *
+   * Equivalent to `floor(total / step)`.
+   *
+   * @param total - The total available amount.
+   * @param step - The cost or size of one unit. Must be greater than zero.
+   * @returns The number of whole units that fit, as an `ArbitraryNumber`.
+   * @throws `"step must be greater than zero"` when `step <= 0`.
+   * @example
+   * const canBuy = ArbitraryNumberHelpers.wholeMultipleCount(gold, upgradeCost);
+   */
+  static wholeMultipleCount(total, step) {
+    const numTotal = _ArbitraryNumberHelpers.coerce(total);
+    const numStep = _ArbitraryNumberHelpers.coerce(step);
+    if (numStep.lessThanOrEqual(ArbitraryNumber.Zero)) {
+      throw new ArbitraryNumberInputError("step must be greater than zero", numStep.toNumber());
+    }
+    if (numTotal.lessThanOrEqual(ArbitraryNumber.Zero)) {
+      return ArbitraryNumber.Zero;
+    }
+    return numTotal.div(numStep).floor();
+  }
+  /**
+   * Returns `value - delta`, clamped to a minimum of `floor` (default `0`).
+   *
+   * @param value - The starting value.
+   * @param delta - The amount to subtract.
+   * @param floor - The minimum result. Defaults to `ArbitraryNumber.Zero`.
+   * @returns `max(value - delta, floor)`.
+   * @example
+   * health = ArbitraryNumberHelpers.subtractWithFloor(health, damage);
+   */
+  static subtractWithFloor(value, delta, floor = ArbitraryNumber.Zero) {
+    const numValue = _ArbitraryNumberHelpers.coerce(value);
+    const numDelta = _ArbitraryNumberHelpers.coerce(delta);
+    const numFloor = _ArbitraryNumberHelpers.coerce(floor);
+    return ArbitraryNumber.clamp(numValue.sub(numDelta), numFloor, numValue);
+  }
+};
+
+export { AlphabetNotation, AnChain, AnFormula, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, ArbitraryNumberOps, CLASSIC_UNITS, COMPACT_UNITS, ScientificNotation, SuffixNotationBase, UnitNotation, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map