README.md

@antv/expr

Have you ever wanted to make your SSR charts more dynamic but worried about security risks?

We've got you covered! Our solution introduces an easy-to-use template syntax that safely serializes functions, allowing you to dynamically render charts without compromising security. 🚀

✨ Features

• 🔒 Secure by default - No access to global objects or prototype chain, does not use eval or new 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.

📥 Installation

npm install @antv/expr
# or
yarn add @antv/expr
# or
pnpm add @antv/expr

🔨 Usage

Synchronous Expression Evaluation

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

Pre-compiling Expressions

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

Registering and Calling Functions

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.

Variable References

// 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

Arithmetic Operations

// 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 and Logical Operations

// 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

Conditional (Ternary) Expressions

// 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'

Timeout Handling

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]);
}

🚀Benchmarks

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

Loading

📮API Reference

evaluate(expression: string, context?: object): any

Synchronously evaluates an expression and returns the result.

• expression: The expression string to evaluate
• context: An object containing variables used in the expression (optional)
• Returns: The result of the expression evaluation

compile(expression: string): (context?: object) => any

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

register(name: string, fn: Function): void

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.

License

MIT