@lediv/evaluator

A sandboxed JavaScript expression evaluator for Lediv templates. Executes user-authored expressions safely by walking an AST with a step budget, blocking prototype-chain attacks, and restricting callable methods to an explicit whitelist.

Install

npm install @lediv/evaluator

Usage

import { evaluateExpression } from '@lediv/evaluator';

const result = evaluateExpression('name.toUpperCase()', { name: 'Alice' });

Scope rules

The scope must be a plain object. Nested values may be plain objects or plain arrays. Functions, symbols, getters/setters, and prototype-chained objects are rejected before evaluation begins.

evaluateExpression('items.filter(x => x.active).map(x => x.label)', {
  items: [
    { label: 'A', active: true },
    { label: 'B', active: false },
  ],
});

Supported expressions

• Literals: strings, numbers, booleans, null, template literals
• Operators: arithmetic, comparison, logical (&&, ||, ??), ternary, unary (+, -, !)
• Member access (dot and bracket notation)
• Array methods: find, some, map, filter, every, includes, reduce
• String methods: includes, startsWith, endsWith, toLowerCase, toUpperCase, trim, slice
• Arrow functions (as callbacks only, not free-standing)
• Object and array literals
• Simple assignment (=) to existing scope variables

Budget

Evaluation is limited to 12,000 steps by default. Scope validation is limited to 30,000 steps. Both limits exist to prevent runaway expressions.

import { DEFAULT_EVALUATION_BUDGET, DEFAULT_SCOPE_VALIDATION_BUDGET } from '@lediv/evaluator';

Errors

import { UnsafeExpressionError, UnsupportedNodeError, BudgetExceededError } from '@lediv/evaluator';

| Class | Code | Thrown when | | ----------------------- | ------------------- | --------------------------------------------------------- | | UnsafeExpressionError | UNSAFE_EXPRESSION | Blocked key access, unsafe scope value, disallowed method | | UnsupportedNodeError | UNSUPPORTED_NODE | AST node type not implemented | | BudgetExceededError | BUDGET_EXCEEDED | Step limit exceeded |

Utilities

import { isSafeIdentifierKey, SAFE_BLOCKED_KEYS } from '@lediv/evaluator';

isSafeIdentifierKey('__proto__'); // false
isSafeIdentifierKey('name'); // true

License

MIT