@the-trybe/formula-engine 1.0.0

package/README.md

@@ -0,0 +1,382 @@
+# Formula Engine
+
+A configuration-driven expression evaluation system with automatic dependency resolution and arbitrary-precision decimal arithmetic.
+
+## Features
+
+- **Expression Parsing**: Parse mathematical and logical expressions into an AST
+- **Automatic Dependency Resolution**: Extracts dependencies from expressions and evaluates formulas in correct order
+- **Circular Dependency Detection**: Fails fast with helpful error messages when cycles are detected
+- **Decimal Precision**: Uses arbitrary-precision arithmetic to avoid floating-point errors (e.g., `0.1 + 0.2 = 0.3`)
+- **40+ Built-in Functions**: Math, string, logical, aggregation, and type functions
+- **Custom Functions**: Register your own functions
+- **Caching**: AST and dependency caching for improved performance
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm install
+```
+
+## Quick Start
+
+```typescript
+import { FormulaEngine } from 'formula-engine';
+
+const engine = new FormulaEngine();
+
+// Evaluate a simple expression
+const result = engine.evaluate('$price * $quantity', {
+  variables: { price: 19.99, quantity: 3 }
+});
+
+console.log(result.value.toString()); // "59.97"
+```
+
+## Usage
+
+### Single Expression Evaluation
+
+```typescript
+const engine = new FormulaEngine();
+
+// Arithmetic
+engine.evaluate('$a + $b * 2', { variables: { a: 10, b: 5 } });
+// Result: 20
+
+// Comparison
+engine.evaluate('$score >= 90', { variables: { score: 85 } });
+// Result: false
+
+// Conditional (ternary)
+engine.evaluate('$quantity > 10 ? $price * 0.9 : $price', {
+  variables: { quantity: 15, price: 100 }
+});
+// Result: 90
+
+// Function calls
+engine.evaluate('ROUND($price * 1.19, 2)', { variables: { price: 99.99 } });
+// Result: 118.99
+```
+
+### Batch Evaluation with Dependencies
+
+The engine automatically determines the correct evaluation order:
+
+```typescript
+const formulas = [
+  { id: 'gross', expression: '$unitPrice * $quantity' },
+  { id: 'discount', expression: '$gross * $discountRate' },
+  { id: 'net', expression: '$gross - $discount' },
+  { id: 'tax', expression: '$net * $taxRate' },
+  { id: 'total', expression: '$net + $tax' },
+];
+
+const context = {
+  variables: {
+    unitPrice: 100,
+    quantity: 5,
+    discountRate: 0.1,
+    taxRate: 0.2,
+  }
+};
+
+const results = engine.evaluateAll(formulas, context);
+
+// Evaluation order: gross → discount → net → tax → total
+console.log(results.results.get('total')?.value.toString()); // "540"
+```
+
+### Decimal Precision
+
+JavaScript floating-point math has precision issues:
+
+```javascript
+// Native JavaScript
+0.1 + 0.2  // 0.30000000000000004 ❌
+
+// Formula Engine
+engine.evaluate('0.1 + 0.2', { variables: {} });
+// Result: "0.3" ✓
+```
+
+### Context Variables
+
+Use `$` for local variables and `@` for context variables:
+
+```typescript
+engine.evaluate('$price * (1 + @taxRate)', {
+  variables: { price: 100 },
+  extra: { taxRate: 0.19 }
+});
+// Result: 119
+```
+
+### Member and Index Access
+
+```typescript
+// Dot notation
+engine.evaluate('$product.price * $product.quantity', {
+  variables: {
+    product: { price: 25, quantity: 4 }
+  }
+});
+
+// Bracket notation
+engine.evaluate('$items[0].name', {
+  variables: {
+    items: [{ name: 'Widget' }, { name: 'Gadget' }]
+  }
+});
+```
+
+### Array Functions
+
+```typescript
+// SUM with expression
+engine.evaluate('SUM($items, $it.price * $it.qty)', {
+  variables: {
+    items: [
+      { price: 10, qty: 2 },
+      { price: 20, qty: 1 },
+    ]
+  }
+});
+// Result: 40
+
+// FILTER
+engine.evaluate('FILTER($numbers, $it > 5)', {
+  variables: { numbers: [1, 3, 7, 9, 2] }
+});
+// Result: [7, 9]
+
+// MAP
+engine.evaluate('MAP($prices, $it * 1.1)', {
+  variables: { prices: [100, 200, 300] }
+});
+// Result: [110, 220, 330]
+```
+
+### Custom Functions
+
+```typescript
+engine.registerFunction({
+  name: 'DISCOUNT_TIER',
+  minArgs: 2,
+  maxArgs: 2,
+  returnType: 'decimal',
+  implementation: (args) => {
+    const [amount, tiers] = args;
+    const tier = tiers
+      .filter(t => amount >= t.threshold)
+      .sort((a, b) => b.threshold - a.threshold)[0];
+    return tier ? amount * tier.rate : 0;
+  }
+});
+
+engine.evaluate('DISCOUNT_TIER($total, @tiers)', {
+  variables: { total: 150 },
+  extra: {
+    tiers: [
+      { threshold: 0, rate: 0 },
+      { threshold: 100, rate: 0.05 },
+      { threshold: 200, rate: 0.10 },
+    ]
+  }
+});
+// Result: 7.5 (150 * 0.05)
+```
+
+### Validation
+
+Validate formulas before evaluation:
+
+```typescript
+const formulas = [
+  { id: 'a', expression: '$b + 1' },
+  { id: 'b', expression: '$a + 1' }, // Circular!
+];
+
+const validation = engine.validate(formulas);
+
+if (!validation.valid) {
+  console.log(validation.errors);
+  // CircularDependencyError: Circular dependency detected: a → b → a
+}
+```
+
+## Built-in Functions
+
+### Math Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `ABS(x)` | Absolute value | `ABS(-5)` → `5` |
+| `ROUND(x, p?)` | Round to precision | `ROUND(3.456, 2)` → `3.46` |
+| `FLOOR(x, p?)` | Round down | `FLOOR(3.9)` → `3` |
+| `CEIL(x, p?)` | Round up | `CEIL(3.1)` → `4` |
+| `TRUNCATE(x, p?)` | Truncate decimals | `TRUNCATE(3.999, 2)` → `3.99` |
+| `MIN(a, b, ...)` | Minimum value | `MIN(5, 3, 8)` → `3` |
+| `MAX(a, b, ...)` | Maximum value | `MAX(5, 3, 8)` → `8` |
+| `POW(x, y)` | Power | `POW(2, 3)` → `8` |
+| `SQRT(x)` | Square root | `SQRT(16)` → `4` |
+| `LOG(x)` | Natural logarithm | `LOG(10)` → `2.302...` |
+| `LOG10(x)` | Base-10 logarithm | `LOG10(100)` → `2` |
+| `SIGN(x)` | Sign (-1, 0, 1) | `SIGN(-5)` → `-1` |
+
+### String Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `LEN(s)` | String length | `LEN("hello")` → `5` |
+| `UPPER(s)` | Uppercase | `UPPER("hello")` → `"HELLO"` |
+| `LOWER(s)` | Lowercase | `LOWER("HELLO")` → `"hello"` |
+| `TRIM(s)` | Trim whitespace | `TRIM("  hi  ")` → `"hi"` |
+| `CONCAT(a, b, ...)` | Concatenate | `CONCAT("a", "b")` → `"ab"` |
+| `SUBSTR(s, start, len?)` | Substring | `SUBSTR("hello", 1, 3)` → `"ell"` |
+| `REPLACE(s, find, rep)` | Replace all | `REPLACE("aaa", "a", "b")` → `"bbb"` |
+| `CONTAINS(s, sub)` | Contains check | `CONTAINS("hello", "ell")` → `true` |
+| `STARTSWITH(s, pre)` | Starts with | `STARTSWITH("hello", "he")` → `true` |
+| `ENDSWITH(s, suf)` | Ends with | `ENDSWITH("hello", "lo")` → `true` |
+
+### Logical Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `IF(cond, t, f)` | Conditional | `IF(true, "yes", "no")` → `"yes"` |
+| `COALESCE(a, b, ...)` | First non-null | `COALESCE(null, 5)` → `5` |
+| `ISNULL(x)` | Check null | `ISNULL(null)` → `true` |
+| `ISEMPTY(x)` | Check empty | `ISEMPTY([])` → `true` |
+| `DEFAULT(x, d)` | Default if null | `DEFAULT(null, 0)` → `0` |
+| `AND(a, b, ...)` | Logical AND | `AND(true, false)` → `false` |
+| `OR(a, b, ...)` | Logical OR | `OR(true, false)` → `true` |
+| `NOT(x)` | Logical NOT | `NOT(true)` → `false` |
+
+### Aggregation Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `SUM(arr)` | Sum of array | `SUM([1, 2, 3])` → `6` |
+| `SUM(arr, expr)` | Sum with expression | `SUM($items, $it.price)` |
+| `AVG(arr)` | Average | `AVG([10, 20, 30])` → `20` |
+| `COUNT(arr)` | Count elements | `COUNT([1, 2, 3])` → `3` |
+| `PRODUCT(arr)` | Product of values | `PRODUCT([2, 3, 4])` → `24` |
+| `FILTER(arr, cond)` | Filter array | `FILTER($arr, $it > 5)` |
+| `MAP(arr, expr)` | Transform array | `MAP($arr, $it * 2)` |
+| `FIRST(arr)` | First element | `FIRST([1, 2, 3])` → `1` |
+| `LAST(arr)` | Last element | `LAST([1, 2, 3])` → `3` |
+
+### Type Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `NUMBER(x)` | Convert to number | `NUMBER("42")` → `42` |
+| `STRING(x)` | Convert to string | `STRING(42)` → `"42"` |
+| `BOOLEAN(x)` | Convert to boolean | `BOOLEAN(1)` → `true` |
+| `TYPEOF(x)` | Get type name | `TYPEOF(42)` → `"decimal"` |
+
+## Configuration
+
+```typescript
+const engine = new FormulaEngine({
+  // Enable expression caching (default: true)
+  enableCache: true,
+
+  // Maximum cache size (default: 1000)
+  maxCacheSize: 1000,
+
+  // Strict mode - fail on undefined variables (default: true)
+  strictMode: true,
+
+  // Decimal configuration
+  decimal: {
+    precision: 20,           // Significant digits
+    roundingMode: 'HALF_UP', // Rounding mode
+    divisionScale: 10,       // Decimal places for division
+  },
+
+  // Security limits
+  security: {
+    maxExpressionLength: 10000,
+    maxRecursionDepth: 100,
+    maxIterations: 10000,
+  },
+});
+```
+
+## Error Handling
+
+```typescript
+const result = engine.evaluate('$a / $b', {
+  variables: { a: 10, b: 0 }
+});
+
+if (!result.success) {
+  console.log(result.error); // DivisionByZeroError
+}
+```
+
+### Error Types
+
+- **Parse Errors**: `SyntaxError`, `UnexpectedTokenError`, `UnterminatedStringError`
+- **Validation Errors**: `CircularDependencyError`, `UndefinedVariableError`, `UndefinedFunctionError`
+- **Evaluation Errors**: `DivisionByZeroError`, `TypeMismatchError`, `ArgumentCountError`
+
+## API Reference
+
+### FormulaEngine
+
+```typescript
+class FormulaEngine {
+  constructor(config?: FormulaEngineConfig);
+
+  // Parse expression to AST
+  parse(expression: string): ASTNode;
+
+  // Extract dependencies from expression
+  extractDependencies(expression: string): Set<string>;
+
+  // Build dependency graph
+  buildDependencyGraph(formulas: FormulaDefinition[]): DependencyGraph;
+
+  // Get evaluation order
+  getEvaluationOrder(formulas: FormulaDefinition[]): string[];
+
+  // Validate formulas
+  validate(formulas: FormulaDefinition[]): ValidationResult;
+
+  // Evaluate single expression
+  evaluate(expression: string, context: EvaluationContext): EvaluationResult;
+
+  // Evaluate all formulas in order
+  evaluateAll(formulas: FormulaDefinition[], context: EvaluationContext): EvaluationResultSet;
+
+  // Register custom function
+  registerFunction(definition: FunctionDefinition): void;
+
+  // Cache management
+  clearCache(): void;
+  getCacheStats(): CacheStats;
+}
+```
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT

package/dist/decimal-utils.d.ts

@@ -0,0 +1,180 @@
+import Decimal from 'decimal.js';
+import { DecimalConfig, DecimalRoundingMode } from './types';
+export type DecimalLike = Decimal | string | number | bigint;
+export interface DecimalUtilsConfig {
+    precision: number;
+    roundingMode: DecimalRoundingMode;
+    divisionScale: number;
+    maxExponent: number;
+    minExponent: number;
+}
+export declare class DecimalUtils {
+    private config;
+    constructor(config?: Partial<DecimalConfig>);
+    /**
+     * Create a Decimal from various input types
+     */
+    from(value: DecimalLike): Decimal;
+    /**
+     * Check if a value is a Decimal
+     */
+    isDecimal(value: unknown): value is Decimal;
+    /**
+     * Convert a value to Decimal if it's numeric
+     */
+    toDecimal(value: unknown): Decimal | unknown;
+    /**
+     * Addition
+     */
+    add(a: DecimalLike, b: DecimalLike): Decimal;
+    /**
+     * Subtraction
+     */
+    subtract(a: DecimalLike, b: DecimalLike): Decimal;
+    /**
+     * Multiplication
+     */
+    multiply(a: DecimalLike, b: DecimalLike): Decimal;
+    /**
+     * Division with scale
+     */
+    divide(a: DecimalLike, b: DecimalLike, scale?: number, roundingMode?: DecimalRoundingMode): Decimal;
+    /**
+     * Modulo
+     */
+    modulo(a: DecimalLike, b: DecimalLike): Decimal;
+    /**
+     * Power
+     */
+    power(base: DecimalLike, exponent: number): Decimal;
+    /**
+     * Negation
+     */
+    negate(value: DecimalLike): Decimal;
+    /**
+     * Absolute value
+     */
+    abs(value: DecimalLike): Decimal;
+    /**
+     * Round to specified decimal places
+     */
+    round(value: DecimalLike, scale: number, roundingMode?: DecimalRoundingMode): Decimal;
+    /**
+     * Floor to specified decimal places
+     */
+    floor(value: DecimalLike, scale?: number): Decimal;
+    /**
+     * Ceiling to specified decimal places
+     */
+    ceil(value: DecimalLike, scale?: number): Decimal;
+    /**
+     * Truncate to specified decimal places
+     */
+    truncate(value: DecimalLike, scale?: number): Decimal;
+    /**
+     * Square root
+     */
+    sqrt(value: DecimalLike): Decimal;
+    /**
+     * Natural logarithm
+     */
+    ln(value: DecimalLike): Decimal;
+    /**
+     * Base-10 logarithm
+     */
+    log10(value: DecimalLike): Decimal;
+    /**
+     * Comparison: returns -1, 0, or 1
+     */
+    compare(a: DecimalLike, b: DecimalLike): -1 | 0 | 1;
+    /**
+     * Equality check
+     */
+    equals(a: DecimalLike, b: DecimalLike): boolean;
+    /**
+     * Greater than
+     */
+    greaterThan(a: DecimalLike, b: DecimalLike): boolean;
+    /**
+     * Greater than or equal
+     */
+    greaterThanOrEqual(a: DecimalLike, b: DecimalLike): boolean;
+    /**
+     * Less than
+     */
+    lessThan(a: DecimalLike, b: DecimalLike): boolean;
+    /**
+     * Less than or equal
+     */
+    lessThanOrEqual(a: DecimalLike, b: DecimalLike): boolean;
+    /**
+     * Check if zero
+     */
+    isZero(value: DecimalLike): boolean;
+    /**
+     * Check if positive
+     */
+    isPositive(value: DecimalLike): boolean;
+    /**
+     * Check if negative
+     */
+    isNegative(value: DecimalLike): boolean;
+    /**
+     * Check if integer
+     */
+    isInteger(value: DecimalLike): boolean;
+    /**
+     * Get sign: -1, 0, or 1
+     */
+    sign(value: DecimalLike): -1 | 0 | 1;
+    /**
+     * Get precision (total significant digits)
+     */
+    precision(value: DecimalLike): number;
+    /**
+     * Get scale (decimal places)
+     */
+    scale(value: DecimalLike): number;
+    /**
+     * Convert to JavaScript number (may lose precision)
+     */
+    toNumber(value: DecimalLike): number;
+    /**
+     * Convert to string
+     */
+    toString(value: DecimalLike): string;
+    /**
+     * Convert to fixed decimal places string
+     */
+    toFixed(value: DecimalLike, scale: number): string;
+    /**
+     * Minimum of values
+     */
+    min(...values: DecimalLike[]): Decimal;
+    /**
+     * Maximum of values
+     */
+    max(...values: DecimalLike[]): Decimal;
+    /**
+     * Sum of values
+     */
+    sum(values: DecimalLike[]): Decimal;
+    /**
+     * Average of values
+     */
+    avg(values: DecimalLike[]): Decimal;
+    /**
+     * Product of values
+     */
+    product(values: DecimalLike[]): Decimal;
+    /**
+     * Create zero
+     */
+    zero(): Decimal;
+    /**
+     * Create one
+     */
+    one(): Decimal;
+}
+export declare const decimalUtils: DecimalUtils;
+export { Decimal };