formula

library3.18.0jsnpmunverified

Formula compiler and function library for JSON spreadsheet-like expressions. Current stable version is 3.18.0, with frequent releases (multiple per month). Key differentiators: supports JSONPath-based access, spreadsheet functions (SUM, VLOOKUP, HLOOKUP, CLEAN), and runs in Node.js and browser via UMD/ESM. Ships TypeScript types.

data serialization

npm install formula

github ↗package ↗

INSTALL

IMPORT

SIG · FORMULA

formula

datajavascriptv3.18.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

run

✓ import { run } from 'formula'

✗ const run = require('formula').run

ESM-only since v3; CommonJS require is not supported.

compile

✓ import { compile } from 'formula'

✗ import compile from 'formula'

Named export, not default.

Formula

✓ import type { Formula } from 'formula'

✗ import { Formula } from 'formula'

Type-only import in TypeScript; Formula is a type, not a value.

Shows basic usage of run() for evaluating expressions and compile() for reusable expression compilation.

import { run } from 'formula'; // Evaluate JSONPath expression with comparison const result1 = run('$.a.b = 1', '{ "a": { "b": 1 } }'); console.log(result1); // true // Use spreadsheet-like functions const result2 = run('sum(a, b, c) = 1+2+3', { a: 1, b: 2, c: 3 }); console.log(result2); // true // Compile expression for repeated use import { compile } from 'formula'; const expr = compile('$.name'); const data = { name: 'Alice' }; const result3 = expr(data); console.log(result3); // 'Alice'

Debug

Known issues

breakingv3.0.0 changed to ESM-only; CommonJS require() no longer works.

fix

Use import syntax or dynamic import(). If using Node.js without --experimental-modules (pre-v12.17), upgrade Node.js.

affects: >=3.0.0

deprecatedv0.x functions like VLOOKUP_OLD are deprecated; use the new cleaner functions.

fix

Replace VLOOKUP_OLD with VLOOKUP; see migration guide.

affects: >=3.0.0

gotchaExpression string must be valid JSON string or object; passing a JavaScript object that is not JSON-serializable may cause unexpected results.

fix

Always ensure data is JSON or a plain object literal.

affects: *

gotcharun() returns boolean when expression contains comparison operators like =; for non-comparison expressions, it returns the computed value.

fix

Check documentation for expression syntax; avoid assuming return type.

affects: *

deprecatedSome older formula functions (e.g., ADD, SUB) removed in v2.x; use sum(), arithmetic operators.

fix

Replace ADD, SUB with +, - or sum().

affects: >=2.0.0

Errors

Common errors & fixes

SyntaxError: Unexpected token '='

Using a single = for assignment instead of == or comparison expression context.

fix

Use == for equality comparison inside expression, or wrap in run('expr = value', data) for assignment expression.

TypeError: run is not a function

Using CommonJS require('formula') after v3 where module is ESM-only.

fix

Use import { run } from 'formula' or use dynamic import().

Cannot find module 'formula'

Package not installed or incorrect import path.

fix

Run npm install formula and ensure node_modules is present.

Expression '' contains invalid JSONPath or function

Malformed expression string (e.g., unmatched quotes or unsupported function).

fix

Verify expression syntax; use compile() to get detailed error message.

Upgrade

Version history

3.18.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/formula/formula ↗

packagehttps://www.npmjs.com/package/formula ↗