@lediv/evaluator

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

You probably want @lediv/vite-plugin. This package is published because @lediv/html depends on it, not because it is meant to be called directly.

Usage

npm install @lediv/evaluator

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

evaluateExpression('name.toUpperCase()', { name: 'Alice' });
evaluateExpression('items.filter((x) => x.active).map((x) => x.label)', { items });

The expression language, and which methods are callable, is documented at https://lediv.com/docs/expressions.

What the sandbox guarantees

The scope must be a plain object, and nested values plain objects or arrays. Functions, symbols, getters and setters, and prototype-chained objects are rejected before evaluation begins, so a hostile scope cannot smuggle behaviour in.

Only whitelisted array and string methods are callable. Arrow functions work as callbacks but not free-standing. Blocked keys (__proto__ and friends) are unreachable through both dot and bracket access; isSafeIdentifierKey and SAFE_BLOCKED_KEYS are exported for callers that need the same rule.

Evaluation stops at 12,000 steps and scope validation at 30,000 (DEFAULT_EVALUATION_BUDGET, DEFAULT_SCOPE_VALIDATION_BUDGET), so a runaway expression cannot hang the process building the page.

Errors

UnsafeExpressionError, UnsupportedNodeError and BudgetExceededError, each carrying a code. They ship with type definitions; read those rather than a table here that can go stale.

License

MIT