xpal

Expression evaluator — recursive descent parser with extensible function registry.

Features

• Parse and evaluate mathematical expressions
• Built-in functions: SUM, AVG, MIN, MAX, ROUND, IF, ABS, CEIL, FLOOR, POWER, SQRT, LOG, LEN, UPPER, LOWER, TRIM, SUBSTRING, NOW, DATEADD, DATEDIFF, COALESCE, CONCAT
• Custom function registration
• TypeScript support

Installation

npm install xpal

Usage

import { Evaluator } from '@nugrhrizki/xpal'

const ev = new Evaluator()

// Register a custom function
ev.register('TAX', ([amount, rate]) => Number(amount) * Number(rate) / 100)

// Evaluate with context and references
const result = ev.evaluate(
  'ROUND(TAX({price}, {tax_rate}), 2)',
  { current: { price: 150000, tax_rate: 11 } },
  [
    { variableName: 'price',    fieldKey: 'price',    aggregateFunction: 'none' },
    { variableName: 'tax_rate', fieldKey: 'tax_rate', aggregateFunction: 'none' },
  ]
)
// → { value: 16500, error: null }

Using the default evaluator

import { evaluateExpression } from 'xpal'

const result = evaluateExpression(
  'SUM({a}, {b})',
  { current: { a: 10, b: 20 } },
  [
    { variableName: 'a', fieldKey: 'a', aggregateFunction: 'none' },
    { variableName: 'b', fieldKey: 'b', aggregateFunction: 'none' },
  ]
)
// → { value: 30, error: null }

API

new Evaluator()

Creates a new evaluator instance.

evaluator.register(name, fn, allowOverride?)

Register a custom function. Name is case-insensitive.

ev.register('DOUBLE', ([x]) => Number(x) * 2)

evaluator.unregister(name)

Remove a registered custom function.

evaluator.parse(expression)

Parse an expression string into an AST. Cache this result for repeated evaluations.

evaluator.evaluate(ast, context, references)

Evaluate a pre-parsed AST.

evaluator.evaluateExpression(expression, context, references)

Parse + evaluate in one call.

evaluator.validate(expression, references)

Validate an expression without a context. Returns null if valid, or an error message string.

License

MIT