@fulcro/types 0.1.0

package/dist/decimal/index.d.ts

@@ -0,0 +1,296 @@
+import { type RoundingMode } from '../roundingMode/index.js';
+/**
+ * A decimal floating point number with the semantics of IEEE 754 decimal128:
+ * thirty-four significant digits, exponents from -6143 to 6144, and the
+ * special values `NaN`, `Infinity`, `-Infinity` and `-0`.
+ *
+ * ```ts
+ * const price = Decimal.from('19.99');
+ *
+ * price.multiply(Decimal.from(3)).toString(); // '59.97'
+ * Decimal.from('0.1').add(Decimal.from('0.2')).equals(Decimal.from('0.3')); // true
+ * ```
+ *
+ * The semantics are those of the TC39 Decimal proposal, so that code written
+ * against this class reads the same against a native one:
+ *
+ * - **Trailing zeros are not observable.** `'1.20'` and `'1.2'` are the same
+ *   value and print the same way.
+ * - **Every operation rounds once**, to thirty-four digits, half to even unless
+ *   a mode is given. An exact result is never rounded.
+ * - **Operators refuse it.** `a + b`, `a < b` and `a == 1` throw a `TypeError`
+ *   instead of coercing: an implicit conversion to `number` would lose exactly
+ *   the digits the type exists to keep. Use the methods.
+ * - **Division by zero is not an error**, as in IEEE 754: it gives an infinity,
+ *   and zero over zero gives `NaN`.
+ *
+ * Values are immutable. The layout is sixteen bytes aligned on sixteen, that of
+ * decimal128 — which is what `sizeOf<Decimal>()` reports, not what an instance
+ * costs in a JavaScript heap.
+ */
+export declare class Decimal {
+    #private;
+    /** Layout of decimal128, declared for `sizeOf` and never assigned. */
+    readonly '~layout': {
+        readonly size: 16;
+        readonly alignment: 16;
+    };
+    /**
+     * Wraps parts that are already normalised. Private, because every value
+     * enters through {@link Decimal.from}, which is where it is checked.
+     *
+     * @param parts The value.
+     */
+    private constructor();
+    /**
+     * The largest finite decimal128 value: thirty-four nines, the last at
+     * 10^6111 — 9.999999999999999999999999999999999 × 10^6144.
+     */
+    static readonly maximum: Decimal;
+    /**
+     * The smallest finite value, the negation of {@link Decimal.maximum}. Not the
+     * smallest positive one, which is 1 × 10^-6176.
+     */
+    static readonly minimum: Decimal;
+    /**
+     * Converts a value into a decimal.
+     *
+     * - A **string** is parsed as a decimal literal — `'-12.5'`, `'1e-3'`,
+     *   `'NaN'`, `'Infinity'` — and rounded half to even past thirty-four
+     *   digits. Surrounding whitespace and hexadecimal are refused.
+     * - A **number** is converted from the shortest text that reads back as it,
+     *   so `Decimal.from(0.1)` is exactly 0.1, not the binary value closest to
+     *   it.
+     * - A **bigint** is converted exactly, then rounded if it has more than
+     *   thirty-four digits.
+     * - A **Decimal** is returned as is.
+     *
+     * @param value Value to convert.
+     * @returns The decimal.
+     * @throws {SyntaxError} When a string is not a decimal literal.
+     * @throws {TypeError} When the value is of another kind.
+     */
+    static from: (value: Decimal | string | number | bigint) => Decimal;
+    /**
+     * Tells whether a value is a decimal.
+     *
+     * @param value Value to inspect.
+     * @returns `true` for an instance of this class.
+     */
+    static is: (value: unknown) => value is Decimal;
+    /**
+     * Adds a value.
+     *
+     * @param other Value to add.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The sum.
+     */
+    add(other: Decimal, mode?: RoundingMode): Decimal;
+    /**
+     * Subtracts a value.
+     *
+     * @param other Value to subtract.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The difference.
+     */
+    subtract(other: Decimal, mode?: RoundingMode): Decimal;
+    /**
+     * Multiplies by a value.
+     *
+     * @param other Value to multiply by.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The product.
+     */
+    multiply(other: Decimal, mode?: RoundingMode): Decimal;
+    /**
+     * Divides by a value.
+     *
+     * @param other Divisor.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The quotient; an infinity for a non-zero value over zero, and
+     * `NaN` for zero over zero.
+     */
+    divide(other: Decimal, mode?: RoundingMode): Decimal;
+    /**
+     * The remainder of a division truncated towards zero, with the sign of this
+     * value, as `%` computes it. Always exact.
+     *
+     * @param other Divisor.
+     * @returns The remainder; `NaN` for a zero divisor or an infinite dividend.
+     */
+    remainder(other: Decimal): Decimal;
+    /**
+     * Raises this value to an integer power, rounded once — the correctly
+     * rounded power whenever the exact one has up to 200,000 digits, which
+     * covers every base not within a hair of one.
+     *
+     * ```ts
+     * Decimal.from('1.1').power(Decimal.from(2)).toString(); // '1.21'
+     * Decimal.from('2').power(Decimal.from(-2)).toString(); // '0.25'
+     * ```
+     *
+     * Anything to the power zero is one, `NaN` included, as IEEE 754's `pown`
+     * has it.
+     *
+     * @param exponent Integer exponent, of any sign.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The power.
+     * @throws {RangeError} When the exponent has a fractional part, or is not
+     * finite.
+     */
+    power(exponent: Decimal, mode?: RoundingMode): Decimal;
+    /**
+     * The value with its sign flipped.
+     *
+     * @returns The negated value.
+     */
+    negate(): Decimal;
+    /**
+     * The value without its sign.
+     *
+     * @returns The absolute value.
+     */
+    absolute(): Decimal;
+    /**
+     * Rounds to a number of places after the point.
+     *
+     * ```ts
+     * Decimal.from('2.345').round(2).toString(); // '2.34', half to even
+     * Decimal.from('2.345').round(2, 'halfAwayFromZero').toString(); // '2.35'
+     * Decimal.from('1250').round(-2).toString(); // '1200'
+     * ```
+     *
+     * @param places Places after the point, zero by default; negative rounds to
+     * tens, hundreds and so on.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The rounded value.
+     * @throws {RangeError} When `places` is not an integer.
+     */
+    round(places?: number, mode?: RoundingMode): Decimal;
+    /**
+     * Compares with a value.
+     *
+     * @param other Value to compare with.
+     * @returns -1 when this value is smaller, 1 when it is larger, 0 when they
+     * are equal — `0` and `-0` included — and `undefined` when either is `NaN`.
+     */
+    compare(other: Decimal): -1 | 0 | 1 | undefined;
+    /**
+     * Tells whether two values are equal. `NaN` equals nothing, itself
+     * included; `0` equals `-0`.
+     *
+     * @param other Value to compare with.
+     * @returns `true` when they are equal.
+     */
+    equals(other: Decimal): boolean;
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is smaller; `false` when either is `NaN`.
+     */
+    lessThan(other: Decimal): boolean;
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is smaller or equal; `false` when either
+     * is `NaN`.
+     */
+    lessThanOrEqual(other: Decimal): boolean;
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is larger; `false` when either is `NaN`.
+     */
+    greaterThan(other: Decimal): boolean;
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is larger or equal; `false` when either
+     * is `NaN`.
+     */
+    greaterThanOrEqual(other: Decimal): boolean;
+    /** @returns `true` when the value is `NaN`. */
+    isNaN(): boolean;
+    /** @returns `true` when the value is neither an infinity nor `NaN`. */
+    isFinite(): boolean;
+    /** @returns `true` for `0` and `-0`. */
+    isZero(): boolean;
+    /**
+     * Reads the sign bit, which is set for `-0` and `-Infinity` as well as for
+     * negative values — the one way to tell `-0` from `0`.
+     *
+     * @returns `true` when the sign bit is set; `false` for `NaN`.
+     */
+    isNegative(): boolean;
+    /**
+     * The shortest text that reads back as this value, in plain notation from
+     * 10^-6 to 10^21 and exponential outside it, as `Number` prints.
+     *
+     * @returns The text.
+     */
+    toString(): string;
+    /**
+     * The value with a fixed number of digits after the point, in plain
+     * notation.
+     *
+     * @param fractionDigits Digits after the point, from 0 to 100; 0 by default.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text.
+     * @throws {RangeError} When `fractionDigits` is out of range.
+     */
+    toFixed(fractionDigits?: number, mode?: RoundingMode): string;
+    /**
+     * The value with a number of significant digits.
+     *
+     * @param precision Significant digits, from 1 to 100.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text, exponential when the exponent is below -6 or at least
+     * the precision, as `Number.prototype.toPrecision` does.
+     * @throws {RangeError} When `precision` is out of range.
+     */
+    toPrecision(precision: number, mode?: RoundingMode): string;
+    /**
+     * The value in exponential notation.
+     *
+     * @param fractionDigits Digits after the point, from 0 to 100, or as many
+     * as the value has when omitted.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text.
+     * @throws {RangeError} When `fractionDigits` is out of range.
+     */
+    toExponential(fractionDigits?: number, mode?: RoundingMode): string;
+    /**
+     * The value formatted for a locale, by `Intl.NumberFormat`, which formats
+     * the decimal text itself rather than a `number` converted from it — so no
+     * digit is lost on the way.
+     *
+     * @param locales Locale or locales, as `Intl.NumberFormat` takes them.
+     * @param options Formatting options, as `Intl.NumberFormat` takes them.
+     * @returns The formatted text.
+     */
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string;
+    /**
+     * The text of the value, so that `JSON.stringify` writes it as a string
+     * rather than as `{}`, and without the digits a JSON number would lose.
+     *
+     * @returns The same text as {@link Decimal.toString}.
+     */
+    toJSON(): string;
+    /**
+     * The nearest `number`, rounded once, from the decimal text.
+     *
+     * @returns The number; `NaN` and the infinities convert to their own.
+     */
+    toNumber(): number;
+    /**
+     * The value as a `bigint`, exactly.
+     *
+     * @returns The integer.
+     * @throws {RangeError} When the value has a fractional part, or is not
+     * finite.
+     */
+    toBigInt(): bigint;
+    /**
+     * Refuses the implicit conversion every operator performs.
+     *
+     * @returns Never.
+     * @throws {TypeError} Always.
+     */
+    valueOf(): never;
+}

package/dist/decimal/index.js

@@ -0,0 +1,407 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Decimal = void 0;
+const roundingMode_1 = require("../roundingMode/index.js");
+const arithmetic_1 = require("./arithmetic");
+const format_1 = require("./format");
+const parse_1 = require("./parse");
+const parts_1 = require("./parts");
+/** Rounding applied wherever a mode is optional. */
+const DEFAULT_MODE = 'halfEven';
+/**
+ * A decimal floating point number with the semantics of IEEE 754 decimal128:
+ * thirty-four significant digits, exponents from -6143 to 6144, and the
+ * special values `NaN`, `Infinity`, `-Infinity` and `-0`.
+ *
+ * ```ts
+ * const price = Decimal.from('19.99');
+ *
+ * price.multiply(Decimal.from(3)).toString(); // '59.97'
+ * Decimal.from('0.1').add(Decimal.from('0.2')).equals(Decimal.from('0.3')); // true
+ * ```
+ *
+ * The semantics are those of the TC39 Decimal proposal, so that code written
+ * against this class reads the same against a native one:
+ *
+ * - **Trailing zeros are not observable.** `'1.20'` and `'1.2'` are the same
+ *   value and print the same way.
+ * - **Every operation rounds once**, to thirty-four digits, half to even unless
+ *   a mode is given. An exact result is never rounded.
+ * - **Operators refuse it.** `a + b`, `a < b` and `a == 1` throw a `TypeError`
+ *   instead of coercing: an implicit conversion to `number` would lose exactly
+ *   the digits the type exists to keep. Use the methods.
+ * - **Division by zero is not an error**, as in IEEE 754: it gives an infinity,
+ *   and zero over zero gives `NaN`.
+ *
+ * Values are immutable. The layout is sixteen bytes aligned on sixteen, that of
+ * decimal128 — which is what `sizeOf<Decimal>()` reports, not what an instance
+ * costs in a JavaScript heap.
+ */
+class Decimal {
+    /** The value, taken apart and normalised. */
+    #parts;
+    /**
+     * Wraps parts that are already normalised. Private, because every value
+     * enters through {@link Decimal.from}, which is where it is checked.
+     *
+     * @param parts The value.
+     */
+    constructor(parts) {
+        this.#parts = parts;
+    }
+    /**
+     * The largest finite decimal128 value: thirty-four nines, the last at
+     * 10^6111 — 9.999999999999999999999999999999999 × 10^6144.
+     */
+    static maximum = new Decimal({
+        kind: 'finite',
+        negative: false,
+        coefficient: (0, parts_1.powerOfTen)(parts_1.PRECISION) - 1n,
+        exponent: parts_1.MAXIMUM_ADJUSTED_EXPONENT - parts_1.PRECISION + 1,
+    });
+    /**
+     * The smallest finite value, the negation of {@link Decimal.maximum}. Not the
+     * smallest positive one, which is 1 × 10^-6176.
+     */
+    static minimum = Decimal.maximum.negate();
+    /**
+     * Converts a value into a decimal.
+     *
+     * - A **string** is parsed as a decimal literal — `'-12.5'`, `'1e-3'`,
+     *   `'NaN'`, `'Infinity'` — and rounded half to even past thirty-four
+     *   digits. Surrounding whitespace and hexadecimal are refused.
+     * - A **number** is converted from the shortest text that reads back as it,
+     *   so `Decimal.from(0.1)` is exactly 0.1, not the binary value closest to
+     *   it.
+     * - A **bigint** is converted exactly, then rounded if it has more than
+     *   thirty-four digits.
+     * - A **Decimal** is returned as is.
+     *
+     * @param value Value to convert.
+     * @returns The decimal.
+     * @throws {SyntaxError} When a string is not a decimal literal.
+     * @throws {TypeError} When the value is of another kind.
+     */
+    static from = (value) => {
+        if (value instanceof Decimal)
+            return value;
+        if (typeof value === 'string')
+            return new Decimal((0, parse_1.parseDecimal)(value));
+        if (typeof value === 'bigint') {
+            return new Decimal((0, parse_1.parseDecimal)(value.toString()));
+        }
+        if (typeof value === 'number') {
+            if (Number.isNaN(value))
+                return new Decimal(parts_1.NOT_A_NUMBER);
+            if (value === Infinity || value === -Infinity) {
+                return new Decimal((0, parts_1.infinity)(value < 0));
+            }
+            // `String(-0)` is `'0'`, which would lose the sign.
+            if (value === 0)
+                return new Decimal((0, parts_1.zero)(Object.is(value, -0)));
+            return new Decimal((0, parse_1.parseDecimal)(String(value)));
+        }
+        throw new TypeError(`Decimal.from: expected a Decimal, a string, a number or a bigint, received ${typeof value}.`);
+    };
+    /**
+     * Tells whether a value is a decimal.
+     *
+     * @param value Value to inspect.
+     * @returns `true` for an instance of this class.
+     */
+    static is = (value) => value instanceof Decimal;
+    /**
+     * Adds a value.
+     *
+     * @param other Value to add.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The sum.
+     */
+    add(other, mode = DEFAULT_MODE) {
+        return new Decimal((0, arithmetic_1.addParts)(this.#parts, other.#parts, (0, roundingMode_1.requireRoundingMode)('Decimal.add', mode)));
+    }
+    /**
+     * Subtracts a value.
+     *
+     * @param other Value to subtract.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The difference.
+     */
+    subtract(other, mode = DEFAULT_MODE) {
+        return new Decimal((0, arithmetic_1.addParts)(this.#parts, other.negate().#parts, (0, roundingMode_1.requireRoundingMode)('Decimal.subtract', mode)));
+    }
+    /**
+     * Multiplies by a value.
+     *
+     * @param other Value to multiply by.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The product.
+     */
+    multiply(other, mode = DEFAULT_MODE) {
+        return new Decimal((0, arithmetic_1.multiplyParts)(this.#parts, other.#parts, (0, roundingMode_1.requireRoundingMode)('Decimal.multiply', mode)));
+    }
+    /**
+     * Divides by a value.
+     *
+     * @param other Divisor.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The quotient; an infinity for a non-zero value over zero, and
+     * `NaN` for zero over zero.
+     */
+    divide(other, mode = DEFAULT_MODE) {
+        return new Decimal((0, arithmetic_1.divideParts)(this.#parts, other.#parts, (0, roundingMode_1.requireRoundingMode)('Decimal.divide', mode)));
+    }
+    /**
+     * The remainder of a division truncated towards zero, with the sign of this
+     * value, as `%` computes it. Always exact.
+     *
+     * @param other Divisor.
+     * @returns The remainder; `NaN` for a zero divisor or an infinite dividend.
+     */
+    remainder(other) {
+        return new Decimal((0, arithmetic_1.remainderParts)(this.#parts, other.#parts));
+    }
+    /**
+     * Raises this value to an integer power, rounded once — the correctly
+     * rounded power whenever the exact one has up to 200,000 digits, which
+     * covers every base not within a hair of one.
+     *
+     * ```ts
+     * Decimal.from('1.1').power(Decimal.from(2)).toString(); // '1.21'
+     * Decimal.from('2').power(Decimal.from(-2)).toString(); // '0.25'
+     * ```
+     *
+     * Anything to the power zero is one, `NaN` included, as IEEE 754's `pown`
+     * has it.
+     *
+     * @param exponent Integer exponent, of any sign.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The power.
+     * @throws {RangeError} When the exponent has a fractional part, or is not
+     * finite.
+     */
+    power(exponent, mode = DEFAULT_MODE) {
+        const { kind, negative, coefficient, exponent: scale } = exponent.#parts;
+        if (kind !== 'finite' || scale < 0) {
+            throw new RangeError(`Decimal.power: expected an integer exponent, received ${exponent.toString()}.`);
+        }
+        const power = (negative ? -coefficient : coefficient) * (0, parts_1.powerOfTen)(scale);
+        return new Decimal((0, arithmetic_1.powerParts)(this.#parts, power, (0, roundingMode_1.requireRoundingMode)('Decimal.power', mode)));
+    }
+    /**
+     * The value with its sign flipped.
+     *
+     * @returns The negated value.
+     */
+    negate() {
+        if (this.#parts.kind === 'nan')
+            return this;
+        return new Decimal({ ...this.#parts, negative: !this.#parts.negative });
+    }
+    /**
+     * The value without its sign.
+     *
+     * @returns The absolute value.
+     */
+    absolute() {
+        if (!this.#parts.negative)
+            return this;
+        return new Decimal({ ...this.#parts, negative: false });
+    }
+    /**
+     * Rounds to a number of places after the point.
+     *
+     * ```ts
+     * Decimal.from('2.345').round(2).toString(); // '2.34', half to even
+     * Decimal.from('2.345').round(2, 'halfAwayFromZero').toString(); // '2.35'
+     * Decimal.from('1250').round(-2).toString(); // '1200'
+     * ```
+     *
+     * @param places Places after the point, zero by default; negative rounds to
+     * tens, hundreds and so on.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The rounded value.
+     * @throws {RangeError} When `places` is not an integer.
+     */
+    round(places = 0, mode = DEFAULT_MODE) {
+        if (!Number.isSafeInteger(places)) {
+            throw new RangeError(`Decimal.round: expected an integer number of places, received ${places}.`);
+        }
+        return new Decimal((0, arithmetic_1.roundParts)(this.#parts, places, (0, roundingMode_1.requireRoundingMode)('Decimal.round', mode)));
+    }
+    /**
+     * Compares with a value.
+     *
+     * @param other Value to compare with.
+     * @returns -1 when this value is smaller, 1 when it is larger, 0 when they
+     * are equal — `0` and `-0` included — and `undefined` when either is `NaN`.
+     */
+    compare(other) {
+        return (0, arithmetic_1.compareParts)(this.#parts, other.#parts);
+    }
+    /**
+     * Tells whether two values are equal. `NaN` equals nothing, itself
+     * included; `0` equals `-0`.
+     *
+     * @param other Value to compare with.
+     * @returns `true` when they are equal.
+     */
+    equals(other) {
+        return this.compare(other) === 0;
+    }
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is smaller; `false` when either is `NaN`.
+     */
+    lessThan(other) {
+        return this.compare(other) === -1;
+    }
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is smaller or equal; `false` when either
+     * is `NaN`.
+     */
+    lessThanOrEqual(other) {
+        const order = this.compare(other);
+        return order === -1 || order === 0;
+    }
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is larger; `false` when either is `NaN`.
+     */
+    greaterThan(other) {
+        return this.compare(other) === 1;
+    }
+    /**
+     * @param other Value to compare with.
+     * @returns `true` when this value is larger or equal; `false` when either
+     * is `NaN`.
+     */
+    greaterThanOrEqual(other) {
+        const order = this.compare(other);
+        return order === 1 || order === 0;
+    }
+    /** @returns `true` when the value is `NaN`. */
+    isNaN() {
+        return this.#parts.kind === 'nan';
+    }
+    /** @returns `true` when the value is neither an infinity nor `NaN`. */
+    isFinite() {
+        return this.#parts.kind === 'finite';
+    }
+    /** @returns `true` for `0` and `-0`. */
+    isZero() {
+        return (0, parts_1.isZero)(this.#parts);
+    }
+    /**
+     * Reads the sign bit, which is set for `-0` and `-Infinity` as well as for
+     * negative values — the one way to tell `-0` from `0`.
+     *
+     * @returns `true` when the sign bit is set; `false` for `NaN`.
+     */
+    isNegative() {
+        return this.#parts.negative;
+    }
+    /**
+     * The shortest text that reads back as this value, in plain notation from
+     * 10^-6 to 10^21 and exponential outside it, as `Number` prints.
+     *
+     * @returns The text.
+     */
+    toString() {
+        return (0, format_1.formatDecimal)(this.#parts);
+    }
+    /**
+     * The value with a fixed number of digits after the point, in plain
+     * notation.
+     *
+     * @param fractionDigits Digits after the point, from 0 to 100; 0 by default.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text.
+     * @throws {RangeError} When `fractionDigits` is out of range.
+     */
+    toFixed(fractionDigits = 0, mode = DEFAULT_MODE) {
+        return (0, format_1.formatFixed)(this.#parts, (0, format_1.requireDigits)('toFixed', fractionDigits, 0), (0, roundingMode_1.requireRoundingMode)('Decimal.toFixed', mode));
+    }
+    /**
+     * The value with a number of significant digits.
+     *
+     * @param precision Significant digits, from 1 to 100.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text, exponential when the exponent is below -6 or at least
+     * the precision, as `Number.prototype.toPrecision` does.
+     * @throws {RangeError} When `precision` is out of range.
+     */
+    toPrecision(precision, mode = DEFAULT_MODE) {
+        return (0, format_1.formatPrecision)(this.#parts, (0, format_1.requireDigits)('toPrecision', precision, 1), (0, roundingMode_1.requireRoundingMode)('Decimal.toPrecision', mode));
+    }
+    /**
+     * The value in exponential notation.
+     *
+     * @param fractionDigits Digits after the point, from 0 to 100, or as many
+     * as the value has when omitted.
+     * @param mode Rounding mode, half to even by default.
+     * @returns The text.
+     * @throws {RangeError} When `fractionDigits` is out of range.
+     */
+    toExponential(fractionDigits, mode = DEFAULT_MODE) {
+        return (0, format_1.formatExponential)(this.#parts, fractionDigits === undefined
+            ? undefined
+            : (0, format_1.requireDigits)('toExponential', fractionDigits, 0), (0, roundingMode_1.requireRoundingMode)('Decimal.toExponential', mode));
+    }
+    /**
+     * The value formatted for a locale, by `Intl.NumberFormat`, which formats
+     * the decimal text itself rather than a `number` converted from it — so no
+     * digit is lost on the way.
+     *
+     * @param locales Locale or locales, as `Intl.NumberFormat` takes them.
+     * @param options Formatting options, as `Intl.NumberFormat` takes them.
+     * @returns The formatted text.
+     */
+    toLocaleString(locales, options) {
+        return new Intl.NumberFormat(locales, options).format(this.toString());
+    }
+    /**
+     * The text of the value, so that `JSON.stringify` writes it as a string
+     * rather than as `{}`, and without the digits a JSON number would lose.
+     *
+     * @returns The same text as {@link Decimal.toString}.
+     */
+    toJSON() {
+        return this.toString();
+    }
+    /**
+     * The nearest `number`, rounded once, from the decimal text.
+     *
+     * @returns The number; `NaN` and the infinities convert to their own.
+     */
+    toNumber() {
+        return Number(this.toString());
+    }
+    /**
+     * The value as a `bigint`, exactly.
+     *
+     * @returns The integer.
+     * @throws {RangeError} When the value has a fractional part, or is not
+     * finite.
+     */
+    toBigInt() {
+        const { kind, negative, coefficient, exponent } = this.#parts;
+        if (kind !== 'finite' || exponent < 0) {
+            throw new RangeError(`Decimal.toBigInt: expected an integer, received ${this.toString()}.`);
+        }
+        const magnitude = coefficient * (0, parts_1.powerOfTen)(exponent);
+        return negative ? -magnitude : magnitude;
+    }
+    /**
+     * Refuses the implicit conversion every operator performs.
+     *
+     * @returns Never.
+     * @throws {TypeError} Always.
+     */
+    valueOf() {
+        throw new TypeError('Decimal cannot be converted to a primitive implicitly: operators such as + and < would lose its digits. ' +
+            'Use add(), compare() or toString() instead.');
+    }
+}
+exports.Decimal = Decimal;