@lotics/xlsx 0.1.0

package/src/formula_engine.ts

@@ -0,0 +1,401 @@
+// =============================================================================
+// Formula Engine
+// =============================================================================
+//
+// Orchestrates formula evaluation using:
+// - fast-formula-parser for parsing and evaluating Excel formulas
+// - DependencyGraph for tracking cell dependencies and recalculation order
+// - WorkbookModel as the cell value source via callbacks
+//
+// Lifecycle:
+// 1. On workbook load: build dependency graph from all formula cells
+// 2. Evaluate cells with missing cached values
+// 3. On cell edit: update graph, recalculate affected dependents
+// =============================================================================
+
+/// <reference path="./fast-formula-parser.d.ts" />
+import FormulaParser from "fast-formula-parser";
+import { DependencyGraph, cellKey, parseCellKey } from "./formula_deps";
+import type { WorkbookModel, CellValue } from "./workbook_model";
+import { refToRowCol, rowColToRef, colLettersToNum } from "./excel_utils";
+import { formatNumFmt } from "./excel_numfmt";
+import { expandStructuredRefs } from "./structured_refs";
+
+// =============================================================================
+// FormulaEngine
+// =============================================================================
+
+export class FormulaEngine {
+  private graph = new DependencyGraph();
+  private parser: FormulaParser;
+  private depParser: InstanceType<typeof FormulaParser.DepParser>;
+  private workbook: WorkbookModel;
+
+  constructor(workbook: WorkbookModel) {
+    this.workbook = workbook;
+
+    this.parser = new FormulaParser({
+      onCell: (ref: { row: number; col: number; sheet?: string }) => this.resolveCell(ref),
+      onRange: (ref: { from: { row: number; col: number }; to: { row: number; col: number }; sheet?: string }) => this.resolveRange(ref),
+      onVariable: (name: string) => this.resolveVariable(name),
+    });
+
+    this.depParser = new FormulaParser.DepParser();
+  }
+
+  // ===========================================================================
+  // Initialization — build graph and evaluate missing values
+  // ===========================================================================
+
+  /** Build dependency graph from all formula cells in the workbook. */
+  buildGraph(): void {
+    this.graph.clear();
+    for (const sheet of this.workbook.sheets) {
+      for (const [ref, cell] of sheet.cells) {
+        if (!cell.formula) continue;
+        const key = cellKey({ sheet: sheet.name, ref });
+        const deps = this.extractDependencies(cell.formula, sheet.name);
+        this.graph.setDependencies(key, deps);
+      }
+    }
+  }
+
+  /** Evaluate all formula cells that have no cached value (value is null). */
+  evaluateMissing(): void {
+    const missing: string[] = [];
+    for (const sheet of this.workbook.sheets) {
+      for (const [ref, cell] of sheet.cells) {
+        if (cell.formula && cell.value === null) {
+          missing.push(cellKey({ sheet: sheet.name, ref }));
+        }
+      }
+    }
+    this.evaluateSet(missing);
+  }
+
+  /**
+   * Evaluate every formula cell, ignoring any previously cached value.
+   *
+   * `evaluateMissing` trusts cached values — the right default for loading
+   * a file that was produced by a correct writer. Use `evaluateAll` when
+   * the cached values are known to be stale, e.g. after a template
+   * substitution pipeline has rewritten the cells a formula references
+   * but didn't recompute the formula itself. Excel does this on every
+   * file open; our writer doesn't, so downstream consumers that trust
+   * `<v>` (our renderer, PDF converters, print-to-image) would otherwise
+   * show stale values.
+   */
+  evaluateAll(): void {
+    const all: string[] = [];
+    for (const sheet of this.workbook.sheets) {
+      for (const [ref, cell] of sheet.cells) {
+        if (cell.formula) {
+          all.push(cellKey({ sheet: sheet.name, ref }));
+        }
+      }
+    }
+    this.evaluateSet(all);
+  }
+
+  private evaluateSet(keys: string[]): void {
+    if (keys.length === 0) return;
+    const order = this.graph.getRecalcOrder(keys);
+    const orderSet = new Set(order);
+    const toEvaluate = [...keys.filter((k) => !orderSet.has(k)), ...order];
+    for (const key of toEvaluate) {
+      this.evaluateCell(key);
+    }
+  }
+
+  // ===========================================================================
+  // Cell edit — update graph and recalculate
+  // ===========================================================================
+
+  /** Called when a cell value changes. Recalculates all affected dependents. */
+  onCellChanged(sheetName: string, ref: string, formula?: string): void {
+    const key = cellKey({ sheet: sheetName, ref });
+
+    if (formula) {
+      const deps = this.extractDependencies(formula, sheetName);
+      this.graph.setDependencies(key, deps);
+
+      const cycle = this.graph.detectCycle(key);
+      if (cycle) {
+        this.setCellError(key, "#CIRC!");
+        return;
+      }
+
+      this.evaluateCell(key);
+    } else {
+      this.graph.removeCell(key);
+    }
+
+    const order = this.graph.getRecalcOrder([key]);
+    for (const depKey of order) {
+      const depCycle = this.graph.detectCycle(depKey);
+      if (depCycle) {
+        this.setCellError(depKey, "#CIRC!");
+        continue;
+      }
+      this.evaluateCell(depKey);
+    }
+  }
+
+  // ===========================================================================
+  // Formula evaluation (boundary handler — catches library errors)
+  // ===========================================================================
+
+  /** Evaluate a single formula cell and update its value. */
+  private evaluateCell(key: string): void {
+    const { sheet: sheetName, ref } = parseCellKey(key);
+    const sheetIndex = this.workbook.sheets.findIndex((s) => s.name === sheetName);
+    if (sheetIndex < 0) return;
+
+    const sheet = this.workbook.sheets[sheetIndex];
+    const cell = sheet.getCell(ref);
+    if (!cell?.formula) return;
+
+    const rc = refToRowCol(ref);
+    if (!rc) return;
+
+    // Expand structured references before evaluation
+    const expandedFormula = expandStructuredRefs(cell.formula, sheet.tables, rc.row);
+
+    // fast-formula-parser uses exceptions as its error-reporting API
+    // (FormulaError for #REF!, #VALUE!, etc.). This catch is a boundary
+    // adapter for the library, not business logic error swallowing.
+    try {
+      const raw = this.parser.parse(expandedFormula, {
+        sheet: sheetName,
+        row: rc.row,
+        col: rc.col,
+      });
+
+      const result = normalizeResult(raw);
+      cell.value = result.value;
+      cell.error = result.error;
+      cell.displayValue = result.error ?? computeDisplay(result.value, cell.numFmtCode, this.workbook.date1904);
+      cell.content = { type: "plain", text: cell.displayValue };
+    } catch (err: unknown) {
+      // Only catch FormulaError (library's error-reporting mechanism).
+      // Rethrow genuine bugs (TypeError, RangeError, etc.).
+      if (isFormulaError(err)) {
+        const errorName = err.name;
+        cell.error = errorName;
+        cell.value = null;
+        cell.displayValue = errorName;
+        cell.content = { type: "plain", text: errorName };
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  private setCellError(key: string, error: string): void {
+    const { sheet: sheetName, ref } = parseCellKey(key);
+    const sheetIndex = this.workbook.sheets.findIndex((s) => s.name === sheetName);
+    if (sheetIndex < 0) return;
+    const cell = this.workbook.sheets[sheetIndex].getCell(ref);
+    if (!cell) return;
+    cell.error = error;
+    cell.value = null;
+    cell.displayValue = error;
+    cell.content = { type: "plain", text: error };
+  }
+
+  // ===========================================================================
+  // Dependency extraction
+  // ===========================================================================
+
+  /** Extract cell/range references from a formula string. Returns empty array for unparseable formulas. */
+  extractDependencies(formula: string, currentSheet: string): string[] {
+    const sheet = this.workbook.sheets.find((s) => s.name === currentSheet);
+    const expanded = sheet ? expandStructuredRefs(formula, sheet.tables, 1) : formula;
+    const deps = this.depParser.parse(expanded, { sheet: currentSheet, row: 1, col: 1 });
+    const refs: string[] = [];
+
+    for (const dep of deps) {
+      const depSheet = dep.sheet ?? currentSheet;
+      if (dep.from && dep.to) {
+        const maxCells = 10000;
+        let count = 0;
+        for (let r = dep.from.row; r <= dep.to.row && count < maxCells; r++) {
+          for (let c = dep.from.col; c <= dep.to.col && count < maxCells; c++) {
+            refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(r, c) }));
+            count++;
+          }
+        }
+      } else if (dep.row != null && dep.col != null) {
+        refs.push(cellKey({ sheet: depSheet, ref: rowColToRef(dep.row, dep.col) }));
+      }
+    }
+
+    return refs;
+  }
+
+  // ===========================================================================
+  // Cell value resolution callbacks
+  // ===========================================================================
+
+  private resolveCell(ref: { row: number; col: number; sheet?: string }): CellValue {
+    const sheetName = ref.sheet ?? this.workbook.sheets[0]?.name ?? "Sheet1";
+    const sheet = this.workbook.sheets.find((s) => s.name === sheetName);
+    if (!sheet) return null;
+
+    const cellRef = rowColToRef(ref.row, ref.col);
+    const cell = sheet.getCell(cellRef);
+    if (!cell) return null;
+    if (cell.error) throw new Error(cell.error);
+    return cell.value;
+  }
+
+  private resolveRange(ref: {
+    from: { row: number; col: number };
+    to: { row: number; col: number };
+    sheet?: string;
+  }): CellValue[][] {
+    const sheetName = ref.sheet ?? this.workbook.sheets[0]?.name ?? "Sheet1";
+    const sheet = this.workbook.sheets.find((s) => s.name === sheetName);
+    if (!sheet) return [[]];
+
+    const result: CellValue[][] = [];
+    for (let r = ref.from.row; r <= ref.to.row; r++) {
+      const row: CellValue[] = [];
+      for (let c = ref.from.col; c <= ref.to.col; c++) {
+        const cell = sheet.getCell(rowColToRef(r, c));
+        row.push(cell?.value ?? null);
+      }
+      result.push(row);
+    }
+    return result;
+  }
+
+  // ===========================================================================
+  // Named range resolution
+  // ===========================================================================
+
+  private resolveVariable(name: string): unknown {
+    const rangeExpr = this.workbook.namedRanges.get(name);
+    if (rangeExpr === undefined) return null;
+
+    // Parse range expression like "Sheet1!$A$1:$B$5" or "Sheet1!$C$11"
+    const cleaned = rangeExpr.replace(/\$/g, "");
+    const sheetMatch = cleaned.match(/^(.+?)!(.+)$/);
+    const sheetName = sheetMatch ? sheetMatch[1].replace(/^'|'$/g, "") : this.workbook.sheets[0]?.name ?? "Sheet1";
+    const rangeStr = sheetMatch ? sheetMatch[2] : cleaned;
+
+    const sheet = this.workbook.sheets.find((s) => s.name === sheetName);
+    if (!sheet) return null;
+
+    // Check if it's a range (A1:B5) or single cell (C11)
+    const rangeMatch = rangeStr.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+    if (rangeMatch) {
+      const fromRow = parseInt(rangeMatch[2], 10);
+      const fromCol = colLettersToNum(rangeMatch[1]);
+      const toRow = parseInt(rangeMatch[4], 10);
+      const toCol = colLettersToNum(rangeMatch[3]);
+      return this.resolveRange({
+        from: { row: fromRow, col: fromCol },
+        to: { row: toRow, col: toCol },
+        sheet: sheetName,
+      });
+    }
+
+    const cellMatch = rangeStr.match(/^([A-Z]+)(\d+)$/);
+    if (cellMatch) {
+      return this.resolveCell({
+        row: parseInt(cellMatch[2], 10),
+        col: colLettersToNum(cellMatch[1]),
+        sheet: sheetName,
+      });
+    }
+
+    return null;
+  }
+
+  // ===========================================================================
+  // Expression evaluation (for CF rules)
+  // ===========================================================================
+
+  /** Evaluate an arbitrary formula expression. Used by CF expression rules. */
+  evaluateExpression(formula: string, sheetName: string, row: number, col: number): unknown {
+    // fast-formula-parser uses exceptions as its error-reporting API
+    try {
+      return this.parser.parse(formula, { sheet: sheetName, row, col });
+    } catch (err: unknown) {
+      if (isFormulaError(err)) return null;
+      throw err;
+    }
+  }
+
+  /** Get the dependency graph (for testing/debugging). */
+  get deps(): DependencyGraph {
+    return this.graph;
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+interface FormulaResult {
+  value: CellValue;
+  error?: string;
+}
+
+/** Type guard for fast-formula-parser FormulaError objects. */
+function isFormulaError(v: unknown): v is Error & { name: string } {
+  return v instanceof Error && typeof v.name === "string" && v.name.startsWith("#");
+}
+
+function normalizeResult(result: unknown): FormulaResult {
+  if (result === null || result === undefined) return { value: null };
+  if (typeof result === "number") return { value: result };
+  if (typeof result === "boolean") return { value: result };
+  if (typeof result === "string") return { value: result };
+  if (isFormulaError(result)) return { value: null, error: result.name };
+  // FormulaError objects that don't extend Error (library v1)
+  if (typeof result === "object" && result !== null && "name" in result) {
+    const name = (result as { name: unknown }).name;
+    if (typeof name === "string" && name.startsWith("#")) {
+      return { value: null, error: name };
+    }
+  }
+  return { value: String(result) };
+}
+
+function computeDisplay(value: CellValue, numFmtCode: string, date1904: boolean): string {
+  if (value === null) return "";
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  if (typeof value === "string") return value;
+  return formatNumFmt(value, numFmtCode, date1904).text;
+}
+
+// =============================================================================
+// Convenience: load-time recompute
+// =============================================================================
+
+/**
+ * Build a dependency graph for the workbook and recompute every formula
+ * cell, overwriting whatever was cached. Use at boundaries where you
+ * just mutated inputs a formula depends on (template substitution, bulk
+ * paste) and need the downstream cached values to match.
+ */
+export function recomputeAll(workbook: WorkbookModel): void {
+  const engine = new FormulaEngine(workbook);
+  engine.buildGraph();
+  engine.evaluateAll();
+}
+
+/**
+ * Refresh every formula cell on a freshly loaded workbook when the file
+ * declares `calcPr.fullCalcOnLoad="1"`. Mirrors Excel's behavior — the
+ * flag is a writer's signal that cached values can't be trusted, usually
+ * because the writer couldn't compute them (template pipelines, manual
+ * XML authoring, older tools). Safe to call on every load: a workbook
+ * without the flag or without formulas returns immediately.
+ */
+export function recomputeIfStale(workbook: WorkbookModel): void {
+  if (!workbook.fullCalcOnLoad) return;
+  recomputeAll(workbook);
+}

package/src/formula_highlight.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { tokenizeFormula } from "./formula_highlight";
+import type { FormulaToken } from "./formula_highlight";
+
+function types(tokens: FormulaToken[]): string[] {
+  return tokens.map((t) => t.type);
+}
+
+function texts(tokens: FormulaToken[]): string[] {
+  return tokens.map((t) => t.text);
+}
+
+describe("tokenizeFormula", () => {
+  it("tokenizes a simple SUM formula", () => {
+    const tokens = tokenizeFormula("SUM(A1:B10)");
+    expect(texts(tokens)).toEqual(["SUM", "(", "A1:B10", ")"]);
+    expect(types(tokens)).toEqual(["function", "paren", "reference", "paren"]);
+  });
+
+  it("tokenizes IF with string and number", () => {
+    const tokens = tokenizeFormula('IF(A1>5,"Yes",0)');
+    expect(texts(tokens)).toEqual(["IF", "(", "A1", ">", "5", ",", '"Yes"', ",", "0", ")"]);
+    expect(types(tokens)).toEqual([
+      "function", "paren", "reference", "operator", "number",
+      "separator", "string", "separator", "number", "paren",
+    ]);
+  });
+
+  it("tokenizes absolute references", () => {
+    const tokens = tokenizeFormula("$A$1+B$2");
+    expect(texts(tokens)).toEqual(["$A$1", "+", "B$2"]);
+    expect(types(tokens)).toEqual(["reference", "operator", "reference"]);
+  });
+
+  it("tokenizes sheet-qualified references", () => {
+    const tokens = tokenizeFormula("Sheet1!A1+'Other Sheet'!$B$2");
+    expect(texts(tokens)).toEqual(["Sheet1!A1", "+", "'Other Sheet'!$B$2"]);
+    expect(types(tokens)).toEqual(["reference", "operator", "reference"]);
+  });
+
+  it("tokenizes nested functions", () => {
+    const tokens = tokenizeFormula("ROUND(SUM(A1:A10)/COUNT(A1:A10),2)");
+    expect(types(tokens)).toEqual([
+      "function", "paren", "function", "paren", "reference", "paren",
+      "operator", "function", "paren", "reference", "paren",
+      "separator", "number", "paren",
+    ]);
+  });
+
+  it("tokenizes multi-char operators", () => {
+    const tokens = tokenizeFormula("A1<>B1");
+    expect(texts(tokens)).toEqual(["A1", "<>", "B1"]);
+    expect(types(tokens)).toEqual(["reference", "operator", "reference"]);
+  });
+
+  it("tokenizes error values", () => {
+    const tokens = tokenizeFormula("IFERROR(A1/B1,#N/A)");
+    expect(texts(tokens)).toEqual(["IFERROR", "(", "A1", "/", "B1", ",", "#N/A", ")"]);
+    expect(types(tokens)).toEqual([
+      "function", "paren", "reference", "operator", "reference",
+      "separator", "error", "paren",
+    ]);
+  });
+
+  it("preserves whitespace", () => {
+    const tokens = tokenizeFormula("A1 + B1");
+    expect(texts(tokens)).toEqual(["A1", " ", "+", " ", "B1"]);
+    expect(types(tokens)).toEqual(["reference", "plain", "operator", "plain", "reference"]);
+  });
+
+  it("handles empty formula", () => {
+    expect(tokenizeFormula("")).toEqual([]);
+  });
+
+  it("reconstructs original text", () => {
+    const formula = 'IF(AND(A1>=10,$B$2<>""),VLOOKUP(A1,Sheet2!A:B,2,FALSE),"N/A")';
+    const tokens = tokenizeFormula(formula);
+    const reconstructed = tokens.map((t) => t.text).join("");
+    expect(reconstructed).toBe(formula);
+  });
+});

package/src/formula_highlight.ts

@@ -0,0 +1,139 @@
+// =============================================================================
+// Formula Syntax Highlighting — Tokenizer
+// =============================================================================
+//
+// Tokenizes an Excel formula string into typed spans for syntax coloring.
+// Only active when the text starts with "=".
+// =============================================================================
+
+export interface FormulaToken {
+  text: string;
+  type: "function" | "reference" | "number" | "string" | "operator" | "paren" | "separator" | "error" | "plain";
+}
+
+// Cell reference pattern: optional sheet prefix, optional $, column letters, optional $, row digits
+// Matches: A1, $A$1, Sheet1!A1, 'Sheet Name'!$A$1:$B$10
+const REF_PATTERN = /^(?:'[^']*'!|\w+!)?\$?[A-Z]{1,3}\$?\d{1,7}(?::\$?[A-Z]{1,3}\$?\d{1,7})?/;
+
+// Function name: letters/digits/dots/underscores followed by (
+const FUNC_PATTERN = /^[A-Z][A-Z0-9_.]*(?=\()/i;
+
+// Number: integer or decimal, optional scientific notation
+const NUM_PATTERN = /^\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/;
+
+// String literal: "..." (Excel uses "" for escaped quotes inside)
+const STR_PATTERN = /^"(?:[^"]|"")*"/;
+
+// Error values
+const ERROR_PATTERN = /^#(?:REF!|NAME\?|VALUE!|DIV\/0!|NULL!|N\/A|NUM!|CALC!|SPILL!|GETTING_DATA)/;
+
+// Operators
+const OPERATORS = new Set(["+", "-", "*", "/", "^", "&", "=", "<", ">", "%"]);
+const MULTI_OPS = ["<>", "<=", ">="];
+
+/** Tokenize a formula string (without leading "=") into colored spans. */
+export function tokenizeFormula(formula: string): FormulaToken[] {
+  const tokens: FormulaToken[] = [];
+  let i = 0;
+
+  while (i < formula.length) {
+    const rest = formula.slice(i);
+
+    // Whitespace
+    if (rest[0] === " " || rest[0] === "\t") {
+      let j = 0;
+      while (j < rest.length && (rest[j] === " " || rest[j] === "\t")) j++;
+      tokens.push({ text: rest.slice(0, j), type: "plain" });
+      i += j;
+      continue;
+    }
+
+    // String literal
+    const strMatch = rest.match(STR_PATTERN);
+    if (strMatch) {
+      tokens.push({ text: strMatch[0], type: "string" });
+      i += strMatch[0].length;
+      continue;
+    }
+
+    // Error values
+    const errMatch = rest.match(ERROR_PATTERN);
+    if (errMatch) {
+      tokens.push({ text: errMatch[0], type: "error" });
+      i += errMatch[0].length;
+      continue;
+    }
+
+    // Function name (must check before reference since both start with letters)
+    const funcMatch = rest.match(FUNC_PATTERN);
+    if (funcMatch) {
+      tokens.push({ text: funcMatch[0], type: "function" });
+      i += funcMatch[0].length;
+      continue;
+    }
+
+    // Cell/range reference (with optional sheet prefix)
+    const refMatch = rest.match(REF_PATTERN);
+    if (refMatch) {
+      tokens.push({ text: refMatch[0], type: "reference" });
+      i += refMatch[0].length;
+      continue;
+    }
+
+    // Number
+    const numMatch = rest.match(NUM_PATTERN);
+    if (numMatch) {
+      tokens.push({ text: numMatch[0], type: "number" });
+      i += numMatch[0].length;
+      continue;
+    }
+
+    // Multi-character operators (<>, <=, >=)
+    const twoChar = rest.slice(0, 2);
+    if (MULTI_OPS.includes(twoChar)) {
+      tokens.push({ text: twoChar, type: "operator" });
+      i += 2;
+      continue;
+    }
+
+    // Single-character operator
+    if (OPERATORS.has(rest[0])) {
+      tokens.push({ text: rest[0], type: "operator" });
+      i += 1;
+      continue;
+    }
+
+    // Parentheses
+    if (rest[0] === "(" || rest[0] === ")") {
+      tokens.push({ text: rest[0], type: "paren" });
+      i += 1;
+      continue;
+    }
+
+    // Comma / semicolon separator
+    if (rest[0] === "," || rest[0] === ";") {
+      tokens.push({ text: rest[0], type: "separator" });
+      i += 1;
+      continue;
+    }
+
+    // Unrecognized — consume one character as plain
+    tokens.push({ text: rest[0], type: "plain" });
+    i += 1;
+  }
+
+  return tokens;
+}
+
+/** Color map for token types. */
+export const TOKEN_COLORS: Record<FormulaToken["type"], string> = {
+  function: "#0000FF",    // blue
+  reference: "#9C27B0",   // purple
+  number: "#098658",      // green
+  string: "#A31515",      // dark red
+  operator: "#383838",    // dark gray
+  paren: "#383838",       // dark gray
+  separator: "#383838",   // dark gray
+  error: "#E53935",       // red
+  plain: "#1F2937",       // default text
+};