npm package: @pro-fa/expr-eval
Description: Mathematical expression evaluator
Author: Matthew Crumley, Mark Sironi, Sander Toonen
Latest version: 6.3.1

Expression Evaluator
==================================

[![npm](https://img.shields.io/npm/v/@pro-fa/expr-eval.svg?maxAge=3600)](https://www.npmjs.com/package/@pro-fa/expr-eval)

## 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](https://pro-fa.github.io/expr-eval/). 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](docs/quick-reference.md) | Cheat sheet of operators, functions, and syntax |
| [Expression Syntax](docs/syntax.md) | Complete syntax reference with examples |

### For Developers

If you're integrating expr-eval into your project:

| Document | Description |
|:---------|:------------|
| [Parser](docs/parser.md) | Parser configuration, methods, and customization |
| [Expression](docs/expression.md) | Expression object methods: evaluate, simplify, variables, toJSFunction |
| [Advanced Features](docs/advanced-features.md) | Promises, custom resolution, type conversion, operator customization |
| [Language Service](docs/language-service.md) | IDE integration: completions, hover info, diagnostics, Monaco Editor |
| [Migration Guide](docs/migration.md) | Upgrading from original expr-eval or previous versions |

### For Contributors

| Document | Description |
|:---------|:------------|
| [Contributing](CONTRIBUTING.md) | Development setup, code style, and PR guidelines |
| [Performance Testing](docs/performance.md) | Benchmarks, profiling, and optimization guidance |
| [Breaking Changes](BREAKING_CHANGES.md) | 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 <project-directory>
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](docs/performance.md) for detailed performance documentation.

## Serving Documentation Locally

The documentation can be served locally using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/).

### Prerequisites

Install MkDocs Material (requires Python):

```bash
pip install mkdocs-material
```

### Serve Documentation

```bash
# 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

```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](http://silentmatt.com/javascript-expression-evaluator/), 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](LICENSE.txt) for license information.