bigdecimal-string 1.0.0

package/dist/index.mjs

@@ -0,0 +1,574 @@
+// src/index.ts
+var RoundingMode = /* @__PURE__ */ ((RoundingMode2) => {
+  RoundingMode2["CEILING"] = "CEILING";
+  RoundingMode2["FLOOR"] = "FLOOR";
+  RoundingMode2["DOWN"] = "DOWN";
+  RoundingMode2["UP"] = "UP";
+  RoundingMode2["HALF_EVEN"] = "HALF_EVEN";
+  RoundingMode2["HALF_UP"] = "HALF_UP";
+  RoundingMode2["HALF_DOWN"] = "HALF_DOWN";
+  return RoundingMode2;
+})(RoundingMode || {});
+var DEFAULT_PRECISION = 2;
+var DEFAULT_ROUNDING_MODE = "HALF_UP" /* HALF_UP */;
+var BigDecimal = class _BigDecimal {
+  /**
+   * 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, precision) {
+    if (value === null || value === void 0 || value === "") {
+      this.unscaledValue = 0n;
+      this.scale = precision ?? DEFAULT_PRECISION;
+      return;
+    }
+    if (value instanceof _BigDecimal) {
+      if (precision !== void 0 && precision !== value.scale) {
+        const adjusted = value.setScale(precision);
+        this.unscaledValue = adjusted.unscaledValue;
+        this.scale = adjusted.scale;
+      } else {
+        this.unscaledValue = value.unscaledValue;
+        this.scale = value.scale;
+      }
+      return;
+    }
+    const parsed = _BigDecimal.parse(value, precision);
+    this.unscaledValue = parsed.unscaledValue;
+    this.scale = parsed.scale;
+  }
+  /**
+   * Parse a value into unscaled bigint and scale
+   */
+  static parse(value, precision) {
+    if (typeof value === "bigint") {
+      const scale = precision ?? DEFAULT_PRECISION;
+      return {
+        unscaledValue: value * _BigDecimal.powerOf10(scale),
+        scale
+      };
+    }
+    let str = typeof value === "number" ? value.toString() : value;
+    if (/[eE]/.test(str)) {
+      str = _BigDecimal.scientificToPlain(str);
+    }
+    const isNegative = str.startsWith("-");
+    if (isNegative || str.startsWith("+")) {
+      str = str.slice(1);
+    }
+    const [intPart, decPart = ""] = str.split(/[.,]/);
+    const detectedScale = decPart.length;
+    const targetScale = precision ?? Math.max(detectedScale, DEFAULT_PRECISION);
+    let cleanIntPart = intPart.replace(/^0+/, "") || "0";
+    let adjustedDecPart;
+    if (decPart.length < targetScale) {
+      adjustedDecPart = decPart.padEnd(targetScale, "0");
+    } else if (decPart.length > targetScale) {
+      adjustedDecPart = decPart.slice(0, targetScale);
+      const nextDigit = parseInt(decPart[targetScale] || "0", 10);
+      if (nextDigit >= 5) {
+        if (targetScale === 0) {
+          cleanIntPart = (BigInt(cleanIntPart) + 1n).toString();
+        } else {
+          const rounded = BigInt(adjustedDecPart || "0") + 1n;
+          const roundedStr = rounded.toString();
+          if (roundedStr.length > targetScale) {
+            cleanIntPart = (BigInt(cleanIntPart) + 1n).toString();
+            adjustedDecPart = "0".repeat(targetScale);
+          } else {
+            adjustedDecPart = roundedStr.padStart(targetScale, "0");
+          }
+        }
+      }
+    } else {
+      adjustedDecPart = decPart;
+    }
+    const combined = targetScale > 0 ? cleanIntPart + adjustedDecPart : cleanIntPart;
+    let unscaledValue = BigInt(combined);
+    if (isNegative) {
+      unscaledValue = -unscaledValue;
+    }
+    return { unscaledValue, scale: targetScale };
+  }
+  /**
+   * Convert scientific notation to plain decimal string
+   */
+  static scientificToPlain(sci) {
+    if (!/[eE]/.test(sci)) return sci;
+    const [coefficient, expPart] = sci.toLowerCase().split("e");
+    const exponent = parseInt(expPart, 10);
+    const isNegative = coefficient.startsWith("-");
+    const cleanCoef = coefficient.replace(/^[-+]/, "");
+    const [intPart, fracPart = ""] = cleanCoef.split(".");
+    const digits = intPart + fracPart;
+    const sign = isNegative ? "-" : "";
+    if (exponent >= 0) {
+      const totalIntDigits = intPart.length + exponent;
+      if (totalIntDigits >= digits.length) {
+        return sign + digits + "0".repeat(totalIntDigits - digits.length);
+      }
+      return sign + digits.slice(0, totalIntDigits) + "." + digits.slice(totalIntDigits);
+    }
+    const zerosNeeded = Math.abs(exponent) - intPart.length;
+    if (zerosNeeded >= 0) {
+      return sign + "0." + "0".repeat(zerosNeeded) + digits;
+    }
+    const splitPoint = intPart.length + exponent;
+    return sign + digits.slice(0, splitPoint) + "." + digits.slice(splitPoint);
+  }
+  /**
+   * Calculate 10^n as bigint
+   */
+  static powerOf10(n) {
+    if (n < 0) throw new Error("Power must be non-negative");
+    return 10n ** BigInt(n);
+  }
+  // ============================================
+  // ARITHMETIC OPERATIONS (Chainable)
+  // ============================================
+  /**
+   * Add another value to this BigDecimal
+   * @returns A new BigDecimal with the result
+   */
+  add(other) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    const [a, b] = _BigDecimal.alignScales(this, otherBd);
+    return _BigDecimal.fromUnscaled(a.unscaledValue + b.unscaledValue, a.scale);
+  }
+  /**
+   * Subtract another value from this BigDecimal
+   * @returns A new BigDecimal with the result
+   */
+  subtract(other) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    const [a, b] = _BigDecimal.alignScales(this, otherBd);
+    return _BigDecimal.fromUnscaled(a.unscaledValue - b.unscaledValue, a.scale);
+  }
+  /**
+   * Alias for subtract
+   */
+  minus(other) {
+    return this.subtract(other);
+  }
+  /**
+   * Alias for add
+   */
+  plus(other) {
+    return this.add(other);
+  }
+  /**
+   * Multiply this BigDecimal by another value
+   * @returns A new BigDecimal with the result
+   */
+  multiply(other) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    const rawResult = this.unscaledValue * otherBd.unscaledValue;
+    const rawScale = this.scale + otherBd.scale;
+    const targetScale = Math.max(this.scale, otherBd.scale);
+    const scaleDiff = rawScale - targetScale;
+    const divisor = _BigDecimal.powerOf10(scaleDiff);
+    const rounded = _BigDecimal.roundDivision(rawResult, divisor, DEFAULT_ROUNDING_MODE);
+    return _BigDecimal.fromUnscaled(rounded, targetScale);
+  }
+  /**
+   * Alias for multiply
+   */
+  times(other) {
+    return this.multiply(other);
+  }
+  /**
+   * 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, precision, roundingMode = DEFAULT_ROUNDING_MODE) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    if (otherBd.unscaledValue === 0n) {
+      throw new Error("Division by zero");
+    }
+    const targetScale = precision ?? this.scale;
+    const scaledDividend = this.unscaledValue * _BigDecimal.powerOf10(otherBd.scale + targetScale);
+    const divisor = otherBd.unscaledValue * _BigDecimal.powerOf10(this.scale);
+    const result = _BigDecimal.roundDivision(scaledDividend, divisor, roundingMode);
+    return _BigDecimal.fromUnscaled(result, targetScale);
+  }
+  /**
+   * Alias for divide
+   */
+  dividedBy(other, precision, roundingMode) {
+    return this.divide(other, precision, roundingMode);
+  }
+  /**
+   * Get the remainder of division
+   */
+  mod(other) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    const [a, b] = _BigDecimal.alignScales(this, otherBd);
+    if (b.unscaledValue === 0n) {
+      throw new Error("Division by zero");
+    }
+    const remainder = a.unscaledValue % b.unscaledValue;
+    return _BigDecimal.fromUnscaled(remainder, a.scale);
+  }
+  // ============================================
+  // COMPARISON OPERATIONS
+  // ============================================
+  /**
+   * Compare this BigDecimal to another
+   * @returns -1 if this < other, 0 if equal, 1 if this > other
+   */
+  compareTo(other) {
+    const otherBd = other instanceof _BigDecimal ? other : new _BigDecimal(other, this.scale);
+    const [a, b] = _BigDecimal.alignScales(this, otherBd);
+    if (a.unscaledValue < b.unscaledValue) return -1;
+    if (a.unscaledValue > b.unscaledValue) return 1;
+    return 0;
+  }
+  /**
+   * Check if this BigDecimal equals another value
+   */
+  equals(other) {
+    return this.compareTo(other) === 0;
+  }
+  /**
+   * Alias for equals
+   */
+  eq(other) {
+    return this.equals(other);
+  }
+  /**
+   * Check if this BigDecimal is less than another
+   */
+  lessThan(other) {
+    return this.compareTo(other) < 0;
+  }
+  /**
+   * Alias for lessThan
+   */
+  lt(other) {
+    return this.lessThan(other);
+  }
+  /**
+   * Check if this BigDecimal is less than or equal to another
+   */
+  lessThanOrEqual(other) {
+    return this.compareTo(other) <= 0;
+  }
+  /**
+   * Alias for lessThanOrEqual
+   */
+  lte(other) {
+    return this.lessThanOrEqual(other);
+  }
+  /**
+   * Check if this BigDecimal is greater than another
+   */
+  greaterThan(other) {
+    return this.compareTo(other) > 0;
+  }
+  /**
+   * Alias for greaterThan
+   */
+  gt(other) {
+    return this.greaterThan(other);
+  }
+  /**
+   * Check if this BigDecimal is greater than or equal to another
+   */
+  greaterThanOrEqual(other) {
+    return this.compareTo(other) >= 0;
+  }
+  /**
+   * Alias for greaterThanOrEqual
+   */
+  gte(other) {
+    return this.greaterThanOrEqual(other);
+  }
+  // ============================================
+  // UTILITY METHODS
+  // ============================================
+  /**
+   * Check if this BigDecimal is zero
+   */
+  isZero() {
+    return this.unscaledValue === 0n;
+  }
+  /**
+   * Check if this BigDecimal is positive (> 0)
+   */
+  isPositive() {
+    return this.unscaledValue > 0n;
+  }
+  /**
+   * Check if this BigDecimal is negative (< 0)
+   */
+  isNegative() {
+    return this.unscaledValue < 0n;
+  }
+  /**
+   * Get the absolute value
+   * @returns A new BigDecimal with the absolute value
+   */
+  abs() {
+    if (this.unscaledValue >= 0n) {
+      return this;
+    }
+    return _BigDecimal.fromUnscaled(-this.unscaledValue, this.scale);
+  }
+  /**
+   * Negate this BigDecimal
+   * @returns A new BigDecimal with the opposite sign
+   */
+  negate() {
+    return _BigDecimal.fromUnscaled(-this.unscaledValue, this.scale);
+  }
+  /**
+   * Get the sign of this BigDecimal
+   * @returns -1, 0, or 1
+   */
+  sign() {
+    if (this.unscaledValue < 0n) return -1;
+    if (this.unscaledValue > 0n) return 1;
+    return 0;
+  }
+  /**
+   * Change the scale (number of decimal places)
+   */
+  setScale(newScale, roundingMode = DEFAULT_ROUNDING_MODE) {
+    if (newScale === this.scale) {
+      return this;
+    }
+    if (newScale > this.scale) {
+      const multiplier = _BigDecimal.powerOf10(newScale - this.scale);
+      return _BigDecimal.fromUnscaled(this.unscaledValue * multiplier, newScale);
+    }
+    const divisor = _BigDecimal.powerOf10(this.scale - newScale);
+    const rounded = _BigDecimal.roundDivision(this.unscaledValue, divisor, roundingMode);
+    return _BigDecimal.fromUnscaled(rounded, newScale);
+  }
+  /**
+   * Get the precision (number of decimal places)
+   */
+  getPrecision() {
+    return this.scale;
+  }
+  // ============================================
+  // CONVERSION METHODS
+  // ============================================
+  /**
+   * 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) {
+    const isNegative = this.unscaledValue < 0n;
+    const absValue = isNegative ? -this.unscaledValue : this.unscaledValue;
+    const sign = isNegative ? "-" : "";
+    let intPart;
+    let decPart;
+    if (this.scale === 0) {
+      intPart = absValue.toString();
+      decPart = "";
+    } else {
+      const str = absValue.toString().padStart(this.scale + 1, "0");
+      intPart = str.slice(0, -this.scale) || "0";
+      decPart = str.slice(-this.scale);
+    }
+    if (options?.prettify) {
+      intPart = _BigDecimal.addThousandSeparators(intPart);
+    }
+    if (this.scale === 0 || !decPart) {
+      return `${sign}${intPart}`;
+    }
+    return `${sign}${intPart}.${decPart}`;
+  }
+  /**
+   * 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() {
+    return this.toString({ prettify: true });
+  }
+  /**
+   * Add thousand separators to an integer string
+   */
+  static addThousandSeparators(intPart) {
+    return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  }
+  /**
+   * Convert to number (may lose precision for large values)
+   * @warning Use with caution - JavaScript numbers have limited precision
+   */
+  toNumber() {
+    return parseFloat(this.toString());
+  }
+  /**
+   * Format with fixed decimal places
+   * @param decimals - Number of decimal places
+   * @param options - Formatting options
+   */
+  toFixed(decimals, options) {
+    return this.setScale(decimals).toString(options);
+  }
+  /**
+   * Get the integer part only
+   */
+  toInteger() {
+    const divisor = _BigDecimal.powerOf10(this.scale);
+    return this.unscaledValue / divisor;
+  }
+  /**
+   * valueOf for implicit conversions
+   */
+  valueOf() {
+    return this.toNumber();
+  }
+  // ============================================
+  // STATIC FACTORY METHODS
+  // ============================================
+  /**
+   * Create from unscaled value and scale
+   */
+  static fromUnscaled(unscaledValue, scale) {
+    const bd2 = Object.create(_BigDecimal.prototype);
+    bd2.unscaledValue = unscaledValue;
+    bd2.scale = scale;
+    return bd2;
+  }
+  /**
+   * Create a BigDecimal with value zero
+   */
+  static zero(precision = DEFAULT_PRECISION) {
+    return new _BigDecimal(0, precision);
+  }
+  /**
+   * Create a BigDecimal with value one
+   */
+  static one(precision = DEFAULT_PRECISION) {
+    return new _BigDecimal(1, precision);
+  }
+  /**
+   * Sum multiple values
+   */
+  static sum(...values) {
+    if (values.length === 0) {
+      return _BigDecimal.zero();
+    }
+    return values.reduce((acc, val) => {
+      return acc.add(val);
+    }, _BigDecimal.zero());
+  }
+  /**
+   * Get the maximum value
+   */
+  static max(...values) {
+    if (values.length === 0) {
+      throw new Error("max requires at least one value");
+    }
+    return values.reduce((max, val) => {
+      const bd2 = val instanceof _BigDecimal ? val : new _BigDecimal(val);
+      return bd2.gt(max) ? bd2 : max;
+    }, new _BigDecimal(values[0]));
+  }
+  /**
+   * Get the minimum value
+   */
+  static min(...values) {
+    if (values.length === 0) {
+      throw new Error("min requires at least one value");
+    }
+    return values.reduce((min, val) => {
+      const bd2 = val instanceof _BigDecimal ? val : new _BigDecimal(val);
+      return bd2.lt(min) ? bd2 : min;
+    }, new _BigDecimal(values[0]));
+  }
+  // ============================================
+  // INTERNAL HELPERS
+  // ============================================
+  /**
+   * Align two BigDecimals to the same scale
+   */
+  static alignScales(a, b) {
+    if (a.scale === b.scale) {
+      return [a, b];
+    }
+    const targetScale = Math.max(a.scale, b.scale);
+    return [a.setScale(targetScale), b.setScale(targetScale)];
+  }
+  /**
+   * Perform division with rounding
+   */
+  static roundDivision(dividend, divisor, mode) {
+    if (divisor === 0n) {
+      throw new Error("Division by zero");
+    }
+    const quotient = dividend / divisor;
+    const remainder = dividend % divisor;
+    if (remainder === 0n) {
+      return quotient;
+    }
+    const isNegative = dividend < 0n !== divisor < 0n;
+    const absRemainder = remainder < 0n ? -remainder : remainder;
+    const absDivisor = divisor < 0n ? -divisor : divisor;
+    const shouldRoundUp = (() => {
+      switch (mode) {
+        case "UP" /* UP */:
+          return true;
+        case "DOWN" /* DOWN */:
+          return false;
+        case "CEILING" /* CEILING */:
+          return !isNegative;
+        case "FLOOR" /* FLOOR */:
+          return isNegative;
+        case "HALF_UP" /* HALF_UP */: {
+          const doubled = absRemainder * 2n;
+          return doubled >= absDivisor;
+        }
+        case "HALF_DOWN" /* HALF_DOWN */: {
+          const doubled = absRemainder * 2n;
+          return doubled > absDivisor;
+        }
+        case "HALF_EVEN" /* HALF_EVEN */: {
+          const doubled = absRemainder * 2n;
+          if (doubled > absDivisor) return true;
+          if (doubled < absDivisor) return false;
+          const absQuotient = quotient < 0n ? -quotient : quotient;
+          return absQuotient % 2n !== 0n;
+        }
+        default:
+          return false;
+      }
+    })();
+    if (shouldRoundUp) {
+      return isNegative ? quotient - 1n : quotient + 1n;
+    }
+    return quotient;
+  }
+};
+function bd(value, precision) {
+  return new BigDecimal(value, precision);
+}
+var index_default = BigDecimal;
+export {
+  BigDecimal,
+  RoundingMode,
+  bd,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "bigdecimal-string",
+  "version": "1.0.0",
+  "description": "Precise decimal arithmetic for JavaScript using BigInt. Avoids floating-point errors with a chainable, immutable API.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bigdecimal",
+    "decimal",
+    "precision",
+    "arithmetic",
+    "bigint",
+    "financial",
+    "money",
+    "currency",
+    "floating-point",
+    "math"
+  ],
+  "author": "ozJSey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ozJSey/big_decimal_string.git"
+  },
+  "homepage": "https://github.com/ozJSey/big_decimal_string#readme",
+  "bugs": {
+    "url": "https://github.com/ozJSey/big_decimal_string/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}