@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/evaluate.js

@@ -16,7 +16,25 @@
 import { FormulaError, isError, err, } from './ast.js';
 import { toNumber, toBool, toText, looseEquals, compare } from './coerce.js';
 import { withCustomFunctions } from './functions.js';
+import { ARRAY_FUNCTIONS } from './packs/array.js';
+import { colToLetters } from './address.js';
+import { parseFormula } from './parse.js';
 import { resolveTableRange, columnIndexOf, } from './tables.js';
+const isLambda = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && 'lambda' in v;
+const isGrid = (v) => Array.isArray(v);
+/** The names a lambda helper takes its function in. */
+const LAMBDA_HELPERS = new Set(['MAP', 'BYROW', 'BYCOL', 'REDUCE', 'SCAN', 'MAKEARRAY']);
+/** A local binding, by name, case-insensitively as Excel reads a name. */
+function localOf(ctx, name) {
+    return ctx.locals?.get(name.toUpperCase());
+}
+/** The same context with more names bound over it. */
+function withLocals(ctx, added) {
+    const next = new Map(ctx.locals ?? []);
+    for (const [name, value] of added)
+        next.set(name.toUpperCase(), value);
+    return { ...ctx, locals: next };
+}
 function rangeGrid(from, to, ctx) {
     const sheet = from.sheet ?? to.sheet;
     const r1 = Math.min(from.row ?? 0, to.row ?? from.row ?? 0);
@@ -56,12 +74,159 @@ function binary(op, l, r) {
 }
 /** Functions handled before the table, because their arguments must not all
  *  be evaluated up front. */
-const SHORT_CIRCUIT = new Set(['IF', 'IFS', 'IFERROR', 'IFNA', 'SWITCH']);
+const SHORT_CIRCUIT = new Set(['IF', 'IFS', 'IFERROR', 'IFNA', 'SWITCH', 'ISERROR', 'ISERR', 'ISNA']);
+/** Functions that PRODUCE a reference rather than a value. In scalar position
+ *  they read as their top-left cell, as a range does; as an argument they
+ *  expand to the range, so =SUM(OFFSET(A1,0,0,3,1)) adds three cells. */
+const REFERENCE_FUNCTIONS = new Set(['OFFSET', 'INDIRECT']);
+/**
+ * The rectangle a node stands for: a cell, a range (open-ended ones closed
+ * at the last used row), a name that refers to one, or a reference
+ * function's result. Null for anything that is a plain value.
+ */
+function referenceOf(node, ctx) {
+    switch (node.k) {
+        case 'ref':
+            return { sheet: node.ref.sheet, r1: node.ref.row ?? 0, c1: node.ref.col, r2: node.ref.row ?? 0, c2: node.ref.col };
+        case 'range': {
+            const sheet = node.from.sheet ?? node.to.sheet;
+            const r1 = Math.min(node.from.row ?? 0, node.to.row ?? node.from.row ?? 0);
+            const r2 = node.to.row === null || node.from.row === null ? ctx.lastRow(sheet) : Math.max(node.from.row, node.to.row);
+            return { sheet, r1, c1: Math.min(node.from.col, node.to.col), r2, c2: Math.max(node.from.col, node.to.col) };
+        }
+        case 'name': {
+            const target = nameTarget(node.name, ctx);
+            return target ? referenceOf(target, ctx) : null;
+        }
+        case 'fn':
+            return REFERENCE_FUNCTIONS.has(node.name) ? referenceCall(node, ctx) : null;
+        case 'table': {
+            // A structured reference is a rectangle too, so SUBTOTAL(109,[Qty])
+            // in a totals row skips the rows a filter folds, as Excel's does,
+            // rather than reading the column's first cell as a scalar.
+            const rect = tableRectOf(node, ctx);
+            return rect ? { sheet: rect.sheet, r1: rect.firstRow, c1: rect.firstCol, r2: rect.lastRow, c2: rect.lastCol } : null;
+        }
+        case 'spill':
+            return spillRectOf(node, ctx);
+        default:
+            return null;
+    }
+}
+/**
+ * The rectangle a spilled-range operator (`A1#`) stands for: the array the
+ * anchor currently spills. Null when the cell is not a spill anchor, which
+ * the callers turn into #REF!, the way Excel does for `A1#` on a cell that
+ * holds no dynamic array.
+ */
+function spillRectOf(node, ctx) {
+    const rect = ctx.spillRect?.(node.ref.sheet, node.ref.row ?? 0, node.ref.col);
+    return rect ? { sheet: node.ref.sheet, r1: rect[0], c1: rect[1], r2: rect[2], c2: rect[3] } : null;
+}
+/**
+ * Every value a 3D reference reads: the cell or rectangle on each sheet in
+ * the tab range, in sheet order. Null when a sheet name is unknown, which the
+ * callers turn into #REF!. Aggregates take the flat list, so a nested
+ * rectangle spans sheet by sheet.
+ */
+function values3d(node, ctx) {
+    const sheets = ctx.sheetsBetween?.(node.sheetFrom, node.sheetTo);
+    if (!sheets)
+        return null;
+    const r1 = Math.min(node.from.row ?? 0, node.to.row ?? 0);
+    const r2 = Math.max(node.from.row ?? 0, node.to.row ?? 0);
+    const c1 = Math.min(node.from.col, node.to.col);
+    const c2 = Math.max(node.from.col, node.to.col);
+    const out = [];
+    for (const s of sheets) {
+        for (let r = r1; r <= r2; r += 1) {
+            for (let c = c1; c <= c2; c += 1)
+                out.push(ctx.resolve(s, r, c));
+        }
+    }
+    return out;
+}
+function rectGrid(rect, ctx) {
+    return rangeGrid({ sheet: rect.sheet, row: rect.r1, col: rect.c1, rowAbs: false, colAbs: false }, { sheet: rect.sheet, row: rect.r2, col: rect.c2, rowAbs: false, colAbs: false }, ctx);
+}
+const scalarArg = (node, ctx) => (node ? evalNode(node, ctx) : '');
+const optNumber = (node, ctx, fallback) => {
+    if (!node || node.k === 'empty')
+        return fallback;
+    const v = evalNode(node, ctx);
+    if (isError(v))
+        throw new FormulaError(v.error);
+    return v === '' ? fallback : toNumber(v);
+};
+/** OFFSET and INDIRECT: the rectangle they name, or a throw for the error. */
+function referenceCall(node, ctx) {
+    const { name, args } = node;
+    if (name === 'INDIRECT') {
+        const text = scalarArg(args[0], ctx);
+        if (isError(text))
+            throw new FormulaError(text.error);
+        const a1 = args[1] && args[1].k !== 'empty' ? toBool(evalNode(args[1], ctx)) : true;
+        if (!a1)
+            throw new FormulaError('#REF!');
+        let parsed;
+        try {
+            parsed = parseFormula(`=${toText(text).trim()}`);
+        }
+        catch {
+            throw new FormulaError('#REF!');
+        }
+        const rect = parsed.k === 'ref' || parsed.k === 'range' || parsed.k === 'name' ? referenceOf(parsed, ctx) : null;
+        if (!rect)
+            throw new FormulaError('#REF!');
+        return rect;
+    }
+    // OFFSET(reference, rows, cols, [height], [width])
+    const base = args[0] ? referenceOf(args[0], ctx) : null;
+    if (!base)
+        throw new FormulaError('#VALUE!');
+    const rows = Math.trunc(optNumber(args[1], ctx, 0));
+    const cols = Math.trunc(optNumber(args[2], ctx, 0));
+    const height = Math.trunc(optNumber(args[3], ctx, base.r2 - base.r1 + 1));
+    const width = Math.trunc(optNumber(args[4], ctx, base.c2 - base.c1 + 1));
+    if (height <= 0 || width <= 0)
+        throw new FormulaError('#REF!');
+    const r1 = base.r1 + rows;
+    const c1 = base.c1 + cols;
+    if (r1 < 0 || c1 < 0)
+        throw new FormulaError('#REF!');
+    return { sheet: base.sheet, r1, c1, r2: r1 + height - 1, c2: c1 + width - 1 };
+}
+/** ROW, COLUMN and ADDRESS: about a reference, not its value. */
+function positionCall(node, ctx) {
+    const { name, args } = node;
+    if (name === 'ADDRESS') {
+        const row = Math.trunc(toNumber(scalarArg(args[0], ctx)));
+        const col = Math.trunc(toNumber(scalarArg(args[1], ctx)));
+        const abs = Math.trunc(optNumber(args[2], ctx, 1));
+        if (row < 1 || col < 1 || abs < 1 || abs > 4)
+            return err('#VALUE!');
+        const sheet = args[4] && args[4].k !== 'empty' ? toText(scalarArg(args[4], ctx)) : '';
+        const rowText = `${abs === 1 || abs === 2 ? '$' : ''}${row}`;
+        const colText = `${abs === 1 || abs === 3 ? '$' : ''}${colToLetters(col - 1)}`;
+        const prefix = sheet ? (/^[A-Za-z_][A-Za-z0-9_]*$/.test(sheet) ? `${sheet}!` : `'${sheet.replace(/'/g, "''")}'!`) : '';
+        return `${prefix}${colText}${rowText}`;
+    }
+    const target = args[0] && args[0].k !== 'empty' ? referenceOf(args[0], ctx) : null;
+    if (!target) {
+        const here = ctx.currentCell;
+        if (!here)
+            return err('#VALUE!');
+        return name === 'ROW' ? here.row + 1 : here.col + 1;
+    }
+    return name === 'ROW' ? target.r1 + 1 : target.c1 + 1;
+}
 function evalNode(node, ctx) {
     switch (node.k) {
         case 'num': return node.v;
         case 'str': return node.v;
         case 'bool': return node.v;
+        case 'err': return err(node.v);
+        case 'empty': return '';
         case 'ref':
             return ctx.resolve(node.ref.sheet, node.ref.row ?? 0, node.ref.col);
         case 'range': {
@@ -70,7 +235,33 @@ function evalNode(node, ctx) {
             const grid = rangeGrid(node.from, node.to, ctx);
             return grid[0]?.[0] ?? '';
         }
+        case 'spill': {
+            // The spilled range in scalar position is its top-left, the anchor's
+            // own value; a cell that anchors no array is #REF!.
+            const rect = spillRectOf(node, ctx);
+            return rect ? ctx.resolve(rect.sheet, rect.r1, rect.c1) : err('#REF!');
+        }
+        case 'ref3d': {
+            // In scalar position a 3D reference reads the cell on the first sheet
+            // of the range, the way an ordinary range collapses to its top-left.
+            const vals = values3d(node, ctx);
+            if (!vals)
+                return err('#REF!');
+            return vals[0] ?? '';
+        }
         case 'name': {
+            // A name bound inside the formula wins over the workbook's own, which
+            // is what makes `=LET(x, 2, x * 3)` mean 6 on a sheet that has an `x`.
+            const local = localOf(ctx, node.name);
+            if (local !== undefined) {
+                // A lambda that is never called is #CALC!, as Excel shows it; a
+                // grid in scalar position reads as its top-left cell.
+                if (isLambda(local))
+                    return err('#CALC!');
+                if (isGrid(local))
+                    return local[0]?.[0] ?? '';
+                return local;
+            }
             const target = nameTarget(node.name, ctx);
             if (target)
                 return evalNode(target, ctx);
@@ -109,7 +300,7 @@ function evalNode(node, ctx) {
  * 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.
  */
-function tableRectOf(node, ctx) {
+export function tableRectOf(node, ctx) {
     const here = ctx.currentCell;
     const table = node.table
         ? ctx.findTable?.(node.table)
@@ -175,6 +366,64 @@ function nameTarget(name, ctx) {
     return node;
 }
 /** Functions whose arguments must not all be evaluated up front. */
+/**
+ * `SUBTOTAL(code, ref1, ...)`: the aggregate Excel's AutoFilter is built on.
+ *
+ * The code names the function - 1 AVERAGE, 2 COUNT, 3 COUNTA, 4 MAX, 5 MIN,
+ * 6 PRODUCT, 7 STDEV, 8 STDEVP, 9 SUM, 10 VAR, 11 VARP - and a hundred more
+ * means "and leave out the rows hidden by hand as well". A filtered-out row
+ * is left out either way, which is what makes a total under a filtered list
+ * follow the filter, and why a table's totals row is written with this
+ * rather than with SUM. A cell holding a SUBTOTAL of its own is skipped, so
+ * a grand total over subtotals counts each row once.
+ */
+const SUBTOTAL_FUNCTIONS = {
+    1: 'AVERAGE', 2: 'COUNT', 3: 'COUNTA', 4: 'MAX', 5: 'MIN', 6: 'PRODUCT',
+    7: 'STDEV', 8: 'STDEVP', 9: 'SUM', 10: 'VAR', 11: 'VARP',
+};
+function subtotalCall(node, ctx) {
+    const first = node.args[0];
+    if (!first)
+        return err('#VALUE!');
+    const codeValue = evalNode(first, ctx);
+    if (isError(codeValue))
+        return codeValue;
+    const code = Math.trunc(toNumber(codeValue));
+    const ignoreHandHidden = code > 100;
+    const fnName = SUBTOTAL_FUNCTIONS[ignoreHandHidden ? code - 100 : code];
+    if (!fnName)
+        return err('#VALUE!');
+    const table = ctx.functions ?? withCustomFunctions(undefined);
+    const fn = table[fnName];
+    if (!fn)
+        return err('#NAME?');
+    const perArg = [];
+    for (const arg of node.args.slice(1)) {
+        const rect = referenceOf(arg, ctx);
+        if (!rect) {
+            // A plain value or an expression: nothing is hidden about it.
+            perArg.push([evalNode(arg, ctx)]);
+            continue;
+        }
+        const values = [];
+        for (let r = rect.r1; r <= rect.r2; r += 1) {
+            const how = ctx.hiddenRow?.(rect.sheet, r) ?? null;
+            if (how === 'filter' || (how === 'hand' && ignoreHandHidden))
+                continue;
+            for (let c = rect.c1; c <= rect.c2; c += 1) {
+                if (ctx.isSubtotal?.(rect.sheet, r, c))
+                    continue;
+                values.push(ctx.resolve(rect.sheet, r, c));
+            }
+        }
+        perArg.push(values);
+    }
+    const flat = perArg.flat();
+    for (const v of flat)
+        if (isError(v))
+            return v;
+    return fn({ flat, args: perArg, grids: perArg.map(() => null) });
+}
 function evalCall(node, ctx) {
     const { name, args } = node;
     // Every short-circuiting function below indexes its arguments directly.
@@ -182,6 +431,26 @@ function evalCall(node, ctx) {
     // TypeError escapes the boundary this module promises never to throw past.
     if (SHORT_CIRCUIT.has(name) && args.length === 0)
         return err('#VALUE!');
+    // LET, LAMBDA and the helpers that take one see the AST rather than
+    // evaluated arguments: a lambda IS its body, and a name bound by LET has
+    // to exist before the expression that reads it is evaluated.
+    if (name === 'LET')
+        return evalLet(args, ctx);
+    // The call the parser builds for `LAMBDA(x, x * 2)(5)`: the callee first,
+    // then the arguments it is called with.
+    if (name === '(')
+        return scalarOf(bindingOf(node, ctx));
+    if (name === 'LAMBDA')
+        return err('#CALC!');
+    if (LAMBDA_HELPERS.has(name)) {
+        const grid = lambdaCall(node, ctx);
+        return Array.isArray(grid) ? grid[0]?.[0] ?? '' : grid;
+    }
+    // `=LET(double, LAMBDA(x, x * 2), double(21))`: a call on a name the
+    // formula bound rather than on a function the library ships.
+    const bound = localOf(ctx, name);
+    if (isLambda(bound))
+        return applyLambda(bound, args.map((a) => bindingOf(a, ctx)), ctx);
     if (name === 'IF') {
         const cond = evalNode(args[0], ctx);
         if (isError(cond))
@@ -191,6 +460,26 @@ function evalCall(node, ctx) {
             return toBool(cond);
         return evalNode(branch, ctx);
     }
+    if (name === 'ISERROR' || name === 'ISERR' || name === 'ISNA') {
+        let code = null;
+        try {
+            const v = evalNode(args[0], ctx);
+            if (isError(v))
+                code = v.error;
+        }
+        catch (e) {
+            if (!(e instanceof FormulaError))
+                throw e;
+            code = e.code;
+        }
+        if (code === null)
+            return false;
+        if (name === 'ISNA')
+            return code === '#N/A';
+        if (name === 'ISERR')
+            return code !== '#N/A';
+        return true;
+    }
     if (name === 'IFERROR' || name === 'IFNA') {
         try {
             const v = evalNode(args[0], ctx);
@@ -232,14 +521,335 @@ function evalCall(node, ctx) {
         // A trailing odd argument is the default.
         return i < args.length ? evalNode(args[i], ctx) : err('#N/A');
     }
+    if (name === 'SUBTOTAL')
+        return subtotalCall(node, ctx);
+    if (name === 'ROW' || name === 'COLUMN' || name === 'ADDRESS')
+        return positionCall(node, ctx);
+    if (REFERENCE_FUNCTIONS.has(name)) {
+        // In scalar position a reference collapses to its top-left cell.
+        const rect = referenceCall(node, ctx);
+        return ctx.resolve(rect.sheet, rect.r1, rect.c1);
+    }
+    if (ARRAY_FUNCTIONS[name]) {
+        // In scalar position a grid reads as its top-left cell; the workbook
+        // asks `evaluateSpill` for the whole of it.
+        const grid = arrayCall(node, ctx);
+        return Array.isArray(grid) ? grid[0]?.[0] ?? '' : grid;
+    }
     const table = ctx.functions ?? withCustomFunctions(undefined);
     const fn = table[name];
     if (!fn)
         return err('#NAME?');
-    // Evaluate every argument, keeping range shape for the lookups that need it.
+    const { perArg, grids } = collectArgs(args, ctx);
+    const flat = perArg.flat();
+    // An error anywhere in the arguments propagates, except for the counting
+    // functions, which Excel lets see errors in their range, and TYPE, whose
+    // whole job is to report that an error IS one (it answers 16).
+    if (name !== 'COUNTA' && name !== 'COUNTBLANK' && name !== 'TYPE') {
+        for (const v of flat)
+            if (isError(v))
+                return v;
+    }
+    const payload = { flat, args: perArg, grids };
+    return fn(payload);
+}
+/**
+ * `LET(name1, value1, [name2, value2, ...], calculation)`.
+ *
+ * Each value is evaluated in the scope built so far, so a later binding can
+ * read an earlier one, and the calculation sees them all. A binding holds a
+ * GRID where its expression is one, which is what lets `LET(r, A1:A9,
+ * SUM(r))` add the range rather than its first cell.
+ */
+function evalLet(args, ctx) {
+    if (args.length < 3 || args.length % 2 === 0)
+        return err('#VALUE!');
+    let scope = ctx;
+    for (let i = 0; i + 1 < args.length - 1; i += 2) {
+        const nameNode = args[i];
+        if (nameNode.k !== 'name')
+            return err('#VALUE!');
+        scope = withLocals(scope, [[nameNode.name, bindingOf(args[i + 1], scope)]]);
+    }
+    const result = bindingOf(args[args.length - 1], scope);
+    if (isLambda(result))
+        return err('#CALC!');
+    if (isGrid(result))
+        return result[0]?.[0] ?? '';
+    return result;
+}
+/** The grid a LET's calculation stands for, or null when it is one value. */
+function letGrid(args, ctx) {
+    if (args.length < 3 || args.length % 2 === 0)
+        return null;
+    let scope = ctx;
+    for (let i = 0; i + 1 < args.length - 1; i += 2) {
+        const nameNode = args[i];
+        if (nameNode.k !== 'name')
+            return null;
+        scope = withLocals(scope, [[nameNode.name, bindingOf(args[i + 1], scope)]]);
+    }
+    const result = bindingOf(args[args.length - 1], scope);
+    return isGrid(result) ? result : null;
+}
+/** What a name is bound to: a lambda, a grid, or a plain value. */
+function bindingOf(node, ctx) {
+    if (node.k === 'fn' && node.name === 'LAMBDA')
+        return lambdaOf(node, ctx);
+    if (node.k === 'fn' && node.name === '(') {
+        const fn = lambdaArg(node.args[0], ctx);
+        if (!fn)
+            return err('#VALUE!');
+        return callLambda(fn, node.args.slice(1).map((a) => bindingOf(a, ctx)), ctx);
+    }
+    if (node.k === 'fn') {
+        const bound = localOf(ctx, node.name);
+        if (isLambda(bound))
+            return callLambda(bound, node.args.map((a) => bindingOf(a, ctx)), ctx);
+    }
+    if (node.k === 'name') {
+        const local = localOf(ctx, node.name);
+        if (local !== undefined)
+            return local;
+    }
+    // Arithmetic over ranges is a grid too, cell by cell: `B2:B6 * D2:D6` is
+    // what a REDUCE or a BYROW is usually handed.
+    if ((node.k === 'binary' || node.k === 'unary') && hasArray(node, ctx))
+        return gridOf(node, ctx);
+    const grid = hasArray(node, ctx) ? rangeValues(node, ctx) : null;
+    if (grid && (grid.length > 1 || (grid[0]?.length ?? 0) > 1))
+        return grid;
+    return evalNode(node, ctx);
+}
+/** The lambda a `LAMBDA(p1, ..., body)` node stands for, closed over `ctx`. */
+function lambdaOf(node, ctx) {
+    const args = node.args;
+    if (args.length < 1)
+        return err('#VALUE!');
+    const params = [];
+    for (let i = 0; i < args.length - 1; i += 1) {
+        const p = args[i];
+        if (p.k !== 'name')
+            return err('#VALUE!');
+        params.push(p.name);
+    }
+    return { lambda: true, params, body: args[args.length - 1], scope: ctx.locals };
+}
+/**
+ * Call a lambda, keeping whatever it answers with: a value, a grid, or
+ * another lambda, which is what a curried `LAMBDA(x, LAMBDA(y, x + y))`
+ * gives back.
+ */
+function callLambda(fn, values, ctx) {
+    // Excel is strict about the count: too few is #VALUE!, and so is too many.
+    if (values.length !== fn.params.length)
+        return err('#VALUE!');
+    const scope = withLocals({ ...ctx, locals: fn.scope }, fn.params.map((p, i) => [p, values[i]]));
+    return bindingOf(fn.body, scope);
+}
+/** The same, in a place that wants one value. */
+function applyLambda(fn, values, ctx) {
+    return scalarOf(callLambda(fn, values, ctx));
+}
+/** A binding where one value is wanted: a lambda is #CALC!, a grid its corner. */
+function scalarOf(binding) {
+    if (isLambda(binding))
+        return err('#CALC!');
+    if (isGrid(binding))
+        return binding[0]?.[0] ?? '';
+    return binding;
+}
+/** The lambda an argument names: written there, or bound to a name. */
+function lambdaArg(node, ctx) {
+    if (!node)
+        return null;
+    if (node.k === 'fn' && node.name === 'LAMBDA') {
+        const made = lambdaOf(node, ctx);
+        return isLambda(made) ? made : null;
+    }
+    if (node.k === 'name') {
+        const local = localOf(ctx, node.name);
+        if (isLambda(local))
+            return local;
+        return null;
+    }
+    // A call that answers with another lambda: `LAMBDA(x, LAMBDA(y, x + y))(2)`.
+    if (node.k === 'fn' && (node.name === '(' || isLambda(localOf(ctx, node.name)))) {
+        const made = bindingOf(node, ctx);
+        return isLambda(made) ? made : null;
+    }
+    return null;
+}
+/** An argument as a grid, one cell wide where it is a plain value. */
+function gridArgOf(node, ctx) {
+    if (!node)
+        return [['']];
+    const binding = bindingOf(node, ctx);
+    if (isGrid(binding))
+        return binding;
+    if (isLambda(binding))
+        return [[err('#CALC!')]];
+    return [[binding]];
+}
+/**
+ * Excel's lambda helpers, which is where a lambda earns its keep:
+ *
+ *   MAP(array, ..., fn)        every cell through the function
+ *   BYROW(array, fn)           one answer per row, as a column
+ *   BYCOL(array, fn)           one answer per column, as a row
+ *   REDUCE(init, array, fn)    folded to one value, accumulator first
+ *   SCAN(init, array, fn)      the same, keeping every step
+ *   MAKEARRAY(rows, cols, fn)  built from the row and column numbers
+ */
+function lambdaCall(node, ctx) {
+    const { name, args } = node;
+    const fn = lambdaArg(args[args.length - 1], ctx);
+    if (!fn)
+        return err('#VALUE!');
+    if (name === 'MAKEARRAY') {
+        const rows = Math.trunc(toNumber(evalNode(args[0] ?? { k: 'num', v: 0 }, ctx)));
+        const cols = Math.trunc(toNumber(evalNode(args[1] ?? { k: 'num', v: 0 }, ctx)));
+        if (!(rows > 0) || !(cols > 0))
+            return err('#VALUE!');
+        if (rows * cols > 1000000)
+            return err('#NUM!');
+        return Array.from({ length: rows }, (_, r) => Array.from({ length: cols }, (_, c) => applyLambda(fn, [r + 1, c + 1], ctx)));
+    }
+    if (name === 'MAP') {
+        const grids = args.slice(0, -1).map((a) => gridArgOf(a, ctx));
+        if (!grids.length)
+            return err('#VALUE!');
+        const rows = grids[0].length;
+        const cols = grids[0][0]?.length ?? 0;
+        // Every array has to be the same shape, as Excel asks.
+        for (const g of grids)
+            if (g.length !== rows || (g[0]?.length ?? 0) !== cols)
+                return err('#VALUE!');
+        return Array.from({ length: rows }, (_, r) => Array.from({ length: cols }, (_, c) => applyLambda(fn, grids.map((g) => g[r]?.[c] ?? ''), ctx)));
+    }
+    if (name === 'BYROW' || name === 'BYCOL') {
+        const grid = gridArgOf(args[0], ctx);
+        if (name === 'BYROW') {
+            // Each row goes in as a grid one row tall, and the answers come back
+            // as a column, which is the shape Excel spills.
+            return grid.map((row) => [applyLambda(fn, [[row]], ctx)]);
+        }
+        // Each column goes in as a grid one column wide, answers along a row.
+        return [transposeGrid(grid).map((col) => applyLambda(fn, [col.map((v) => [v])], ctx))];
+    }
+    // REDUCE and SCAN: the accumulator, then each cell in reading order.
+    const grid = gridArgOf(args[1], ctx);
+    let acc = args[0] ? evalNode(args[0], ctx) : '';
+    const steps = [];
+    for (const row of grid) {
+        const line = [];
+        for (const cell of row) {
+            acc = applyLambda(fn, [acc, cell], ctx);
+            line.push(acc);
+        }
+        steps.push(line);
+    }
+    return name === 'SCAN' ? steps : acc;
+}
+/** A grid with its rows and columns swapped. */
+function transposeGrid(grid) {
+    const cols = grid.reduce((m, row) => Math.max(m, row.length), 0);
+    return Array.from({ length: cols }, (_, c) => grid.map((row) => row[c] ?? ''));
+}
+/** Whether a node stands for a grid: a range, an array or reference function, a name to one, or arithmetic over those. */
+function hasArray(node, ctx, depth = 0) {
+    switch (node.k) {
+        case 'range': return true;
+        case 'spill': return true;
+        case 'name': {
+            if (isGrid(localOf(ctx, node.name)))
+                return true;
+            const target = depth < 8 ? nameTarget(node.name, ctx) : null;
+            return target ? hasArray(target, ctx, depth + 1) : false;
+        }
+        case 'fn': return REFERENCE_FUNCTIONS.has(node.name) || Boolean(ARRAY_FUNCTIONS[node.name]) || LAMBDA_HELPERS.has(node.name) || node.name === 'LET';
+        case 'binary': return hasArray(node.left, ctx, depth) || hasArray(node.right, ctx, depth);
+        case 'unary': return hasArray(node.arg, ctx, depth);
+        default: return false;
+    }
+}
+/**
+ * A node as a grid, with Excel's broadcasting: a side that is one row, one
+ * column or one cell stretches to the other's shape, and where both are
+ * bigger and differ the cells past the shorter side are #N/A.
+ */
+function gridOf(node, ctx) {
+    if (node.k === 'binary') {
+        const l = gridOf(node.left, ctx);
+        const r = gridOf(node.right, ctx);
+        return broadcast(l, r, (a, b) => {
+            if (isError(a))
+                return a;
+            if (isError(b))
+                return b;
+            try {
+                return binary(node.op, a, b);
+            }
+            catch (e) {
+                if (e instanceof FormulaError)
+                    return err(e.code);
+                throw e;
+            }
+        });
+    }
+    if (node.k === 'unary') {
+        return gridOf(node.arg, ctx).map((row) => row.map((v) => {
+            if (isError(v))
+                return v;
+            try {
+                return node.op === '-' ? -toNumber(v) : node.op === '%' ? toNumber(v) / 100 : toNumber(v);
+            }
+            catch (e) {
+                if (e instanceof FormulaError)
+                    return err(e.code);
+                throw e;
+            }
+        }));
+    }
+    const grid = rangeValues(node, ctx);
+    return grid ?? [[evalNode(node, ctx)]];
+}
+function broadcast(l, r, op) {
+    const lr = l.length, lc = l[0]?.length ?? 0;
+    const rr = r.length, rc = r[0]?.length ?? 0;
+    const rows = lr === 1 ? rr : rr === 1 ? lr : Math.max(lr, rr);
+    const cols = lc === 1 ? rc : rc === 1 ? lc : Math.max(lc, rc);
+    const pick = (g, gr, gc, i, j) => {
+        const y = gr === 1 ? 0 : i;
+        const x = gc === 1 ? 0 : j;
+        if (y >= gr || x >= gc)
+            return err('#N/A');
+        return g[y]?.[x] ?? '';
+    };
+    return Array.from({ length: rows }, (_, i) => Array.from({ length: cols }, (_, j) => op(pick(l, lr, lc, i, j), pick(r, rr, rc, i, j))));
+}
+/** An array function's answer: a grid, or a value where it had none to give. */
+function arrayCall(node, ctx) {
+    const { perArg, grids } = collectArgs(node.args, ctx);
+    // Errors stay inside the array: FILTER and SORT carry an error cell
+    // through as Excel does, and decide for themselves about the rest.
+    return ARRAY_FUNCTIONS[node.name]({ flat: perArg.flat(), args: perArg, grids });
+}
+/** Every argument evaluated, keeping range shape for the functions that need it. */
+function collectArgs(args, ctx) {
     const perArg = [];
     const grids = [];
     for (const given of args) {
+        // A name bound inside the formula, by LET or as a lambda's parameter,
+        // hands over its grid: `LET(r, A1:C1, SUM(r))` adds the range.
+        if (given.k === 'name') {
+            const local = localOf(ctx, given.name);
+            if (isGrid(local)) {
+                grids.push(local);
+                perArg.push(local.flat());
+                continue;
+            }
+        }
         // A name stands for whatever it was defined as. Substituting the node
         // here, before the shape check, is what lets `Sales` in =SUM(Sales) be a
         // whole column rather than the top-left cell a scalar read would give.
@@ -249,6 +859,13 @@ function evalCall(node, ctx) {
             grids.push(grid);
             perArg.push(grid.flat());
         }
+        else if (arg.k === 'fn' && REFERENCE_FUNCTIONS.has(arg.name)) {
+            // OFFSET and INDIRECT hand their whole rectangle to the caller, so
+            // =SUM(OFFSET(A1,0,0,3,1)) adds three cells rather than one.
+            const grid = rectGrid(referenceCall(arg, ctx), ctx);
+            grids.push(grid);
+            perArg.push(grid.flat());
+        }
         else if (arg.k === 'table') {
             // A structured reference expands exactly as a range does, which is
             // what makes =SUM(Orders[Amount]) work.
@@ -262,21 +879,67 @@ function evalCall(node, ctx) {
                 perArg.push(grid.flat());
             }
         }
+        else if (arg.k === 'spill') {
+            // The spilled range hands the whole array to the caller, so
+            // =SUM(E1#) adds every cell the dynamic array reaches.
+            const rect = spillRectOf(arg, ctx);
+            if (!rect) {
+                grids.push(null);
+                perArg.push([err('#REF!')]);
+            }
+            else {
+                const grid = rectGrid(rect, ctx);
+                grids.push(grid);
+                perArg.push(grid.flat());
+            }
+        }
+        else if (arg.k === 'ref3d') {
+            // A 3D reference hands over its cell on every sheet in the range, so
+            // =SUM(Sheet1:Sheet3!A1) adds the same cell down the tabs.
+            const vals = values3d(arg, ctx);
+            grids.push(null);
+            perArg.push(vals ?? [err('#REF!')]);
+        }
+        else if (arg.k === 'fn' && ARRAY_FUNCTIONS[arg.name]) {
+            // An array function nested in another hands over its grid, so
+            // =SORT(FILTER(...)) and =SUM(SEQUENCE(10)) work.
+            const grid = arrayCall(arg, ctx);
+            if (Array.isArray(grid)) {
+                grids.push(grid);
+                perArg.push(grid.flat());
+            }
+            else {
+                grids.push(null);
+                perArg.push([grid]);
+            }
+        }
+        else if (arg.k === 'fn' && LAMBDA_HELPERS.has(arg.name)) {
+            // And so do the lambda helpers: =SUM(MAP(A1:A9, LAMBDA(v, v * 2))) is
+            // the sum of every doubled value, not of the first one. REDUCE hands
+            // back one value rather than a grid, which is the same branch.
+            const grid = lambdaCall(arg, ctx);
+            if (Array.isArray(grid)) {
+                grids.push(grid);
+                perArg.push(grid.flat());
+            }
+            else {
+                grids.push(null);
+                perArg.push([grid]);
+            }
+        }
+        else if ((arg.k === 'binary' || arg.k === 'unary') && hasArray(arg, ctx)) {
+            // Arithmetic over a range is a grid, cell by cell: the `B2:B9>3` a
+            // FILTER takes, or `A1:A9*2` on its own.
+            const grid = gridOf(arg, ctx);
+            grids.push(grid);
+            perArg.push(grid.flat());
+        }
         else {
             grids.push(null);
             perArg.push([evalNode(arg, ctx)]);
         }
     }
-    const flat = perArg.flat();
-    // An error anywhere in the arguments propagates, except for the counting
-    // functions, which Excel lets see errors in their range.
-    if (name !== 'COUNTA' && name !== 'COUNTBLANK') {
-        for (const v of flat)
-            if (isError(v))
-                return v;
-    }
-    const payload = { flat, args: perArg, grids };
-    return fn(payload);
+    return { perArg, grids };
 }
 /**
  * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
@@ -293,10 +956,32 @@ export function rangeValues(node, ctx) {
             return rangeGrid(node.from, node.to, ctx);
         if (node.k === 'ref')
             return [[ctx.resolve(node.ref.sheet, node.ref.row ?? 0, node.ref.col)]];
+        if (node.k === 'spill') {
+            const rect = spillRectOf(node, ctx);
+            return rect ? rectGrid(rect, ctx) : [[err('#REF!')]];
+        }
         if (node.k === 'name') {
+            const local = localOf(ctx, node.name);
+            if (isGrid(local))
+                return local;
             const target = nameTarget(node.name, ctx);
             return target ? rangeValues(target, ctx) : null;
         }
+        if (node.k === 'fn' && REFERENCE_FUNCTIONS.has(node.name))
+            return rectGrid(referenceCall(node, ctx), ctx);
+        if (node.k === 'fn' && ARRAY_FUNCTIONS[node.name]) {
+            const grid = arrayCall(node, ctx);
+            return Array.isArray(grid) ? grid : [[grid]];
+        }
+        if (node.k === 'fn' && LAMBDA_HELPERS.has(node.name)) {
+            const grid = lambdaCall(node, ctx);
+            return Array.isArray(grid) ? grid : [[grid]];
+        }
+        // `=LET(r, A1:A9, SORT(r))` spills what its calculation is.
+        if (node.k === 'fn' && node.name === 'LET') {
+            const grid = letGrid(node.args, ctx);
+            return grid ?? [[evalNode(node, ctx)]];
+        }
         return null;
     }
     catch (e) {
@@ -305,6 +990,33 @@ export function rangeValues(node, ctx) {
         throw e;
     }
 }
+/**
+ * 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 function evaluateSpill(node, ctx) {
+    try {
+        let grid = null;
+        if (node.k === 'range' || node.k === 'name' || node.k === 'spill'
+            || (node.k === 'fn' && (REFERENCE_FUNCTIONS.has(node.name) || ARRAY_FUNCTIONS[node.name] || LAMBDA_HELPERS.has(node.name) || node.name === 'LET'))) {
+            grid = rangeValues(node, ctx);
+        }
+        else if ((node.k === 'binary' || node.k === 'unary') && hasArray(node, ctx)) {
+            grid = gridOf(node, ctx);
+        }
+        if (!grid || (grid.length === 1 && (grid[0]?.length ?? 0) <= 1))
+            return null;
+        const width = grid.reduce((m, row) => Math.max(m, row.length), 0);
+        return grid.map((row) => Array.from({ length: width }, (_, i) => row[i] ?? ''));
+    }
+    catch (e) {
+        if (e instanceof FormulaError)
+            return null;
+        throw e;
+    }
+}
 export function evaluate(node, ctx) {
     try {
         return evalNode(node, ctx);