escalc

escalc is an opinionated NCalc expression evaluator in TypeScript. It exposes a parser, a tree-walk evaluator, a formatter, and a parameter extractor for a well-defined subset of the NCalc expression language.

Designed for a small footprint and fast execution with zero dependencies.

Install

npm install @imogenz/escalc
# or
pnpm add @imogenz/escalc
# or
yarn add @imogenz/escalc

Quick start

import { evaluate } from "@imogenz/escalc";

// Basic arithmetic
evaluate("1 + 2"); // => 3
evaluate("2 ** 8"); // => 256
evaluate("Max(Abs(-5), 2)"); // => 5

// Parameters
evaluate("[price] * (1 + [tax])", {
  params: new Map([
    ["price", 100],
    ["tax", 0.2],
  ]),
}); // => 120

// Safe variant - no throwing
import { evaluateSafe } from "@imogenz/escalc";
const result = evaluateSafe(userInput);
if (result.type === "success") console.log(result.result);

Demos

See the Demos guide for complete real-world examples.

See also

• Getting Started
• TypeScript API reference

Implementation

Created using a recursive descent parser with a handwritten lexer and tree-walk evaluator. The parser supports error recovery: with stopOnFirstError: false it collects all recoverable errors and returns a partial AST via incompleteExpression.

Support matrix

| Feature | Status | | ------------------------------------------------ | --------------------------------------- | | Arithmetic (+ - * / % **) | ✅ | | Comparison (> < >= <= == !=) | ✅ | | Logical (&& \|\| !) with short-circuit | ✅ | | Bitwise (& \| ^ << >> ~) | ✅ | | Ternary (? :) | ✅ | | in / not in | ✅ | | String / number / boolean / date / list literals | ✅ | | Parameter references ([name], {name}) | ✅ | | Built-in math functions (Abs, Sin, Sqrt, …) | ✅ | | if / ifs conditional functions | ✅ | | Custom functions | ✅ | | Lazy parameters | ✅ | | Custom operator implementation (Calculator) | ✅ | | Result caching | ❌ won't implement - cache at call site | | GUID value type | ❌ won't implement - use a string |

See Supported Features for the full reference.

Equivalent NCalc flags

| NCalc flag | ESCalc equivalent | | ----------------------------------- | -------------------------------------------------- | | EvaluateOptions.IterateParameters | Not supported | | EvaluateOptions.IgnoreCase | Not supported - parameter names are case-sensitive | | EvaluateOptions.NoCache | Default behaviour (no caching) | | EvaluateOptions.RoundAwayFromZero | Override Calculator.modulus / Round | | Custom function handler | functions option in evaluate / execute | | Custom value factory | Extend StandardCalculator |

How to extend behaviour

Override the provided Calculator interface or extend StandardCalculator to change how operators work. Extend AbstractVisitor<T> for custom AST traversal.

See Overriding Evaluation for examples.

License

MIT License © 2026 ImogenZ