atomic-fns 1.2.0 → 2.0.0

package/dist/decimal/currency.js

@@ -0,0 +1,321 @@
+var _a;
+import { Decimal } from './decimal.js';
+import { quoteForError } from './internal/echo.js';
+import { isoMinorUnits } from './internal/minor-units.js';
+/** Fraction digits {@link Currency.format} shows by default, so an exact amount keeps its digits. */
+const EXACT_FRACTION_DIGITS = 20;
+const CURRENCY_CODE = /^[A-Za-z]{3}$/;
+function minorUnitDigits(code) {
+    const digits = isoMinorUnits(code);
+    if (digits === undefined) {
+        throw new RangeError(`${code} has no ISO 4217 minor unit; pass the digits to round()`);
+    }
+    return digits;
+}
+/** True unless `options` already say how many digits to show. */
+function showsExactDigits(options) {
+    return (options.maximumFractionDigits === undefined &&
+        options.minimumSignificantDigits === undefined &&
+        options.maximumSignificantDigits === undefined &&
+        (options.roundingIncrement ?? 1) === 1 &&
+        (options.notation ?? 'standard') === 'standard');
+}
+function assertCurrency(value) {
+    if (!(value instanceof Currency))
+        throw new TypeError('expected a Currency');
+}
+/**
+ * An exact amount of money in one ISO 4217 currency, as the TC39 Amount proposal pairs a value
+ * with its unit. Arithmetic and ordering with another currency throw `RangeError`; nothing
+ * converts between currencies.
+ *
+ * @example
+ * ```ts
+ * const price = new Currency('19.99', 'USD')
+ * price.multiply(3).format('en-US') // '$59.97'
+ * price.add(new Currency('0.01', 'USD')).toString() // '20 USD'
+ * ```
+ */
+export class Currency {
+    /**
+     * Orders two amounts of the same currency, for `toSorted` and sorted collections.
+     * @throws {TypeError} when `a` or `b` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * [new Currency(5, 'EUR'), new Currency(2, 'EUR')].toSorted(Currency.compare).map(String)
+     * // ['2 EUR', '5 EUR']
+     * ```
+     */
+    static compare(a, b) {
+        assertCurrency(a);
+        return a.compare(b);
+    }
+    #amount;
+    #currency;
+    /**
+     * Pairs an amount with a currency code.
+     * @param amount The amount, read as {@link Decimal} reads it.
+     * @param currency A three-letter ISO 4217 code, in any case.
+     * @throws {TypeError} when `currency` is not a string, or `amount` not a Decimal input.
+     * @throws {RangeError} when `currency` is not three letters, or `amount` is malformed.
+     * @example
+     * ```ts
+     * new Currency('12.50', 'usd').currency // 'USD'
+     * ```
+     */
+    constructor(amount, currency) {
+        if (typeof currency !== 'string')
+            throw new TypeError('currency must be a string');
+        if (!CURRENCY_CODE.test(currency)) {
+            throw new RangeError(`currency must be a three-letter ISO 4217 code, not ${quoteForError(currency)}`);
+        }
+        this.#amount = amount instanceof Decimal ? amount : new Decimal(amount);
+        this.#currency = currency.toUpperCase();
+    }
+    /** The exact amount. */
+    get amount() {
+        return this.#amount;
+    }
+    /** The upper-case ISO 4217 code, such as `'USD'`. */
+    get currency() {
+        return this.#currency;
+    }
+    #with(amount) {
+        return new _a(amount, this.#currency);
+    }
+    #amountOf(other) {
+        assertCurrency(other);
+        if (other.#currency !== this.#currency) {
+            throw new RangeError(`currency mismatch: ${this.#currency} and ${other.#currency}`);
+        }
+        return other.#amount;
+    }
+    /**
+     * The sum of two amounts of the same currency.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency('0.1', 'USD').add(new Currency('0.2', 'USD')).toString() // '0.3 USD'
+     * ```
+     */
+    add(other) {
+        return this.#with(this.#amount.add(this.#amountOf(other)));
+    }
+    /**
+     * The difference of two amounts of the same currency.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(10, 'EUR').subtract(new Currency('2.5', 'EUR')).toString() // '7.5 EUR'
+     * ```
+     */
+    subtract(other) {
+        return this.#with(this.#amount.subtract(this.#amountOf(other)));
+    }
+    /**
+     * This amount times a plain factor.
+     * @example
+     * ```ts
+     * new Currency('19.99', 'USD').multiply(3).toString() // '59.97 USD'
+     * ```
+     */
+    multiply(factor) {
+        return this.#with(this.#amount.multiply(factor));
+    }
+    /**
+     * This amount divided by a plain divisor, rounded as {@link Decimal.divide} rounds, to 34
+     * significant digits by default; follow with {@link Currency.round} for the minor unit.
+     * @throws {RangeError} for a zero divisor.
+     * @example
+     * ```ts
+     * new Currency(10, 'USD').divide(3).round().toString() // '3.33 USD'
+     * ```
+     */
+    divide(divisor, options) {
+        return this.#with(this.#amount.divide(divisor, options));
+    }
+    /**
+     * This amount with the opposite sign.
+     * @example
+     * ```ts
+     * new Currency(5, 'USD').negate().toString() // '-5 USD'
+     * ```
+     */
+    negate() {
+        return this.#with(this.#amount.negate());
+    }
+    /**
+     * The absolute amount.
+     * @example
+     * ```ts
+     * new Currency(-5, 'USD').abs().toString() // '5 USD'
+     * ```
+     */
+    abs() {
+        return this.#with(this.#amount.abs());
+    }
+    /**
+     * Rounds the amount, by default to the currency's ISO 4217 minor unit (2 digits for USD, 0 for
+     * JPY, 3 for IQD). The mode defaults to `'halfEven'`, while {@link Currency.format} rounds what
+     * it shows half away from zero, as `Intl.NumberFormat` does.
+     * @param digits Fractional digits (may be negative); defaults to the minor unit.
+     * @param roundingMode One of the `Intl.NumberFormat` rounding modes; defaults to `'halfEven'`.
+     * @throws {RangeError} when `digits` is left out and ISO 4217 gives the code no minor unit, as
+     * for XAU or a code it does not list.
+     * @example
+     * ```ts
+     * new Currency('2.675', 'USD').round().toString() // '2.68 USD'
+     * new Currency('1234.5', 'JPY').round().toString() // '1234 JPY'
+     * new Currency('2.665', 'USD').round(undefined, 'halfExpand').toString() // '2.67 USD'
+     * ```
+     */
+    round(digits = minorUnitDigits(this.#currency), roundingMode) {
+        return this.#with(this.#amount.round(digits, roundingMode));
+    }
+    /**
+     * Orders this amount against another of the same currency: -1, 0 or 1.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').compare(new Currency('1.00', 'USD')) // 0
+     * ```
+     */
+    compare(other) {
+        return this.#amount.compare(this.#amountOf(other));
+    }
+    /**
+     * True for a Currency with the same code and amount; false for anything else, including the
+     * same amount in another currency.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').equals(new Currency(1, 'EUR')) // false
+     * ```
+     */
+    equals(other) {
+        return (other instanceof _a &&
+            other.#currency === this.#currency &&
+            this.#amount.equals(other.#amount));
+    }
+    /**
+     * True when this amount is less than `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').lessThan(new Currency(2, 'USD')) // true
+     * ```
+     */
+    lessThan(other) {
+        return this.compare(other) < 0;
+    }
+    /**
+     * True when this amount is less than or equal to `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(2, 'USD').lessThanOrEqual(new Currency(2, 'USD')) // true
+     * ```
+     */
+    lessThanOrEqual(other) {
+        return this.compare(other) <= 0;
+    }
+    /**
+     * True when this amount is greater than `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(3, 'USD').greaterThan(new Currency(2, 'USD')) // true
+     * ```
+     */
+    greaterThan(other) {
+        return this.compare(other) > 0;
+    }
+    /**
+     * True when this amount is greater than or equal to `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(2, 'USD').greaterThanOrEqual(new Currency(3, 'USD')) // false
+     * ```
+     */
+    greaterThanOrEqual(other) {
+        return this.compare(other) >= 0;
+    }
+    /**
+     * Formats with `Intl.NumberFormat` in currency style. Unless `options` set the digits, the
+     * amount keeps its own fraction digits, up to 20, instead of rounding to the minor unit, so
+     * `0.125` dollars show as `$0.125`; pass `{ maximumFractionDigits: 2 }` or {@link Currency.round}
+     * first for minor units. A `roundingMode` alone changes nothing, since no digits are cut; pair it
+     * with `maximumFractionDigits`. `style` and `currency` always come from this amount.
+     * @throws {RangeError} when the amount is beyond `Number.MAX_VALUE`, which `Intl` shows as `∞`,
+     * or the locale is malformed or longer than 255 characters.
+     * @example
+     * ```ts
+     * new Currency('1234.5', 'EUR').format('de-DE') // '1.234,50 €'
+     * new Currency('0.125', 'USD').format('en-US', { maximumFractionDigits: 2 }) // '$0.13'
+     * ```
+     */
+    format(locale, options = {}) {
+        const merged = {
+            ...options,
+            style: 'currency',
+            currency: this.#currency
+        };
+        if (showsExactDigits(merged)) {
+            merged.maximumFractionDigits = Math.max(EXACT_FRACTION_DIGITS, merged.minimumFractionDigits ?? 0);
+        }
+        return this.#amount.toLocaleString(locale, merged);
+    }
+    /**
+     * The same as {@link Currency.format}, under the name `Intl` and Temporal use.
+     * @example
+     * ```ts
+     * new Currency(5, 'GBP').toLocaleString('en-GB') // '£5.00'
+     * ```
+     */
+    toLocaleString(locales, options) {
+        return this.format(locales, options);
+    }
+    /**
+     * The amount's canonical string and the code, such as `'12.5 USD'`, for logs and keys.
+     * @example
+     * ```ts
+     * new Currency('12.50', 'usd').toString() // '12.5 USD'
+     * ```
+     */
+    toString() {
+        return `${this.#amount.toString()} ${this.#currency}`;
+    }
+    /** The same string as {@link Currency.toString}, so `JSON.stringify` keeps every digit. */
+    toJSON() {
+        return this.toString();
+    }
+    /**
+     * What `console.log` and `util.inspect` show, such as `Currency { 12.5 USD }`. The symbol is
+     * the runtime's own inspection hook, read by Node and runtimes compatible with it, not a
+     * protocol of this package.
+     * @example
+     * ```ts
+     * console.log(new Currency('12.50', 'USD')) // Currency { 12.5 USD }
+     * ```
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `Currency { ${this.toString()} }`;
+    }
+    /**
+     * Throws, so `<` and `+` cannot silently compare or add amounts. Use {@link Currency.compare}
+     * or {@link Currency.add}.
+     * @throws {TypeError} always.
+     */
+    valueOf() {
+        throw new TypeError('Currency cannot be converted to a primitive implicitly; use compare(), add() or format()');
+    }
+}
+_a = Currency;

package/dist/decimal/decimal.d.ts

@@ -0,0 +1,299 @@
+/**
+ * How {@link Decimal.divide}, {@link Decimal.round}, {@link Decimal.sqrt} and
+ * {@link Decimal.toFixed} round, with the names `Intl.NumberFormat` uses:
+ * - `ceil`: toward +Infinity.
+ * - `floor`: toward -Infinity.
+ * - `expand`: away from zero.
+ * - `trunc`: toward zero.
+ * - `halfCeil`: nearest, ties toward +Infinity (as `Math.round`).
+ * - `halfFloor`: nearest, ties toward -Infinity.
+ * - `halfExpand`: nearest, ties away from zero (as `Number.prototype.toFixed`).
+ * - `halfTrunc`: nearest, ties toward zero.
+ * - `halfEven`: nearest, ties to the even neighbor (the default).
+ */
+export type RoundingMode = 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven';
+/** Options for {@link Decimal.divide} and {@link Decimal.sqrt}. */
+export interface DivideOptions {
+    /**
+     * Significant digits of the result, from 1 to `Decimal.MAX_DIGITS` (default 34, as the TC39
+     * draft's 128-bit decimals carry). It counts significant digits, not fractional ones.
+     */
+    precision?: number;
+    /** How the last digit rounds (default `'halfEven'`). */
+    roundingMode?: RoundingMode;
+}
+/**
+ * A value {@link Decimal} reads: a Decimal, a decimal string, a bigint or a finite number.
+ * @example
+ * ```ts
+ * const inputs: DecimalInput[] = [new Decimal('1.5'), '2.5', 3n, 4.5]
+ * inputs.map((value) => new Decimal(value).toString()) // ['1.5', '2.5', '3', '4.5']
+ * ```
+ */
+export type DecimalInput = Decimal | string | bigint | number;
+/**
+ * An exact decimal number, shaped after the TC39 Decimal proposal: immutable, with arithmetic
+ * methods instead of operators. Values carry up to {@link Decimal.MAX_DIGITS} significant digits
+ * and an exponent within {@link Decimal.MAX_EXPONENT}; a result past either throws `RangeError`.
+ * Each operation costs time that grows with the digits of its operands, so size-limit untrusted
+ * lists before summing them.
+ *
+ * @example
+ * ```ts
+ * const total = new Decimal('0.1').add('0.2')
+ * total.toString() // '0.3'
+ * total.equals('0.3') // true
+ * ```
+ */
+export declare class Decimal {
+    #private;
+    /** Significant digits a Decimal holds; longer inputs and results throw `RangeError`. */
+    static get MAX_DIGITS(): number;
+    /** Largest absolute exponent a Decimal stores; larger values throw `RangeError`. */
+    static get MAX_EXPONENT(): number;
+    /** Largest fractional `digits` {@link Decimal.round} and {@link Decimal.toFixed} take. */
+    static get MAX_PRECISION(): number;
+    /**
+     * Orders two values, for `toSorted` and sorted collections.
+     * @example
+     * ```ts
+     * ['10', '9', '9.5'].map((s) => new Decimal(s)).toSorted(Decimal.compare).map(String)
+     * // ['9', '9.5', '10']
+     * ```
+     */
+    static compare(a: DecimalInput, b: DecimalInput): -1 | 0 | 1;
+    /**
+     * Reads a Decimal, a decimal string (`'-1.5'`, `'.5'`, `'2e-3'`, surrounding spaces allowed),
+     * a bigint, or a finite number through its shortest round-trip string, so `new Decimal(0.1)`
+     * is exactly `0.1`.
+     * @throws {TypeError} for any other type.
+     * @throws {RangeError} for a malformed string, a non-finite number, or a value past the bounds.
+     * @example
+     * ```ts
+     * new Decimal('1.50').toString() // '1.5'
+     * new Decimal(2n ** 64n).toString() // '18446744073709551616'
+     * ```
+     */
+    constructor(value: DecimalInput);
+    /**
+     * The exact sum.
+     * @example
+     * ```ts
+     * new Decimal('0.1').add('0.2').toString() // '0.3'
+     * ```
+     */
+    add(other: DecimalInput): Decimal;
+    /**
+     * The exact difference.
+     * @example
+     * ```ts
+     * new Decimal('1').subtract('0.9').toString() // '0.1'
+     * ```
+     */
+    subtract(other: DecimalInput): Decimal;
+    /**
+     * The exact product.
+     * @example
+     * ```ts
+     * new Decimal('1.5').multiply('-2').toString() // '-3'
+     * ```
+     */
+    multiply(other: DecimalInput): Decimal;
+    /**
+     * The quotient rounded to `precision` significant digits (default 34), as the TC39 draft
+     * rounds, so `new Decimal('1e-30').divide(3)` keeps its scale. An exact quotient with fewer
+     * digits is returned whole.
+     * @throws {TypeError} for `options` that is not an object.
+     * @throws {RangeError} for a zero divisor, a `precision` out of range, an unknown mode, or a
+     * rounded quotient past the exponent bound: one too large, or one whose last digit falls below
+     * `10^-Decimal.MAX_EXPONENT`, as `new Decimal('1e-9990').divide(3)` does at 34 digits.
+     * @example
+     * ```ts
+     * new Decimal(1).divide(3).toString() // '0.3333333333333333333333333333333333'
+     * new Decimal(2).divide(3, { precision: 2, roundingMode: 'trunc' }).toString() // '0.66'
+     * new Decimal(1).divide(8).toString() // '0.125'
+     * ```
+     */
+    divide(other: DecimalInput, options?: DivideOptions): Decimal;
+    /**
+     * The exact remainder of truncating division, with the sign of this value, as `%` gives.
+     * @throws {RangeError} for a zero divisor.
+     * @example
+     * ```ts
+     * new Decimal('7.5').remainder(2).toString() // '1.5'
+     * new Decimal('-7.5').remainder(2).toString() // '-1.5'
+     * ```
+     */
+    remainder(other: DecimalInput): Decimal;
+    /**
+     * This value with the opposite sign.
+     * @example
+     * ```ts
+     * new Decimal('5').negate().toString() // '-5'
+     * ```
+     */
+    negate(): Decimal;
+    /**
+     * The absolute value.
+     * @example
+     * ```ts
+     * new Decimal('-1.5').abs().toString() // '1.5'
+     * ```
+     */
+    abs(): Decimal;
+    /**
+     * Rounds to `digits` fractional digits; a negative count rounds to tens, hundreds, and so on.
+     * @param digits Fractional digits, from `-Decimal.MAX_EXPONENT` to `Decimal.MAX_PRECISION`
+     * (default 0).
+     * @param roundingMode How ties and remainders round (default `'halfEven'`).
+     * @throws {RangeError} for `digits` out of range, an unknown mode, or a result past the
+     * exponent bound.
+     * @example
+     * ```ts
+     * new Decimal('2.5').round().toString() // '2'
+     * new Decimal('2.5').round(0, 'halfExpand').toString() // '3'
+     * new Decimal('1234').round(-2).toString() // '1200'
+     * ```
+     */
+    round(digits?: number, roundingMode?: RoundingMode): Decimal;
+    /**
+     * The square root rounded to `precision` significant digits (default 34). An exact root with
+     * fewer digits is returned whole.
+     * @throws {TypeError} for `options` that is not an object.
+     * @throws {RangeError} for a negative value, a `precision` out of range, an unknown mode, or a
+     * rounded root whose last digit falls below `10^-Decimal.MAX_EXPONENT`.
+     * @example
+     * ```ts
+     * new Decimal(2).sqrt().toString() // '1.414213562373095048801688724209698'
+     * new Decimal('6.25').sqrt().toString() // '2.5'
+     * new Decimal(2).sqrt({ precision: 5 }).toString() // '1.4142'
+     * ```
+     */
+    sqrt(options?: DivideOptions): Decimal;
+    /**
+     * Orders this value against `other`: -1, 0 or 1.
+     * @example
+     * ```ts
+     * new Decimal('1.10').compare('1.1') // 0
+     * new Decimal('-2').compare(1) // -1
+     * ```
+     */
+    compare(other: DecimalInput): -1 | 0 | 1;
+    /**
+     * True when both are the same number, whatever their written form.
+     * @example
+     * ```ts
+     * new Decimal('2.50').equals('2.5') // true
+     * ```
+     */
+    equals(other: DecimalInput): boolean;
+    /**
+     * True when this value is less than `other`.
+     * @example
+     * ```ts
+     * new Decimal('0.1').lessThan('0.2') // true
+     * ```
+     */
+    lessThan(other: DecimalInput): boolean;
+    /**
+     * True when this value is less than or equal to `other`.
+     * @example
+     * ```ts
+     * new Decimal('0.2').lessThanOrEqual('0.20') // true
+     * ```
+     */
+    lessThanOrEqual(other: DecimalInput): boolean;
+    /**
+     * True when this value is greater than `other`.
+     * @example
+     * ```ts
+     * new Decimal('1e3').greaterThan(999) // true
+     * ```
+     */
+    greaterThan(other: DecimalInput): boolean;
+    /**
+     * True when this value is greater than or equal to `other`.
+     * @example
+     * ```ts
+     * new Decimal('-0').greaterThanOrEqual(0) // true
+     * ```
+     */
+    greaterThanOrEqual(other: DecimalInput): boolean;
+    /**
+     * The canonical string: plain notation while that pads at most 64 zeros, scientific past that
+     * (`'1e+65'`, `'1.5e-70'`), so its length follows the significant digits and not the exponent.
+     * The constructor reads both forms back.
+     * @example
+     * ```ts
+     * new Decimal('1.50').toString() // '1.5'
+     * new Decimal('1e100').toString() // '1e+100'
+     * ```
+     */
+    toString(): string;
+    /**
+     * Plain notation at any magnitude. A short input such as `'1e10000'` expands to 10,001
+     * characters, so prefer {@link Decimal.toString} for untrusted values.
+     * @example
+     * ```ts
+     * new Decimal('1e5').toPlainString() // '100000'
+     * new Decimal('-1.5e-3').toPlainString() // '-0.0015'
+     * ```
+     */
+    toPlainString(): string;
+    /**
+     * Plain notation with exactly `digits` fractional digits. Ties round half away from zero
+     * (`'halfExpand'`), as `Number.prototype.toFixed` rounds, not half to even as
+     * {@link Decimal.round} does by default; pass `roundingMode` to choose another.
+     * @param digits Fractional digits, from 0 to `Decimal.MAX_PRECISION` (default 0).
+     * @param roundingMode How the last digit rounds (default `'halfExpand'`).
+     * @throws {RangeError} for `digits` out of range or an unknown mode.
+     * @example
+     * ```ts
+     * new Decimal('2.5').toFixed() // '3'
+     * new Decimal('1.005').toFixed(2) // '1.01'
+     * new Decimal('3').toFixed(2) // '3.00'
+     * ```
+     */
+    toFixed(digits?: number, roundingMode?: RoundingMode): string;
+    /** The canonical string, as {@link Decimal.toString}, so `JSON.stringify` keeps every digit. */
+    toJSON(): string;
+    /**
+     * Formats the exact value with `Intl.NumberFormat`, which reads decimal strings without going
+     * through a `Number`, so digits past 2^53 survive.
+     * @throws {RangeError} when the value is beyond `Number.MAX_VALUE`, which `Intl` shows as `∞`,
+     * or so close to zero that it rounds to a `Number` zero, which `Intl` may show as `0`.
+     * @throws {RangeError} for a malformed locale tag, or a locale list longer than 255 characters
+     * joined, which `Intl` canonicalizes in quadratic time.
+     * @throws {TypeError} for a locale that is neither a string nor an `Intl.Locale`.
+     * @example
+     * ```ts
+     * new Decimal('12345678901234567.25').toLocaleString('en-US', { maximumFractionDigits: 2 })
+     * // '12,345,678,901,234,567.25'
+     * ```
+     */
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string;
+    /**
+     * The nearest `Number`, read from the coefficient and exponent, so extreme exponents stay cheap.
+     * @example
+     * ```ts
+     * new Decimal('0.1').toNumber() // 0.1
+     * new Decimal('1e400').toNumber() // Infinity
+     * ```
+     */
+    toNumber(): number;
+    /**
+     * The value as a bigint.
+     * @throws {RangeError} when the value has a fractional part.
+     * @example
+     * ```ts
+     * new Decimal('1.2e3').toBigInt() // 1200n
+     * ```
+     */
+    toBigInt(): bigint;
+    /**
+     * Throws, so `<`, `+` and `==` cannot silently turn a Decimal into a lossy `Number`. Use
+     * {@link Decimal.compare}, {@link Decimal.add} or {@link Decimal.toNumber}.
+     * @throws {TypeError} always.
+     */
+    valueOf(): never;
+}