@parsrun/core 0.1.29 → 0.1.30

package/dist/index.js

@@ -390,23 +390,55 @@ var Logger = class _Logger {
       transport.log(entry);
     }
   }
+  /**
+   * Log a trace message (most verbose level).
+   * @param message - Log message
+   * @param context - Optional context data
+   */
   trace(message, context) {
     this.log("TRACE", message, context);
   }
+  /**
+   * Log a debug message.
+   * @param message - Log message
+   * @param context - Optional context data
+   */
   debug(message, context) {
     this.log("DEBUG", message, context);
   }
+  /**
+   * Log an informational message.
+   * @param message - Log message
+   * @param context - Optional context data
+   */
   info(message, context) {
     this.log("INFO", message, context);
   }
+  /**
+   * Log a warning message.
+   * @param message - Log message
+   * @param context - Optional context data
+   */
   warn(message, context) {
     this.log("WARN", message, context);
   }
+  /**
+   * Log an error message with optional Error object.
+   * @param message - Log message
+   * @param error - Optional Error object or context
+   * @param context - Optional additional context
+   */
   error(message, error, context) {
     const err2 = error instanceof Error ? error : void 0;
     const ctx = error instanceof Error ? context : error;
     this.log("ERROR", message, ctx, err2);
   }
+  /**
+   * Log a fatal error message (most severe level).
+   * @param message - Log message
+   * @param error - Optional Error object or context
+   * @param context - Optional additional context
+   */
   fatal(message, error, context) {
     const err2 = error instanceof Error ? error : void 0;
     const ctx = error instanceof Error ? context : error;
@@ -475,7 +507,9 @@ var Decimal = class _Decimal {
     return trimmed.replace(/^(-?)0+(?=\d)/, "$1").replace(/\.?0+$/, "") || "0";
   }
   /**
-   * Add two decimals
+   * 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);
@@ -483,7 +517,9 @@ var Decimal = class _Decimal {
     return new _Decimal(a + b);
   }
   /**
-   * Subtract
+   * Subtract a value from this decimal.
+   * @param other - Value to subtract
+   * @returns A new Decimal with the result
    */
   sub(other) {
     const a = parseFloat(this.value);
@@ -491,7 +527,9 @@ var Decimal = class _Decimal {
     return new _Decimal(a - b);
   }
   /**
-   * Multiply
+   * Multiply this decimal by another value.
+   * @param other - Value to multiply by
+   * @returns A new Decimal with the result
    */
   mul(other) {
     const a = parseFloat(this.value);
@@ -499,7 +537,10 @@ var Decimal = class _Decimal {
     return new _Decimal(a * b);
   }
   /**
-   * Divide
+   * Divide this decimal by another value.
+   * @param other - Value to divide by
+   * @returns A new Decimal with the result
+   * @throws Error if dividing by zero
    */
   div(other) {
     const a = parseFloat(this.value);
@@ -510,7 +551,9 @@ var Decimal = class _Decimal {
     return new _Decimal(a / b);
   }
   /**
-   * Modulo
+   * Get the modulo (remainder) of dividing this decimal by another value.
+   * @param other - Value to divide by
+   * @returns A new Decimal with the remainder
    */
   mod(other) {
     const a = parseFloat(this.value);
@@ -518,14 +561,18 @@ var Decimal = class _Decimal {
     return new _Decimal(a % b);
   }
   /**
-   * Power
+   * Raise this decimal to a power.
+   * @param exp - The exponent
+   * @returns A new Decimal with the result
    */
   pow(exp) {
     const a = parseFloat(this.value);
     return new _Decimal(Math.pow(a, exp));
   }
   /**
-   * Square root
+   * Calculate the square root of this decimal.
+   * @returns A new Decimal with the square root
+   * @throws Error if the value is negative
    */
   sqrt() {
     const a = parseFloat(this.value);
@@ -535,21 +582,25 @@ var Decimal = class _Decimal {
     return new _Decimal(Math.sqrt(a));
   }
   /**
-   * Absolute value
+   * 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));
   }
   /**
-   * Negate
+   * Negate this decimal (multiply by -1).
+   * @returns A new Decimal with the negated value
    */
   neg() {
     const a = parseFloat(this.value);
     return new _Decimal(-a);
   }
   /**
-   * Round to decimal places
+   * Round to the specified number of decimal places using standard rounding.
+   * @param decimals - Number of decimal places (default: 0)
+   * @returns A new Decimal with the rounded value
    */
   round(decimals = 0) {
     const a = parseFloat(this.value);
@@ -557,7 +608,9 @@ var Decimal = class _Decimal {
     return new _Decimal(Math.round(a * factor) / factor);
   }
   /**
-   * Floor to decimal places
+   * Round down to the specified number of decimal places.
+   * @param decimals - Number of decimal places (default: 0)
+   * @returns A new Decimal with the floored value
    */
   floor(decimals = 0) {
     const a = parseFloat(this.value);
@@ -565,7 +618,9 @@ var Decimal = class _Decimal {
     return new _Decimal(Math.floor(a * factor) / factor);
   }
   /**
-   * Ceiling to decimal places
+   * Round up to the specified number of decimal places.
+   * @param decimals - Number of decimal places (default: 0)
+   * @returns A new Decimal with the ceiled value
    */
   ceil(decimals = 0) {
     const a = parseFloat(this.value);
@@ -573,7 +628,9 @@ var Decimal = class _Decimal {
     return new _Decimal(Math.ceil(a * factor) / factor);
   }
   /**
-   * Compare: returns -1, 0, or 1
+   * Compare this decimal to another value.
+   * @param other - Value to compare against
+   * @returns -1 if less, 0 if equal, 1 if greater
    */
   cmp(other) {
     const a = parseFloat(this.value);
@@ -583,85 +640,107 @@ var Decimal = class _Decimal {
     return 0;
   }
   /**
-   * Equality check
+   * Check if this decimal equals another value.
+   * @param other - Value to compare against
+   * @returns True if values are equal
    */
   eq(other) {
     return this.cmp(other) === 0;
   }
   /**
-   * Greater than
+   * Check if this decimal is greater than another value.
+   * @param other - Value to compare against
+   * @returns True if this is greater
    */
   gt(other) {
     return this.cmp(other) === 1;
   }
   /**
-   * Greater than or equal
+   * Check if this decimal is greater than or equal to another value.
+   * @param other - Value to compare against
+   * @returns True if this is greater or equal
    */
   gte(other) {
     return this.cmp(other) >= 0;
   }
   /**
-   * Less than
+   * Check if this decimal is less than another value.
+   * @param other - Value to compare against
+   * @returns True if this is less
    */
   lt(other) {
     return this.cmp(other) === -1;
   }
   /**
-   * Less than or equal
+   * Check if this decimal is less than or equal to another value.
+   * @param other - Value to compare against
+   * @returns True if this is less or equal
    */
   lte(other) {
     return this.cmp(other) <= 0;
   }
   /**
-   * Check if zero
+   * Check if this decimal is exactly zero.
+   * @returns True if value is zero
    */
   isZero() {
     return parseFloat(this.value) === 0;
   }
   /**
-   * Check if positive
+   * Check if this decimal is positive (greater than zero).
+   * @returns True if value is positive
    */
   isPositive() {
     return parseFloat(this.value) > 0;
   }
   /**
-   * Check if negative
+   * Check if this decimal is negative (less than zero).
+   * @returns True if value is negative
    */
   isNegative() {
     return parseFloat(this.value) < 0;
   }
   /**
-   * Convert to number
+   * Convert this decimal to a JavaScript number.
+   * @returns The numeric value
    */
   toNumber() {
     return parseFloat(this.value);
   }
   /**
-   * Convert to string
+   * Convert this decimal to its string representation.
+   * @returns The string value
    */
   toString() {
     return this.value;
   }
   /**
-   * Format with fixed decimal places
+   * Format this decimal with a fixed number of decimal places.
+   * @param decimals - Number of decimal places (default: 2)
+   * @returns Formatted string
    */
   toFixed(decimals = 2) {
     return parseFloat(this.value).toFixed(decimals);
   }
   /**
-   * Convert to JSON (string representation)
+   * Convert to JSON (returns string representation for serialization).
+   * @returns The string value for JSON serialization
    */
   toJSON() {
     return this.value;
   }
   /**
-   * Static: Create from value
+   * Create a Decimal from a value (alias for constructor).
+   * @param value - The value to convert
+   * @returns A new Decimal instance
    */
   static from(value) {
     return new _Decimal(value);
   }
   /**
-   * Static: Sum array of values
+   * Calculate the sum of an array of values.
+   * @param values - Array of values to sum
+   * @returns A new Decimal with the sum
    */
   static sum(values) {
     return values.reduce(
@@ -670,14 +749,19 @@ var Decimal = class _Decimal {
     );
   }
   /**
-   * Static: Average of array
+   * Calculate the average of an array of values.
+   * @param values - Array of values to average
+   * @returns A new Decimal with the average (0 if empty array)
    */
   static avg(values) {
     if (values.length === 0) return new _Decimal(0);
     return _Decimal.sum(values).div(values.length);
   }
   /**
-   * Static: Min of array
+   * Find the minimum value from the provided values.
+   * @param values - Values to compare
+   * @returns A new Decimal with the minimum value
+   * @throws Error if no values provided
    */
   static min(...values) {
     if (values.length === 0) throw new Error("No values provided");
@@ -687,7 +771,10 @@ var Decimal = class _Decimal {
     }, new _Decimal(values[0]));
   }
   /**
-   * Static: Max of array
+   * Find the maximum value from the provided values.
+   * @param values - Values to compare
+   * @returns A new Decimal with the maximum value
+   * @throws Error if no values provided
    */
   static max(...values) {
     if (values.length === 0) throw new Error("No values provided");
@@ -699,51 +786,73 @@ var Decimal = class _Decimal {
 };
 var DecimalUtils = {
   /**
-   * Convert number to database decimal string
+   * Convert a number to a database-safe decimal string.
+   * @param value - The value to convert
+   * @returns The decimal string or null if value is null/undefined
    */
   toDecimalString(value) {
     if (value === null || value === void 0) return null;
     return new Decimal(value).toString();
   },
   /**
-   * Convert database decimal string to number
+   * Convert a database decimal string to a JavaScript number.
+   * @param value - The decimal string from database
+   * @returns The numeric value (0 if null/undefined/empty)
    */
   fromDecimalString(value) {
     if (!value) return 0;
     return new Decimal(value).toNumber();
   },
   /**
-   * Perform precise decimal multiplication
+   * Multiply two values with precise decimal arithmetic.
+   * @param a - First value
+   * @param b - Second value
+   * @returns The product as a string
    */
   multiply(a, b) {
     return new Decimal(a).mul(b).toString();
   },
   /**
-   * Perform precise decimal addition
+   * Add two values with precise decimal arithmetic.
+   * @param a - First value
+   * @param b - Second value
+   * @returns The sum as a string
    */
   add(a, b) {
     return new Decimal(a).add(b).toString();
   },
   /**
-   * Perform precise decimal subtraction
+   * Subtract two values with precise decimal arithmetic.
+   * @param a - Value to subtract from
+   * @param b - Value to subtract
+   * @returns The difference as a string
    */
   subtract(a, b) {
     return new Decimal(a).sub(b).toString();
   },
   /**
-   * Perform precise decimal division
+   * Divide two values with precise decimal arithmetic.
+   * @param a - Dividend
+   * @param b - Divisor
+   * @returns The quotient as a string
    */
   divide(a, b) {
     return new Decimal(a).div(b).toString();
   },
   /**
-   * Format decimal for display
+   * Format a decimal value for display with fixed decimal places.
+   * @param value - The value to format
+   * @param decimalPlaces - Number of decimal places (default: 2)
+   * @returns Formatted string
    */
   format(value, decimalPlaces = 2) {
     return new Decimal(value).toFixed(decimalPlaces);
   },
   /**
-   * Format as currency
+   * Format a value as currency using Intl.NumberFormat.
+   * @param value - The value to format
+   * @param options - Currency formatting options
+   * @returns Formatted currency string
    */
   formatCurrency(value, options = {}) {
     const { currency = "USD", locale = "en-US", decimals = 2 } = options;
@@ -756,7 +865,10 @@ var DecimalUtils = {
     }).format(num);
   },
   /**
-   * Convert object with decimal fields for database insert/update
+   * Prepare an object for database insert/update by converting numeric fields to decimal strings.
+   * @param data - The object to prepare
+   * @param decimalFields - Array of field names that should be converted to decimal strings
+   * @returns A new object with specified fields converted to decimal strings
    */
   prepareForDatabase(data, decimalFields) {
     const result = { ...data };
@@ -771,7 +883,10 @@ var DecimalUtils = {
     return result;
   },
   /**
-   * Convert object with decimal fields from database
+   * Parse an object from database by converting decimal string fields to JavaScript numbers.
+   * @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
    */
   parseFromDatabase(data, decimalFields) {
     const result = { ...data };