Lightweight JavaScript expression parser and evaluator, safety and high-performance. 🚀
Used to parse a mathematical expressions to JavaScript function safely. For example, in @antv/g2, we can set the style with an expressions.
{ // Equivalent to function: `d => d.value > 100 ? 'red' : 'green'` fill: "{ d.value > 100 ? 'red' : 'green' }", }
- 🔒 Secure by default - No access to global objects or prototype chain, does not use
evalornew Function. - 🚀 High performance - Supports pre-compilation of expressions for improved performance with repeated evaluations.
- 🛠️ Extensible - Register custom functions to easily extend functionality.
- 🪩 Lightweight - Zero dependencies, small footprint, before gzip it was less than
8 Kb.
npm install @antv/expr # or yarn add @antv/expr # or pnpm add @antv/expr
- Synchronous Expression Evaluation
- Pre-compiling Expressions
- Registering and Calling Functions
- Variable References
- Arithmetic Operations
- Comparison and Logical Operations
- Conditional (Ternary) Expressions
- Timeout Handling
import { evaluate } from '@antv/expr'; // Basic evaluation const result = evaluate('x + y', { x: 10, y: 20 }); // returns 30 // Using dot notation and array access const data = { values: [1, 2, 3], status: 'active' }; const result = evaluate('data.values[0] + data.values[1]', { data }); // returns 3
import { compile } from '@antv/expr'; // Compile an expression const evaluator = compile('price * quantity'); const result1 = evaluator({ price: 10, quantity: 5 }); // returns 50 const result2 = evaluator({ price: 20, quantity: 3 }); // returns 60
import { register, evaluate } from '@antv/expr'; // Register functions register('formatCurrency', (amount) => `$${amount.toFixed(2)}`); // Function call with arguments const result = evaluate('@max(a, b, c)', { a: 5, b: 9, c: 2 }); // returns 9 // Expression as function arguments const result = evaluate('@formatCurrency(price * quantity)', { price: 10.5, quantity: 3 }); // returns '31ドル.50'
Build-in Functions: abs, ceil, floor, round, sqrt, pow, max, min.
// Simple variable reference const result = evaluate('x', { x: 42 }); // returns 42 // Nested property access with dot notation const result = evaluate('user.profile.name', { user: { profile: { name: 'John' } } }); // returns 'John' // Array access with bracket notation const result = evaluate('items[0]', { items: [10, 20, 30] }); // returns 10 // Mixed dot and bracket notation const result = evaluate('data.items[0].value', { data: { items: [{ value: 42 }] } }); // returns 42
// Basic arithmetic const result = evaluate('a + b * c', { a: 5, b: 3, c: 2 }); // returns 11 // Using parentheses for grouping const result = evaluate('(a + b) * c', { a: 5, b: 3, c: 2 }); // returns 16 // Modulo operation const result = evaluate('a % b', { a: 10, b: 3 }); // returns 1
// Comparison operators const result = evaluate('age >= 18', { age: 20 }); // returns true // Logical AND const result = evaluate('isActive && !isDeleted', { isActive: true, isDeleted: false }); // returns true // Logical OR const result = evaluate('status === "active" || status === "pending"', { status: 'pending' }); // returns true
// Simple ternary expression const result = evaluate('age >= 18 ? "adult" : "minor"', { age: 20 }); // returns 'adult' // Nested ternary expressions const result = evaluate('score >= 90 ? "A" : score >= 80 ? "B" : "C"', { score: 85 }); // returns 'B'
You can implement timeout handling by wrapping your evaluation in a Promise.race with a timeout:
import { evaluate } from "@antv/expr"; // Create a function that evaluates with a timeout function evaluateWithTimeout(expr, context, timeoutMs) { const evaluationPromise = new Promise((resolve) => { resolve(evaluate(expr, context)); }); const timeoutPromise = new Promise((_, reject) => { setTimeout( () => reject(new Error(`Evaluation timed out after ${timeoutMs}ms`)), timeoutMs, ); }); return Promise.race([evaluationPromise, timeoutPromise]); }
Performance comparison of different evaluation methods: (baseline: new Function)
| Expression Type | new Function vs evaluate after compile | new Function vs evaluate without compile | new Function vs expr-eval Parser |
|---|---|---|---|
| Simple Expressions | 1.59x faster | 6.36x faster | 23.94x faster |
| Medium Expressions | 2.16x faster | 9.81x faster | 37.81x faster |
| Complex Expressions | 1.59x faster | 4.89x faster | 32.74x faster |
gantt
title Performance Comparison (Baseline: new Function) * 100
dateFormat X
axisFormat %s
section Simple
expr evaluate after compile :done, 0, 159
expr evaluate without compile :done, 0, 636
expr-eval Parser :done, 0, 2394
section Medium
expr evaluate after compile :done, 0, 216
expr evaluate without compile :done, 0, 981
expr-eval Parser :done, 0, 3781
section Complex
expr evaluate after compile :done, 0, 159
expr evaluate without compile :done, 0, 489
expr-eval Parser :done, 0, 3274
Synchronously evaluates an expression and returns the result.
expression: The expression string to evaluatecontext: An object containing variables used in the expression (optional)- Returns: The result of the expression evaluation
Synchronously compiles an expression, returning a function that can be used multiple times.
expression: The expression string to compile- Returns: A function that accepts a context object and returns the evaluation result
Registers a custom function that can be used in expressions.
name: Function name (used with @ prefix in expressions)fn: Function implementation
All evaluation errors throw an ExpressionError type exception with detailed error information.
MIT