@code4js/eval-box

A secure, extensible JavaScript expression evaluation sandbox. Safely evaluate user-provided expressions without eval(), new Function(), or vm -- just a pure TypeScript lexer, parser, and tree-walk evaluator with configurable security controls.

Features

• Zero runtime dependencies -- pure TypeScript, no external packages
• Security first -- prototype chain blocking, dangerous identifier rejection, configurable limits
• Rich expression syntax -- arithmetic, comparison, logic, ternary, nullish coalescing, template literals, array literals
• 60+ built-in functions -- math, trig, string, array, type conversion
• Plugin system -- extend with custom functions, constants, and operators
• Compiled expressions -- parse once, evaluate many times with different contexts
• Fully typed -- complete TypeScript type definitions and AST exports

Installation

npm install @code4js/eval-box

Quick Start

import { EvalBox } from '@code4js/eval-box';

// Static convenience
EvalBox.evaluate('1 + 2');                          // 3
EvalBox.evaluate('price * qty', { price: 10, qty: 3 }); // 30

// Instance with options
const box = new EvalBox({ allowMemberAccess: true });
box.evaluate('user.name', { user: { name: 'Alice' } }); // 'Alice'

Supported Syntax

Literals

Type	Examples
Numbers	42, 3.14, .5, 1e3, 2.5e-1
Hex / Binary / Octal	0xFF, 0b1010, 0o17
Strings	'hello', "world"
Template literals	`hello ${name}`
Booleans	true, false
Null / Undefined	null, undefined
Arrays	[1, 2, 3]

Operators

Category	Operators
Arithmetic	+ - * / % **
Comparison	== != === !== > < >= <=
Logical	&& `
Nullish coalescing	??
Ternary	condition ? a : b
Membership	"a" in array
Member access (opt-in)	obj.prop, obj?.prop, arr[0]

Operator Precedence (highest to lowest)

1. ** (right-associative)
2. * / %
3. + -
4. > < >= <=
5. == != === !==
6. in
7. &&
8. ||
9. ??
10. ? : (ternary)

Built-in Functions

Math

abs(-5)           // 5
ceil(1.2)         // 2
floor(1.8)        // 1
round(1.5)        // 2
trunc(1.9)        // 1
sign(-5)          // -1
sqrt(16)          // 4
cbrt(27)          // 3
pow(2, 10)        // 1024
exp(1)            // 2.718...
log(E)            // 1
log2(8)           // 3
log10(1000)       // 3
clamp(15, 0, 10)  // 10
random()          // 0..1

Trigonometry

sin(0)  cos(0)  tan(0)
asin(0) acos(1) atan(0) atan2(1, 0)
sinh(0) cosh(0) tanh(0)
asinh(0) acosh(1) atanh(0)
hypot(3, 4)       // 5

Aggregation

min(3, 1, 2)         // 1
max(3, 1, 2)         // 3
sum(1, 2, 3)         // 6
avg(2, 4, 6)         // 4
min([5, 2, 8])       // 2  (also accepts arrays)

String

length("hello")              // 5
toLowerCase("HELLO")         // "hello"
toUpperCase("hello")         // "HELLO"
trim("  hi  ")               // "hi"
startsWith("hello", "hel")   // true
endsWith("hello", "llo")     // true
includes("hello", "ell")     // true
indexOf("hello", "ll")       // 2
substring("hello", 1, 3)     // "el"
replace("hello", "l", "r")   // "herlo"
split("a,b,c", ",")          // ["a", "b", "c"]
concat("a", "b", "c")        // "abc"

Array

join(["a", "b"], "-")  // "a-b"
reverse([1, 2, 3])     // [3, 2, 1]
slice([1,2,3,4], 1, 3) // [2, 3]
flat([[1,2],[3,4]])     // [1, 2, 3, 4]
length([1, 2, 3])       // 3

Type Conversion & Checking

Number("42")     // 42
String(42)       // "42"
Boolean(1)       // true
isNaN(0/0)       // true
isFinite(42)     // true
isArray([1])     // true
typeof(42)       // "number"

Constants

PI, E, LN2, LN10, LOG2E, LOG10E, SQRT2, SQRT1_2, Infinity, NaN

Customization & Extensibility

Custom Functions

const box = new EvalBox({
  functions: {
    double: (x: number) => x * 2,
    greet: (name: string) => `Hello, ${name}!`,
  },
});

box.evaluate('double(21)');          // 42
box.evaluate('greet("World")');      // "Hello, World!"

Or add them dynamically (chainable):

const box = new EvalBox()
  .addFunction('square', (x: number) => x * x)
  .addFunction('cube', (x: number) => x ** 3);

box.evaluate('square(4) + cube(2)');  // 24

Custom Constants

const box = new EvalBox({
  constants: { TAU: Math.PI * 2, GOLDEN: 1.618 },
});

box.evaluate('TAU');     // 6.2831...
box.evaluate('GOLDEN');  // 1.618

Or dynamically:

box.addConstant('MAX_SCORE', 100);
box.evaluate('score <= MAX_SCORE', { score: 85 });  // true

Custom Operators

const box = new EvalBox({
  binaryOperators: {
    // Override + to always concatenate strings
    '+': (a, b) => String(a) + String(b),
  },
});

box.evaluate('1 + 2');  // "12"

Plugin System

Plugins bundle related functions, constants, and operators into reusable modules:

import { EvalBox, EvalBoxPlugin } from '@code4js/eval-box';

// Define a plugin
const datePlugin: EvalBoxPlugin = {
  name: 'date',
  functions: {
    now: () => Date.now(),
    year: () => new Date().getFullYear(),
    formatDate: (ts: number) => new Date(ts).toISOString(),
  },
  constants: {
    EPOCH: 0,
    DAY_MS: 86400000,
  },
};

// Use it
const box = new EvalBox({ plugins: [datePlugin] });
box.evaluate('year()');  // 2026

// Or register after construction (chainable)
box.use(anotherPlugin).use(yetAnotherPlugin);

Plugin with Setup Hook

The setup callback receives the EvalBox instance, enabling advanced initialization:

const plugin: EvalBoxPlugin = {
  name: 'advanced',
  setup: (box) => {
    box.addFunction('register', () => 'registered');
    box.addConstant('VERSION', '1.0.0');
  },
};

Plugin Interface

interface EvalBoxPlugin {
  name: string;
  functions?: Record<string, SafeFunction>;
  constants?: Record<string, any>;
  unaryOperators?: Record<string, UnaryOperatorFn>;
  binaryOperators?: Record<string, BinaryOperatorFn>;
  setup?: (box: EvalBox) => void;
}

Operator Enable/Disable

Restrict which operators are allowed:

const box = new EvalBox({
  operators: {
    '+': true, '-': true, '*': true, '/': true,
    '==': true, '!=': true, '===': true, '!==': true,
    '>': true, '<': true, '>=': true, '<=': true,
    '&&': true, '||': true,
    '**': false,  // disable exponentiation
    '%': false,   // disable modulo
  },
});

box.evaluate('1 + 2');    // 3
box.evaluate('2 ** 3');   // throws: Operator '**' is disabled

Compiled Expressions

Parse an expression once, evaluate it many times with different contexts:

const box = new EvalBox();

// Compile once
const expr = box.compile('price * qty * (1 - discount)');

// Evaluate many times
expr.evaluate({ price: 100, qty: 3, discount: 0.1 });  // 270
expr.evaluate({ price: 50, qty: 10, discount: 0.2 });   // 400

// Inspect the AST
console.log(expr.getAST());

Alternatively, use parse() + evaluateAST() for the same effect:

const ast = box.parse('x ** 2 + y ** 2');
box.evaluateAST(ast, { x: 3, y: 4 });  // 25
box.evaluateAST(ast, { x: 5, y: 12 }); // 169

Security

Design Principles

1. No native eval -- pure lexer + parser + tree-walk evaluator; zero use of eval, Function, or vm
2. Prototype chain blocking -- access to __proto__, prototype, constructor, __defineGetter__, __defineSetter__, __lookupGetter__, __lookupSetter__ throws SecurityError
3. Dangerous identifier blocking -- eval, Function, require, import, globalThis, global, window, self, process, module, exports throw SecurityError
4. No arbitrary function calls -- only explicitly registered functions can be called; context variables cannot be invoked
5. Member access off by default -- must opt-in via allowMemberAccess: true
6. Complexity limits -- configurable max expression length, token count, and AST depth
7. Timeout -- configurable evaluation timeout (default: 1000ms)
8. Input validation -- tokenizer rejects unknown characters immediately

Security Options

const box = new EvalBox({
  allowMemberAccess: false,       // default: no obj.prop access
  maxExpressionLength: 2000,      // default: 2000 characters
  maxTokens: 500,                 // default: 500 tokens
  maxDepth: 50,                   // default: 50 nesting levels
  timeout: 1000,                  // default: 1000ms
});

Error Types

import {
  EvalBoxError,    // base error class
  ParseError,      // syntax errors (includes position)
  SecurityError,   // security violations
  TimeoutError,    // evaluation timeout
  LimitError,      // expression complexity limits
} from '@code4js/eval-box';

try {
  box.evaluate('obj.__proto__', { obj: {} });
} catch (e) {
  if (e instanceof SecurityError) {
    console.log('Blocked!', e.message);
  }
}

Advanced Usage

AST Inspection

All AST node types are exported for building custom tooling:

import { EvalBox, ASTNode } from '@code4js/eval-box';

const ast = EvalBox.parse('1 + 2 * 3');
// {
//   type: 'BinaryExpression',
//   operator: '+',
//   left: { type: 'NumberLiteral', value: 1 },
//   right: {
//     type: 'BinaryExpression',
//     operator: '*',
//     left: { type: 'NumberLiteral', value: 2 },
//     right: { type: 'NumberLiteral', value: 3 }
//   }
// }

Direct Tokenizer/Parser Access

For advanced use cases, the internal components are fully exported:

import { Tokenizer, Parser, evaluateAST } from '@code4js/eval-box';

// Tokenize
const tokenizer = new Tokenizer('1 + 2');
const tokens = tokenizer.tokenize();

// Parse
const parser = new Parser({ allowMemberAccess: false });
const ast = parser.parse('1 + 2');

Introspection

const box = new EvalBox();

// List all registered function names
box.getFunctions();   // ['abs', 'ceil', 'floor', ...]

// Get all constants with values
box.getConstants();   // { PI: 3.14159..., E: 2.71828..., ... }

Real-World Examples

Rule Engine

const box = new EvalBox();

const rules = [
  { condition: 'age >= 18 and status === "active"', action: 'allow' },
  { condition: 'score > 90', action: 'award_bonus' },
  { condition: 'balance < 0', action: 'send_alert' },
];

const context = { age: 25, status: 'active', score: 95, balance: 100 };

const triggered = rules.filter(r => box.evaluate(r.condition, context));

Dynamic Pricing

const box = new EvalBox()
  .addFunction('tierDiscount', (qty: number) =>
    qty >= 100 ? 0.2 : qty >= 50 ? 0.1 : qty >= 10 ? 0.05 : 0
  );

const formula = 'price * qty * (1 - tierDiscount(qty))';
box.evaluate(formula, { price: 29.99, qty: 75 }); // 2024.325

Template Rendering

const box = new EvalBox();

const template = '`Dear ${name}, your order #${orderId} totals $${total}`';
box.evaluate(template, { name: 'Alice', orderId: 1234, total: 99.99 });
// "Dear Alice, your order #1234 totals $99.99"

Form Validation

const box = new EvalBox();

const validations = {
  email: 'includes(value, "@") and length(value) >= 5',
  age: 'value >= 0 and value <= 150',
  password: 'length(value) >= 8',
};

function validate(field: string, value: any): boolean {
  return box.evaluate(validations[field], { value });
}

API Reference

EvalBox

Method	Description
constructor(options?)	Create an instance with optional configuration
evaluate(expr, context?)	Evaluate an expression string
parse(expr)	Parse an expression into an AST
evaluateAST(ast, context?)	Evaluate a pre-parsed AST
compile(expr)	Create a reusable CompiledExpression
use(plugin)	Register a plugin (chainable)
addFunction(name, fn)	Add a custom function (chainable)
addConstant(name, value)	Add a custom constant (chainable)
addUnaryOperator(name, fn)	Add a custom unary operator (chainable)
addBinaryOperator(name, fn)	Add a custom binary operator (chainable)
getFunctions()	List all registered function names
getConstants()	Get all constants with their values
static evaluate(expr, context?)	Static convenience method
static parse(expr)	Static convenience method

CompiledExpression

Method	Description
evaluate(context?)	Evaluate with a variable context
getAST()	Get the parsed AST node

EvalBoxOptions

Option	Type	Default	Description
allowMemberAccess	boolean	false	Enable obj.prop and arr[i] access
operators	Record<string, boolean>	null (all enabled)	Enable/disable specific operators
functions	Record<string, Function>	--	Custom functions (merged with built-ins)
constants	Record<string, any>	--	Custom constants (merged with built-ins)
unaryOperators	Record<string, Function>	--	Custom unary operators
binaryOperators	Record<string, Function>	--	Custom binary operators
maxExpressionLength	number	2000	Max input string length
maxTokens	number	500	Max number of tokens
maxDepth	number	50	Max AST nesting depth
timeout	number	1000	Evaluation timeout in ms
plugins	EvalBoxPlugin[]	--	Plugins to load

License

MIT