Skip to content

README.md

Latest commit

 

History

History
144 lines (99 loc) · 4.89 KB

README.md

File metadata and controls

144 lines (99 loc) · 4.89 KB

Expression Evaluator

npm

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.