@parsrun/core 0.2.6 → 0.2.9

package/dist/decimal.d.ts

@@ -1,7 +1,9 @@
+import DecimalJS from 'decimal.js';
+
 /**
  * @parsrun/core - Decimal Utilities
  * Precise decimal calculations for financial and quantity operations.
- * Edge-compatible - no external dependencies.
+ * Edge-compatible - wraps decimal.js for arbitrary precision arithmetic.
  *
  * @example
  * ```typescript
@@ -15,14 +17,20 @@
  * const total = price.mul(quantity).round(2);
  * console.log(total.toString()); // '59.97'
  *
+ * // Precision info
+ * const d = new Decimal('123.45');
+ * d.precision();      // 5 (total significant digits)
+ * d.decimalPlaces();  // 2 (digits after decimal point)
+ *
  * // Static helpers
  * const sum = Decimal.sum(['10.50', '20.25', '15.75']);
  * const avg = Decimal.avg([100, 200, 300]);
  * ```
  */
+
 /**
  * Decimal class for precise arithmetic operations.
- * Uses string-based representation internally to avoid floating point issues.
+ * Wraps decimal.js to provide arbitrary precision decimal arithmetic.
  *
  * @example
  * ```typescript
@@ -33,10 +41,8 @@
  * ```
  */
 declare class Decimal {
-    private value;
-    constructor(value: number | string | Decimal);
-    private normalizeNumber;
-    private normalizeString;
+    private readonly _value;
+    constructor(value: number | string | Decimal | DecimalJS);
     /**
      * Add another value to this decimal.
      * @param other - Value to add
@@ -159,8 +165,39 @@ declare class Decimal {
      * @returns True if value is negative
      */
     isNegative(): boolean;
+    /**
+     * Check if this decimal is an integer (no decimal places).
+     * @returns True if value is an integer
+     */
+    isInteger(): boolean;
+    /**
+     * Get the number of decimal places (digits after the decimal point).
+     * @returns Number of decimal places
+     *
+     * @example
+     * ```typescript
+     * new Decimal('123.45').decimalPlaces(); // 2
+     * new Decimal('100').decimalPlaces();    // 0
+     * new Decimal('1.500').decimalPlaces();  // 1 (trailing zeros removed)
+     * ```
+     */
+    decimalPlaces(): number;
+    /**
+     * Get the precision (total number of significant digits).
+     * @param includeZeros - If true, include trailing zeros in the count
+     * @returns The precision
+     *
+     * @example
+     * ```typescript
+     * new Decimal('123.45').precision();     // 5
+     * new Decimal('100').precision();        // 1
+     * new Decimal('100').precision(true);    // 3
+     * ```
+     */
+    precision(includeZeros?: boolean): number;
     /**
      * Convert this decimal to a JavaScript number.
+     * Warning: May lose precision for very large or very precise numbers.
      * @returns The numeric value
      */
     toNumber(): number;
@@ -180,6 +217,12 @@ declare class Decimal {
      * @returns The string value for JSON serialization
      */
     toJSON(): string;
+    /**
+     * Get the underlying decimal.js instance.
+     * Useful for advanced operations not covered by this wrapper.
+     * @returns The underlying DecimalJS instance
+     */
+    toDecimalJS(): DecimalJS;
     /**
      * Create a Decimal from a value (alias for constructor).
      * @param value - The value to convert
@@ -212,6 +255,18 @@ declare class Decimal {
      * @throws Error if no values provided
      */
     static max(...values: (number | string | Decimal)[]): Decimal;
+    /**
+     * Check if a value is a valid decimal representation.
+     * @param value - The value to check
+     * @returns True if the value can be converted to a Decimal
+     */
+    static isValid(value: unknown): boolean;
+    /**
+     * Create a Decimal or return null if the value is invalid.
+     * @param value - The value to convert
+     * @returns A Decimal or null
+     */
+    static tryParse(value: unknown): Decimal | null;
 }
 /**
  * Utility functions for working with decimals in database operations.
@@ -296,12 +351,27 @@ declare const DecimalUtils: {
      */
     prepareForDatabase<T extends Record<string, unknown>>(data: T, decimalFields: string[]): T;
     /**
-     * Parse an object from database by converting decimal string fields to JavaScript numbers.
+     * Parse an object from database by converting decimal string fields to Decimal instances.
      * @param data - The object from database
-     * @param decimalFields - Array of field names that should be converted from decimal strings
-     * @returns A new object with specified fields converted to numbers
+     * @param decimalFields - Array of field names that should be converted to Decimal
+     * @returns A new object with specified fields converted to Decimal instances
      */
     parseFromDatabase<T extends Record<string, unknown>>(data: T, decimalFields: string[]): T;
+    /**
+     * Validate that a value matches the specified precision and scale.
+     * @param value - The value to validate
+     * @param precision - Total number of digits (integer + decimal)
+     * @param scale - Number of decimal places
+     * @returns An error message if invalid, or null if valid
+     *
+     * @example
+     * ```typescript
+     * DecimalUtils.validate('123.45', 5, 2);   // null (valid)
+     * DecimalUtils.validate('123.456', 5, 2);  // "max 2 decimal places allowed"
+     * DecimalUtils.validate('1234.56', 5, 2);  // "max 3 integer digits allowed"
+     * ```
+     */
+    validate(value: number | string | Decimal, precision: number, scale: number): string | null;
 };
 /**
  * Shorthand function for creating a Decimal instance.

package/dist/decimal.js

@@ -1,38 +1,30 @@
 // src/decimal.ts
-var PRECISION = 20;
+import DecimalJS from "decimal.js";
+DecimalJS.set({
+  precision: 40,
+  rounding: DecimalJS.ROUND_HALF_UP,
+  toExpNeg: -9,
+  toExpPos: 21
+});
 var Decimal = class _Decimal {
-  value;
+  _value;
   constructor(value) {
     if (value instanceof _Decimal) {
-      this.value = value.value;
-    } else if (typeof value === "number") {
-      this.value = this.normalizeNumber(value);
+      this._value = value._value;
+    } else if (value instanceof DecimalJS) {
+      this._value = value;
     } else {
-      this.value = this.normalizeString(value);
+      this._value = new DecimalJS(value);
     }
   }
-  normalizeNumber(n) {
-    if (!isFinite(n)) {
-      throw new Error(`Invalid number: ${n}`);
-    }
-    return n.toFixed(PRECISION).replace(/\.?0+$/, "") || "0";
-  }
-  normalizeString(s) {
-    const trimmed = s.trim();
-    if (!/^-?\d*\.?\d+$/.test(trimmed)) {
-      throw new Error(`Invalid decimal string: ${s}`);
-    }
-    return trimmed.replace(/^(-?)0+(?=\d)/, "$1").replace(/\.?0+$/, "") || "0";
-  }
   /**
    * Add another value to this decimal.
    * @param other - Value to add
    * @returns A new Decimal with the result
    */
   add(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    return new _Decimal(a + b);
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return new _Decimal(this._value.plus(otherValue));
   }
   /**
    * Subtract a value from this decimal.
@@ -40,9 +32,8 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the result
    */
   sub(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    return new _Decimal(a - b);
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return new _Decimal(this._value.minus(otherValue));
   }
   /**
    * Multiply this decimal by another value.
@@ -50,9 +41,8 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the result
    */
   mul(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    return new _Decimal(a * b);
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return new _Decimal(this._value.times(otherValue));
   }
   /**
    * Divide this decimal by another value.
@@ -61,12 +51,12 @@ var Decimal = class _Decimal {
    * @throws Error if dividing by zero
    */
   div(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    if (b === 0) {
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    const divisor = new DecimalJS(otherValue);
+    if (divisor.isZero()) {
       throw new Error("Division by zero");
     }
-    return new _Decimal(a / b);
+    return new _Decimal(this._value.dividedBy(divisor));
   }
   /**
    * Get the modulo (remainder) of dividing this decimal by another value.
@@ -74,9 +64,8 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the remainder
    */
   mod(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    return new _Decimal(a % b);
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return new _Decimal(this._value.modulo(otherValue));
   }
   /**
    * Raise this decimal to a power.
@@ -84,8 +73,7 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the result
    */
   pow(exp) {
-    const a = parseFloat(this.value);
-    return new _Decimal(Math.pow(a, exp));
+    return new _Decimal(this._value.pow(exp));
   }
   /**
    * Calculate the square root of this decimal.
@@ -93,27 +81,24 @@ var Decimal = class _Decimal {
    * @throws Error if the value is negative
    */
   sqrt() {
-    const a = parseFloat(this.value);
-    if (a < 0) {
+    if (this._value.isNegative()) {
       throw new Error("Square root of negative number");
     }
-    return new _Decimal(Math.sqrt(a));
+    return new _Decimal(this._value.sqrt());
   }
   /**
    * Get the absolute value of this decimal.
    * @returns A new Decimal with the absolute value
    */
   abs() {
-    const a = parseFloat(this.value);
-    return new _Decimal(Math.abs(a));
+    return new _Decimal(this._value.abs());
   }
   /**
    * Negate this decimal (multiply by -1).
    * @returns A new Decimal with the negated value
    */
   neg() {
-    const a = parseFloat(this.value);
-    return new _Decimal(-a);
+    return new _Decimal(this._value.negated());
   }
   /**
    * Round to the specified number of decimal places using standard rounding.
@@ -121,9 +106,7 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the rounded value
    */
   round(decimals = 0) {
-    const a = parseFloat(this.value);
-    const factor = Math.pow(10, decimals);
-    return new _Decimal(Math.round(a * factor) / factor);
+    return new _Decimal(this._value.toDecimalPlaces(decimals, DecimalJS.ROUND_HALF_UP));
   }
   /**
    * Round down to the specified number of decimal places.
@@ -131,9 +114,7 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the floored value
    */
   floor(decimals = 0) {
-    const a = parseFloat(this.value);
-    const factor = Math.pow(10, decimals);
-    return new _Decimal(Math.floor(a * factor) / factor);
+    return new _Decimal(this._value.toDecimalPlaces(decimals, DecimalJS.ROUND_FLOOR));
   }
   /**
    * Round up to the specified number of decimal places.
@@ -141,9 +122,7 @@ var Decimal = class _Decimal {
    * @returns A new Decimal with the ceiled value
    */
   ceil(decimals = 0) {
-    const a = parseFloat(this.value);
-    const factor = Math.pow(10, decimals);
-    return new _Decimal(Math.ceil(a * factor) / factor);
+    return new _Decimal(this._value.toDecimalPlaces(decimals, DecimalJS.ROUND_CEIL));
   }
   /**
    * Compare this decimal to another value.
@@ -151,11 +130,8 @@ var Decimal = class _Decimal {
    * @returns -1 if less, 0 if equal, 1 if greater
    */
   cmp(other) {
-    const a = parseFloat(this.value);
-    const b = parseFloat(other instanceof _Decimal ? other.value : String(other));
-    if (a < b) return -1;
-    if (a > b) return 1;
-    return 0;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.comparedTo(otherValue);
   }
   /**
    * Check if this decimal equals another value.
@@ -163,7 +139,8 @@ var Decimal = class _Decimal {
    * @returns True if values are equal
    */
   eq(other) {
-    return this.cmp(other) === 0;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.equals(otherValue);
   }
   /**
    * Check if this decimal is greater than another value.
@@ -171,7 +148,8 @@ var Decimal = class _Decimal {
    * @returns True if this is greater
    */
   gt(other) {
-    return this.cmp(other) === 1;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.greaterThan(otherValue);
   }
   /**
    * Check if this decimal is greater than or equal to another value.
@@ -179,7 +157,8 @@ var Decimal = class _Decimal {
    * @returns True if this is greater or equal
    */
   gte(other) {
-    return this.cmp(other) >= 0;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.greaterThanOrEqualTo(otherValue);
   }
   /**
    * Check if this decimal is less than another value.
@@ -187,7 +166,8 @@ var Decimal = class _Decimal {
    * @returns True if this is less
    */
   lt(other) {
-    return this.cmp(other) === -1;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.lessThan(otherValue);
   }
   /**
    * Check if this decimal is less than or equal to another value.
@@ -195,42 +175,80 @@ var Decimal = class _Decimal {
    * @returns True if this is less or equal
    */
   lte(other) {
-    return this.cmp(other) <= 0;
+    const otherValue = other instanceof _Decimal ? other._value : other;
+    return this._value.lessThanOrEqualTo(otherValue);
   }
   /**
    * Check if this decimal is exactly zero.
    * @returns True if value is zero
    */
   isZero() {
-    return parseFloat(this.value) === 0;
+    return this._value.isZero();
   }
   /**
    * Check if this decimal is positive (greater than zero).
    * @returns True if value is positive
    */
   isPositive() {
-    return parseFloat(this.value) > 0;
+    return this._value.isPositive() && !this._value.isZero();
   }
   /**
    * Check if this decimal is negative (less than zero).
    * @returns True if value is negative
    */
   isNegative() {
-    return parseFloat(this.value) < 0;
+    return this._value.isNegative();
+  }
+  /**
+   * Check if this decimal is an integer (no decimal places).
+   * @returns True if value is an integer
+   */
+  isInteger() {
+    return this._value.isInteger();
+  }
+  /**
+   * Get the number of decimal places (digits after the decimal point).
+   * @returns Number of decimal places
+   *
+   * @example
+   * ```typescript
+   * new Decimal('123.45').decimalPlaces(); // 2
+   * new Decimal('100').decimalPlaces();    // 0
+   * new Decimal('1.500').decimalPlaces();  // 1 (trailing zeros removed)
+   * ```
+   */
+  decimalPlaces() {
+    return this._value.decimalPlaces();
+  }
+  /**
+   * Get the precision (total number of significant digits).
+   * @param includeZeros - If true, include trailing zeros in the count
+   * @returns The precision
+   *
+   * @example
+   * ```typescript
+   * new Decimal('123.45').precision();     // 5
+   * new Decimal('100').precision();        // 1
+   * new Decimal('100').precision(true);    // 3
+   * ```
+   */
+  precision(includeZeros = false) {
+    return this._value.precision(includeZeros);
   }
   /**
    * Convert this decimal to a JavaScript number.
+   * Warning: May lose precision for very large or very precise numbers.
    * @returns The numeric value
    */
   toNumber() {
-    return parseFloat(this.value);
+    return this._value.toNumber();
   }
   /**
    * Convert this decimal to its string representation.
    * @returns The string value
    */
   toString() {
-    return this.value;
+    return this._value.toString();
   }
   /**
    * Format this decimal with a fixed number of decimal places.
@@ -238,14 +256,22 @@ var Decimal = class _Decimal {
    * @returns Formatted string
    */
   toFixed(decimals = 2) {
-    return parseFloat(this.value).toFixed(decimals);
+    return this._value.toFixed(decimals);
   }
   /**
    * Convert to JSON (returns string representation for serialization).
    * @returns The string value for JSON serialization
    */
   toJSON() {
-    return this.value;
+    return this._value.toString();
+  }
+  /**
+   * Get the underlying decimal.js instance.
+   * Useful for advanced operations not covered by this wrapper.
+   * @returns The underlying DecimalJS instance
+   */
+  toDecimalJS() {
+    return this._value;
   }
   /**
    * Create a Decimal from a value (alias for constructor).
@@ -301,6 +327,30 @@ var Decimal = class _Decimal {
       return d.gt(max) ? d : max;
     }, new _Decimal(values[0]));
   }
+  /**
+   * Check if a value is a valid decimal representation.
+   * @param value - The value to check
+   * @returns True if the value can be converted to a Decimal
+   */
+  static isValid(value) {
+    if (value === null || value === void 0) return false;
+    if (value instanceof _Decimal) return true;
+    try {
+      new DecimalJS(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Create a Decimal or return null if the value is invalid.
+   * @param value - The value to convert
+   * @returns A Decimal or null
+   */
+  static tryParse(value) {
+    if (!_Decimal.isValid(value)) return null;
+    return new _Decimal(value);
+  }
 };
 var DecimalUtils = {
   /**
@@ -393,30 +443,62 @@ var DecimalUtils = {
     for (const field of decimalFields) {
       if (field in result && result[field] !== void 0 && result[field] !== null) {
         const value = result[field];
-        if (typeof value === "number") {
+        if (typeof value === "number" || typeof value === "string") {
           result[field] = DecimalUtils.toDecimalString(value);
+        } else if (value instanceof Decimal) {
+          result[field] = value.toString();
         }
       }
     }
     return result;
   },
   /**
-   * Parse an object from database by converting decimal string fields to JavaScript numbers.
+   * Parse an object from database by converting decimal string fields to Decimal instances.
    * @param data - The object from database
-   * @param decimalFields - Array of field names that should be converted from decimal strings
-   * @returns A new object with specified fields converted to numbers
+   * @param decimalFields - Array of field names that should be converted to Decimal
+   * @returns A new object with specified fields converted to Decimal instances
    */
   parseFromDatabase(data, decimalFields) {
     const result = { ...data };
     for (const field of decimalFields) {
       if (field in result && result[field] !== void 0 && result[field] !== null) {
         const value = result[field];
-        if (typeof value === "string") {
-          result[field] = DecimalUtils.fromDecimalString(value);
+        if (typeof value === "string" || typeof value === "number") {
+          result[field] = new Decimal(value);
         }
       }
     }
     return result;
+  },
+  /**
+   * Validate that a value matches the specified precision and scale.
+   * @param value - The value to validate
+   * @param precision - Total number of digits (integer + decimal)
+   * @param scale - Number of decimal places
+   * @returns An error message if invalid, or null if valid
+   *
+   * @example
+   * ```typescript
+   * DecimalUtils.validate('123.45', 5, 2);   // null (valid)
+   * DecimalUtils.validate('123.456', 5, 2);  // "max 2 decimal places allowed"
+   * DecimalUtils.validate('1234.56', 5, 2);  // "max 3 integer digits allowed"
+   * ```
+   */
+  validate(value, precision, scale) {
+    const d = value instanceof Decimal ? value : new Decimal(value);
+    const maxIntDigits = precision - scale;
+    if (d.decimalPlaces() > scale) {
+      return `max ${scale} decimal places allowed`;
+    }
+    const absValue = d.abs();
+    if (!absValue.isZero()) {
+      const integerPart = absValue.floor(0);
+      const intDigits = integerPart.isZero() ? 0 : integerPart.precision(true);
+      if (intDigits > maxIntDigits) {
+        return `max ${maxIntDigits} integer digits allowed`;
+      }
+    }
+    return null;
   }
 };
 function decimal(value) {