arbitrary-numbers 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1211 @@
+/**
+ * A number stored in normalised scientific notation as `coefficient * 10^exponent`,
+ * where `1 <= |coefficient| < 10` (or `coefficient === 0`).
+ *
+ * @example
+ * const n: NormalizedNumber = { coefficient: 1.5, exponent: 3 }; // 1500
+ * const z: NormalizedNumber = { coefficient: 0,   exponent: 0 }; // 0
+ */
+interface NormalizedNumber {
+    /** The significand, always in `[1, 10)` or `0`. */
+    coefficient: number;
+    /** The power of 10 by which the coefficient is scaled. */
+    exponent: number;
+}
+/** The result of a three-way comparison: negative, zero, or positive. */
+type Signum = -1 | 0 | 1;
+/** Remainder after dividing an exponent by 3 - the within-tier offset. */
+type Mod3 = 0 | 1 | 2;
+/**
+ * Type of the {@link an} shorthand function.
+ *
+ * Callable as `an(coefficient, exponent?)` and also has a
+ * `.from(value)` static method for plain JS number conversion.
+ */
+interface AnFunction {
+    (coefficient: number, exponent?: number): ArbitraryNumber;
+    from(value: number): ArbitraryNumber;
+}
+
+/**
+ * A plugin that formats a normalised scientific notation number into a display string.
+ *
+ * Implement this interface and pass an instance to {@link ArbitraryNumber.toString}
+ * to customise how numbers are rendered.
+ *
+ * @example
+ * const myPlugin: NotationPlugin = {
+ *   format(coefficient, exponent, decimals) {
+ *     return `${coefficient.toFixed(decimals)}e${exponent}`;
+ *   },
+ * };
+ * number.toString(myPlugin); // "1.50e3"
+ */
+interface NotationPlugin {
+    /**
+     * Formats a normalised value as a display string.
+     *
+     * @param coefficient - The significand, always in `[1, 10)` or `0`.
+     * @param exponent - The power of 10.
+     * @param decimals - Number of decimal places to render.
+     * @returns The formatted string.
+     */
+    format(coefficient: number, exponent: number, decimals: number): string;
+}
+/**
+ * Minimal interface for anything that can map a tier to a suffix string.
+ *
+ * Used as the `fallback` type on {@link UnitNotation} - only `getSuffix` is
+ * ever called, so a simple object literal is enough:
+ *
+ * @example
+ * const myFallback: SuffixProvider = {
+ *   getSuffix(tier) { return tier > 10 ? "big" : ""; },
+ * };
+ */
+interface SuffixProvider {
+    /**
+     * Returns the suffix label for the given tier, where `tier = floor(exponent / 3)`.
+     *
+     * @param tier - The exponent tier (`floor(exponent / 3)`).
+     * @returns The suffix string (e.g. `"K"`, `"a"`), or `""` for no suffix.
+     */
+    getSuffix(tier: number): string;
+}
+/**
+ * A full suffix-based {@link NotationPlugin} - combines formatting and suffix lookup.
+ *
+ * Extend {@link SuffixNotationBase} rather than implementing this interface directly.
+ */
+interface SuffixNotationPlugin extends NotationPlugin, SuffixProvider {
+}
+/**
+ * Options shared by all suffix-based notation plugins.
+ */
+interface SuffixNotationPluginOptions {
+    /**
+     * String placed between the formatted number and its suffix.
+     *
+     * Defaults to `""` for most plugins. {@link UnitNotation} overrides this to `" "`,
+     * so `new UnitNotation({ units })` produces `"1.50 K"` without an explicit separator.
+     *
+     * @example " " -> "1.50 K"  |  "" -> "1.50K"
+     */
+    separator?: string;
+}
+/**
+ * A display label for one tier of magnitude, used by {@link UnitNotation}.
+ *
+ * Units are stored in a **tier-indexed array** - the array index is the tier number,
+ * where `tier = Math.floor(exponent / 3)`. Tier 1 = thousands, tier 2 = millions, etc.
+ * The exponent is therefore implicit: `exponent = tier * 3`.
+ *
+ * @example
+ * // In a tier-indexed array, index 2 represents 10^6 (millions):
+ * const units: UnitArray = [undefined, { symbol: "K" }, { symbol: "M" }];
+ */
+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;
+}
+/**
+ * A tier-indexed array of units for use with {@link UnitNotation}.
+ *
+ * The array index equals the tier number (`Math.floor(exponent / 3)`).
+ * `undefined` at an index signals "no unit for this tier" - the fallback plugin
+ * (or plain fixed-point rendering) will be used instead.
+ *
+ * Sparse arrays are valid: unset indices are implicitly `undefined`.
+ *
+ * @example
+ * const myUnits: UnitArray = [
+ *   undefined,          // tier 0: < 1000, no suffix
+ *   { symbol: "K" },   // tier 1: thousands
+ *   { symbol: "M" },   // tier 2: millions
+ * ];
+ */
+type UnitArray = ReadonlyArray<Unit | undefined>;
+/**
+ * Options for constructing an {@link AlphabetNotation} instance.
+ */
+interface AlphabetNotationOptions extends SuffixNotationPluginOptions {
+    /**
+     * The ordered symbol set used to build multi-character suffixes.
+     *
+     * The algorithm is base-N positional: tier 1 = `alphabet[0]`, tier N = `alphabet[N-1]`,
+     * tier N+1 = `alphabet[0]+alphabet[0]`, and so on - identical to Excel column naming
+     * when `alphabet` is `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"`.
+     *
+     * @default `"abcdefghijklmnopqrstuvwxyz"`
+     */
+    alphabet?: string;
+}
+/**
+ * Options for constructing a {@link UnitNotation} instance.
+ */
+interface UnitNotationOptions extends SuffixNotationPluginOptions {
+    /**
+     * Tier-indexed array of units. The array index equals the tier number
+     * (`Math.floor(exponent / 3)`). Use `undefined` at an index to signal
+     * "no unit for this tier" - the fallback plugin will be used instead.
+     *
+     * @example
+     * // index 0 = tier 0 (< 1000, no suffix)
+     * // index 1 = tier 1 (thousands) -> "K"
+     * // index 2 = tier 2 (millions)  -> "M"
+     */
+    units: UnitArray;
+    /**
+     * Suffix provider used when no unit is defined for a tier.
+     *
+     * Only {@link SuffixProvider.getSuffix} is called - the number and separator are
+     * still formatted by this `UnitNotation` instance, keeping presentation consistent.
+     * A simple object literal with just `getSuffix` is sufficient; a full plugin is not required.
+     *
+     * When omitted, tiers with no unit are rendered as a plain fixed-point number (no suffix).
+     *
+     * @default undefined
+     */
+    fallback?: SuffixProvider;
+}
+
+/**
+ * An immutable number with effectively unlimited range, stored as `coefficient * 10^exponent`
+ * in normalised scientific notation.
+ *
+ * The coefficient is always in `[1, 10)` (or `0`). Addition short-circuits when the exponent
+ * difference between operands exceeds {@link PrecisionCutoff} - the smaller value is below
+ * the precision floor of the larger and is silently discarded.
+ *
+ * @example
+ * const a = new ArbitraryNumber(1.5, 3);  // 1,500
+ * const b = new ArbitraryNumber(2.5, 3);  // 2,500
+ * a.add(b).toString(); // "4.00e+3"
+ * a.mul(b).toString(); // "3.75e+6"
+ */
+declare class ArbitraryNumber implements NormalizedNumber {
+    /** The significand, always in `[1, 10)` or `0`. */
+    readonly coefficient: number;
+    /** The power of 10 by which the coefficient is scaled. */
+    readonly exponent: number;
+    /**
+     * 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.
+     */
+    static PrecisionCutoff: number;
+    /** The additive identity: `0`. */
+    static readonly Zero: ArbitraryNumber;
+    /** The multiplicative identity: `1`. */
+    static readonly One: ArbitraryNumber;
+    /** `10`. */
+    static readonly Ten: 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: number): ArbitraryNumber;
+    /**
+     * 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: number, exponent: number);
+    /**
+     * @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.
+     */
+    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`.
+     *
+     * 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: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns `this - other`.
+     *
+     * @example
+     * new ArbitraryNumber(3.5, 3).sub(new ArbitraryNumber(1.5, 3)); // 2*10^3
+     */
+    sub(other: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns `this * other`.
+     *
+     * @example
+     * new ArbitraryNumber(2, 3).mul(new ArbitraryNumber(3, 4)); // 6*10^7
+     */
+    mul(other: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns the arithmetic negation of this number (`-this`).
+     *
+     * @example
+     * new ArbitraryNumber(1.5, 3).negate(); // -1.5*10^3
+     */
+    negate(): ArbitraryNumber;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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: number): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, subtrahend: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber[]): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber): number;
+    /** Returns `true` if `this > other`. */
+    greaterThan(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this < other`. */
+    lessThan(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this >= other`. */
+    greaterThanOrEqual(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this <= other`. */
+    lessThanOrEqual(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this === other` in value. */
+    equals(other: ArbitraryNumber): boolean;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, min: ArbitraryNumber, max: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns the smaller of `a` and `b`.
+     * @example ArbitraryNumber.min(a, b)
+     */
+    static min(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns the larger of `a` and `b`.
+     * @example ArbitraryNumber.max(a, b)
+     */
+    static max(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumber, b: ArbitraryNumber, t: number): ArbitraryNumber;
+    /**
+     * 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<T>(cutoff: number, fn: () => T): T;
+    /**
+     * 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(): number;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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(): ArbitraryNumber;
+    /**
+     * 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(): Signum;
+    /**
+     * 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(): number;
+    /** Returns `true` when this number is zero. */
+    isZero(): boolean;
+    /** Returns `true` when this number is strictly positive. */
+    isPositive(): boolean;
+    /** Returns `true` when this number is strictly negative. */
+    isNegative(): boolean;
+    /**
+     * Returns `true` when this number has no fractional part.
+     * Numbers with `exponent >= PrecisionCutoff` are always considered integers.
+     */
+    isInteger(): boolean;
+    /**
+     * 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?: NotationPlugin, decimals?: number): string;
+}
+
+/**
+ * Base class for all errors thrown by the arbitrary-numbers library.
+ *
+ * Catch this to handle any error from the library regardless of type.
+ */
+declare class ArbitraryNumberError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when invalid input is provided to a constructor or factory method.
+ *
+ * @example
+ * try {
+ *     ArbitraryNumber.from(Infinity);
+ * } catch (e) {
+ *     if (e instanceof ArbitraryNumberInputError) {
+ *         console.log(e.value); // Infinity
+ *     }
+ * }
+ */
+declare class ArbitraryNumberInputError extends ArbitraryNumberError {
+    /** The invalid value that caused the error. */
+    readonly value: number | string;
+    constructor(message: string, value: number | string);
+}
+/**
+ * Thrown when a mathematical operation is undefined for the given operands.
+ *
+ * @example
+ * try {
+ *     an(10).div(an(0));
+ * } catch (e) {
+ *     if (e instanceof ArbitraryNumberDomainError) {
+ *         console.log(e.context); // { dividend: 10 }
+ *     }
+ * }
+ */
+declare class ArbitraryNumberDomainError extends ArbitraryNumberError {
+    /** The operands involved in the failed operation, as plain numbers. */
+    readonly context: Record<string, number>;
+    constructor(message: string, context: Record<string, number>);
+}
+
+declare const an: AnFunction;
+
+/**
+ * Fluent builder for multi-step `ArbitraryNumber` expressions.
+ *
+ * Each method mutates the accumulated value in-place and returns `this`,
+ * enabling a readable left-to-right pipeline with no expression-tree
+ * overhead.  Every step delegates directly to the underlying
+ * `ArbitraryNumber` method - fused variants (`mulAdd`, `mulSub`, etc.)
+ * are available here too.
+ *
+ * @example
+ * // Damage formula: ((base - armour) * mult) + flatBonus
+ * const result = chain(base)
+ *     .subMul(armour, multiplier)
+ *     .add(flatBonus)
+ *     .done();
+ *
+ * @remarks
+ * No deferred execution - each call runs immediately.  Overhead vs direct
+ * method chaining is a single extra method call + `return this` per step
+ * (~1-2 ns).  Use fused ops for hot inner loops; the builder is optimised
+ * for readability in complex multi-step formulas.
+ */
+declare class AnChain {
+    private value;
+    private constructor();
+    /** Creates an `AnChain` from an `ArbitraryNumber` or a plain `number`. */
+    static from(value: ArbitraryNumber | number): AnChain;
+    /** Adds `other` to the accumulated value. */
+    add(other: ArbitraryNumber): this;
+    /** Subtracts `other` from the accumulated value. */
+    sub(other: ArbitraryNumber): this;
+    /** Multiplies the accumulated value by `other`. */
+    mul(other: ArbitraryNumber): this;
+    /** Divides the accumulated value by `other`. */
+    div(other: ArbitraryNumber): this;
+    /** Raises the accumulated value to `exp`. */
+    pow(exp: number): this;
+    /** `(this * mult) + add` */
+    mulAdd(mult: ArbitraryNumber, add: ArbitraryNumber): this;
+    /** `(this + add) * mult` */
+    addMul(add: ArbitraryNumber, mult: ArbitraryNumber): this;
+    /** `(this * mult) - sub` */
+    mulSub(mult: ArbitraryNumber, sub: ArbitraryNumber): this;
+    /** `(this - sub) * mult` */
+    subMul(sub: ArbitraryNumber, mult: ArbitraryNumber): this;
+    /** `(this / div) + add` */
+    divAdd(div: ArbitraryNumber, add: ArbitraryNumber): this;
+    /** Absolute value. */
+    abs(): this;
+    /** Negates the accumulated value. */
+    neg(): this;
+    /** Square root of the accumulated value. */
+    sqrt(): this;
+    /** Rounds down to the nearest integer. */
+    floor(): this;
+    /** Rounds up to the nearest integer. */
+    ceil(): this;
+    /** Rounds to the nearest integer. */
+    round(): this;
+    /** Returns the accumulated `ArbitraryNumber` result. */
+    done(): ArbitraryNumber;
+}
+/**
+ * Creates an {@link AnChain} builder starting from `value`.
+ *
+ * Mirrors the `an` factory shorthand.
+ *
+ * @example
+ * import { chain, an } from 'arbitrary-numbers';
+ *
+ * const result = chain(an(1.5, 6))
+ *     .mulAdd(multiplier, bonus)
+ *     .floor()
+ *     .done();
+ */
+declare function chain(value: ArbitraryNumber | number): AnChain;
+
+type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
+/**
+ * A reusable, named pipeline of `ArbitraryNumber` operations.
+ *
+ * Unlike {@link AnChain}, which executes each step immediately against an
+ * accumulated value, `AnFormula` stores the operations as a list of closures
+ * and runs them only when {@link apply} is called.  The same formula can be
+ * applied to any number of values without re-defining the pipeline.
+ *
+ * Each builder method returns a **new** `AnFormula` - the original is
+ * unchanged.  This makes branching and composition safe:
+ *
+ * @example
+ * const base      = formula().mul(an(2));
+ * const withFloor = base.floor();   // new formula - base is unchanged
+ * const withCeil  = base.ceil();    // another branch from base
+ *
+ * @example
+ * // Define once, apply to many values
+ * const armorReduction = formula("Armor Reduction")
+ *     .subMul(armor, an(0.75))
+ *     .floor();
+ *
+ * const physDamage = armorReduction.apply(physBase);
+ * const magDamage  = armorReduction.apply(magBase);
+ *
+ * @example
+ * // Compose formulas
+ * const critBonus = formula("Crit Bonus").mul(critMult).ceil();
+ * const full      = armorReduction.then(critBonus);
+ * const result    = full.apply(baseDamage);
+ */
+declare class AnFormula {
+    private readonly _name?;
+    private readonly steps;
+    /**
+     * Prefer the {@link formula} factory function over calling this directly.
+     */
+    constructor(name?: string, steps?: ReadonlyArray<FormulaStep>);
+    /** The name passed to {@link formula}, if any. */
+    get name(): string | undefined;
+    /**
+     * 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: string): AnFormula;
+    private step;
+    /** Appends `+ other` to the pipeline. */
+    add(other: ArbitraryNumber): AnFormula;
+    /** Appends `- other` to the pipeline. */
+    sub(other: ArbitraryNumber): AnFormula;
+    /** Appends `* other` to the pipeline. */
+    mul(other: ArbitraryNumber): AnFormula;
+    /** Appends `/ other` to the pipeline. */
+    div(other: ArbitraryNumber): AnFormula;
+    /** Appends `^ exp` to the pipeline. */
+    pow(exp: number): AnFormula;
+    /** Appends `(value * mult) + add` to the pipeline. */
+    mulAdd(mult: ArbitraryNumber, add: ArbitraryNumber): AnFormula;
+    /** Appends `(value + add) * mult` to the pipeline. */
+    addMul(add: ArbitraryNumber, mult: ArbitraryNumber): AnFormula;
+    /** Appends `(value * mult) - sub` to the pipeline. */
+    mulSub(mult: ArbitraryNumber, sub: ArbitraryNumber): AnFormula;
+    /** Appends `(value - sub) * mult` to the pipeline. */
+    subMul(sub: ArbitraryNumber, mult: ArbitraryNumber): AnFormula;
+    /** Appends `(value / div) + add` to the pipeline. */
+    divAdd(div: ArbitraryNumber, add: ArbitraryNumber): AnFormula;
+    /** Appends `abs()` to the pipeline. */
+    abs(): AnFormula;
+    /** Appends `neg()` to the pipeline. */
+    neg(): AnFormula;
+    /** Appends `sqrt()` to the pipeline. */
+    sqrt(): AnFormula;
+    /** Appends `floor()` to the pipeline. */
+    floor(): AnFormula;
+    /** Appends `ceil()` to the pipeline. */
+    ceil(): AnFormula;
+    /** Appends `round()` to the pipeline. */
+    round(): AnFormula;
+    /**
+     * 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: AnFormula): AnFormula;
+    /**
+     * 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: ArbitraryNumber | number): ArbitraryNumber;
+}
+/**
+ * Creates an {@link AnFormula} pipeline, optionally named.
+ *
+ * Build the pipeline by chaining methods - each returns a new `AnFormula`
+ * so the original is always safe to branch or reuse.  Call {@link AnFormula.apply}
+ * to run the pipeline against a value.
+ *
+ * @param name - Optional label, available via {@link AnFormula.name} for debugging.
+ * @example
+ * import { formula, an } from 'arbitrary-numbers';
+ *
+ * const armorReduction = formula("Armor Reduction")
+ *     .subMul(armor, an(0.75))   // (base - armor) * 0.75
+ *     .floor();
+ *
+ * const critBonus = formula("Crit Bonus").mul(critMult).ceil();
+ *
+ * // Reuse across many values
+ * const physDmg = armorReduction.apply(physBase);
+ * const magDmg  = armorReduction.apply(magBase);
+ *
+ * // Compose
+ * const full   = armorReduction.then(critBonus);
+ * const result = full.apply(baseDamage);
+ */
+declare function formula(name?: string): AnFormula;
+
+/**
+ * Formats numbers using standard scientific notation: `"1.50e+3"`, `"1.50e-5"`.
+ *
+ * Numbers with `exponent === 0` are formatted without an exponent part: `"1.50"`.
+ * This is the default plugin used by {@link ArbitraryNumber.toString}.
+ *
+ * @example
+ * const n = new ArbitraryNumber(1.5, 3);
+ * n.toString();                       // "1.50e+3"   (default decimals = 2)
+ * n.toString(scientificNotation, 6);  // "1.500000e+3"
+ */
+declare class ScientificNotation implements NotationPlugin {
+    /**
+     * 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: number, exponent: number, decimals: number): string;
+}
+/** Pre-built {@link ScientificNotation} instance. The default notation used by {@link ArbitraryNumber.toString}. */
+declare const scientificNotation: ScientificNotation;
+
+/**
+ * Abstract base class for suffix-based notation plugins (e.g. `"1.50 K"`, `"3.20a"`).
+ *
+ * Subclasses implement {@link getSuffix} to map a tier to a display label.
+ * All coefficient/remainder math is handled here.
+ *
+ * @example
+ * class EmojiNotation extends SuffixNotationBase {
+ *   private static readonly TIERS = ["", "🔥", "💥", "🌟", "🚀"];
+ *   getSuffix(tier: number): string {
+ *     return EmojiNotation.TIERS[tier] ?? `e+${tier * 3}`;
+ *   }
+ * }
+ */
+declare abstract class SuffixNotationBase implements SuffixNotationPlugin {
+    /** Lookup for remainder values 0, 1, 2 (exponent mod 3). */
+    protected readonly displayScale: readonly [1, 10, 100];
+    protected readonly separator: string;
+    /**
+     * @param options - Plugin options. `separator` defaults to `""`.
+     */
+    constructor(options?: SuffixNotationPluginOptions);
+    /**
+     * Returns the suffix label for the given tier, where `tier = floor(exponent / 3)`.
+     *
+     * Tier 0 corresponds to values below 10^3 - return `""` to render with no suffix.
+     * Tier 1 = 10^3, tier 2 = 10^6, and so on.
+     *
+     * @param tier - The exponent tier (`floor(exponent / 3)`), >= 0.
+     * @returns The suffix string (e.g. `"K"`, `"a"`), or `""` for no suffix.
+     */
+    abstract getSuffix(tier: number): string;
+    /**
+     * 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: number, exponent: number, decimals: number): string;
+}
+
+/**
+ * Converts a tier number to a multi-character suffix using an ordered symbol set.
+ *
+ * This is the raw algorithm behind {@link AlphabetNotation}, exposed as a standalone
+ * function for cases where you need suffix generation without the full notation plugin
+ * (e.g. column headers, label generators, custom renderers).
+ *
+ * The algorithm is base-N positional with no leading-symbol ambiguity:
+ * - Tier 0 -> `""` (no suffix)
+ * - Tier 1 -> `alphabet[0]`
+ * - Tier N -> `alphabet[N-1]` (last single-character suffix)
+ * - Tier N+1 -> `alphabet[0]+alphabet[0]` (first two-character suffix)
+ *
+ * This matches Excel column naming when `alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"`.
+ *
+ * @param tier - The tier number (`Math.floor(exponent / 3)` in notation context). Must be >= 0.
+ * @param alphabet - The ordered symbol set. Defaults to `"abcdefghijklmnopqrstuvwxyz"`.
+ * @returns The suffix string, or `""` for tier 0.
+ *
+ * @example
+ * alphabetSuffix(0, "abc")   // ""
+ * alphabetSuffix(1, "abc")   // "a"
+ * alphabetSuffix(3, "abc")   // "c"
+ * alphabetSuffix(4, "abc")   // "aa"
+ * alphabetSuffix(6, "abc")   // "ac"
+ * alphabetSuffix(7, "abc")   // "ba"
+ *
+ * // Excel columns
+ * alphabetSuffix(1, "ABCDEFGHIJKLMNOPQRSTUVWXYZ")  // "A"
+ * alphabetSuffix(26, "ABCDEFGHIJKLMNOPQRSTUVWXYZ") // "Z"
+ * alphabetSuffix(27, "ABCDEFGHIJKLMNOPQRSTUVWXYZ") // "AA"
+ */
+declare function alphabetSuffix(tier: number, alphabet?: string): string;
+/**
+ * Formats numbers using multi-character suffixes derived from a configurable symbol set
+ * (e.g. `"1.50a"`, `"3.20b"`, `"1.00aa"`).
+ *
+ * The suffix sequence is generated by {@link alphabetSuffix}: tier 1 -> first symbol,
+ * tier N -> last symbol, tier N+1 -> first two-symbol combination, and so on.
+ *
+ * Pass a custom `alphabet` to produce any suffix sequence - lowercase letters (default),
+ * uppercase (Excel-style columns), Greek letters, emoji, or any ordered set of strings.
+ *
+ * @example
+ * // Default: lowercase a-z
+ * letterNotation.format(1.5, 3, 2);  // "1.50a"
+ * letterNotation.format(1.5, 78, 2); // "1.50z"
+ * letterNotation.format(1.5, 81, 2); // "1.50aa"
+ *
+ * @example
+ * // Excel-style columns
+ * const excelNotation = new AlphabetNotation({ alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ" });
+ * excelNotation.format(1.5, 3, 2);   // "1.50A"
+ * excelNotation.format(1.5, 78, 2);  // "1.50Z"
+ * excelNotation.format(1.5, 81, 2);  // "1.50AA"
+ */
+declare class AlphabetNotation extends SuffixNotationBase {
+    private readonly defaultSuffix;
+    private readonly alphabet;
+    private readonly suffixCache;
+    /**
+     * @param options - Plugin options. `alphabet` defaults to `"abcdefghijklmnopqrstuvwxyz"`.
+     *   `separator` defaults to `""` (no space between the number and suffix).
+     */
+    constructor(options?: AlphabetNotationOptions);
+    /**
+     * 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: number): string;
+}
+/** Pre-built {@link AlphabetNotation} instance using lowercase `a-z` with no separator. */
+declare const letterNotation: AlphabetNotation;
+
+/**
+ * Formats numbers using a tier-indexed array of named units
+ * (e.g. `"1.50 K"`, `"3.20 M"`, `"1.00 B"`).
+ *
+ * The `units` array is indexed by tier (`Math.floor(exponent / 3)`), so lookup
+ * is O(1) - no search required. A `undefined` entry means "no unit for this tier";
+ * the fallback plugin handles it.
+ *
+ * @example
+ * const notation = new UnitNotation({ units: CLASSIC_UNITS, separator: " " });
+ * notation.format(1.5, 6, 2);  // "1.50 M"
+ *
+ * @example
+ * // Pre-built instance with space separator and letterNotation fallback:
+ * number.toString(unitNotation);  // "1.50 K"
+ */
+declare class UnitNotation extends SuffixNotationBase {
+    protected readonly fallback?: SuffixProvider;
+    protected readonly units: UnitArray;
+    /**
+     * @param options - Tier-indexed unit array, optional suffix fallback plugin, and separator.
+     *   `separator` defaults to `" "` (a space between number and unit symbol).
+     */
+    constructor(options: UnitNotationOptions);
+    /**
+     * 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: number): string;
+}
+/**
+ * Pre-built {@link UnitNotation} instance using {@link CLASSIC_UNITS} (K, M, B, T…)
+ * with a space separator and {@link letterNotation} as fallback for very large numbers.
+ */
+declare const unitNotation: UnitNotation;
+
+/**
+ * Full tier-indexed unit list from Thousand (tier 1, 10^3) to Centillion (tier 101, 10^303).
+ *
+ * Array index = tier = `Math.floor(exponent / 3)`. Tiers 34-100 are `undefined` -
+ * numbers in that range fall through to whatever fallback is configured on the
+ * {@link UnitNotation} instance (letterNotation for the pre-built `unitNotation`).
+ *
+ * @example
+ * const notation = new UnitNotation({ units: CLASSIC_UNITS, separator: " " });
+ * notation.format(1.5, 3, 2);  // "1.50 K"
+ * notation.format(1.5, 6, 2);  // "1.50 M"
+ */
+declare const CLASSIC_UNITS: UnitArray;
+/**
+ * Compact tier-indexed unit list from Thousand (tier 1, 10^3) to Nonillion (tier 10, 10^30).
+ *
+ * Intended for tight UI spaces. Tiers beyond 10 (exponent > 32) fall back to whatever
+ * fallback plugin is configured on the {@link UnitNotation} instance.
+ *
+ * @example
+ * const notation = new UnitNotation({ units: COMPACT_UNITS, fallback: letterNotation, separator: " " });
+ * notation.format(1.5, 3, 2);  // "1.50 k"
+ * notation.format(1.5, 6, 2);  // "1.50 M"
+ */
+declare const COMPACT_UNITS: UnitArray;
+
+/**
+ * Type-guard helpers for {@link ArbitraryNumber} and {@link NormalizedNumber}.
+ *
+ * @example
+ * if (ArbitraryNumberGuard.isArbitraryNumber(value)) {
+ *   value.add(ArbitraryNumber.One);
+ * }
+ */
+declare 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: unknown): obj is 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: unknown): obj is NormalizedNumber;
+    /**
+     * 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: 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.
+ *
+ * Each method accepts either type and coerces plain `number` values via
+ * {@link ArbitraryNumber.from} before delegating to the corresponding instance method.
+ *
+ * Prefer `ArbitraryNumber` instance methods directly on hot paths - this class is
+ * intended for system boundaries (event handlers, serialisation, UI callbacks) where
+ * the input type is unknown.
+ *
+ * @example
+ * import { ArbitraryNumberOps as ops } from "arbitrary-numbers";
+ * ops.add(1500, 2500)              // ArbitraryNumber (4000)
+ * ops.mul(an(2, 0), 5)            // ArbitraryNumber (10)
+ * ops.from(1_500_000)             // ArbitraryNumber { coefficient: 1.5, exponent: 6 }
+ */
+declare 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: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: ArbitraryNumberish, right: ArbitraryNumberish): number;
+    /**
+     * 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: ArbitraryNumberish, min: ArbitraryNumberish, max: ArbitraryNumberish): ArbitraryNumber;
+}
+
+/**
+ * Domain-level helpers for common game and simulation patterns.
+ *
+ * These sit above the core arithmetic layer - each method accepts
+ * mixed input (`number | ArbitraryNumber`) via
+ * {@link ArbitraryNumberOps.from} so they work at system boundaries
+ * where you may receive raw numbers.
+ *
+ * For hot-path code, use `ArbitraryNumber` methods directly.
+ */
+declare class ArbitraryNumberHelpers {
+    private static coerce;
+    /**
+     * 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: ArbitraryNumberish, threshold: ArbitraryNumberish): boolean;
+    /**
+     * 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: ArbitraryNumberish, step: ArbitraryNumberish): ArbitraryNumber;
+    /**
+     * 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: 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 };