@vandenberghinc/volt 1.2.5 → 1.2.6

package/backend/dist/esm/backend/src/database/quota/safe_int.js

@@ -1,810 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
- */
-/* ============================================================================
-   SafeInt — a single, generic, integer-only amount class
-   ----------------------------------------------------------------------------
-   - **No derived classes.** A single generic class parameterized by its scale `S`.
-   - **Exact-by-default.** No silent rounding anywhere; rounding only when `round` is provided.
-   - **Same-scale arithmetic only.** Operations accept raw numbers or the same generic `SafeInt<S>`.
-   - **Strong typing for rescaling.** `to_scale<T>()` and helpers (`base/milli/micro/nano/pico`)
-     return `SafeInt<T>` with the correct type at compile time.
-   - **Constructor defaults to Base scale.** Multiple signatures are provided as requested.
-   ========================================================================== */
-/**
- * Scaled, integer-only amount with explicit, type-safe scale semantics.
- *
- * @template S The canonical integer scale (see {@link SafeInt.Scale}) at which this instance stores its value.
- *
- * @remarks
- * - The stored value is always an **integer (`bigint`)** (may be negative) measured in units of `S`.
- * - Instances are **immutable**; all arithmetic returns new `SafeInt` instances.
- * - Conversions are **exact by default**. Provide a {@link SafeInt.Rounding} `round` to allow rounding.
- * - Arithmetic is **same-scale only**: pass raw integers or another `SafeInt<S>`.
- *
- * @nav Database
- * @docs
- */
-export class SafeInt {
-    // ----------------------------------------------------------------
-    // Fields
-    // ----------------------------------------------------------------
-    /**
-     * The stored integer (may be negative) measured at {@link int_scale}.
-     */
-    int_value;
-    /**
-     * The canonical integer scale for {@link int_value}.
-     */
-    int_scale;
-    // ----------------------------------------------------------------
-    // Constructors
-    // ----------------------------------------------------------------
-    /**
-     * Construct by converting from `opts.from_scale` to `opts.to_scale`. **Exact by default**.
-     *
-     * @param value The numeric input at `opts.from_scale`.
-     *              - If `from_scale === Base`, `value` may be a float. When `round` is omitted,
-     *                `value * to_scale` must be an integer. If `round` is provided, that rounding is applied.
-     *              - If `from_scale !== Base`, `value` must be a safe integer.
-     *              - If `value` is a string:
-     *                - If `from_scale === Base`, it may be a decimal string (exact parsing).
-     *                - Otherwise it must be an integer string.
-     * @param opts  The canonical scale or scale options.
-     * @param opts.to_scale   The target scale for storage (the resulting instance type is `SafeInt<opts.to_scale>`).
-     * @param opts.from_scale The source scale of {@link value}, defaults to {@link SafeInt.Scale.Base}.
-     * @param opts.round       Optional rounding mode for non-exact conversions (default: `"exact"`).
-     *
-     * @example
-     * new SafeInt(123_000, SafeInt.Scale.Nano)
-     * @example
-     * new SafeInt(123_000, "nano")
-     * @example
-     * new SafeInt(1.5, { from_scale: SafeInt.Scale.Base, to_scale: SafeInt.Scale.Milli, round: "round" }) // 1500
-     * @example
-     * new SafeInt(2n, { from_scale: SafeInt.Scale.Base, to_scale: SafeInt.Scale.Nano }) // 2_000_000_000n
-     * @example
-     * // Exact, decimal-safe parsing (no float surprises)
-     * new SafeInt("1.005", { from_scale: "base", to_scale: "milli", round: "round" }) // 1005
-     * @example
-     * // Integer string at already-at-scale (underscores allowed)
-     * new SafeInt("123_000", "nano")
-     *
-     * @throws
-     * Error If inputs are invalid, conversion overflows, or exactness is required but not met.
-     *
-     * @docs
-     */
-    constructor(value, opts) {
-        // Already-at-scale (exact)
-        if (typeof opts === "number" || typeof opts === "string") {
-            const scale = typeof opts === "string"
-                ? SafeInt.str_to_scale(opts)
-                : opts;
-            // validate scale (must be a positive safe integer)
-            if (!Number.isSafeInteger(scale) || scale <= 0) {
-                throw new Error(`Invalid scale: expected positive safe integer, got ${scale}`);
-            }
-            // value can be any integer (negative allowed); validate number inputs are safe integers
-            if (typeof value === "string") {
-                // already-at-scale string must be an integer string (no decimal point)
-                this.int_value = SafeInt.parse_int_str(value, "value");
-            }
-            else if (typeof value === "number") {
-                if (!Number.isSafeInteger(value)) {
-                    throw new Error(`Invalid value: expected safe integer, got ${value}`);
-                }
-                this.int_value = BigInt(value);
-            }
-            else {
-                this.int_value = value;
-            }
-            this.int_scale = scale;
-            return;
-        }
-        // Convert from -> to (exact by default; optional rounding)
-        let { to_scale, from_scale = SafeInt.Scale.Base, round = "exact" } = opts;
-        if (typeof to_scale === "string") {
-            to_scale = SafeInt.str_to_scale(to_scale);
-        }
-        if (typeof from_scale === "string") {
-            from_scale = SafeInt.str_to_scale(from_scale);
-        }
-        // validate scales (must be positive safe integers)
-        if (!Number.isSafeInteger(from_scale) || from_scale <= 0) {
-            throw new Error(`Invalid from_scale: expected positive safe integer, got ${from_scale}`);
-        }
-        if (!Number.isSafeInteger(to_scale) || to_scale <= 0) {
-            throw new Error(`Invalid to_scale: expected positive safe integer, got ${to_scale}`);
-        }
-        let converted;
-        if (from_scale === to_scale) {
-            if (to_scale === SafeInt.Scale.Base) {
-                // Base scale can accept:
-                // - number input (may be float; exactness/rounding rules apply)
-                // - bigint input (always an integer; rounding is a no-op)
-                if (typeof value === "string") {
-                    // base->base stores integer base units; string must be integer
-                    converted = SafeInt.parse_int_str(value, "value");
-                }
-                else if (typeof value === "bigint") {
-                    converted = value;
-                }
-                else {
-                    const n = value;
-                    if (round === "exact") {
-                        if (!Number.isSafeInteger(n)) {
-                            throw new Error(`Exact constructor requires integer at base scale, got ${n}`);
-                        }
-                        converted = BigInt(n);
-                    }
-                    else {
-                        const rounded = SafeInt.apply_round(n, round);
-                        if (!Number.isSafeInteger(rounded)) {
-                            throw new Error(`Rounding produced non-integer at base scale: ${rounded}`);
-                        }
-                        converted = BigInt(rounded);
-                    }
-                }
-            }
-            else {
-                if (typeof value === "string") {
-                    // non-base, same-scale: must be integer
-                    converted = SafeInt.parse_int_str(value, "value");
-                }
-                else if (typeof value === "number") {
-                    if (!Number.isSafeInteger(value)) {
-                        throw new Error(`Invalid value: expected safe integer at scale=${to_scale}, got ${value}`);
-                    }
-                    converted = BigInt(value);
-                }
-                else {
-                    converted = value;
-                }
-            }
-        }
-        else if (from_scale === SafeInt.Scale.Base) {
-            // base -> integer scale
-            // - number input may be float; exactness/rounding rules apply
-            // - bigint input represents an integer base amount; conversion is exact bigint math (rounding is a no-op)
-            if (typeof value === "string") {
-                // Decimal-safe path: parse base string exactly, then scale in bigint space.
-                converted = SafeInt.parse_base_decimal_to_scaled(value, to_scale, round);
-            }
-            else if (typeof value === "bigint") {
-                converted = value * BigInt(to_scale);
-            }
-            else {
-                const n = value;
-                const product = n * to_scale;
-                if (round === "exact") {
-                    if (!Number.isFinite(product) || !Number.isInteger(product)) {
-                        throw new Error(`Exact conversion failed: ${n} * ${to_scale} is not an integer`);
-                    }
-                    if (!Number.isSafeInteger(product)) {
-                        throw new Error(`Overflow converting base->${to_scale}: ${product}`);
-                    }
-                    converted = BigInt(product);
-                }
-                else {
-                    const rounded = SafeInt.apply_round(product, round);
-                    if (!Number.isSafeInteger(rounded)) {
-                        throw new Error(`Overflow/invalid rounding converting base->${to_scale}: ${product} -> ${rounded}`);
-                    }
-                    converted = BigInt(rounded);
-                }
-            }
-        }
-        else if (to_scale === SafeInt.Scale.Base) {
-            // integer scale -> base integer, possibly rounded
-            if (typeof value === "string") {
-                const v = SafeInt.parse_int_str(value, "value");
-                converted = SafeInt.div_to_base(v, from_scale, round);
-            }
-            else if (typeof value === "number") {
-                if (!Number.isSafeInteger(value)) {
-                    throw new Error(`Invalid value: expected safe integer at scale=${from_scale}, got ${value}`);
-                }
-                converted = SafeInt.div_to_base(BigInt(value), from_scale, round);
-            }
-            else {
-                converted = SafeInt.div_to_base(value, from_scale, round);
-            }
-        }
-        else {
-            // integer-scale -> integer-scale
-            if (typeof value === "number") {
-                if (!Number.isSafeInteger(value)) {
-                    throw new Error(`Invalid value: expected safe integer at scale=${from_scale}, got ${value}`);
-                }
-            }
-            const v = typeof value === "string" ? SafeInt.parse_int_str(value, "value")
-                : typeof value === "number" ? BigInt(value)
-                    : value;
-            converted = SafeInt.convert_int_scale(v, from_scale, to_scale, round);
-        }
-        this.int_value = converted;
-        this.int_scale = to_scale;
-    }
-    // ----------------------------------------------------------------
-    // value & scale accessors
-    // ----------------------------------------------------------------
-    /**
-     * Retrieve the underlying integer (measured in {@link scale} units).
-     *
-     * @returns The stored integer.
-     *
-     * @docs
-     */
-    value() {
-        return this.int_value;
-    }
-    /**
-     * Conver the stored integer to a `number`.
-     *
-     * @returns The amount in stored integer units as `number` instead of `bigint`.
-     * @throws Error if the stored integer cannot be represented safely as a `number`.
-     *
-     * @docs
-     */
-    to_number() {
-        // Convert to number only when the stored integer can be represented safely as a JS number.
-        const max_safe = BigInt(Number.MAX_SAFE_INTEGER);
-        if (this.int_value > max_safe || this.int_value < -max_safe) {
-            throw new Error(`Cannot represent value as number safely for to_number(): ${this.int_value.toString()}`);
-        }
-        return Number(this.int_value);
-    }
-    /**
-     * Alias of {@link value}. Provided for JavaScript numeric coercion.
-     *
-     * @returns The stored integer.
-     *
-     * @docs
-     */
-    valueOf() {
-        return this.int_value;
-    }
-    /**
-     * Retrieve this instance's canonical scale.
-     *
-     * @returns The positive integer scale for this value.
-     *
-     * @docs
-     */
-    scale() {
-        return this.int_scale;
-    }
-    // ----------------------------------------------------------------
-    // presentation conversion
-    // ----------------------------------------------------------------
-    /**
-     * Convert to base scale (1) as a floating-point number (presentation).
-     *
-     * @returns The amount in base units as a float.
-     *
-     * @docs
-     */
-    to_base_float() {
-        if (this.int_scale === SafeInt.Scale.Base)
-            return this.to_number();
-        const denom = BigInt(this.int_scale);
-        const q = this.int_value / denom;
-        const r = this.int_value % denom;
-        const max_safe = BigInt(Number.MAX_SAFE_INTEGER);
-        if (q > max_safe || q < -max_safe) {
-            throw new Error(`Cannot represent base float safely: quotient ${q.toString()} out of range`);
-        }
-        // r fits in denom; denom is a safe integer scale, so Number(denom) is safe
-        return Number(q) + Number(r) / Number(denom);
-    }
-    // ----------------------------------------------------------------
-    // scale conversion — strongly typed
-    // ----------------------------------------------------------------
-    /**
-     * Convert this instance to another integer scale.
-     * **Exact by default** — provide a {@link SafeInt.Rounding} to allow rounding.
-     *
-     * @typeParam T - Target scale (see {@link SafeInt.Scale}).
-     * @param to_scale The target canonical scale.
-     * @param round     Rounding mode for non-exact ratios (default `"exact"`).
-     *
-     * @returns A new {@link SafeInt} typed as `SafeInt<T>`, storing an integer at `to_scale`.
-     *
-     * @docs
-     */
-    to_scale(to_scale, round = "exact") {
-        // validate target scale
-        if (!Number.isSafeInteger(to_scale) || to_scale <= 0) {
-            throw new Error(`Invalid to_scale: expected positive safe integer, got ${to_scale}`);
-        }
-        if (this.int_scale === to_scale) {
-            // Preserve type at call-site
-            return new SafeInt(this.int_value, to_scale);
-        }
-        if (to_scale === SafeInt.Scale.Base) {
-            const base_int = SafeInt.div_to_base(this.int_value, this.int_scale, round);
-            return new SafeInt(base_int, SafeInt.Scale.Base);
-        }
-        if (this.int_scale === SafeInt.Scale.Base) {
-            // base-scale values are stored as integers; multiplying by `to_scale` stays integer-safe in bigint space
-            const product = this.int_value * BigInt(to_scale);
-            return new SafeInt(product, to_scale);
-        }
-        const n = SafeInt.convert_int_scale(this.int_value, this.int_scale, to_scale, round);
-        return new SafeInt(n, to_scale);
-    }
-    /**
-     * Rescale to base (1).
-     *
-     * @returns A new `SafeInt<SafeInt.Scale.Base>`.
-     *
-     * @docs
-     */
-    base() {
-        return this.to_scale(SafeInt.Scale.Base);
-    }
-    /**
-     * Rescale to milli (1e3).
-     *
-     * @returns A new `SafeInt<SafeInt.Scale.Milli>`.
-     *
-     * @docs
-     */
-    milli() {
-        return this.to_scale(SafeInt.Scale.Milli);
-    }
-    /**
-     * Rescale to micro (1e6).
-     *
-     * @returns A new `SafeInt<SafeInt.Scale.Micro>`.
-     *
-     * @docs
-     */
-    micro() {
-        return this.to_scale(SafeInt.Scale.Micro);
-    }
-    /**
-     * Rescale to nano (1e9).
-     *
-     * @returns A new `SafeInt<SafeInt.Scale.Nano>`.
-     *
-     * @docs
-     */
-    nano() {
-        return this.to_scale(SafeInt.Scale.Nano);
-    }
-    /**
-     * Rescale to pico (1e12).
-     *
-     * @returns A new `SafeInt<SafeInt.Scale.Pico>`.
-     *
-     * @docs
-     */
-    pico() {
-        return this.to_scale(SafeInt.Scale.Pico);
-    }
-    // ----------------------------------------------------------------
-    // arithmetic — same-scale only
-    // ----------------------------------------------------------------
-    /**
-     * Add an amount at the same scale.
-     *
-     * @param other The addend, as a raw safe integer or a `SafeInt<S>`.
-     * @returns     A new `SafeInt<S>` with the sum.
-     *
-     * @throws Error If the operand is invalid.
-     *
-     * @docs
-     */
-    add(other) {
-        const b = typeof other === "number"
-            ? (Number.isSafeInteger(other) ? BigInt(other) : (() => { throw new Error(`Invalid 'addend': expected a safe integer, got ${other}`); })())
-            : (typeof other === "bigint" ? other : other.int_value);
-        const sum = this.int_value + b;
-        return new SafeInt(sum, this.int_scale);
-    }
-    /**
-     * Subtract an amount at the same scale.
-     *
-     * @param other The subtrahend, as a raw safe integer or a `SafeInt<S>`.
-     * @returns     A new `SafeInt<S>` with the difference.
-     *
-     * @throws Error If the operand is invalid.
-     *
-     * @docs
-     */
-    sub(other) {
-        const b = typeof other === "number"
-            ? (Number.isSafeInteger(other) ? BigInt(other) : (() => { throw new Error(`Invalid 'subtrahend': expected a safe integer, got ${other}`); })())
-            : (typeof other === "bigint" ? other : other.int_value);
-        const diff = this.int_value - b;
-        return new SafeInt(diff, this.int_scale);
-    }
-    /**
-     * Multiply by an integer factor at the same scale.
-     *
-     * @param factor The factor as a raw safe integer or a `SafeInt<S>`.
-     * @returns      A new `SafeInt<S>` with the product.
-     *
-     * @throws Error If the factor is invalid.
-     *
-     * @docs
-     */
-    mul(factor) {
-        const f = typeof factor === "number"
-            ? (Number.isSafeInteger(factor) ? BigInt(factor) : (() => { throw new Error(`Invalid 'factor': expected a safe integer, got ${factor}`); })())
-            : (typeof factor === "bigint" ? factor : factor.int_value);
-        const product = this.int_value * f;
-        return new SafeInt(product, this.int_scale);
-    }
-    /**
-     * Divide by a positive integer divisor at the same scale.
-     *
-     * @param divisor Positive safe integer or `SafeInt<S>` divisor.
-     * @param round    Rounding mode. Default `"exact"` requires no remainder.
-     * @returns       A new `SafeInt<S>` with the integer quotient (per {@link round}).
-     *
-     * @throws Error If the divisor is invalid, division by zero, or non-exact remainder in `"exact"` round.
-     *
-     * @docs
-     */
-    div(divisor, round = "exact") {
-        const d = typeof divisor === "number"
-            ? (Number.isSafeInteger(divisor) ? BigInt(divisor) : (() => { throw new Error(`Invalid 'divisor': expected a non-zero safe integer, got ${divisor}`); })())
-            : (typeof divisor === "bigint" ? divisor : divisor.int_value);
-        if (d === 0n) {
-            throw new Error(`Invalid 'divisor': expected a non-zero safe integer, got 0`);
-        }
-        const q = SafeInt.div_int_checked(this.int_value, d, round);
-        return new SafeInt(q, this.int_scale);
-    }
-    // ----------------------------------------------------------------
-    // comparisons — same-scale only
-    // ----------------------------------------------------------------
-    /**
-     * Compare with another `SafeInt<S>`.
-     *
-     * @param other The other amount (same scale).
-     * @returns     `-1` if this < other, `0` if equal, `1` if this > other.
-     *
-     * @docs
-     */
-    cmp(other) {
-        const rhs = other.int_value;
-        if (this.int_value < rhs)
-            return -1;
-        if (this.int_value > rhs)
-            return 1;
-        return 0;
-    }
-    /**
-     * Test equality with another `SafeInt<S>`.
-     *
-     * @param other The other amount (same scale).
-     * @returns     `true` if equal, otherwise `false`.
-     *
-     * @docs
-     */
-    eq(other) {
-        return this.cmp(other) === 0;
-    }
-    // ----------------------------------------------------------------
-    // Member & static assertions.
-    // ----------------------------------------------------------------
-    /**
-     * Assert `value` is a `>=0` integer.
-     *
-     * @docs
-     */
-    assert_non_negative() {
-        if (this.int_value < 0n) {
-            throw new Error(`Invalid value: expected non-negative integer, got ${this.int_value.toString()}`);
-        }
-    }
-    /**
-     * Assert `value` is a `>0` integer.
-     *
-     * @docs
-     */
-    assert_positive() {
-        if (this.int_value <= 0n) {
-            throw new Error(`Invalid value: expected positive integer, got ${this.int_value.toString()}`);
-        }
-    }
-    /**
-     * Assert `value` is a `<=0` integer.
-     *
-     * @docs
-     */
-    assert_non_positive() {
-        if (this.int_value > 0n) {
-            throw new Error(`Invalid value: expected non-positive integer, got ${this.int_value.toString()}`);
-        }
-    }
-    /**
-     * Assert `value` is a `<0` integer.
-     *
-     * @docs
-     */
-    assert_negative() {
-        if (this.int_value >= 0n) {
-            throw new Error(`Invalid value: expected negative integer, got ${this.int_value.toString()}`);
-        }
-    }
-    /**
-     * Assert `value` is a `>=0` safe integer.
-     *
-     * @docs
-     */
-    static assert_non_negative(value, label) {
-        if (!Number.isSafeInteger(value) || value < 0) {
-            throw new Error(`Invalid '${label}': expected non-negative safe integer, got ${value}`);
-        }
-    }
-    /**
-     * Assert `value` is a `>0` safe integer.
-     *
-     * @docs
-     */
-    static assert_positive(value, label) {
-        if (!Number.isSafeInteger(value) || value <= 0) {
-            throw new Error(`Invalid '${label}': expected positive safe integer, got ${value}`);
-        }
-    }
-    /**
-     * Assert `value` is a `<=0` safe integer.
-     *
-     * @docs
-     */
-    static assert_non_positive(value, label) {
-        if (!Number.isSafeInteger(value) || value > 0) {
-            throw new Error(`Invalid '${label}': expected non-positive safe integer, got ${value}`);
-        }
-    }
-    /**
-     * Assert `value` is a `<0` safe integer.
-     *
-     * @docs
-     */
-    static assert_negative(value, label) {
-        if (!Number.isSafeInteger(value) || value >= 0) {
-            throw new Error(`Invalid '${label}': expected negative safe integer, got ${value}`);
-        }
-    }
-    // ----------------------------------------------------------------
-    // static helpers (internal)
-    // ----------------------------------------------------------------
-    /**
-     * Apply a rounding to a floating value.
-     *
-     * @param v    Floating value to round.
-     * @param round Rounding mode.
-     * @returns    Rounded integer (validated by the caller).
-     * @internal
-     */
-    static apply_round(v, round) {
-        if (!Number.isFinite(v))
-            throw new Error(`Invalid value for rounding: ${v}`);
-        if (round === "floor")
-            return Math.floor(v);
-        if (round === "ceil")
-            return Math.ceil(v);
-        if (round === "round")
-            return Math.round(v);
-        throw new Error(`apply_round() called with round='exact' which forbids rounding`);
-    }
-    /**
-     * Parse an integer string into bigint.
-     * - Allows optional leading +/-.
-     * - Allows underscores as separators.
-     * - Rejects decimals.
-     *
-     * @internal
-     */
-    static parse_int_str(text, label) {
-        const s = text.trim().replace(/_/g, "");
-        if (s.length === 0)
-            throw new Error(`Invalid '${label}': empty string`);
-        if (!/^[+-]?\d+$/.test(s)) {
-            throw new Error(`Invalid '${label}': expected integer string, got '${text}'`);
-        }
-        // BigInt() accepts leading +/- and digits.
-        return BigInt(s);
-    }
-    /**
-     * Parse a base-scale decimal string and convert to an integer at `to_scale` using bigint math.
-     *
-     * Examples:
-     *  "1.5" with to_scale=1000 => 1500
-     *  "-0.001" with to_scale=1000 => -1
-     *
-     * - Underscores are allowed.
-     * - Exact by default; non-exact requires a rounding mode.
-     *
-     * @internal
-     */
-    static parse_base_decimal_to_scaled(text, to_scale, round) {
-        const raw = text.trim().replace(/_/g, "");
-        if (raw.length === 0)
-            throw new Error(`Invalid 'value': empty string`);
-        let sign = 1n;
-        let s = raw;
-        if (s[0] === "+")
-            s = s.slice(1);
-        else if (s[0] === "-") {
-            sign = -1n;
-            s = s.slice(1);
-        }
-        if (s.length === 0)
-            throw new Error(`Invalid 'value': expected digits, got '${text}'`);
-        const parts = s.split(".");
-        if (parts.length > 2)
-            throw new Error(`Invalid 'value': too many decimal points in '${text}'`);
-        const int_part = parts[0] === "" ? "0" : parts[0];
-        const frac_part = parts.length === 2 ? (parts[1] ?? "") : "";
-        if (!/^\d+$/.test(int_part)) {
-            throw new Error(`Invalid 'value': invalid integer part in '${text}'`);
-        }
-        if (frac_part !== "" && !/^\d+$/.test(frac_part)) {
-            throw new Error(`Invalid 'value': invalid fractional part in '${text}'`);
-        }
-        const k = frac_part.length;
-        const denom = k === 0 ? 1n : SafeInt.pow10(k);
-        const whole = BigInt(int_part);
-        const frac = frac_part === "" ? 0n : BigInt(frac_part);
-        const numerator = (whole * denom + frac) * sign; // value = numerator / denom
-        // scaled = (numerator * to_scale) / denom with rounding
-        const scaled_num = numerator * BigInt(to_scale);
-        return SafeInt.div_int_checked(scaled_num, denom, round);
-    }
-    /**
-     * Compute 10^n as bigint.
-     * @internal
-     */
-    static pow10(n) {
-        if (!Number.isSafeInteger(n) || n < 0) {
-            throw new Error(`Invalid pow10 exponent: ${n}`);
-        }
-        // Guard against pathological inputs (optional; adjust as you like)
-        if (n > 1_000) {
-            throw new Error(`Invalid decimal precision: ${n} (too large)`);
-        }
-        // Fast enough for typical precision values; avoids floating-point.
-        return BigInt("1" + "0".repeat(n));
-    }
-    /**
-     * Convert integer-scale value → base **integer** using a rounding policy.
-     *
-     * @param value      Integer at `from_scale` (may be negative).
-     * @param from_scale Source scale.
-     * @param round       Rounding (default exact).
-     * @returns          Base-scale integer.
-     * @internal
-     */
-    static div_to_base(value, from_scale, round) {
-        const denom = BigInt(from_scale);
-        if (round === "exact") {
-            if (value % denom !== 0n) {
-                throw new Error(`Exact conversion to base failed: ${value.toString()} % ${from_scale} !== 0`);
-            }
-            return value / denom;
-        }
-        return SafeInt.div_int_checked(value, denom, round);
-    }
-    /**
-     * Integer division helper with selectable rounding semantics.
-     *
-     * @param numerator   Integer (may be negative).
-     * @param denominator Positive integer.
-     * @param round        Rounding mode (default `"exact"`).
-     * @returns           Integer quotient as per {@link round}.
-     *
-     * @throws Error On invalid inputs, division by zero, or non-exact remainder in `"exact"`.
-     * @internal
-     */
-    static div_int_checked(numerator, denominator, round = "exact") {
-        if (denominator <= 0n)
-            throw new Error(`Invalid denominator: ${denominator.toString()}`);
-        const q = numerator / denominator; // trunc toward 0
-        const rem = numerator % denominator; // same sign as numerator
-        if (round === "exact") {
-            if (rem !== 0n)
-                throw new Error(`Non-exact division: ${numerator.toString()} / ${denominator.toString()} leaves remainder ${rem.toString()}`);
-            return q;
-        }
-        if (rem === 0n)
-            return q;
-        if (round === "floor") {
-            // if numerator is negative, trunc is "too high" (closer to 0) compared to floor
-            return numerator < 0n ? q - 1n : q;
-        }
-        if (round === "ceil") {
-            // if numerator is positive, trunc is "too low" compared to ceil
-            return numerator > 0n ? q + 1n : q;
-        }
-        if (round === "round") {
-            const absRem = rem < 0n ? -rem : rem;
-            const twice = absRem * 2n;
-            if (twice < denominator)
-                return q;
-            // ties + above: move away from zero
-            return numerator >= 0n ? q + 1n : q - 1n;
-        }
-        throw new Error(`Invalid round: ${round}`);
-    }
-    /**
-     * Integer-only scale converter with rounding policy.
-     *
-     * @param value       Integer at {@link from_scale} (may be negative).
-     * @param from_scale  Integer source scale.
-     * @param to_scale    Integer target scale.
-     * @param round        Rounding mode (default exact).
-     * @returns           Integer at `to_scale`.
-     *
-     * @throws Error On invalid inputs.
-     * @internal
-     */
-    static convert_int_scale(value, from_scale, to_scale, round) {
-        if (!Number.isSafeInteger(from_scale) || from_scale <= 0) {
-            throw new Error(`Invalid from_scale: expected positive safe integer, got ${from_scale}`);
-        }
-        if (!Number.isSafeInteger(to_scale) || to_scale <= 0) {
-            throw new Error(`Invalid to_scale: expected positive safe integer, got ${to_scale}`);
-        }
-        if (from_scale === to_scale)
-            return value;
-        // exact divisor path
-        if (from_scale % to_scale === 0) {
-            const divisor = BigInt(Math.trunc(from_scale / to_scale));
-            return SafeInt.div_int_checked(value, divisor, round);
-        }
-        // exact multiplier path
-        if (to_scale % from_scale === 0) {
-            const multiplier = BigInt(Math.trunc(to_scale / from_scale));
-            return value * multiplier;
-        }
-        // general ratio: (value * to_scale) / from_scale with chosen rounding
-        const numerator = value * BigInt(to_scale);
-        return SafeInt.div_int_checked(numerator, BigInt(from_scale), round);
-    }
-}
-/* ============================================================================
-   Namespace: shared types & constants for SafeInt
-   ========================================================================== */
-(function (SafeInt) {
-    /**
-     * Canonical integer scales (units-per-base).
-     *
-     * @example
-     * Base = 1, Milli = 1e3, Micro = 1e6, Nano = 1e9, Pico = 1e12
-     *
-     * @docs
-     */
-    let Scale;
-    (function (Scale) {
-        /** Base units (whole units). */
-        Scale[Scale["Base"] = 1] = "Base";
-        /** Milli units (1e3 per base). */
-        Scale[Scale["Milli"] = 1000] = "Milli";
-        /** Micro units (1e6 per base). */
-        Scale[Scale["Micro"] = 1000000] = "Micro";
-        /** Nano units (1e9 per base). */
-        Scale[Scale["Nano"] = 1000000000] = "Nano";
-        /** Pico units (1e12 per base). */
-        Scale[Scale["Pico"] = 1000000000000] = "Pico";
-    })(Scale = SafeInt.Scale || (SafeInt.Scale = {}));
-    /** Convert a string scale to the actual scale. */
-    function str_to_scale(scale) {
-        switch (scale) {
-            case "base": return Scale.Base;
-            case "milli": return Scale.Milli;
-            case "micro": return Scale.Micro;
-            case "nano": return Scale.Nano;
-            case "pico": return Scale.Pico;
-            default: throw new Error(`Unknown scale: ${scale}`);
-        }
-    }
-    SafeInt.str_to_scale = str_to_scale;
-})(SafeInt || (SafeInt = {}));