{"id":25605,"library":"formula","title":"formula","description":"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.","status":"active","version":"3.18.0","language":"javascript","source_language":"en","source_url":"https://github.com/formula/formula","tags":["javascript","Spreadsheets","JavaScript","typescript"],"install":[{"cmd":"npm install formula","lang":"bash","label":"npm"},{"cmd":"yarn add formula","lang":"bash","label":"yarn"},{"cmd":"pnpm add formula","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v3; CommonJS require is not supported.","wrong":"const run = require('formula').run","symbol":"run","correct":"import { run } from 'formula'"},{"note":"Named export, not default.","wrong":"import compile from 'formula'","symbol":"compile","correct":"import { compile } from 'formula'"},{"note":"Type-only import in TypeScript; Formula is a type, not a value.","wrong":"import { Formula } from 'formula'","symbol":"Formula","correct":"import type { Formula } from 'formula'"}],"quickstart":{"code":"import { run } from 'formula';\n\n// Evaluate JSONPath expression with comparison\nconst result1 = run('$.a.b = 1', '{ \"a\": { \"b\": 1 } }');\nconsole.log(result1); // true\n\n// Use spreadsheet-like functions\nconst result2 = run('sum(a, b, c) = 1+2+3', { a: 1, b: 2, c: 3 });\nconsole.log(result2); // true\n\n// Compile expression for repeated use\nimport { compile } from 'formula';\nconst expr = compile('$.name');\nconst data = { name: 'Alice' };\nconst result3 = expr(data);\nconsole.log(result3); // 'Alice'","lang":"typescript","description":"Shows basic usage of run() for evaluating expressions and compile() for reusable expression compilation."},"warnings":[{"fix":"Use import syntax or dynamic import(). If using Node.js without --experimental-modules (pre-v12.17), upgrade Node.js.","message":"v3.0.0 changed to ESM-only; CommonJS require() no longer works.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace VLOOKUP_OLD with VLOOKUP; see migration guide.","message":"v0.x functions like VLOOKUP_OLD are deprecated; use the new cleaner functions.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Always ensure data is JSON or a plain object literal.","message":"Expression string must be valid JSON string or object; passing a JavaScript object that is not JSON-serializable may cause unexpected results.","severity":"gotcha","affected_versions":"*"},{"fix":"Check documentation for expression syntax; avoid assuming return type.","message":"run() returns boolean when expression contains comparison operators like =; for non-comparison expressions, it returns the computed value.","severity":"gotcha","affected_versions":"*"},{"fix":"Replace ADD, SUB with +, - or sum().","message":"Some older formula functions (e.g., ADD, SUB) removed in v2.x; use sum(), arithmetic operators.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use == for equality comparison inside expression, or wrap in run('expr = value', data) for assignment expression.","cause":"Using a single = for assignment instead of == or comparison expression context.","error":"SyntaxError: Unexpected token '='"},{"fix":"Use import { run } from 'formula' or use dynamic import().","cause":"Using CommonJS require('formula') after v3 where module is ESM-only.","error":"TypeError: run is not a function"},{"fix":"Run npm install formula and ensure node_modules is present.","cause":"Package not installed or incorrect import path.","error":"Cannot find module 'formula'"},{"fix":"Verify expression syntax; use compile() to get detailed error message.","cause":"Malformed expression string (e.g., unmatched quotes or unsupported function).","error":"Expression '' contains invalid JSONPath or function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}