arbitrary-numbers 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -27,6 +27,44 @@ interface AnFunction {
     from(value: number): ArbitraryNumber;
 }
 
+/**
+ * A value that can be either a plain `number` or an `ArbitraryNumber`.
+ */
+type ArbitraryNumberish = ArbitraryNumber | number;
+/**
+ * A value that is either `T` or `undefined`.
+ *
+ * Use for genuinely optional values where the absence is meaningful
+ * (e.g. optional names, optional fallback plugins).
+ *
+ * @example
+ * let label: Maybe<string>;   // string | undefined
+ */
+type Maybe<T> = T | undefined;
+/**
+ * A value that is either `T` or `null`.
+ *
+ * Use for explicit "no result" returns from functions that would otherwise throw
+ * (e.g. `tryFrom` at system boundaries where bad input should be handled gracefully).
+ *
+ * @example
+ * function parse(s: string): Nullable<ArbitraryNumber> { ... }
+ */
+type Nullable<T> = T | null;
+/**
+ * A stable, compact JSON representation of an {@link ArbitraryNumber}.
+ *
+ * Keys are intentionally short (`c`/`e`) to keep save-game blobs small.
+ * Produced by {@link ArbitraryNumber.toJSON} and consumed by {@link ArbitraryNumber.fromJSON}.
+ *
+ * @example
+ * const saved: ArbitraryNumberJson = an(1500).toJSON(); // { c: 1.5, e: 3 }
+ */
+type ArbitraryNumberJson = {
+    c: number;
+    e: number;
+};
+
 /**
  * A plugin that formats a normalised scientific notation number into a display string.
  *
@@ -91,7 +129,7 @@ interface SuffixNotationPluginOptions {
      *
      * @example " " -> "1.50 K"  |  "" -> "1.50K"
      */
-    separator?: string;
+    separator?: Maybe<string>;
 }
 /**
  * A display label for one tier of magnitude, used by {@link UnitNotation}.
@@ -108,7 +146,7 @@ interface Unit {
     /** Short symbol displayed after the number, e.g. `"M"`. */
     symbol: string;
     /** Optional full name, e.g. `"Million"`. Used for display purposes only. */
-    name?: string;
+    name?: Maybe<string>;
 }
 /**
  * A tier-indexed array of units for use with {@link UnitNotation}.
@@ -126,7 +164,7 @@ interface Unit {
  *   { symbol: "M" },   // tier 2: millions
  * ];
  */
-type UnitArray = ReadonlyArray<Unit | undefined>;
+type UnitArray = ReadonlyArray<Maybe<Unit>>;
 /**
  * Options for constructing an {@link AlphabetNotation} instance.
  */
@@ -140,7 +178,7 @@ interface AlphabetNotationOptions extends SuffixNotationPluginOptions {
      *
      * @default `"abcdefghijklmnopqrstuvwxyz"`
      */
-    alphabet?: string;
+    alphabet?: Maybe<string>;
 }
 /**
  * Options for constructing a {@link UnitNotation} instance.
@@ -168,7 +206,21 @@ interface UnitNotationOptions extends SuffixNotationPluginOptions {
      *
      * @default undefined
      */
-    fallback?: SuffixProvider;
+    fallback?: Maybe<SuffixProvider>;
+    /**
+     * When `true` (default), the fallback's tier is offset by the last defined tier in `units`
+     * so that fallback suffixes are visually distinct from those the fallback would generate
+     * for low tiers.
+     *
+     * Example with `CLASSIC_UNITS` (last defined tier = 33) and `letterNotation` as fallback:
+     * - `offsetFallback: true`  → exponent 102 (tier 34) → `"a"` (fallback tier 1, distinct from "K")
+     * - `offsetFallback: false` → exponent 102 (tier 34) → `"h"` (fallback tier 34, same as exponent 24)
+     *
+     * Set to `false` only for backwards compatibility with pre-1.1 behaviour.
+     *
+     * @default true
+     */
+    offsetFallback?: Maybe<boolean>;
 }
 
 /**
@@ -220,8 +272,9 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * 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: number): ArbitraryNumber;
@@ -246,14 +299,6 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * Do NOT use for unnormalised inputs - call new ArbitraryNumber(c, e) instead.
      */
     private static createNormalized;
-    /**
-     * 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.
-     */
     private static normalizeFrom;
     /**
      * Returns `this + other`.
@@ -370,6 +415,21 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * @throws `"Division by zero"` when divisor is zero.
      */
     divAdd(divisor: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, divisor: ArbitraryNumber): ArbitraryNumber;
     /**
      * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
      *
@@ -388,6 +448,36 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * @param numbers - Array to sum. Empty array returns {@link Zero}. Single element returned as-is.
      */
     static sumArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber[]): ArbitraryNumber;
     /**
      * Compares this number to `other`.
      *
@@ -499,6 +589,62 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * new ArbitraryNumber(1, 4).sqrt();   // 1*10^2  (= 100)
      */
     sqrt(): ArbitraryNumber;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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: number): number;
+    /**
+     * 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(): number;
+    /**
+     * 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: number): ArbitraryNumber;
     /**
      * Returns the nearest integer value (rounds half-up).
      *
@@ -511,6 +657,20 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * new ArbitraryNumber(-1.5, 0).round(); // -1 (half-up toward positive infinity)
      */
     round(): ArbitraryNumber;
+    /**
+     * 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(): ArbitraryNumber;
     /**
      * Returns `1` if positive, `-1` if negative, `0` if zero.
      *
@@ -532,6 +692,55 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * new ArbitraryNumber(1, 400).toNumber();  // Infinity
      */
     toNumber(): number;
+    /**
+     * 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(): ArbitraryNumberJson;
+    /**
+     * 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(): string;
+    /**
+     * 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: unknown): ArbitraryNumber;
+    /**
+     * 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: string): ArbitraryNumber;
     /** Returns `true` when this number is zero. */
     isZero(): boolean;
     /** Returns `true` when this number is strictly positive. */
@@ -543,6 +752,13 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * Numbers with `exponent >= PrecisionCutoff` are always considered integers.
      */
     isInteger(): boolean;
+    /**
+     * 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: string): number | string;
     /**
      * Formats this number as a string using the given notation plugin.
      *
@@ -715,14 +931,14 @@ type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
  * const result    = full.apply(baseDamage);
  */
 declare class AnFormula {
-    private readonly _name?;
+    private readonly _name;
     private readonly steps;
     /**
      * Prefer the {@link formula} factory function over calling this directly.
      */
-    constructor(name?: string, steps?: ReadonlyArray<FormulaStep>);
+    constructor(name?: Maybe<string>, steps?: ReadonlyArray<FormulaStep>);
     /** The name passed to {@link formula}, if any. */
-    get name(): string | undefined;
+    get name(): Maybe<string>;
     /**
      * Returns a copy of this formula with a new name, leaving the original unchanged.
      *
@@ -816,7 +1032,7 @@ declare class AnFormula {
  * const full   = armorReduction.then(critBonus);
  * const result = full.apply(baseDamage);
  */
-declare function formula(name?: string): AnFormula;
+declare function formula(name?: Maybe<string>): AnFormula;
 
 /**
  * Formats numbers using standard scientific notation: `"1.50e+3"`, `"1.50e-5"`.
@@ -988,14 +1204,23 @@ declare const letterNotation: AlphabetNotation;
 declare class UnitNotation extends SuffixNotationBase {
     protected readonly fallback?: SuffixProvider;
     protected readonly units: UnitArray;
+    /** The highest tier index that has a defined unit in `units`. Used to offset fallback calls. */
+    private readonly lastDefinedTier;
+    private readonly offsetFallback;
     /**
      * @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: UnitNotationOptions);
     /**
      * 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.
@@ -1072,11 +1297,6 @@ declare class ArbitraryNumberGuard {
     static isZero(obj: unknown): boolean;
 }
 
-/**
- * A value that can be either a plain `number` or an `ArbitraryNumber`.
- */
-type ArbitraryNumberish = ArbitraryNumber | number;
-
 /**
  * Convenience helpers for mixed `number | ArbitraryNumber` inputs.
  *
@@ -1099,8 +1319,25 @@ declare 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: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish): Nullable<ArbitraryNumber>;
     /**
      * Returns `left + right`, coercing both operands as needed.
      *
@@ -1208,4 +1445,4 @@ declare class ArbitraryNumberHelpers {
     static subtractWithFloor(value: ArbitraryNumberish, delta: ArbitraryNumberish, floor?: ArbitraryNumberish): ArbitraryNumber;
 }
 
-export { AlphabetNotation, type AlphabetNotationOptions, AnChain, AnFormula, type AnFunction, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, ArbitraryNumberOps, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, type Mod3, type NormalizedNumber, type NotationPlugin, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };
+export { AlphabetNotation, type AlphabetNotationOptions, AnChain, AnFormula, type AnFunction, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, type ArbitraryNumberJson, ArbitraryNumberOps, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, type Maybe, type Mod3, type NormalizedNumber, type NotationPlugin, type Nullable, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };