bigdecimal-string 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,289 @@
+/**
+ * BigDecimal - Precise decimal arithmetic for JavaScript
+ *
+ * Avoids floating-point precision issues by using bigint internally.
+ * Supports chainable operations and configurable precision.
+ *
+ * @example
+ * ```ts
+ * const price = new BigDecimal("19.99");
+ * const tax = price.multiply(0.08);
+ * const total = price.add(tax);
+ *
+ * // Chaining
+ * const result = new BigDecimal("100.00")
+ *   .subtract("25.50")
+ *   .multiply(2)
+ *   .add("10")
+ *   .toString(); // "159.00"
+ * ```
+ */
+type BigDecimalInput = string | number | bigint | BigDecimal | null | undefined;
+/**
+ * Configuration options for BigDecimal operations
+ */
+interface BigDecimalConfig {
+    /** Number of decimal places (default: 2) */
+    precision?: number;
+    /** Rounding mode for division and precision changes */
+    roundingMode?: RoundingMode;
+}
+declare enum RoundingMode {
+    /** Round towards positive infinity */
+    CEILING = "CEILING",
+    /** Round towards negative infinity */
+    FLOOR = "FLOOR",
+    /** Round towards zero (truncate) */
+    DOWN = "DOWN",
+    /** Round away from zero */
+    UP = "UP",
+    /** Round to nearest, ties go to even (banker's rounding) */
+    HALF_EVEN = "HALF_EVEN",
+    /** Round to nearest, ties round up */
+    HALF_UP = "HALF_UP",
+    /** Round to nearest, ties round down */
+    HALF_DOWN = "HALF_DOWN"
+}
+declare class BigDecimal {
+    /** Internal representation: value * 10^scale */
+    private readonly unscaledValue;
+    /** Number of decimal places */
+    private readonly scale;
+    /**
+     * Creates a new BigDecimal instance
+     * @param value - The value to create from (string, number, bigint, or another BigDecimal)
+     * @param precision - Number of decimal places (default: auto-detected or 2)
+     */
+    constructor(value?: BigDecimalInput, precision?: number);
+    /**
+     * Parse a value into unscaled bigint and scale
+     */
+    private static parse;
+    /**
+     * Convert scientific notation to plain decimal string
+     */
+    private static scientificToPlain;
+    /**
+     * Calculate 10^n as bigint
+     */
+    private static powerOf10;
+    /**
+     * Add another value to this BigDecimal
+     * @returns A new BigDecimal with the result
+     */
+    add(other: BigDecimalInput): BigDecimal;
+    /**
+     * Subtract another value from this BigDecimal
+     * @returns A new BigDecimal with the result
+     */
+    subtract(other: BigDecimalInput): BigDecimal;
+    /**
+     * Alias for subtract
+     */
+    minus(other: BigDecimalInput): BigDecimal;
+    /**
+     * Alias for add
+     */
+    plus(other: BigDecimalInput): BigDecimal;
+    /**
+     * Multiply this BigDecimal by another value
+     * @returns A new BigDecimal with the result
+     */
+    multiply(other: BigDecimalInput): BigDecimal;
+    /**
+     * Alias for multiply
+     */
+    times(other: BigDecimalInput): BigDecimal;
+    /**
+     * Divide this BigDecimal by another value
+     * @param other - The divisor
+     * @param precision - Precision for the result (default: this.scale)
+     * @param roundingMode - How to round (default: HALF_UP)
+     * @returns A new BigDecimal with the result
+     */
+    divide(other: BigDecimalInput, precision?: number, roundingMode?: RoundingMode): BigDecimal;
+    /**
+     * Alias for divide
+     */
+    dividedBy(other: BigDecimalInput, precision?: number, roundingMode?: RoundingMode): BigDecimal;
+    /**
+     * Get the remainder of division
+     */
+    mod(other: BigDecimalInput): BigDecimal;
+    /**
+     * Compare this BigDecimal to another
+     * @returns -1 if this < other, 0 if equal, 1 if this > other
+     */
+    compareTo(other: BigDecimalInput): -1 | 0 | 1;
+    /**
+     * Check if this BigDecimal equals another value
+     */
+    equals(other: BigDecimalInput): boolean;
+    /**
+     * Alias for equals
+     */
+    eq(other: BigDecimalInput): boolean;
+    /**
+     * Check if this BigDecimal is less than another
+     */
+    lessThan(other: BigDecimalInput): boolean;
+    /**
+     * Alias for lessThan
+     */
+    lt(other: BigDecimalInput): boolean;
+    /**
+     * Check if this BigDecimal is less than or equal to another
+     */
+    lessThanOrEqual(other: BigDecimalInput): boolean;
+    /**
+     * Alias for lessThanOrEqual
+     */
+    lte(other: BigDecimalInput): boolean;
+    /**
+     * Check if this BigDecimal is greater than another
+     */
+    greaterThan(other: BigDecimalInput): boolean;
+    /**
+     * Alias for greaterThan
+     */
+    gt(other: BigDecimalInput): boolean;
+    /**
+     * Check if this BigDecimal is greater than or equal to another
+     */
+    greaterThanOrEqual(other: BigDecimalInput): boolean;
+    /**
+     * Alias for greaterThanOrEqual
+     */
+    gte(other: BigDecimalInput): boolean;
+    /**
+     * Check if this BigDecimal is zero
+     */
+    isZero(): boolean;
+    /**
+     * Check if this BigDecimal is positive (> 0)
+     */
+    isPositive(): boolean;
+    /**
+     * Check if this BigDecimal is negative (< 0)
+     */
+    isNegative(): boolean;
+    /**
+     * Get the absolute value
+     * @returns A new BigDecimal with the absolute value
+     */
+    abs(): BigDecimal;
+    /**
+     * Negate this BigDecimal
+     * @returns A new BigDecimal with the opposite sign
+     */
+    negate(): BigDecimal;
+    /**
+     * Get the sign of this BigDecimal
+     * @returns -1, 0, or 1
+     */
+    sign(): -1 | 0 | 1;
+    /**
+     * Change the scale (number of decimal places)
+     */
+    setScale(newScale: number, roundingMode?: RoundingMode): BigDecimal;
+    /**
+     * Get the precision (number of decimal places)
+     */
+    getPrecision(): number;
+    /**
+     * Convert to string representation
+     * @param options - Formatting options
+     * @param options.prettify - Add thousand separators (commas)
+     *
+     * @example
+     * ```ts
+     * bd("1234567.89").toString()                    // "1234567.89"
+     * bd("1234567.89").toString({ prettify: true }) // "1,234,567.89"
+     * bd("1e15").toString()                          // "1000000000000000.00"
+     * bd("1e15").toString({ prettify: true })       // "1,000,000,000,000,000.00"
+     * ```
+     */
+    toString(options?: {
+        prettify?: boolean;
+    }): string;
+    /**
+     * Format as a display string with thousand separators
+     * Shorthand for toString({ prettify: true })
+     *
+     * @example
+     * ```ts
+     * bd("1234567.89").toFormat()  // "1,234,567.89"
+     * bd("1e12").toFormat()        // "1,000,000,000,000.00"
+     * ```
+     */
+    toFormat(): string;
+    /**
+     * Add thousand separators to an integer string
+     */
+    private static addThousandSeparators;
+    /**
+     * Convert to number (may lose precision for large values)
+     * @warning Use with caution - JavaScript numbers have limited precision
+     */
+    toNumber(): number;
+    /**
+     * Format with fixed decimal places
+     * @param decimals - Number of decimal places
+     * @param options - Formatting options
+     */
+    toFixed(decimals: number, options?: {
+        prettify?: boolean;
+    }): string;
+    /**
+     * Get the integer part only
+     */
+    toInteger(): bigint;
+    /**
+     * valueOf for implicit conversions
+     */
+    valueOf(): number;
+    /**
+     * Create from unscaled value and scale
+     */
+    private static fromUnscaled;
+    /**
+     * Create a BigDecimal with value zero
+     */
+    static zero(precision?: number): BigDecimal;
+    /**
+     * Create a BigDecimal with value one
+     */
+    static one(precision?: number): BigDecimal;
+    /**
+     * Sum multiple values
+     */
+    static sum(...values: BigDecimalInput[]): BigDecimal;
+    /**
+     * Get the maximum value
+     */
+    static max(...values: BigDecimalInput[]): BigDecimal;
+    /**
+     * Get the minimum value
+     */
+    static min(...values: BigDecimalInput[]): BigDecimal;
+    /**
+     * Align two BigDecimals to the same scale
+     */
+    private static alignScales;
+    /**
+     * Perform division with rounding
+     */
+    private static roundDivision;
+}
+/**
+ * Shorthand factory function
+ *
+ * @example
+ * ```ts
+ * const price = bd("19.99");
+ * const total = bd(100).subtract(25).multiply(2);
+ * ```
+ */
+declare function bd(value?: BigDecimalInput, precision?: number): BigDecimal;
+
+export { BigDecimal, type BigDecimalConfig, type BigDecimalInput, RoundingMode, bd, BigDecimal as default };