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

``bash
npm install @pro-fa/expr-eval
`

Quick Start

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

$3

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 |

$3

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 |

$3

| 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

`bash
cd
npm install
npm test
`

Performance Benchmarks

`bash


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.

$3

Install MkDocs Material (requires Python):

`bash
pip install mkdocs-material
`

$3

`bash


Start local documentation server


mkdocs serve
`

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

$3

`bash


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.