Registry / serialization / hot-formula-parser

hot-formula-parser

library4.0.0jsnpmunverified

hot-formula-parser is a JavaScript library providing a `Parser` class capable of evaluating Excel and mathematical formulas. It supports a wide range of features including arithmetic, logical, and comparison operations, JavaScript Math constants, string concatenation, relative and absolute cell coordinates, custom variables, and custom functions. The current stable version is 4.0.0, released in 2023, which focuses on enhancing module compatibility for both CommonJS and ECMAScript environments. While major releases are not frequent, the project maintains an active development pace with dependency updates and feature enhancements. Its key differentiators include comprehensive Excel formula support via `@handsontable/formulajs`, robust error handling, and the flexibility to extend with custom logic, making it suitable for spreadsheet-like applications in both Node.js and browser environments.

serialization database

npm install hot-formula-parser

github ↗package ↗

INSTALL

IMPORT

SIG · HOT-FORMULA-PARSER

hot-formula-parser

serializationjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import { Parser } from 'hot-formula-parser';

✗ import FormulaParser from 'hot-formula-parser'; const FormulaParser = require('hot-formula-parser');

Since v4.0.0, the package is compatible with both ESM and CJS. For ESM, use named import. For CJS, `require('hot-formula-parser')` returns an object with `Parser` as a property. Older versions might have required `require('hot-formula-parser').Parser` directly.

Parser (CJS)

✓ const { Parser } = require('hot-formula-parser');

✗ import { Parser } from 'hot-formula-parser';

This is the preferred CommonJS import style since v4.0.0 for better compatibility and explicit named export. Attempting `import` in a pure CJS environment will result in errors.

SUPPORTED_FORMULAS

✓ import { SUPPORTED_FORMULAS } from 'hot-formula-parser';

✗ import SUPPORTED_FORMULAS from 'hot-formula-parser';

This is a named export, available for both ESM and CJS modules to list all supported formula functions.

Demonstrates initializing the parser, setting custom variables and functions, and parsing formulas with both custom and built-in logic, including error handling.

import { Parser } from 'hot-formula-parser'; const parser = new Parser(); // Set custom variables parser.setVariable('SALES_TAX_RATE', 0.05); parser.setVariable('ITEM_PRICE', 100); // Set a custom function parser.setFunction('CALC_TOTAL_WITH_TAX', (params) => { const price = params[0]; const taxRate = params[1]; return price * (1 + taxRate); }); // Parse a formula using variables and the custom function const result1 = parser.parse('ITEM_PRICE * (1 + SALES_TAX_RATE)'); console.log('Result 1:', result1); // Expected: { error: null, result: 105 } const result2 = parser.parse('CALC_TOTAL_WITH_TAX(ITEM_PRICE, SALES_TAX_RATE)'); console.log('Result 2:', result2); // Expected: { error: null, result: 105 } // Example with a built-in Excel function and error handling const sumResult = parser.parse('SUM(10, 20, "invalid")'); console.log('Sum with error:', sumResult); // Expected: { error: "#VALUE!", result: null }

Debug

Known issues

breakingSeveral Excel functions including `NUMERAL`, `DOLLAR`, `FIXED`, `TEXT`, and `VALUE` were either removed or marked as not implemented in v3.0.0 due to incompatibility or internal changes in the underlying `@handsontable/formula.js` package.

fix

Review your formulas and replace usage of the deprecated functions with alternative logic or custom functions where possible. Refer to the `@handsontable/formula.js` documentation for compatible functions.

affects: >=3.0.0

breakingVersion 3.0.0 updated the core `@handsontable/formula.js` package to a new major version. This update may introduce subtle behavior changes or incompatibilities in certain Excel formula evaluations, even for functions not explicitly listed as removed.

fix

Thoroughly test existing formulas after upgrading to v3.0.0 or later. Consult the `@handsontable/formula.js` release notes for detailed changes.

affects: >=3.0.0

gotchaPrior to v4.0.0, module import patterns could be inconsistent, particularly for ESM environments. Version 4.0.0 repackaged the library to improve compatibility with both CommonJS and ECMAScript modules, potentially affecting build processes or specific import statements.

fix

For ESM, use `import { Parser } from 'hot-formula-parser';`. For CommonJS, `const { Parser } = require('hot-formula-parser');` is recommended. Ensure your build configuration (e.g., Webpack, Rollup) correctly handles module resolution.

affects: >=4.0.0

gotchaThe `eval` usage was removed from the source code in version 3.0.1. While this is a security and CSP improvement, environments or custom configurations that might have implicitly relied on `eval` behavior (though unlikely for direct usage) could see changes.

fix

No direct fix is required for most users, as this improves security. However, if you have very unusual custom parsing logic that somehow interacted with the library's internal `eval` usage, review its behavior.

affects: >=3.0.1

Errors

Common errors & fixes

parser.parse('SUM(MY_VAR)'); // returns `Object {error: '#NAME?', result: null}`

The formula contains a function or variable name that has not been defined or recognized by the parser.

fix

Ensure that all custom variables are set using `parser.setVariable(name, value)` and custom functions using `parser.setFunction(name, fn)` before parsing. Check for typos in function or variable names.

parser.parse('10 / 0'); // returns `Object {error: '#DIV/0!', result: null}`

The formula attempts to divide a number by zero.

fix

Modify the formula to prevent division by zero, or implement checks in your custom functions to handle zero divisors gracefully.

parser.parse('SUM(1, 2, "text")'); // returns `Object {error: '#VALUE!', result: null}`

One or more arguments provided to a formula function are of the wrong data type.

fix

Ensure that the arguments passed to functions match their expected types (e.g., numbers for `SUM`). Validate user input or intermediate calculation results before they are fed into the parser.

parser.parse('1;;1'); // returns `Object {error: '#ERROR!', result: null}`

A general parsing error occurred, often due to malformed syntax in the formula.

fix

Review the formula for syntax errors such as unmatched parentheses, incorrect delimiters, or invalid operator sequences. Use a linter or syntax highlighter for complex formulas if possible.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@handsontable/formulajsrequiredProvides the core Excel-like formula implementations and functions.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/handsontable/formula-parser ↗

packagehttps://www.npmjs.com/package/hot-formula-parser ↗