A versatile expression evaluation library that goes beyond mathematical expressions. It parses and evaluates expressions that can manipulate strings, objects, and arrays, providing a safer alternative to JavaScript's eval function.
It has built-in support for common math operators and functions. Additionally, you can add your own JavaScript functions. Expressions can be evaluated directly, or compiled into native JavaScript functions.
npm install @pro-fa/expr-evalimport { Parser } from '@pro-fa/expr-eval';
const parser = new Parser();
const expr = parser.parse('2 * x + 1');
console.log(expr.evaluate({ x: 3 })); // 7
// or evaluate directly
Parser.evaluate('6 * x', { x: 7 }); // 42Try out the expression evaluator and its language server capabilities directly in your browser at the Playground. The playground provides an interactive environment with:
- Live expression evaluation
- Code completions and IntelliSense
- Syntax highlighting
- Hover information for functions and variables
If you're writing expressions in an application powered by expr-eval:
| Document | Description |
|---|---|
| Quick Reference | Cheat sheet of operators, functions, and syntax |
| Expression Syntax | Complete syntax reference with examples |
If you're integrating expr-eval into your project:
| Document | Description |
|---|---|
| Parser | Parser configuration, methods, and customization |
| Expression | Expression object methods: evaluate, simplify, variables, toJSFunction |
| Advanced Features | Promises, custom resolution, type conversion, operator customization |
| Language Service | IDE integration: completions, hover info, diagnostics, Monaco Editor |
| Migration Guide | Upgrading from original expr-eval or previous versions |
| Document | Description |
|---|---|
| Contributing | Development setup, code style, and PR guidelines |
| Performance Testing | Benchmarks, profiling, and optimization guidance |
| Breaking Changes | Version-by-version breaking change documentation |
- Mathematical Expressions - Full support for arithmetic, comparison, and logical operators
- Built-in Functions - Trigonometry, logarithms, min/max, array operations, string manipulation
- Custom Functions - Add your own JavaScript functions
- Variable Support - Evaluate expressions with dynamic variable values
- Expression Compilation - Convert expressions to native JavaScript functions
- TypeScript Support - Full type definitions included
- Undefined Support - Graceful handling of undefined values
- Coalesce Operator -
??operator for null/undefined fallback - SQL Case Blocks - SQL-style CASE/WHEN/THEN/ELSE expressions
- Object Construction - Create objects and arrays in expressions
- Language Service - IDE integration with completions, hover info, and highlighting
cd <project-directory>
npm install
npm test# Run all benchmarks
npm run bench
# Run specific categories
npm run bench:parsing # Parser performance
npm run bench:evaluation # Evaluation performance
npm run bench:memory # Memory usageSee docs/performance.md for detailed performance documentation.
The documentation can be served locally using MkDocs with the Material theme.
Install MkDocs Material (requires Python):
pip install mkdocs-material# Start local documentation server
mkdocs serveThis will start a local server at http://127.0.0.1:8000 with live reload.
# Build static HTML files
mkdocs buildThe static site will be generated in the site/ directory.
This library was originally based on expr-eval 2.0.2, but has been restructured with a modular architecture, TypeScript support, and comprehensive testing using Vitest.
While the original expr-eval was focused on mathematical expressions, this library aims to be a tool for evaluating expressions that can manipulate strings, objects, and arrays.
See LICENSE.txt for license information.