/** * Framework-agnostic spreadsheet model that ties the engine modules together. * * The addressable unit is a **table** (a table object on a Numbers-style * canvas). A `Workbook` owns a flat list of tables and, across all of them: * - the raw text of every non-empty cell, * - the parsed AST of every formula cell (or an `#ERR` marker), * - the computed value of every cell, * - the document-wide {@link DependencyGraph}. * * It implements {@link EngineHost} so the evaluator can read neighbouring cell * values through it. The Vue store wraps an instance of this class in `reactive` * and mirrors its computed values into a reactive map, which makes every formula * cell behave like a `computed` value in the UI. * * Recalculation is incremental: `setCell` reparses one cell, updates its graph * edges and recomputes only the affected sub-graph in topological order. * Structural edits (rename / delete table, add rows, ...) call `rebuild()` for a * full, still-cheap pass. */ import { DependencyGraph } from './graph'; import { collectRefs, parseFormula, type Node } from './parser'; import { expandRange } from './refs'; import { FormulaError, isError, keyOf, parseKey, type CellValue, type EngineHost, } from './types'; import { evaluate } from './evaluator'; export interface TableModel { id: string; /** document-unique table name, used as the qualifier in formulas */ name: string; cols: number; rows: number; /** key `${col},${row}` -> raw user input. Absent = empty cell. */ inputs: Map; } const NUMBER_RE = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/; function localKey(col: number, row: number): string { return `${col},${row}`; } /** Interpret a raw literal (non-formula) cell input. */ export function literalValue(raw: string): CellValue { const t = raw.trim(); if (t === '') return null; if (NUMBER_RE.test(t)) return Number(t); return raw; } export class Workbook implements EngineHost { tables: TableModel[]; /** transiently set to the home table while a formula is being evaluated */ homeTableId = ''; private readonly graph = new DependencyGraph(); /** cellKey -> parsed formula AST, or an error marker for un-parsable input */ private readonly asts = new Map(); /** cellKey -> computed value */ private readonly values = new Map(); constructor(tables: TableModel[]) { this.tables = tables; this.rebuild(); } // ---- EngineHost --------------------------------------------------------- resolveTableName(name: string): string | null { const needle = name.trim().toLowerCase(); const hit = this.tables.find((t) => t.name.trim().toLowerCase() === needle); return hit ? hit.id : null; } tableSize(tableId: string): { cols: number; rows: number } | null { const t = this.tableById(tableId); return t ? { cols: t.cols, rows: t.rows } : null; } getComputed(tableId: string, col: number, row: number): CellValue { if (col < 0 || row < 0) return new FormulaError('#REF'); const v = this.values.get(keyOf(tableId, col, row)); return v === undefined ? null : v; } // ---- reads ------------------------------------------------------------ tableById(id: string): TableModel | undefined { return this.tables.find((t) => t.id === id); } getInput(tableId: string, col: number, row: number): string { return this.tableById(tableId)?.inputs.get(localKey(col, row)) ?? ''; } /** Public computed-value read used by the store / UI. */ cellValue(tableId: string, col: number, row: number): CellValue { const v = this.values.get(keyOf(tableId, col, row)); return v === undefined ? null : v; } // ---- writes --------------------------------------------------------- /** Set (or clear, with `''`) one cell and recalculate the affected cells. */ setCell(tableId: string, col: number, row: number, raw: string): void { const table = this.tableById(tableId); if (!table) return; const lk = localKey(col, row); if (raw === '') table.inputs.delete(lk); else table.inputs.set(lk, raw); const key = keyOf(tableId, col, row); this.parseCell(key, tableId, raw); this.recalc([key]); } /** Reparse every formula, rebuild the graph, recompute everything. */ rebuild(): void { this.graph.reset(); this.asts.clear(); const all: string[] = []; for (const table of this.tables) { for (const [lk, raw] of table.inputs) { const [c, r] = lk.split(',').map(Number); const key = keyOf(table.id, c, r); all.push(key); this.parseCell(key, table.id, raw); } } this.recalcAll(all); } // ---- internals ------------------------------------------------------ /** Parse one cell's raw input and (re)wire its graph edges. */ private parseCell(key: string, tableId: string, raw: string): void { if (!raw.startsWith('=')) { this.asts.delete(key); this.graph.clear(key); return; } let ast: Node; try { ast = parseFormula(raw); } catch (e) { // a bad formula is a cell-level error, never a crash this.asts.set(key, new FormulaError('#ERR', (e as Error).message)); this.graph.setPrecedents(key, []); return; } this.asts.set(key, ast); this.graph.setPrecedents(key, this.precedentsOf(ast, tableId)); } /** Resolve every reference in `ast` to concrete cell keys (home = tableId). */ private precedentsOf(ast: Node, tableId: string): string[] { const out: string[] = []; for (const ref of collectRefs(ast)) { const target = ref.qualifier == null ? tableId : this.resolveTableName(ref.qualifier); if (!target) continue; // unknown table -> no edge; evaluator emits #REF if (ref.kind === 'cell') { out.push(keyOf(target, ref.col, ref.row)); } else { for (const c of expandRange(ref.start, ref.end)) { out.push(keyOf(target, c.col, c.row)); } } } return out; } /** Incremental recalculation starting from `dirty`. */ private recalc(dirty: string[]): void { this.evaluateSet(this.graph.affected(dirty)); } /** Full recalculation of the given (complete) cell set. */ private recalcAll(all: string[]): void { this.values.clear(); this.evaluateSet(new Set(all)); } private evaluateSet(affected: Set): void { const { order, circular } = this.graph.topoOrder(affected); for (const key of circular) this.values.set(key, new FormulaError('#CIRC')); for (const key of order) this.values.set(key, this.evaluateCell(key)); } private evaluateCell(key: string): CellValue { const ast = this.asts.get(key); if (ast === undefined) { const { tableId, col, row } = parseKey(key); return literalValue(this.getInput(tableId, col, row)); } if (isError(ast)) return ast; this.homeTableId = parseKey(key).tableId; try { return evaluate(ast, this); } catch { return new FormulaError('#ERR', 'evaluation failed'); } } /** Recompute order for a hand-picked dirty set -- exposed for tests. */ debugOrder(dirty: string[]): { order: string[]; circular: string[] } { const { order, circular } = this.graph.topoOrder(this.graph.affected(dirty)); return { order, circular: [...circular] }; } }