Formula Language

July 8, 2026 ยท View on GitHub

Current state

  • JS is still the semantic oracle
  • canonical production routing is closed for 431 of 431 canonical rows
  • 0 canonical rows remain implemented-js
  • 0 canonical rows remain blocked
  • the generated source of truth is packages/formula/src/__tests__/fixtures/formula-compatibility-snapshot.json

Canonical corpus milestone

The active milestone is the canonical Excel for the web worksheet formula corpus represented in packages/formula/src/compatibility.ts.

The current code-backed canonical registry contains 431 rows.

There are no non-production canonical rows.

The canonical grouped-array SUM forms for GROUPBY and PIVOTBY now route through internal native grouped-array builtins on the wasm path.

Google Sheets compatibility subset

QUERY is supported for local WorkPaper ranges, not provider-backed Sheets data. The current deterministic subset covers:

  • select column projections
  • where comparisons against scalar literals
  • group by with projected group columns plus sum(column) and count(column)
  • order by, limit, and offset
  • bounded label clauses for selected output columns and supported aggregate outputs

Unsupported Google Visualization Query Language clauses such as pivot, having, format, and options still fail closed with #VALUE!.

Full target

The full formula target remains Excel 365 worksheet parity as of 2026-03-15, including:

  • absolute and mixed refs
  • quoted sheet refs
  • unions and intersections
  • %, @, #
  • array literals
  • defined names
  • tables and structured references
  • dynamic arrays
  • LET
  • LAMBDA

Host and service function boundary

The worksheet engine keeps non-worksheet Excel surfaces behind the adapter contract in packages/formula/src/external-function-adapter.ts.

  • native builtins stay focused on the worksheet corpus tracked in this package
  • cube, web, host-backed, external-data, add-in-like, and Python-in-Excel surfaces register through installExternalFunctionAdapter()
  • adapters can expose scalar or range-aware functions to the JS evaluator
  • adapted functions do not receive a BuiltinId and do not enter the WASM fast path
  • known provider-backed functions such as PY, COPILOT, TRANSLATE, IMPORTRANGE, GOOGLEFINANCE, and cube/web data functions fail closed as #BLOCKED! when no adapter is installed
  • Google Sheets import functions such as IMPORTRANGE, IMPORTDATA, IMPORTHTML, IMPORTXML, IMPORTFEED, and GOOGLEFINANCE are compatibility hooks: a host adapter must fetch or authorize the provider data, then return scalar values or imported cells to the evaluator

Semantic rules

  • Excel for the web is the behavior oracle
  • visible error strings follow Excel codes
  • JS and WASM must not diverge on coercion, blanks, error precedence, spill blocking, or lookup comparison rules
  • a canonical row is not complete until production execution can route it through WASM

Canonical companions