Skip to content

ExpresZo ExpresZo

ExpresZo Typescript

npm

A fast, safe, and extensible expression evaluator for JavaScript and TypeScript.

ExpresZo parses and evaluates expressions at runtime — a configurable alternative to eval() that won't execute arbitrary code. Use it to power user-facing formula editors, rule engines, template systems, or any place you need to evaluate dynamic expressions safely.

Why ExpresZo?

Fast

ExpresZo uses a Pratt parser — a top-down operator-precedence parsing algorithm that processes tokens in a single pass with no backtracking. Compared to the recursive-descent parser in the original expr-eval, this means significantly faster parsing, predictable linear performance scaling, and better error messages with precise diagnostics.

Parsed expressions compile to an immutable AST that can be evaluated repeatedly against different variable sets with near-zero overhead.

Safe

  • No code execution — expressions can only call explicitly registered functions
  • Prototype pollution protection — access to __proto__, prototype, and constructor is blocked
  • Recursion depth limit — deeply nested expressions are rejected at parse time
  • No eval() or new Function() — evaluation runs on a stack-based AST walker

Extensible

Build exactly the parser you need with tree-shakeable presets, or use the full kitchen-sink parser with zero configuration.

The package family

ExpresZo ships as three independent npm packages so you only install what you need:

Package When to install
@pro-fa/expreszo Always. The core parser, evaluator, presets, and language service.
@pro-fa/expreszo-datetime Optional. Adds ~30 Luxon-backed date/time functions (now, parseISO, addDuration, format, …). The core never imports Luxon.
@pro-fa/expreszo-mcp-server Optional. Exposes the language service to AI assistants over MCP. Pulls in @modelcontextprotocol/sdk and zod.

Installation

npm install @pro-fa/expreszo

Quick Start

import { Parser } from '@pro-fa/expreszo';

const parser = new Parser();
const expr = parser.parse('2 * x + 1');
console.log(expr.evaluate({ x: 3 })); // 7

Adding an optional plugin

Companion packages export a Plugin that registers in one call:

import { defineParser, fullParser } from '@pro-fa/expreszo';
import { dateTimePlugin }            from '@pro-fa/expreszo-datetime';

const parser = defineParser({ ...fullParser })
  .use(dateTimePlugin);

parser.parse("format(addDuration(now(), 7, 'days'), 'yyyy-MM-dd')").evaluate();

See the Parser docs for parser.use(plugin) semantics, and Date / Time for the full datetime function reference.

Documentation

For Expression Writers

For Developers

  • Parser - Parser configuration, methods, and customization
  • Expression - Expression object methods: evaluate, simplify, variables
  • Advanced Features - Promises, custom resolution, type conversion, operator customization
  • Date / Time integration - How to wire the optional Luxon-backed datetime package into a parser
  • Language Service - IDE integration: completions, hover info, diagnostics, Monaco Editor
  • MCP Server - Expose the language service to AI assistants (Claude Desktop, Claude Code, Cursor) — separate package
  • Migration Guide - Migrating from expr-eval, legacy mode, version history

For Contributors

Playground

Try it live at the Playground — an interactive environment with code completions, syntax highlighting, and real-time evaluation.

License

See LICENSE.txt for license information.