Expression Evaluator

Description

This is a modern TypeScript port of the expr-eval library, completely rewritten with contemporary build tools and development practices. Originally based on expr-eval 2.0.2, this version has been restructured with a modular architecture, TypeScript support, and comprehensive testing using Vitest.

Parses and evaluates mathematical expressions. It's a safer and more math-oriented alternative to using JavaScript's eval function for mathematical expressions.

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

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

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

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.

License

See LICENSE.txt for license information.