@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/evaluate.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The evaluator.
+ *
+ * Errors travel as VALUES once evaluation finishes, but as thrown
+ * `FormulaError`s while it runs. That split is deliberate: a coercion buried
+ * three calls deep inside a function needs to abort the whole expression, and
+ * threading a result type through every branch of every builtin would swamp the
+ * table. The throw is caught here, at the one boundary, and becomes a value.
+ *
+ * Four functions never reach the table because they must NOT have every
+ * argument evaluated first: IF and IFS pick a branch, IFERROR needs to catch,
+ * and SWITCH matches before evaluating. Evaluating both branches of an IF is
+ * not just wasted work - `=IF(A1=0, 0, 100/A1)` would raise #DIV/0! from the
+ * branch it did not take.
+ */
+import { type CellValue, type Node } from './ast.js';
+import { type SheetFunction } from './functions.js';
+import { type Grid } from './packs/array.js';
+import { type TableRegion } from './tables.js';
+export type EvalContext = {
+    /** Read one cell. Out of bounds should return `{ error: '#REF!' }`. */
+    resolve(sheet: string | null, row: number, col: number): CellValue;
+    /** Last used row of a sheet, for open-ended whole-column ranges. */
+    lastRow(sheet: string | null): number;
+    /**
+     * The rectangle a dynamic array anchored at (row, col) currently spills
+     * into, as `[r1, c1, r2, c2]`, or null when that cell is not a spill
+     * anchor. Backs the spilled-range operator `A1#`: without it the operator
+     * reads #REF!, since only the workbook knows how far an array spilled.
+     */
+    spillRect?(sheet: string | null, row: number, col: number): readonly [number, number, number, number] | null;
+    /**
+     * The sheets from `from` to `to` in tab order, inclusive, or null when
+     * either name is unknown. Backs a 3D reference (`Sheet1:Sheet3!A1`), which
+     * reads its cell on each of them.
+     */
+    sheetsBetween?(from: string, to: string): string[] | null;
+    /**
+     * Resolve a defined name to the reference it stands for, or null when
+     * there is no such name. The node is evaluated in place of the name, so a
+     * name that refers to a range behaves as that range: `=SUM(Sales)` adds
+     * the whole column and `=VLOOKUP(x, Prices, 2)` searches the whole table.
+     * Preferred over `resolveName`, which can only ever produce one value.
+     */
+    resolveNameNode?(name: string): Node | null;
+    /** Resolve a defined name to a single value. Consulted when
+     *  `resolveNameNode` is absent or returns null; undefined is #NAME?. */
+    resolveName?(name: string): CellValue | undefined;
+    functions?: Record<string, SheetFunction>;
+    /** Look a table up by name. */
+    findTable?(name: string): TableRegion | undefined;
+    /** The table containing the cell the formula lives in, which is the only
+     *  way the unqualified `[@Amount]` form can mean anything. */
+    tableAt?(sheet: string | null, row: number, col: number): TableRegion | undefined;
+    /** Where the formula being evaluated sits. Needed for `[@Column]`, which
+     *  is relative to the formula rather than to the table. */
+    currentCell?: {
+        sheet: string | null;
+        row: number;
+        col: number;
+    };
+    /**
+     * Whether a row is folded away, and by what: `'filter'` for an AutoFilter,
+     * `'hand'` for Hide Rows, null for a row on the screen. Only `SUBTOTAL`
+     * asks, and it is what tells its 1-11 codes from its 101-111 ones. A
+     * consumer that hides nothing leaves this out.
+     */
+    hiddenRow?(sheet: string | null, row: number): 'filter' | 'hand' | null;
+    /**
+     * Whether a cell holds a `SUBTOTAL` of its own. Excel's SUBTOTAL skips
+     * those, so a grand total over a column of subtotals counts each row once
+     * rather than twice.
+     */
+    isSubtotal?(sheet: string | null, row: number, col: number): boolean;
+    /**
+     * Names bound INSIDE the formula, by `LET` or by a lambda's parameters.
+     * Looked up before the workbook's own names, which is what makes
+     * `=LET(x, 2, x * 3)` mean 6 on a sheet that also has a name `x`.
+     * Copied rather than chained: a scope holds a handful of names, and a
+     * flat map is faster to read than a chain is to walk.
+     */
+    locals?: ReadonlyMap<string, LocalBinding>;
+};
+/** A lambda, closed over the scope it was written in. */
+export type Lambda = {
+    readonly lambda: true;
+    params: string[];
+    body: Node;
+    scope: ReadonlyMap<string, LocalBinding> | undefined;
+};
+/** What a name bound inside a formula can hold: a value, a grid, a lambda. */
+export type LocalBinding = CellValue | Grid | Lambda;
+/**
+ * Turn a structured reference into a rectangle and read it.
+ *
+ * Every failure here is #REF! rather than a throw, because a table reference
+ * naming a column that was renamed is an ordinary thing to find in a sheet,
+ * and one broken total should not take the rest of the workbook with it.
+ */
+export declare function tableRectOf(node: Extract<Node, {
+    k: 'table';
+}>, ctx: EvalContext): {
+    sheet: string;
+    firstRow: number;
+    lastRow: number;
+    firstCol: number;
+    lastCol: number;
+} | null;
+/**
+ * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
+ * inside becomes the matching error value.
+ */
+/**
+ * The values a node stands for as a grid: a range, a reference (one cell),
+ * or a name that refers to either. Null for anything else, which is how a
+ * caller tells "a list source that is a range" from "a formula".
+ */
+export declare function rangeValues(node: Node, ctx: EvalContext): CellValue[][] | null;
+/**
+ * The grid a formula spills, or null when it is a plain value: a range on
+ * its own (`=A1:A5`), a name that refers to one, a reference function's
+ * rectangle, or an array function's answer, when that is more than one
+ * cell. A throw inside is the error the cell shows, and no spill.
+ */
+export declare function evaluateSpill(node: Node, ctx: EvalContext): Grid | null;
+export declare function evaluate(node: Node, ctx: EvalContext): CellValue;
+/** Render a computed value the way a cell shows it. */
+export declare function formatValue(v: CellValue): string;