Expression Evaluator

Description

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.

Installation

npm install @pro-fa/expr-eval

Quick Start

import { 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 }); // 42

Playground Example

Try 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

Documentation

For Expression Writers

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 |

For Developers

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 |

For Contributors

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

Key Features

• 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

Running Tests

cd <project-directory>
npm install
npm test

Performance Benchmarks

# 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 usage

See docs/performance.md for detailed performance documentation.

Serving Documentation Locally

The documentation can be served locally using MkDocs with the Material theme.

Prerequisites

Install MkDocs Material (requires Python):

pip install mkdocs-material

Serve Documentation

# Start local documentation server
mkdocs serve

This will start a local server at http://127.0.0.1:8000 with live reload.

Build Static Site

# Build static HTML files
mkdocs build

The static site will be generated in the site/ directory.

Origins

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.

License

See LICENSE.txt for license information.