Evaluate a Formula

Formula evaluation is useful when your application needs spreadsheet semantics without loading a whole workbook UI.

Excel errors are values

#DIV/0!, #VALUE!, and #NAME? travel as spreadsheet values. Host API failures use status envelopes, exceptions, or non-zero CLI exits depending on surface.

JavaScript / WASM

import createFormulon, { ValueKind } from '@libraz/formulon'

const Module = await createFormulon()

const result = Module.evalFormula('=SUM(1,2,3)')
if (!result.status.ok) {
  throw new Error(result.status.message)
}

if (result.value.kind === ValueKind.Number) {
  console.log(result.value.number)
}

Python

import formulon

value = formulon.eval_formula("=SUM(1,2,3)")
print(value.to_python())

CLI

formulon eval '=SUM(1,2,3)'
formulon eval --json '=1/0'

Cell-level Excel errors are values. =1/0 should return an error value such as #DIV/0!; it should not be treated as a process, Python, or JS exception. Host-side failures, such as invalid workbook bytes or a missing file, are reported through the surface-specific error path.

The panel below is where to check that claim. Its =1/0 preset comes back with value kind Error and the text #DIV/0! — a value you can inspect, not an exception you have to catch. Its second tab evaluates against a small seeded workbook, the evaluateFormulaText path described in the next section.

Evaluate a formula

The WASM engine in this page evaluates whatever you type. Standalone evaluation calls evalFormula(); workbook evaluation calls evaluateFormulaText() so references resolve.

Powered by the real Formulon engine (WASM) — it runs entirely in your browser, nothing is uploaded.

Evaluating against a loaded workbook

The examples above always evaluate in a fresh, disposable formula context: there is no workbook, so cell references, defined names, and ROW() / COLUMN() have nothing to resolve against. evaluateFormulaText (and its conditional-formatting counterpart, evaluateConditionalFormula) evaluates formula text as if it were entered at a specific cell of an already-loaded workbook, without changing anything in it.

Read-only, and scalar-only

evaluateFormulaText / evaluateConditionalFormula never mutate the workbook and never join the dependency graph — a self-reference reads the target cell's cached value instead of raising #REF!. Array and spill results are reduced to their top-left element; this is the direct scalar-result behavior, not Excel's implicit-intersection or spill behavior. See Dynamic arrays for how spilling actually works.

Whole-array variant

When you want the entire spilled result rather than just the top-left element, use evaluateFormulaArray(sheet, row, col, formula) — it returns the whole Array (EvalArrayResult) of a dynamic-array formula. Python exposes the same operation as evaluate_formula_array(...).

JavaScript / WASM and Native Node

import createFormulon, { ValueKind } from '@libraz/formulon'

const Module = await createFormulon()
const workbook = Module.Workbook.loadBytes(xlsxBytes)

try {
  if (!workbook.isValid()) {
    throw new Error(Module.lastErrorMessage())
  }

  // Evaluate as if `=B4*1.1` were entered at sheet 0, row 5, col 1 (B6) --
  // resolves against the workbook's live cells without writing anything.
  const preview = workbook.evaluateFormulaText(0, 5, 1, '=B4*1.1')
  if (!preview.status.ok) {
    throw new Error(preview.status.message)
  }

  if (preview.value.kind === ValueKind.Number) {
    console.log(preview.value.number)
  }
} finally {
  workbook.delete()
}

The Native Node package (packages/npm-native) exposes the identical evaluateFormulaText / evaluateConditionalFormula methods on the same Workbook shape; see Native Node integration.

Python boundary

Python does not expose the general scalar evaluate_formula_text equivalent. It does expose evaluate_cf_formula for conditional-format predicates and evaluate_formula_array for full array results. For a general scalar evaluated in workbook context, write the formula into a cell with set_formula and call recalc().