formula-parser

hot-formula-parser exposes a Parser class that evaluates Excel-style formulas and mathematical expressions in Node.js and the browser. It supports arithmetic, logical, and comparison operators, absolute and relative cell coordinates, custom variables and functions, and the full set of formulas implemented by @handsontable/formulajs (Excel-compatible functions like SUM, VLOOKUP, and IF).

Rather than binding to any specific grid or data model, the parser stays host-agnostic: it fires events (callCellValue, callRangeValue, callVariable, callFunction) that a consuming application — most notably the Handsontable spreadsheet grid, which originated this project — can hook into to resolve cell references against its own data. Results are always returned as a structured {error, result} object using Excel’s own error vocabulary (#DIV/0!, #NAME?, #VALUE!, etc.) instead of throwing.

What You Get

• A Parser class with .parse(expression) returning a structured {error, result} object
• Support for arithmetic, logical, and comparison operators plus string concatenation (&)
• Relative and absolute cell coordinate syntax (A1, $A1, A$1, $A$1) and range syntax (A1:B3)
• The full @handsontable/formulajs function library (Excel-compatible SUM, VLOOKUP, IF, and more)
• Custom variable (setVariable/getVariable) and custom function (setFunction/getFunction) registration
• Event hooks (callVariable, callFunction, callCellValue, callRangeValue) for wiring the parser to a host application’s own data source
• Node.js (CommonJS/ESM) and browser (UMD/minified) builds distributed from the same package

Common Use Cases

• Powering formula evaluation inside a custom spreadsheet or data-grid component
• Adding Excel-style calculated fields to a form builder or reporting tool
• Evaluating user-entered mathematical or logical expressions safely, with structured error codes instead of exceptions
• Building a lightweight formula engine for a no-code/low-code app builder

Under The Hood

Architecture The Parser class extends tiny-emitter and wraps a Jison-generated grammar parser (compiled from grammar-parser.jison into grammar-parser.js), injecting a yy context of helper callbacks — toNumber, trimEdges, invertNumber, throwError, callVariable, evaluateByOperator, callFunction, cellValue, rangeValue — that the generated grammar invokes during parsing. parse() delegates to this grammar parser inside a try/catch, routing any thrown message through error.js to map it onto Excel’s own error vocabulary (#DIV/0!, #NAME?, #VALUE!, etc.) rather than letting exceptions escape. Extensibility comes entirely through emitted events (callVariable, callFunction, callCellValue, callRangeValue), which let a host application — Handsontable’s grid, in the common case — resolve cell and range references against its own data model without the parser needing any knowledge of that model. evaluate-by-operator.js implements a small pluggable operator registry (registerOperation/availableOperators) under evaluate-by-operator/operator/*, keeping arithmetic and comparison logic cleanly separated from the grammar layer and from the external formula-function library. The result is a lean, clearly layered pipeline — grammar → parser orchestration/events → operator dispatch → formula library — where changing the core Parser class affects only orchestration and event wiring, not grammar rules or formula computation.

Tech Stack Plain ES2015+ JavaScript transpiled via Babel into CommonJS, ESM, and Webpack-built UMD bundles (including a minified build) published together from one package, with jsdelivr/unpkg CDN entries for direct browser use. tiny-emitter supplies the event-emitter base class, @handsontable/formulajs supplies the actual Excel-compatible formula implementations, and jison generates the expression grammar parser from a .jison grammar file at build time. Tests run under Jest; linting uses ESLint with the Airbnb base config; historical CI ran on Travis; releases are cut with generate-release.

Code Quality The project has an extensive test suite — unit tests for the parser, error mapping, each individual operator module, and helper functions, plus integration tests organized by formula category (math, logical, text, date-time, financial, engineering, information, lookup-reference, statistical, miscellaneous). Jest is configured with coverage collection, and ESLint enforces consistent style across src and test. Error handling is explicit and centralized — thrown exceptions are always mapped to a fixed set of Excel error codes rather than swallowed or left to bubble as raw JS errors. There is no TypeScript or other static typing; documentation relies on JSDoc comments rather than generated type declarations. The repository itself is explicitly marked deprecated in favor of the maintainers’ newer HyperFormula engine, and has seen no commits since 2021.

API Design The public surface is small and deliberately host-agnostic: construct a Parser, call .parse(expression), and optionally register variables/functions or subscribe to the four event hooks to wire in live cell data. Getting started requires almost no boilerplate, and results are always a structured object rather than a thrown exception, which makes the API easy to use defensively in form/UI contexts. The four event hooks are a genuinely useful design choice — they let very different host data structures (a grid, a form, a document) plug into the same evaluator without the library imposing its own storage model. The tradeoff is that this ergonomic design is now superseded: the same maintainers point users toward HyperFormula for anything beyond legacy Handsontable compatibility.