@quentinadam/decimal 0.1.8

package/README.md

@@ -0,0 +1,33 @@
+# @quentinadam/decimal
+
+[![JSR][jsr-image]][jsr-url] [![NPM][npm-image]][npm-url] [![CI][ci-image]][ci-url]
+
+A library for working with arbitrary precision decimal numbers.
+
+Decimal numbers are represented by a mantissa (bigint) and an exponent (number). Instances of the Decimal class are
+immutable; calling functions (like `abs`, `add`, `ceil`, ...) on an instance will return a new Decimal instance with the
+result. Division may fail if the resulting number cannot be represented with a fixed number of decimals (like 1/3).
+Please check the documentation of the `div` function for more details.
+
+## Usage
+
+```ts
+import Decimal from '@quentinadam/decimal';
+
+const a = Decimal.from('1.11111111111111111111');
+
+const b = a.mul(2);
+
+console.log(b.toString()); // prints 2.22222222222222222222
+
+const c = a.add(b);
+
+console.log(c.toString()); // prints 3.33333333333333333333
+```
+
+[ci-image]: https://img.shields.io/github/actions/workflow/status/quentinadam/deno-decimal/ci.yml?branch=main&logo=github&style=flat-square
+[ci-url]: https://github.com/quentinadam/deno-decimal/actions/workflows/ci.yml
+[npm-image]: https://img.shields.io/npm/v/@quentinadam/decimal.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/@quentinadam/decimal
+[jsr-image]: https://jsr.io/badges/@quentinadam/decimal?style=flat-square
+[jsr-url]: https://jsr.io/@quentinadam/decimal

package/dist/Decimal.d.ts

@@ -0,0 +1,400 @@
+/**
+ * A type alias representing the different types a Decimal instance can be created from.
+ */
+export type DecimalType = Decimal | number | bigint | string;
+/**
+ * A class to represent arbitrary precision decimal numbers.
+ */
+export default class Decimal {
+    readonly mantissa: bigint;
+    readonly exponent: number;
+    /**
+     * Constructs a new Decimal instance, from a `mantissa` and an `exponent`.
+     *
+     * Conceptually, a Decimal instance represents the value `mantissa * 10 ^ exponent`.
+     *
+     * The constructor normalizes the mantissa and exponent, ensuring that the mantissa is as small as possible.
+     *
+     * If the mantissa is 0, the exponent is set to 0.
+     *
+     * @param mantissa The mantissa, represented as a bigint.
+     * @param exponent The exponent, representing the power of 10 by which the mantissa is multiplied. Defaults to 0.
+     * @throws Will throw an error if the exponent is not an integer.
+     */
+    constructor(mantissa: bigint, exponent?: number);
+    /**
+     * Returns the absolute value of the current Decimal instance.
+     *
+     * @returns A new Decimal instance representing the absolute value.
+     */
+    abs(): Decimal;
+    /**
+     * Adds the provided value to the current Decimal instance.
+     *
+     * @param value The value to add.
+     * @returns A new Decimal instance representing the sum.
+     */
+    add(value: DecimalType): Decimal;
+    /**
+     * Rounds the current value up towards positive infinity to the nearest multiple of the specified precision.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    ceil(precision?: DecimalType): Decimal;
+    /**
+     * Compares the current Decimal instance with the provided value.
+     *
+     * @param other The value to compare with.
+     * @returns 0 if both values are equal, 1 if the current instance is greater, and -1 if it is less.
+     */
+    compare(other: DecimalType): number;
+    /**
+     * Divides the current Decimal instance by the provided value.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to divide by such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.from(1).div(3); // Throws
+     * Decimal.from(1).div(3, 2); // Returns 0.33
+     * ```
+     *
+     * @param value The value to divide by.
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the result of the division.
+     */
+    div(value: DecimalType, significantDigits?: number): Decimal;
+    /**
+     * Multiplies the current Decimal instance by 10 raised to the provided integer exponent.
+     *
+     * @param exponent The integer exponent to raise 10 to.
+     * @returns A new Decimal instance representing the result.
+     */
+    e(exponent: number): Decimal;
+    /**
+     * Checks if the current Decimal instance is equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the values are equal, false otherwise.
+     */
+    eq(value: DecimalType): boolean;
+    /**
+     * Checks if the current Decimal instance is equal to zero.
+     *
+     * @returns True if the value is zero, false otherwise.
+     */
+    eq0(): boolean;
+    /**
+     * Rounds the current value down towards negative infinity to the nearest multiple of the specified precision.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    floor(precision?: DecimalType): Decimal;
+    /**
+     * Checks if the current Decimal instance is greater than the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is greater, false otherwise.
+     */
+    gt(value: DecimalType): boolean;
+    /**
+     * Checks if the current Decimal instance is greater than zero.
+     *
+     * @returns True if the value is greater than zero, false otherwise.
+     */
+    gt0(): boolean;
+    /**
+     * Checks if the current Decimal instance is greater than or equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is greater or equal, false otherwise.
+     */
+    gte(value: DecimalType): boolean;
+    /**
+     * Checks if the current Decimal instance is greater than or equal to zero.
+     *
+     * @returns True if the value is greater than or equal to zero, false otherwise.
+     */
+    gte0(): boolean;
+    /**
+     * Returns the multiplicative inverse of the current Decimal instance.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to invert such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.from(3).inv(); // Throws
+     * Decimal.from(3).inv(2); // Returns 0.33
+     * ```
+     *
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the inverse.
+     */
+    inv(significantDigits?: number): Decimal;
+    /**
+     * Checks if the current Decimal instance is an integer.
+     *
+     * @returns True if the value is an integer, false otherwise.
+     */
+    isInteger(): boolean;
+    /**
+     * Checks if the current Decimal instance is less than the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is less, false otherwise.
+     */
+    lt(value: DecimalType): boolean;
+    /**
+     * Checks if the current Decimal instance is less than zero.
+     *
+     * @returns True if the value is less than zero, false otherwise.
+     */
+    lt0(): boolean;
+    /**
+     * Checks if the current Decimal instance is less than or equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is less or equal, false otherwise.
+     */
+    lte(value: DecimalType): boolean;
+    /**
+     * Checks if the current Decimal instance is less than or equal to zero.
+     *
+     * @returns True if the value is less than or equal to zero, false otherwise.
+     */
+    lte0(): boolean;
+    /**
+     * Returns the order of magnitude (defined as `floor(log10(abs(value)))`) of the current Decimal instance.
+     *
+     * @returns A number representing the order of magnitude.
+     */
+    magnitude(): number;
+    /**
+     * Returns the remainder when dividing the current Decimal instance by the provided value.
+     *
+     * @param value The value to divide by.
+     * @returns A new Decimal instance representing the remainder.
+     */
+    mod(value: DecimalType): Decimal;
+    /**
+     * Multiplies the current Decimal instance by the provided value.
+     *
+     * @param value The value to multiply by.
+     * @returns A new Decimal instance representing the product.
+     */
+    mul(value: DecimalType): Decimal;
+    /**
+     * Negates the current Decimal instance.
+     *
+     * @returns A new Decimal instance representing the negated value.
+     */
+    neg(): Decimal;
+    /**
+     * Checks if the current value is not equal to the provided value.
+     *
+     * @param value The value to compare against.
+     * @returns True if the values are not equal, false otherwise.
+     */
+    neq(value: DecimalType): boolean;
+    /**
+     * Checks if the current value is not equal to zero.
+     *
+     * @returns True if the value is not zero, false otherwise.
+     */
+    neq0(): boolean;
+    /**
+     * Raises the current Decimal instance to the power of the provided integer exponent.
+     *
+     * @param value The integer exponent to raise to.
+     * @returns A new Decimal instance representing the result of the exponentiation.
+     */
+    pow(value: number): Decimal;
+    /**
+     * Rounds the current value towards the nearest multiple of the specified precision.
+     *
+     * If the current value is exactly halfway between two multiples of the precision, it is rounded up towards positive infinity.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    round(precision?: DecimalType): Decimal;
+    /**
+     * Returns the sign of the current value as a Decimal instance.
+     *
+     * @returns A Decimal instance representing the sign: 1 for positive, -1 for negative, and 0 for zero.
+     */
+    sign(): Decimal;
+    /**
+     * Subtracts the provided value from the current Decimal instance.
+     *
+     * @param value The value to subtract.
+     * @returns A new Decimal instance representing the result of the subtraction.
+     */
+    sub(value: DecimalType): Decimal;
+    /**
+     * Converts the current Decimal instance to a bigint, if it is an integer.
+     *
+     * Throws if the Decimal instance is not an integer.
+     *
+     * @returns A bigint representing the integer value of the Decimal instance.
+     */
+    toBigInt(): bigint;
+    /**
+     * Converts the current Decimal instance to a fixed-point notation string.
+     *
+     * @param precision The number of decimal places to include in the result.
+     * @returns A string representing the Decimal instance in fixed-point notation.
+     */
+    toFixed(precision: number): string;
+    /**
+     * Converts the current value to a fraction represented by a numerator and denominator.
+     *
+     * Simplifies the fraction to its lowest terms.
+     *
+     * @returns An object with numerator and denominator properties.
+     */
+    toFraction(): {
+        numerator: bigint;
+        denominator: bigint;
+    };
+    /**
+     * Converts the current Decimal value to a JSON string.
+     *
+     * @returns A string representing the Decimal value in JSON format.
+     */
+    toJSON(): string;
+    /**
+     * Converts the current value to a number.
+     *
+     * This may lose precision if the Decimal cannot be exactly represented as a number.
+     *
+     * @returns The number representation of the current Decimal value.
+     */
+    toNumber(): number;
+    /**
+     * Converts the current value to a string.
+     *
+     * @returns A string representing the current Decimal value.
+     */
+    toString(): string;
+    /**
+     * A static constant representing the decimal value -1.
+     */
+    static minusOne: Decimal;
+    /**
+     * A static constant representing the decimal value 1.
+     */
+    static one: Decimal;
+    /**
+     * A static constant representing the decimal value 0.
+     */
+    static zero: Decimal;
+    /**
+     * Adds multiple values together.
+     *
+     * @param values An array of values to add.
+     * @returns A new Decimal instance representing the sum of the values.
+     */
+    static add(...values: DecimalType[]): Decimal;
+    /**
+     * Divides one value by another.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to divide by such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.div(1, 3); // Throws
+     * Decimal.div(1, 3, 2); // Returns 0.33
+     * ```
+     * @param dividend The value to divide.
+     * @param divisor The value to divide by.
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the quotient.
+     */
+    static div(dividend: DecimalType, divisor: DecimalType, significantDigits?: number): Decimal;
+    /**
+     * Creates a Decimal instance from a string (in standard or scientific notation), a number or a bigint.
+     *
+     * @param value The value to convert.
+     * @returns A Decimal instance representing the provided value.
+     */
+    static from(value: DecimalType): Decimal;
+    /**
+     * Creates a Decimal instance from a fraction.
+     *
+     * Throws if the fraction cannot be represented with a fixed number of decimals.
+     *
+     * @param numerator The numerator of the fraction.
+     * @param denominator The denominator of the fraction.
+     * @returns A Decimal instance representing the fraction.
+     */
+    static fromFraction({ numerator, denominator }: {
+        numerator: bigint;
+        denominator: bigint;
+    }): Decimal;
+    /**
+     * Creates a Decimal instance from a bigint.
+     *
+     * @param value The bigint value to convert.
+     * @returns A Decimal instance representing the provided bigint value.
+     */
+    static fromBigInt(value: bigint): Decimal;
+    /**
+     * Creates a Decimal instance from a number.
+     *
+     * @param value The number value to convert.
+     * @returns A Decimal instance representing the provided number.
+     */
+    static fromNumber(value: number): Decimal;
+    /**
+     * Creates a Decimal instance from a string (in standard or scientific notation).
+     *
+     * @param string The string value to convert.
+     * @returns A Decimal instance representing the provided string.
+     */
+    static fromString(string: string): Decimal;
+    /**
+     * Finds the maximum value among the provided values.
+     *
+     * @param first The first value to compare.
+     * @param values Additional values to compare.
+     * @returns A new Decimal instance representing the maximum value.
+     */
+    static max(first: DecimalType, ...values: DecimalType[]): Decimal;
+    /**
+     * Finds the minimum value among the provided values.
+     *
+     * @param first The first value to compare.
+     * @param values Additional values to compare.
+     * @returns A new Decimal instance representing the minimum value.
+     */
+    static min(first: DecimalType, ...values: DecimalType[]): Decimal;
+    /**
+     * Multiplies multiple values together.
+     *
+     * @param values An array of values to multiply.
+     * @returns A new Decimal instance representing the product of the values.
+     */
+    static mul(...values: DecimalType[]): Decimal;
+    /**
+     * Subtracts one value from another.
+     *
+     * @param minuend The value to subtract from.
+     * @param subtrahend The value to subtract.
+     * @returns A new Decimal instance representing the result of the subtraction.
+     */
+    static sub(minuend: DecimalType, subtrahend: DecimalType): Decimal;
+    /**
+     * Calculates the greatest common divisor (GCD) of two values.
+     *
+     * @param a The first value.
+     * @param b The second value.
+     * @returns A new Decimal instance representing the GCD of the two values.
+     */
+    static gcd(a: DecimalType, b: DecimalType): Decimal;
+}

package/dist/Decimal.js

@@ -0,0 +1,736 @@
+import assert from '@quentinadam/assert';
+/**
+ * A class to represent arbitrary precision decimal numbers.
+ */
+export default class Decimal {
+    mantissa;
+    exponent;
+    /**
+     * Constructs a new Decimal instance, from a `mantissa` and an `exponent`.
+     *
+     * Conceptually, a Decimal instance represents the value `mantissa * 10 ^ exponent`.
+     *
+     * The constructor normalizes the mantissa and exponent, ensuring that the mantissa is as small as possible.
+     *
+     * If the mantissa is 0, the exponent is set to 0.
+     *
+     * @param mantissa The mantissa, represented as a bigint.
+     * @param exponent The exponent, representing the power of 10 by which the mantissa is multiplied. Defaults to 0.
+     * @throws Will throw an error if the exponent is not an integer.
+     */
+    constructor(mantissa, exponent = 0) {
+        assert(Number.isInteger(exponent), `Exponent must be an integer, got ${exponent}`);
+        if (mantissa === 0n) {
+            this.mantissa = 0n;
+            this.exponent = 0;
+        }
+        else {
+            while (mantissa % 10n === 0n) {
+                mantissa /= 10n;
+                exponent += 1;
+            }
+            this.mantissa = mantissa;
+            this.exponent = exponent;
+        }
+    }
+    /**
+     * Custom inspection method for Deno which returns the string representation of the Decimal instance.
+     *
+     * @returns A string representing the Decimal value.
+     */
+    [Symbol.for('Deno.customInspect')]() {
+        return this.toString();
+    }
+    /**
+     * Returns the absolute value of the current Decimal instance.
+     *
+     * @returns A new Decimal instance representing the absolute value.
+     */
+    abs() {
+        return this.gt0() ? this : this.neg();
+    }
+    /**
+     * Adds the provided value to the current Decimal instance.
+     *
+     * @param value The value to add.
+     * @returns A new Decimal instance representing the sum.
+     */
+    add(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2, exponent } = normalize(this, value);
+        return new Decimal(mantissa1 + mantissa2, exponent);
+    }
+    /**
+     * Rounds the current value up towards positive infinity to the nearest multiple of the specified precision.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    ceil(precision = Decimal.one) {
+        const remainder = this.mod(precision);
+        if (remainder.eq0()) {
+            return this;
+        }
+        return this.sub(remainder).add(precision);
+    }
+    /**
+     * Compares the current Decimal instance with the provided value.
+     *
+     * @param other The value to compare with.
+     * @returns 0 if both values are equal, 1 if the current instance is greater, and -1 if it is less.
+     */
+    compare(other) {
+        return this.sub(other).sign().toNumber();
+    }
+    /**
+     * Divides the current Decimal instance by the provided value.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to divide by such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.from(1).div(3); // Throws
+     * Decimal.from(1).div(3, 2); // Returns 0.33
+     * ```
+     *
+     * @param value The value to divide by.
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the result of the division.
+     */
+    div(value, significantDigits) {
+        value = Decimal.from(value);
+        assert(value.neq0(), 'Division by zero');
+        if (this.eq0()) {
+            return Decimal.zero;
+        }
+        if (this.lt0()) {
+            return this.neg().div(value, significantDigits).neg();
+        }
+        if (value.lt0()) {
+            return this.div(value.neg(), significantDigits).neg();
+        }
+        let { mantissa1, mantissa2 } = normalize(this, value);
+        if (significantDigits === undefined) {
+            return Decimal.fromFraction({ numerator: mantissa1, denominator: mantissa2 });
+        }
+        else {
+            assert(Number.isInteger(significantDigits) && significantDigits > 0, `Significant digits must be a positive integer, got ${significantDigits}`);
+            let exponent = 0;
+            while (mantissa1 < mantissa2) {
+                mantissa1 *= 10n;
+                exponent -= 1;
+            }
+            while (mantissa2 < mantissa1) {
+                mantissa2 *= 10n;
+                exponent += 1;
+            }
+            for (let i = 0; i < significantDigits; i++) {
+                mantissa1 *= 10n;
+                exponent -= 1;
+            }
+            let quotient = mantissa1 / mantissa2;
+            const remainder = mantissa1 % mantissa2;
+            if (remainder * 2n >= mantissa2) {
+                quotient += 1n;
+            }
+            return new Decimal(quotient, exponent);
+        }
+    }
+    /**
+     * Multiplies the current Decimal instance by 10 raised to the provided integer exponent.
+     *
+     * @param exponent The integer exponent to raise 10 to.
+     * @returns A new Decimal instance representing the result.
+     */
+    e(exponent) {
+        return this.mul(new Decimal(10n).pow(exponent));
+    }
+    /**
+     * Checks if the current Decimal instance is equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the values are equal, false otherwise.
+     */
+    eq(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2 } = normalize(this, value);
+        return mantissa1 === mantissa2;
+    }
+    /**
+     * Checks if the current Decimal instance is equal to zero.
+     *
+     * @returns True if the value is zero, false otherwise.
+     */
+    eq0() {
+        return this.mantissa === 0n;
+    }
+    /**
+     * Rounds the current value down towards negative infinity to the nearest multiple of the specified precision.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    floor(precision = Decimal.one) {
+        const remainder = this.mod(precision);
+        if (remainder.eq0()) {
+            return this;
+        }
+        return this.sub(remainder);
+    }
+    /**
+     * Checks if the current Decimal instance is greater than the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is greater, false otherwise.
+     */
+    gt(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2 } = normalize(this, value);
+        return mantissa1 > mantissa2;
+    }
+    /**
+     * Checks if the current Decimal instance is greater than zero.
+     *
+     * @returns True if the value is greater than zero, false otherwise.
+     */
+    gt0() {
+        return this.mantissa > 0n;
+    }
+    /**
+     * Checks if the current Decimal instance is greater than or equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is greater or equal, false otherwise.
+     */
+    gte(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2 } = normalize(this, value);
+        return mantissa1 >= mantissa2;
+    }
+    /**
+     * Checks if the current Decimal instance is greater than or equal to zero.
+     *
+     * @returns True if the value is greater than or equal to zero, false otherwise.
+     */
+    gte0() {
+        return this.mantissa >= 0n;
+    }
+    /**
+     * Returns the multiplicative inverse of the current Decimal instance.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to invert such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.from(3).inv(); // Throws
+     * Decimal.from(3).inv(2); // Returns 0.33
+     * ```
+     *
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the inverse.
+     */
+    inv(significantDigits) {
+        return Decimal.one.div(this, significantDigits);
+    }
+    /**
+     * Checks if the current Decimal instance is an integer.
+     *
+     * @returns True if the value is an integer, false otherwise.
+     */
+    isInteger() {
+        return this.exponent >= 0;
+    }
+    /**
+     * Checks if the current Decimal instance is less than the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is less, false otherwise.
+     */
+    lt(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2 } = normalize(this, value);
+        return mantissa1 < mantissa2;
+    }
+    /**
+     * Checks if the current Decimal instance is less than zero.
+     *
+     * @returns True if the value is less than zero, false otherwise.
+     */
+    lt0() {
+        return this.mantissa < 0n;
+    }
+    /**
+     * Checks if the current Decimal instance is less than or equal to the provided value.
+     *
+     * @param value The value to compare with.
+     * @returns True if the current instance is less or equal, false otherwise.
+     */
+    lte(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2 } = normalize(this, value);
+        return mantissa1 <= mantissa2;
+    }
+    /**
+     * Checks if the current Decimal instance is less than or equal to zero.
+     *
+     * @returns True if the value is less than or equal to zero, false otherwise.
+     */
+    lte0() {
+        return this.mantissa <= 0n;
+    }
+    /**
+     * Returns the order of magnitude (defined as `floor(log10(abs(value)))`) of the current Decimal instance.
+     *
+     * @returns A number representing the order of magnitude.
+     */
+    magnitude() {
+        if (this.lt0()) {
+            return this.neg().magnitude();
+        }
+        let mantissa = 1n;
+        let exponent = -1;
+        while (this.mantissa >= mantissa) {
+            mantissa *= 10n;
+            exponent += 1;
+        }
+        return exponent + this.exponent;
+    }
+    /**
+     * Returns the remainder when dividing the current Decimal instance by the provided value.
+     *
+     * @param value The value to divide by.
+     * @returns A new Decimal instance representing the remainder.
+     */
+    mod(value) {
+        value = Decimal.from(value);
+        assert(value.neq0(), `Division by zero`);
+        if (value.lt0()) {
+            return this.mod(value.neg());
+        }
+        const { mantissa1, mantissa2, exponent } = normalize(this, value);
+        const result = mantissa1 % mantissa2;
+        return new Decimal(result < 0n ? result + mantissa2 : result, exponent);
+    }
+    /**
+     * Multiplies the current Decimal instance by the provided value.
+     *
+     * @param value The value to multiply by.
+     * @returns A new Decimal instance representing the product.
+     */
+    mul(value) {
+        value = Decimal.from(value);
+        return new Decimal(this.mantissa * value.mantissa, this.exponent + value.exponent);
+    }
+    /**
+     * Negates the current Decimal instance.
+     *
+     * @returns A new Decimal instance representing the negated value.
+     */
+    neg() {
+        return new Decimal(-this.mantissa, this.exponent);
+    }
+    /**
+     * Checks if the current value is not equal to the provided value.
+     *
+     * @param value The value to compare against.
+     * @returns True if the values are not equal, false otherwise.
+     */
+    neq(value) {
+        return !this.eq(value);
+    }
+    /**
+     * Checks if the current value is not equal to zero.
+     *
+     * @returns True if the value is not zero, false otherwise.
+     */
+    neq0() {
+        return !this.eq0();
+    }
+    /**
+     * Raises the current Decimal instance to the power of the provided integer exponent.
+     *
+     * @param value The integer exponent to raise to.
+     * @returns A new Decimal instance representing the result of the exponentiation.
+     */
+    pow(value) {
+        assert(Number.isInteger(value), `Exponent must be an integer, got ${value}`);
+        if (value === 0) {
+            return Decimal.one;
+        }
+        else if (value === 1) {
+            return this;
+        }
+        else if (value < 0) {
+            return this.inv().pow(-value);
+        }
+        else {
+            return new Decimal(this.mantissa ** BigInt(value), this.exponent * value);
+        }
+    }
+    /**
+     * Rounds the current value towards the nearest multiple of the specified precision.
+     *
+     * If the current value is exactly halfway between two multiples of the precision, it is rounded up towards positive infinity.
+     *
+     * @param precision The precision to round to. Defaults to `Decimal.one`, meaning it rounds to the nearest integer.
+     * @returns A new Decimal instance representing the rounded value.
+     */
+    round(precision = Decimal.one) {
+        return this.add(new Decimal(5n, -1).mul(precision)).floor(precision);
+    }
+    /**
+     * Returns the sign of the current value as a Decimal instance.
+     *
+     * @returns A Decimal instance representing the sign: 1 for positive, -1 for negative, and 0 for zero.
+     */
+    sign() {
+        if (this.gt0()) {
+            return Decimal.one;
+        }
+        if (this.lt0()) {
+            return Decimal.minusOne;
+        }
+        return Decimal.zero;
+    }
+    /**
+     * Subtracts the provided value from the current Decimal instance.
+     *
+     * @param value The value to subtract.
+     * @returns A new Decimal instance representing the result of the subtraction.
+     */
+    sub(value) {
+        value = Decimal.from(value);
+        const { mantissa1, mantissa2, exponent } = normalize(this, value);
+        return new Decimal(mantissa1 - mantissa2, exponent);
+    }
+    /**
+     * Converts the current Decimal instance to a bigint, if it is an integer.
+     *
+     * Throws if the Decimal instance is not an integer.
+     *
+     * @returns A bigint representing the integer value of the Decimal instance.
+     */
+    toBigInt() {
+        assert(this.isInteger(), `Decimal ${this} is not an integer`);
+        return this.mantissa * 10n ** BigInt(this.exponent);
+    }
+    /**
+     * Converts the current Decimal instance to a fixed-point notation string.
+     *
+     * @param precision The number of decimal places to include in the result.
+     * @returns A string representing the Decimal instance in fixed-point notation.
+     */
+    toFixed(precision) {
+        assert(Number.isInteger(precision) && precision >= 0, `Precision must be a non-negative integer, got ${precision}`);
+        if (this.lt0()) {
+            return '-' + this.neg().toFixed(precision);
+        }
+        const value = this.e(precision).round().e(-precision);
+        if (value.exponent >= 0) {
+            const result = value.mantissa.toString() + '0'.repeat(value.exponent);
+            return precision > 0 ? result + '.' + '0'.repeat(precision) : result;
+        }
+        else {
+            const string = value.mantissa.toString().padStart(-value.exponent + 1, '0');
+            return string.slice(0, value.exponent) + '.' + string.slice(value.exponent).padEnd(precision, '0');
+        }
+    }
+    /**
+     * Converts the current value to a fraction represented by a numerator and denominator.
+     *
+     * Simplifies the fraction to its lowest terms.
+     *
+     * @returns An object with numerator and denominator properties.
+     */
+    toFraction() {
+        if (this.lt0()) {
+            const { numerator, denominator } = this.neg().toFraction();
+            return { numerator: -numerator, denominator };
+        }
+        if (this.exponent >= 0) {
+            return { numerator: this.mantissa * 10n ** BigInt(this.exponent), denominator: 1n };
+        }
+        else {
+            const numerator = this.mantissa;
+            const denominator = 10n ** BigInt(-this.exponent);
+            const divisor = gcd(numerator, denominator);
+            return { numerator: numerator / divisor, denominator: denominator / divisor };
+        }
+    }
+    /**
+     * Converts the current Decimal value to a JSON string.
+     *
+     * @returns A string representing the Decimal value in JSON format.
+     */
+    toJSON() {
+        return this.toString();
+    }
+    /**
+     * Converts the current value to a number.
+     *
+     * This may lose precision if the Decimal cannot be exactly represented as a number.
+     *
+     * @returns The number representation of the current Decimal value.
+     */
+    toNumber() {
+        return Number(this.toString());
+    }
+    /**
+     * Converts the current value to a string.
+     *
+     * @returns A string representing the current Decimal value.
+     */
+    toString() {
+        if (this.lt0()) {
+            return '-' + this.neg().toString();
+        }
+        if (this.exponent >= 0) {
+            return this.mantissa.toString() + '0'.repeat(this.exponent);
+        }
+        else {
+            const string = this.mantissa.toString().padStart(-this.exponent + 1, '0');
+            return string.slice(0, this.exponent) + '.' + string.slice(this.exponent);
+        }
+    }
+    /**
+     * A static constant representing the decimal value -1.
+     */
+    static minusOne = new Decimal(-1n);
+    /**
+     * A static constant representing the decimal value 1.
+     */
+    static one = new Decimal(1n);
+    /**
+     * A static constant representing the decimal value 0.
+     */
+    static zero = new Decimal(0n);
+    /**
+     * Adds multiple values together.
+     *
+     * @param values An array of values to add.
+     * @returns A new Decimal instance representing the sum of the values.
+     */
+    static add(...values) {
+        return values.reduce((previous, current) => {
+            return previous.add(current);
+        }, Decimal.zero);
+    }
+    /**
+     * Divides one value by another.
+     *
+     * Throws if the resulting value cannot be represented with a fixed number of decimals (like 1/3).
+     *
+     * If you need to divide by such a value, use the optional `significantDigits` parameter to specify the number of significant digits to use in the result.
+     *
+     * ```ts
+     * Decimal.div(1, 3); // Throws
+     * Decimal.div(1, 3, 2); // Returns 0.33
+     * ```
+     * @param dividend The value to divide.
+     * @param divisor The value to divide by.
+     * @param significantDigits The number of significant digits to use in the result.
+     * @returns A new Decimal instance representing the quotient.
+     */
+    static div(dividend, divisor, significantDigits) {
+        return Decimal.from(dividend).div(divisor, significantDigits);
+    }
+    /**
+     * Creates a Decimal instance from a string (in standard or scientific notation), a number or a bigint.
+     *
+     * @param value The value to convert.
+     * @returns A Decimal instance representing the provided value.
+     */
+    static from(value) {
+        if (typeof value === 'string') {
+            return this.fromString(value);
+        }
+        if (typeof value === 'number') {
+            return this.fromNumber(value);
+        }
+        if (typeof value === 'bigint') {
+            return this.fromBigInt(value);
+        }
+        return value;
+    }
+    /**
+     * Creates a Decimal instance from a fraction.
+     *
+     * Throws if the fraction cannot be represented with a fixed number of decimals.
+     *
+     * @param numerator The numerator of the fraction.
+     * @param denominator The denominator of the fraction.
+     * @returns A Decimal instance representing the fraction.
+     */
+    static fromFraction({ numerator, denominator }) {
+        if (denominator < 0n) {
+            numerator = -numerator;
+            denominator = -denominator;
+        }
+        if (numerator < 0n) {
+            return this.fromFraction({ numerator: -numerator, denominator }).neg();
+        }
+        const divisor = gcd(numerator, denominator);
+        numerator /= divisor;
+        denominator /= divisor;
+        let value = denominator;
+        let factor = 1n;
+        let exponent = 0;
+        while (value > 1 && (value % 2n === 0n)) {
+            value /= 2n;
+            factor *= 5n;
+            exponent -= 1;
+        }
+        while (value > 1 && (value % 5n === 0n)) {
+            value /= 5n;
+            factor *= 2n;
+            exponent -= 1;
+        }
+        assert(value === 1n, `Fraction ${numerator}/${denominator} cannot be represented with a fixed number of decimals`);
+        return new Decimal(numerator * factor, exponent);
+    }
+    /**
+     * Creates a Decimal instance from a bigint.
+     *
+     * @param value The bigint value to convert.
+     * @returns A Decimal instance representing the provided bigint value.
+     */
+    static fromBigInt(value) {
+        return new Decimal(value);
+    }
+    /**
+     * Creates a Decimal instance from a number.
+     *
+     * @param value The number value to convert.
+     * @returns A Decimal instance representing the provided number.
+     */
+    static fromNumber(value) {
+        if (Number.isInteger(value)) {
+            return new Decimal(BigInt(value));
+        }
+        else {
+            return this.fromString(value.toString());
+        }
+    }
+    /**
+     * Creates a Decimal instance from a string (in standard or scientific notation).
+     *
+     * @param string The string value to convert.
+     * @returns A Decimal instance representing the provided string.
+     */
+    static fromString(string) {
+        if (/^(-?[0-9]+|0x[0-9a-f]+|0o[0-7]+|0b[01]+)$/i.test(string)) {
+            return this.fromBigInt(BigInt(string));
+        }
+        const match = string.match(/^(-?\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i);
+        assert(match !== null, `Could not parse Decimal from string ${string}`);
+        let exponent = 0;
+        if (match[3] !== undefined) {
+            exponent = Number(match[3]);
+        }
+        const mantissa = (() => {
+            if (match[2] !== undefined) {
+                exponent -= match[2].length;
+                return match[1] + match[2];
+            }
+            else {
+                assert(match[1] !== undefined);
+                return match[1];
+            }
+        })();
+        return new Decimal(BigInt(mantissa), exponent);
+    }
+    /**
+     * Finds the maximum value among the provided values.
+     *
+     * @param first The first value to compare.
+     * @param values Additional values to compare.
+     * @returns A new Decimal instance representing the maximum value.
+     */
+    static max(first, ...values) {
+        return values.reduce((max, value) => {
+            return max.lt(value) ? this.from(value) : max;
+        }, this.from(first));
+    }
+    /**
+     * Finds the minimum value among the provided values.
+     *
+     * @param first The first value to compare.
+     * @param values Additional values to compare.
+     * @returns A new Decimal instance representing the minimum value.
+     */
+    static min(first, ...values) {
+        return values.reduce((min, value) => {
+            return min.gt(value) ? this.from(value) : min;
+        }, this.from(first));
+    }
+    /**
+     * Multiplies multiple values together.
+     *
+     * @param values An array of values to multiply.
+     * @returns A new Decimal instance representing the product of the values.
+     */
+    static mul(...values) {
+        return values.reduce((previous, current) => {
+            return previous.mul(current);
+        }, Decimal.one);
+    }
+    /**
+     * Subtracts one value from another.
+     *
+     * @param minuend The value to subtract from.
+     * @param subtrahend The value to subtract.
+     * @returns A new Decimal instance representing the result of the subtraction.
+     */
+    static sub(minuend, subtrahend) {
+        return Decimal.from(minuend).sub(subtrahend);
+    }
+    /**
+     * Calculates the greatest common divisor (GCD) of two values.
+     *
+     * @param a The first value.
+     * @param b The second value.
+     * @returns A new Decimal instance representing the GCD of the two values.
+     */
+    static gcd(a, b) {
+        a = Decimal.from(a);
+        b = Decimal.from(b);
+        if (a.lt0()) {
+            a = a.neg();
+        }
+        if (b.lt0()) {
+            b = b.neg();
+        }
+        return ((a, b) => {
+            while (b.neq0()) {
+                const t = b;
+                b = a.mod(b);
+                a = t;
+            }
+            return a;
+        })(a, b);
+    }
+}
+function gcd(a, b) {
+    if (a < 0n) {
+        a = -a;
+    }
+    if (b < 0n) {
+        b = -b;
+    }
+    while (b !== 0n) {
+        const t = b;
+        b = a % b;
+        a = t;
+    }
+    return a;
+}
+function normalize(value1, value2) {
+    const exponent = Math.min(value1.exponent, value2.exponent);
+    return {
+        mantissa1: value1.mantissa * 10n ** BigInt(value1.exponent - exponent),
+        mantissa2: value2.mantissa * 10n ** BigInt(value2.exponent - exponent),
+        exponent,
+    };
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@quentinadam/decimal",
+  "version": "0.1.8",
+  "description": "A library for working with arbitrary precision decimal numbers",
+  "license": "MIT",
+  "author": "Quentin Adam",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quentinadam/deno-decimal.git"
+  },
+  "type": "module",
+  "exports": "./dist/Decimal.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@quentinadam/assert": "^0.1.10"
+  }
+}