arbitrary-numbers 1.0.2 → 1.1.0

package/dist/index.js

@@ -9,9 +9,17 @@ var ScientificNotation = class {
    * @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)}`;
+    let c = coefficient;
+    let e = exponent;
+    let fixed = c.toFixed(decimals);
+    if (Math.abs(parseFloat(fixed)) >= 10) {
+      c = c / 10;
+      e = e + 1;
+      fixed = c.toFixed(decimals);
+    }
+    if (e === 0) return fixed;
+    const sign = e < 0 ? "-" : "+";
+    return `${fixed}e${sign}${Math.abs(e)}`;
   }
 };
 var scientificNotation = new ScientificNotation();
@@ -38,6 +46,9 @@ var POW10 = [
 function pow10(n) {
   return n >= 0 && n < 16 ? POW10[n] : Math.pow(10, n);
 }
+function pow10Int(n) {
+  return n >= 0 && n < 16 ? POW10[n] : Math.pow(10, n);
+}
 
 // src/errors.ts
 var ArbitraryNumberError = class extends Error {
@@ -74,8 +85,9 @@ var _ArbitraryNumber = class _ArbitraryNumber {
    * ArbitraryNumber.from(1500);   // { coefficient: 1.5, exponent: 3 }
    * ArbitraryNumber.from(0.005);  // { coefficient: 5,   exponent: -3 }
    * ArbitraryNumber.from(0);      // ArbitraryNumber.Zero
+   * ArbitraryNumber.from(-0);     // ArbitraryNumber.Zero  (signed zero is normalised to +0)
    *
-   * @param value - Any finite number.
+   * @param value - Any finite number. Signed zero (`-0`) is treated as `0`.
    * @throws `"ArbitraryNumber.from: value must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
    */
   static from(value) {
@@ -127,19 +139,14 @@ var _ArbitraryNumber = class _ArbitraryNumber {
    * Do NOT use for unnormalised inputs - call new ArbitraryNumber(c, e) instead.
    */
   static createNormalized(coefficient, exponent) {
+    if (typeof process !== "undefined" && process.env["NODE_ENV"] !== "production" && coefficient === 0 && exponent !== 0) {
+      console.warn(`ArbitraryNumber.createNormalized: zero coefficient with non-zero exponent (${exponent}). Use ArbitraryNumber.Zero instead.`);
+    }
     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);
@@ -160,16 +167,17 @@ var _ArbitraryNumber = class _ArbitraryNumber {
   add(other) {
     if (this.coefficient === 0) return other;
     if (other.coefficient === 0) return this;
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     const diff = this.exponent - other.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return other;
+    if (diff > cutoff) return this;
+    if (diff < -cutoff) return other;
     let c;
     let e;
     if (diff >= 0) {
-      c = this.coefficient + other.coefficient / pow10(diff);
+      c = this.coefficient + other.coefficient / pow10Int(diff);
       e = this.exponent;
     } else {
-      c = other.coefficient + this.coefficient / pow10(-diff);
+      c = other.coefficient + this.coefficient / pow10Int(-diff);
       e = other.exponent;
     }
     return _ArbitraryNumber.normalizeFrom(c, e);
@@ -184,16 +192,17 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     if (other.coefficient === 0) return this;
     const negC = -other.coefficient;
     if (this.coefficient === 0) return _ArbitraryNumber.createNormalized(negC, other.exponent);
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     const diff = this.exponent - other.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return this;
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(negC, other.exponent);
+    if (diff > cutoff) return this;
+    if (diff < -cutoff) return _ArbitraryNumber.createNormalized(negC, other.exponent);
     let c;
     let e;
     if (diff >= 0) {
-      c = this.coefficient + negC / pow10(diff);
+      c = this.coefficient + negC / pow10Int(diff);
       e = this.exponent;
     } else {
-      c = negC + this.coefficient / pow10(-diff);
+      c = negC + this.coefficient / pow10Int(-diff);
       e = other.exponent;
     }
     return _ArbitraryNumber.normalizeFrom(c, e);
@@ -307,15 +316,16 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       ep += 1;
     }
     if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     const diff = ep - addend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    if (diff > cutoff) return _ArbitraryNumber.createNormalized(cp, ep);
+    if (diff < -cutoff) return addend;
     let c, e;
     if (diff >= 0) {
-      c = cp + addend.coefficient / pow10(diff);
+      c = cp + addend.coefficient / pow10Int(diff);
       e = ep;
     } else {
-      c = addend.coefficient + cp / pow10(-diff);
+      c = addend.coefficient + cp / pow10Int(-diff);
       e = addend.exponent;
     }
     return _ArbitraryNumber.normalizeFrom(c, e);
@@ -343,19 +353,20 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       cs = this.coefficient;
       es = this.exponent;
     } else {
+      const cutoff = _ArbitraryNumber.PrecisionCutoff;
       const diff = this.exponent - addend.exponent;
-      if (diff > _ArbitraryNumber.PrecisionCutoff) {
+      if (diff > cutoff) {
         cs = this.coefficient;
         es = this.exponent;
-      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+      } else if (diff < -cutoff) {
         cs = addend.coefficient;
         es = addend.exponent;
       } else {
         if (diff >= 0) {
-          cs = this.coefficient + addend.coefficient / pow10(diff);
+          cs = this.coefficient + addend.coefficient / pow10Int(diff);
           es = this.exponent;
         } else {
-          cs = addend.coefficient + this.coefficient / pow10(-diff);
+          cs = addend.coefficient + this.coefficient / pow10Int(-diff);
           es = addend.exponent;
         }
         if (cs === 0) return _ArbitraryNumber.Zero;
@@ -396,17 +407,18 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       ep += 1;
     }
     if (subtrahend.coefficient === 0) return _ArbitraryNumber.createNormalized(cp, ep);
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     const diff = ep - subtrahend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cp, ep);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+    if (diff > cutoff) return _ArbitraryNumber.createNormalized(cp, ep);
+    if (diff < -cutoff) {
       return _ArbitraryNumber.createNormalized(-subtrahend.coefficient, subtrahend.exponent);
     }
     let c, e;
     if (diff >= 0) {
-      c = cp - subtrahend.coefficient / pow10(diff);
+      c = cp - subtrahend.coefficient / pow10Int(diff);
       e = ep;
     } else {
-      c = -subtrahend.coefficient + cp / pow10(-diff);
+      c = -subtrahend.coefficient + cp / pow10Int(-diff);
       e = subtrahend.exponent;
     }
     return _ArbitraryNumber.normalizeFrom(c, e);
@@ -429,19 +441,20 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       cs = this.coefficient;
       es = this.exponent;
     } else {
+      const cutoff = _ArbitraryNumber.PrecisionCutoff;
       const diff = this.exponent - subtrahend.exponent;
-      if (diff > _ArbitraryNumber.PrecisionCutoff) {
+      if (diff > cutoff) {
         cs = this.coefficient;
         es = this.exponent;
-      } else if (diff < -_ArbitraryNumber.PrecisionCutoff) {
+      } else if (diff < -cutoff) {
         cs = -subtrahend.coefficient;
         es = subtrahend.exponent;
       } else {
         if (diff >= 0) {
-          cs = this.coefficient - subtrahend.coefficient / pow10(diff);
+          cs = this.coefficient - subtrahend.coefficient / pow10Int(diff);
           es = this.exponent;
         } else {
-          cs = -subtrahend.coefficient + this.coefficient / pow10(-diff);
+          cs = -subtrahend.coefficient + this.coefficient / pow10Int(-diff);
           es = subtrahend.exponent;
         }
         if (cs === 0) return _ArbitraryNumber.Zero;
@@ -482,19 +495,44 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       ed -= 1;
     }
     if (addend.coefficient === 0) return _ArbitraryNumber.createNormalized(cd, ed);
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     const diff = ed - addend.exponent;
-    if (diff > _ArbitraryNumber.PrecisionCutoff) return _ArbitraryNumber.createNormalized(cd, ed);
-    if (diff < -_ArbitraryNumber.PrecisionCutoff) return addend;
+    if (diff > cutoff) return _ArbitraryNumber.createNormalized(cd, ed);
+    if (diff < -cutoff) return addend;
     let c, e;
     if (diff >= 0) {
-      c = cd + addend.coefficient / pow10(diff);
+      c = cd + addend.coefficient / pow10Int(diff);
       e = ed;
     } else {
-      c = addend.coefficient + cd / pow10(-diff);
+      c = addend.coefficient + cd / pow10Int(-diff);
       e = addend.exponent;
     }
     return _ArbitraryNumber.normalizeFrom(c, e);
   }
+  /**
+   * Fused multiply-divide: `(this * multiplier) / divisor`.
+   *
+   * Avoids one intermediate allocation vs `.mul(multiplier).div(divisor)`.
+   * The divisor zero-check is performed before the multiply to avoid unnecessary work.
+   *
+   * Common pattern - idle-tick math: `(production * deltaTime) / cost`
+   *
+   * @example
+   * // Equivalent to production.mul(deltaTime).div(cost) but ~30-40% faster
+   * const consumed = production.mulDiv(deltaTime, cost);
+   *
+   * @throws `"Division by zero"` when divisor is zero.
+   */
+  mulDiv(multiplier, divisor) {
+    if (divisor.coefficient === 0) throw new ArbitraryNumberDomainError("Division by zero", { dividend: this.toNumber(), divisor: 0 });
+    if (this.coefficient === 0 || multiplier.coefficient === 0) return _ArbitraryNumber.Zero;
+    const c = this.coefficient * multiplier.coefficient / divisor.coefficient;
+    const e = this.exponent + multiplier.exponent - divisor.exponent;
+    const absC = c < 0 ? -c : c;
+    if (absC >= 10) return _ArbitraryNumber.createNormalized(c / 10, e + 1);
+    if (absC < 1) return _ArbitraryNumber.createNormalized(c * 10, e - 1);
+    return _ArbitraryNumber.createNormalized(c, e);
+  }
   /**
    * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
    *
@@ -521,13 +559,14 @@ var _ArbitraryNumber = class _ArbitraryNumber {
       const n = numbers[i];
       if (n.exponent > pivotExp) pivotExp = n.exponent;
     }
+    const cutoff = _ArbitraryNumber.PrecisionCutoff;
     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 (diff > cutoff) continue;
+      total += n.coefficient / pow10Int(diff);
     }
     if (total === 0) return _ArbitraryNumber.Zero;
     const abs = Math.abs(total);
@@ -536,6 +575,69 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     if (scale === 0) return _ArbitraryNumber.Zero;
     return _ArbitraryNumber.createNormalized(total / scale, pivotExp + shift);
   }
+  /**
+   * Multiplies an array of `ArbitraryNumber`s in a single pass.
+   *
+   * Coefficients are multiplied together with intermediate normalisation after each step
+   * to keep values in [1, 10). Exponents are summed. One total normalisation at the end.
+   *
+   * Empty array returns {@link One}. Single element returned as-is.
+   *
+   * @example
+   * ArbitraryNumber.productArray([an(2), an(3), an(4)]); // 24
+   */
+  static productArray(numbers) {
+    const len = numbers.length;
+    if (len === 0) return _ArbitraryNumber.One;
+    if (len === 1) return numbers[0];
+    let c = 1;
+    let e = 0;
+    for (let i = 0; i < len; i++) {
+      const n = numbers[i];
+      if (n.coefficient === 0) return _ArbitraryNumber.Zero;
+      c *= n.coefficient;
+      e += n.exponent;
+      if (c >= 10 || c <= -10) {
+        const absC = c < 0 ? -c : c;
+        const shift = Math.floor(Math.log10(absC));
+        c /= pow10(shift);
+        e += shift;
+      }
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Returns the largest value in an array.
+   *
+   * Empty array returns {@link Zero}. Single element returned as-is.
+   *
+   * @example
+   * ArbitraryNumber.maxOfArray([an(1), an(3), an(2)]); // an(3)
+   */
+  static maxOfArray(numbers) {
+    if (numbers.length === 0) return _ArbitraryNumber.Zero;
+    let max = numbers[0];
+    for (let i = 1; i < numbers.length; i++) {
+      if (numbers[i].greaterThan(max)) max = numbers[i];
+    }
+    return max;
+  }
+  /**
+   * Returns the smallest value in an array.
+   *
+   * Empty array returns {@link Zero}. Single element returned as-is.
+   *
+   * @example
+   * ArbitraryNumber.minOfArray([an(3), an(1), an(2)]); // an(1)
+   */
+  static minOfArray(numbers) {
+    if (numbers.length === 0) return _ArbitraryNumber.Zero;
+    let min = numbers[0];
+    for (let i = 1; i < numbers.length; i++) {
+      if (numbers[i].lessThan(min)) min = numbers[i];
+    }
+    return min;
+  }
   /**
    * Compares this number to `other`.
    *
@@ -730,6 +832,84 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     }
     return _ArbitraryNumber.createNormalized(Math.sqrt(this.coefficient), this.exponent / 2);
   }
+  /**
+   * Returns the cube root of this number: `∛this`.
+   *
+   * Computed without `Math.log10`. For exponents divisible by 3: `cbrt(c) * 10^(e/3)`.
+   * For remainder 1: `cbrt(c * 10) * 10^((e-1)/3)`.
+   * For remainder 2: `cbrt(c * 100) * 10^((e-2)/3)`.
+   *
+   * Supports negative numbers (cube root of a negative is negative).
+   *
+   * @example
+   * new ArbitraryNumber(8, 0).cbrt();   // 2
+   * new ArbitraryNumber(1, 9).cbrt();   // 1*10^3  (= 1,000)
+   * new ArbitraryNumber(-8, 0).cbrt();  // -2
+   */
+  cbrt() {
+    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
+    const rem = (this.exponent % 3 + 3) % 3;
+    const baseExp = (this.exponent - rem) / 3;
+    if (rem === 0) return _ArbitraryNumber.createNormalized(Math.cbrt(this.coefficient), baseExp);
+    if (rem === 1) return _ArbitraryNumber.createNormalized(Math.cbrt(this.coefficient * 10), baseExp);
+    return _ArbitraryNumber.createNormalized(Math.cbrt(this.coefficient * 100), baseExp);
+  }
+  /**
+   * Returns `log_base(this)` as a plain JavaScript `number`.
+   *
+   * Computed as `log10(this) / log10(base)`. The numerator is exact due to the
+   * stored `coefficient × 10^exponent` form.
+   *
+   * @param base - The logarithm base. Must be positive and not 1.
+   * @throws `"Logarithm of zero is undefined"` when this is zero.
+   * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+   * @throws `"Logarithm base must be positive and not 1"` for invalid base.
+   *
+   * @example
+   * new ArbitraryNumber(8, 0).log(2);    // 3
+   * new ArbitraryNumber(1, 6).log(10);   // 6
+   */
+  log(base) {
+    if (base <= 0 || base === 1 || !isFinite(base)) {
+      throw new ArbitraryNumberDomainError("Logarithm base must be positive and not 1", { base });
+    }
+    return this.log10() / Math.log10(base);
+  }
+  /**
+   * Returns `ln(this)` — the natural logarithm — as a plain JavaScript `number`.
+   *
+   * Computed as `log10(this) / log10(e)`.
+   *
+   * @throws `"Logarithm of zero is undefined"` when this is zero.
+   * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+   *
+   * @example
+   * new ArbitraryNumber(1, 0).ln();  // 0
+   */
+  ln() {
+    return this.log10() / Math.LOG10E;
+  }
+  /**
+   * Returns `10^n` as an `ArbitraryNumber`, where `n` is a plain JS `number`.
+   *
+   * This is the inverse of {@link log10}. Useful for converting a log10 result
+   * back into an `ArbitraryNumber`.
+   *
+   * @example
+   * ArbitraryNumber.exp10(6);    // 1*10^6  (= 1,000,000)
+   * ArbitraryNumber.exp10(3.5);  // 10^3.5 ≈ 3162.3
+   *
+   * @throws `"ArbitraryNumber.exp10: n must be finite"` for non-finite `n`.
+   */
+  static exp10(n) {
+    if (!isFinite(n)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.exp10: n must be finite", n);
+    }
+    const intPart = Math.floor(n);
+    const fracPart = n - intPart;
+    const c = Math.pow(10, fracPart);
+    return _ArbitraryNumber.createNormalized(c, intPart);
+  }
   /**
    * Returns the nearest integer value (rounds half-up).
    *
@@ -751,6 +931,25 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     }
     return new _ArbitraryNumber(Math.round(this.coefficient * pow10(this.exponent)), 0);
   }
+  /**
+   * Returns the integer part of this number, truncating toward zero.
+   *
+   * Unlike `floor()`, which rounds toward −∞, `trunc()` always rounds toward 0:
+   * - `trunc(1.7)  = 1`  (same as floor)
+   * - `trunc(-1.7) = -1` (different from floor, which gives -2)
+   *
+   * Numbers with `exponent >= PrecisionCutoff` are already integers and returned unchanged.
+   *
+   * @example
+   * new ArbitraryNumber(1.7, 0).trunc();   //  1
+   * new ArbitraryNumber(-1.7, 0).trunc();  // -1
+   */
+  trunc() {
+    if (this.coefficient === 0) return _ArbitraryNumber.Zero;
+    if (this.exponent >= _ArbitraryNumber.PrecisionCutoff) return this;
+    if (this.exponent < 0) return _ArbitraryNumber.Zero;
+    return new _ArbitraryNumber(Math.trunc(this.coefficient * pow10(this.exponent)), 0);
+  }
   /**
    * Returns `1` if positive, `-1` if negative, `0` if zero.
    *
@@ -776,6 +975,95 @@ var _ArbitraryNumber = class _ArbitraryNumber {
   toNumber() {
     return this.coefficient * pow10(this.exponent);
   }
+  /**
+   * Returns a stable, minimal JSON representation: `{ c: number, e: number }`.
+   *
+   * The keys `c` and `e` are intentionally short to keep save-game blobs small.
+   * Reconstruct via {@link ArbitraryNumber.fromJSON}.
+   *
+   * Round-trip guarantee: `ArbitraryNumber.fromJSON(x.toJSON()).equals(x)` is always `true`.
+   *
+   * @example
+   * JSON.stringify(an(1.5, 6)); // '{"c":1.5,"e":6}'
+   */
+  toJSON() {
+    return { c: this.coefficient, e: this.exponent };
+  }
+  /**
+   * Returns a raw string representation: `"<coefficient>|<exponent>"`.
+   *
+   * Useful for compact textual serialization. Reconstruct via {@link ArbitraryNumber.parse}.
+   *
+   * @example
+   * an(1.5, 3).toRaw();  // "1.5|3"
+   * an(-2, 6).toRaw();   // "-2|6"
+   */
+  toRaw() {
+    return `${this.coefficient}|${this.exponent}`;
+  }
+  /**
+   * Reconstructs an `ArbitraryNumber` from a `toJSON()` blob.
+   *
+   * @example
+   * const n = an(1.5, 6);
+   * ArbitraryNumber.fromJSON(n.toJSON()).equals(n); // true
+   *
+   * @param obj - Object with numeric `c` (coefficient) and `e` (exponent) fields.
+   * @throws `ArbitraryNumberInputError` when the object shape is invalid or values are non-finite.
+   */
+  static fromJSON(obj) {
+    if (obj === null || typeof obj !== "object" || !("c" in obj) || !("e" in obj) || typeof obj.c !== "number" || typeof obj.e !== "number") {
+      throw new ArbitraryNumberInputError(
+        "ArbitraryNumber.fromJSON: expected { c: number, e: number }",
+        String(obj)
+      );
+    }
+    const { c, e } = obj;
+    if (!isFinite(c)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.fromJSON: c must be finite", c);
+    }
+    if (!isFinite(e)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.fromJSON: e must be finite", e);
+    }
+    return _ArbitraryNumber.normalizeFrom(c, e);
+  }
+  /**
+   * Parses a string into an `ArbitraryNumber`.
+   *
+   * Accepted formats:
+   * - Raw pipe format (exact round-trip): `"1.5|3"`, `"-2.5|-6"`
+   * - Standard scientific notation: `"1.5e+3"`, `"1.5e-3"`, `"1.5E3"`, `"1.5e3"`
+   * - Plain decimal: `"1500"`, `"-0.003"`, `"0"`
+   *
+   * @example
+   * ArbitraryNumber.parse("1.5|3");    // same as an(1.5, 3)
+   * ArbitraryNumber.parse("1.5e+3");   // same as ArbitraryNumber.from(1500)
+   * ArbitraryNumber.parse("1500");     // same as ArbitraryNumber.from(1500)
+   *
+   * @throws `ArbitraryNumberInputError` when the string cannot be parsed or produces a non-finite value.
+   */
+  static parse(s) {
+    if (typeof s !== "string" || s.trim() === "") {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.parse: input must be a non-empty string", s);
+    }
+    const trimmed = s.trim();
+    const pipeIdx = trimmed.indexOf("|");
+    if (pipeIdx !== -1) {
+      const cStr = trimmed.slice(0, pipeIdx);
+      const eStr = trimmed.slice(pipeIdx + 1);
+      const c = Number(cStr);
+      const e = Number(eStr);
+      if (!isFinite(c) || !isFinite(e) || cStr === "" || eStr === "") {
+        throw new ArbitraryNumberInputError("ArbitraryNumber.parse: invalid pipe format", s);
+      }
+      return _ArbitraryNumber.normalizeFrom(c, e);
+    }
+    const n = Number(trimmed);
+    if (!isFinite(n)) {
+      throw new ArbitraryNumberInputError("ArbitraryNumber.parse: value is not finite", s);
+    }
+    return new _ArbitraryNumber(n, 0);
+  }
   /** Returns `true` when this number is zero. */
   isZero() {
     return this.coefficient === 0;
@@ -798,6 +1086,22 @@ var _ArbitraryNumber = class _ArbitraryNumber {
     if (this.exponent < 0) return false;
     return Number.isInteger(this.coefficient * pow10(this.exponent));
   }
+  /**
+   * Allows implicit coercion via `+an(1500)` (returns `toNumber()`) and
+   * template literals / string concatenation (returns `toString()`).
+   *
+   * `hint === "number"` → `toNumber()`; all other hints → `toString()`.
+   */
+  [Symbol.toPrimitive](hint) {
+    return hint === "number" ? this.toNumber() : this.toString();
+  }
+  /**
+   * Custom Node.js inspect output so `console.log(an(1500))` renders `"1.50e+3"`
+   * instead of the raw object representation.
+   */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
   /**
    * Formats this number as a string using the given notation plugin.
    *
@@ -1103,7 +1407,7 @@ var SuffixNotationBase = class {
    */
   format(coefficient, exponent, decimals) {
     if (exponent < 0) {
-      return (coefficient * Math.pow(10, exponent)).toFixed(decimals);
+      return (coefficient / pow10(-exponent)).toFixed(decimals);
     }
     const tier = Math.floor(exponent / 3);
     const remainder = exponent - tier * 3;
@@ -1118,6 +1422,7 @@ var SuffixNotationBase = class {
 function alphabetSuffix(tier, alphabet = "abcdefghijklmnopqrstuvwxyz") {
   if (alphabet.length === 0) throw new ArbitraryNumberInputError("alphabet must not be empty", alphabet);
   if (tier <= 0) return "";
+  if (alphabet.length === 1) return alphabet.repeat(tier);
   const index = tier - 1;
   let length = 1;
   let capacity = alphabet.length;
@@ -1276,21 +1581,40 @@ 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).
+   *   `offsetFallback` defaults to `true` — the fallback tier is offset so its suffixes
+   *   are visually distinct from any low-tier suffixes the same fallback would produce.
    */
   constructor(options) {
     super({ separator: " ", ...options });
     this.units = options.units;
     this.fallback = options.fallback;
+    this.offsetFallback = options.offsetFallback !== false;
+    let last = 0;
+    for (let i = options.units.length - 1; i >= 0; i--) {
+      if (options.units[i] !== void 0) {
+        last = i;
+        break;
+      }
+    }
+    this.lastDefinedTier = last;
   }
   /**
    * Returns the suffix for the given tier: the own unit symbol if defined,
-   * otherwise the fallback's suffix, otherwise `""`.
+   * otherwise the fallback's suffix (offset by the last defined tier when
+   * `offsetFallback` is `true`), otherwise `""`.
+   *
+   * The offset ensures fallback suffixes start at tier 1 of the fallback's sequence,
+   * avoiding visual ambiguity with low-tier suffixes from the same fallback plugin.
    *
    * @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) ?? "";
+    const ownSymbol = this.units[tier]?.symbol;
+    if (ownSymbol !== void 0) return ownSymbol;
+    if (this.fallback === void 0) return "";
+    const fallbackTier = this.offsetFallback ? tier - this.lastDefinedTier : tier;
+    return this.fallback.getSuffix(fallbackTier) ?? "";
   }
 };
 var unitNotation = new UnitNotation({
@@ -1342,10 +1666,31 @@ var ArbitraryNumberOps = class _ArbitraryNumberOps {
    *
    * @param value - A plain `number` or an existing `ArbitraryNumber`.
    * @returns The corresponding `ArbitraryNumber`.
+   * @throws `ArbitraryNumberInputError` when `value` is `NaN`, `Infinity`, or `-Infinity`.
    */
   static from(value) {
     return value instanceof ArbitraryNumber ? value : ArbitraryNumber.from(value);
   }
+  /**
+   * Converts `value` to an `ArbitraryNumber`, returning `null` for non-finite inputs
+   * instead of throwing.
+   *
+   * Use this at system boundaries (form inputs, external APIs) where you want to handle
+   * bad input gracefully rather than catching an exception.
+   *
+   * @param value - A plain `number` or an existing `ArbitraryNumber`.
+   * @returns The `ArbitraryNumber`, or `null` if the input is `NaN`, `Infinity`, or `-Infinity`.
+   *
+   * @example
+   * ops.tryFrom(1500)      // ArbitraryNumber { coefficient: 1.5, exponent: 3 }
+   * ops.tryFrom(Infinity)  // null
+   * ops.tryFrom(NaN)       // null
+   */
+  static tryFrom(value) {
+    if (value instanceof ArbitraryNumber) return value;
+    if (!isFinite(value)) return null;
+    return ArbitraryNumber.from(value);
+  }
   /**
    * Returns `left + right`, coercing both operands as needed.
    *
@@ -1475,7 +1820,8 @@ var ArbitraryNumberHelpers = class _ArbitraryNumberHelpers {
     const numValue = _ArbitraryNumberHelpers.coerce(value);
     const numDelta = _ArbitraryNumberHelpers.coerce(delta);
     const numFloor = _ArbitraryNumberHelpers.coerce(floor);
-    return ArbitraryNumber.clamp(numValue.sub(numDelta), numFloor, numValue);
+    const result = numValue.sub(numDelta);
+    return result.lessThan(numFloor) ? numFloor : result;
   }
 };