formula

3.18.0 verified Fri May 01 auth: no javascript

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.

Common errors

error SyntaxError: Unexpected token '=' ↓

cause 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.

error TypeError: run is not a function ↓

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

fix

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

error Cannot find module 'formula' ↓

cause Package not installed or incorrect import path.

fix

Run npm install formula and ensure node_modules is present.

error Expression '' contains invalid JSONPath or function ↓

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

fix

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

Warnings

breaking v3.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.

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

fix Replace VLOOKUP_OLD with VLOOKUP; see migration guide.

gotcha Expression 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.

gotcha run() 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.

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

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

Install

npm install formula

yarn add formula

pnpm add formula

Imports

run

wrong

const run = require('formula').run

correct

import { run } from 'formula'

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

compile

wrong

import compile from 'formula'

correct

import { compile } from 'formula'

Named export, not default.

Formula
wrong
```
import { Formula } from 'formula'
```
correct
```
import type { Formula } from 'formula'
```
Type-only import in TypeScript; Formula is a type, not a value.

Quickstart

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'