@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/calculation/NamedLambdaFunction.d.ts

@@ -0,0 +1,28 @@
+import { TypedFunction } from '../scripting/TypedFunction';
+import { ICalculation } from './ICalculation';
+/**
+ * A defined name whose body is `LAMBDA(…)`, answered by `IFunctionCollection.getByName` as a function
+ * so that a signature or help lookup can describe it.
+ *
+ * @remarks
+ * Not registered and never executed. The engine's own function lookups skip `isLambda()`, so a call to
+ * the name still compiles as an application of the NAME — its dependency edge, `#NAME?` healing,
+ * recursion and `LET` shadowing are all the name's. `execute` answers `#CALC!`, a lambda's verdict
+ * wherever it is not applied.
+ */
+export declare class NamedLambdaFunction extends TypedFunction {
+    /** @inheritdoc IFunction.isLambda */
+    isLambda(): boolean;
+}
+/** The category a named lambda is listed under — beside the built-in categories, in search and pickers. */
+export declare const LAMBDA_CATEGORY = "Lambda";
+/**
+ * The function a lambda-valued defined name exports, or `null` when its body is not a `LAMBDA`.
+ *
+ * @remarks
+ * The parameters are the ROOT lambda's declarations — `LAMBDA(n,LAMBDA(x,x+n))` takes `n` — with
+ * optional ones flagged, and the summary is the name's comment, or its formula when it has none. One
+ * instance per name while those stay the same.
+ */
+export declare const namedLambdaFunction: (item: ICalculation.INamedFormula) => NamedLambdaFunction | null;
+//# sourceMappingURL=NamedLambdaFunction.d.ts.map

package/types/src/calculation/TokenType.d.ts

@@ -86,6 +86,15 @@ export declare const TokenType: {
      * A named formula reference, e.g. `TotalRevenue`.
      */
     readonly Named: "named";
+    /**
+     * A `LET` / `LAMBDA` name — its declaration (`x` in `LET(x,1,x+1)`) or a use bound to it. `value` is
+     * a {@link ICalculation.NamedRef} whose `declaration` flag marks the declaration.
+     *
+     * @remarks
+     * Token-only: in a formula tree these remain `named` nodes. Unlike a `named` token it never resolves
+     * against the workbook — its scope is the formula itself.
+     */
+    readonly Parameter: "parameter";
     /**
      * Tokens related to structured reference parsing. (e.g. Table[])
      *

package/types/src/calculation/Types.d.ts

@@ -30,6 +30,20 @@ export interface NamedReference {
      */
     readonly optional?: boolean;
 }
+/**
+ * An error reference — the `value` of an error REFERENCE AST node (`#REF!`, `#NAME?`): the error
+ * itself, and the sheet the dead reference named. INTERNAL, as {@link NamedReference} is.
+ *
+ * @remarks
+ * `scope` is the sheet's stableId once linked, the raw sheet name before. The public counterpart is
+ * {@link ICalculation.ErrorRef}, the `value` of an `error` {@link ICalculation.FormulaToken}, which
+ * carries the error as its label so that the token is plain data; `generateFormulaTokens` projects
+ * this onto that.
+ */
+export interface ErrorReference {
+    readonly error: FormulaError.Known;
+    readonly scope?: string | null;
+}
 /**
  * Pre-computed structured reference (table) query.
  *
@@ -84,11 +98,51 @@ export interface StructuredReference {
  * - `IRange.FixableCellCoords` — a single *cell* reference (`colIndex`/`rowIndex`). Passing this REPLACES
  *   the reference's shape: an existing range collapses to a lone cell (`A1:B2` → `A1`). This is how a
  *   caller says "I mean a cell" without a side-channel flag — the type carries the intent.
+ * - `TableReferenceCoords` — a structured reference, resolved (distinguish via `'tableId' in ref`)
  * - `NamedReference` — a named formula reference (distinguish via `'nameId' in ref`)
  * - `FormulaError.Ref` — a broken reference (`#REF!`)
  * - `null` — no reference at this slot
  */
-export type ReferenceCoords = IRange.FixableCoords | IRange.FixableCellCoords | NamedReference | FormulaError.Ref | null;
+export type ReferenceCoords = IRange.FixableCoords | IRange.FixableCellCoords | TableReferenceCoords | NamedReference | FormulaError.Ref | null;
+/**
+ * The cells a structured reference designates, marked with the table that designates them.
+ *
+ * @remarks
+ * A structured reference names a table, not cells: the table re-resolves it after every structural
+ * change, so a shift that moves cells must leave the reference alone. Without the mark the resolved
+ * coordinates are indistinguishable from an absolute range (every axis is `$`) and the shift paths
+ * rewrote the reference into one. Distinguish via `'tableId' in ref`, as `'nameId' in ref` does for
+ * a name.
+ */
+export interface TableReferenceCoords extends IRange.FixableCoords {
+    /** The stable id of the table. */
+    tableId: string;
+}
+/**
+ * A named formula as a NODE in a graph answer - everything needed to build the range object
+ * that carries it, and nothing that needs the engine.
+ *
+ * @remarks
+ * The calculation layer knows the graph; the model layer knows how to be a range. This struct is
+ * the seam, and it is deliberately plain data: a name crossing into the model used to arrive as an
+ * object carrying lazy graph queries as closures, which meant the model reached into the
+ * calculation to get one and could not have received it over a wire at all. The queries are
+ * public on {@link ICalculation.INamedFormula}, resolved from {@link id} when asked.
+ */
+export interface NamedNodeInfo {
+    /** The name's stable id - also the id of the virtual grid its body compiles into. */
+    id: string;
+    /** The name as authored, unqualified. Scope qualification is the view's job, led by the id. */
+    name: string;
+    /**
+     * The anchor sheet's display NAME, or `null` when it cannot be resolved (a file-loaded name
+     * whose defining sheet is unknowable) - the consumer picks a default sheet then.
+     */
+    sheetName: string | null;
+    /** The anchor cell - the name's defining cell (the active cell at authoring time). */
+    rowIndex: number;
+    colIndex: number;
+}
 /**
  * Options for `IFormulaBlock.setReferenceAt`.
  */
@@ -101,10 +155,37 @@ export interface SetReferenceOptions {
      * Measured in Excel: a row/area delete leaves the qualified form (`Data!#REF!`), which is the
      * breadcrumb naming whose cells went; deleting the sheet itself leaves a bare `#REF!`, since
      * there is no longer a sheet to name. Only the caller knows which of the two it is performing —
-     * `CalcGrid.delete` is walking the precedents OF the grid it is about to drop, while every
+     * `CalcGridBackend.delete` is walking the precedents OF the grid it is about to drop, while every
      * shift path is deleting rows within a sheet that survives. It cannot be inferred here: the
      * sheet is still registered when this rewrite runs, so resolving the qualifier still succeeds.
      */
     scopeDeleted?: boolean;
 }
+/**
+ * A block's static precedent edges in RELATIVE form — one entry per edge, in the order
+ * `resolvedPrecedentsAt` returns them — for the blocks whose edges are the same rects at every
+ * cell's own offset. See {@link IFormulaBlock.getPrecedentTemplate}.
+ */
+export interface PrecedentTemplate {
+    /**
+     * The stored reference behind each edge, translated against the asking cell — or the error the
+     * edge IS (`#REF!`), which is the same at every cell and translates to nothing. The resolver
+     * answers the same error in that slot, so a block whose only reference is broken still has an
+     * edge list it can share, and the blank-aware predicate treats it as an input that does not vary.
+     */
+    readonly relative: readonly (IRange.FixableCoords | FormulaError.Known)[];
+    /**
+     * The SECOND endpoint of an edge written as a range (`A1:B4` — a `:` operator over two cell
+     * leaves, which is how the compiler stores every range); `null` where the edge is one
+     * reference. The edge is then the union of the two translated endpoints, exactly as
+     * `resolvedPrecedentsAt`'s range-operator branch forms it.
+     */
+    readonly second: readonly (IRange.FixableCoords | null)[];
+    /**
+     * Per edge, the compiler's per-axis anchoring — what `resolvedPrecedentsAt` stamps onto the
+     * coords it hands back. Constant for the block, so a materialized buffer is stamped once.
+     */
+    readonly verticalAbs: readonly boolean[];
+    readonly horizontalAbs: readonly boolean[];
+}
 //# sourceMappingURL=Types.d.ts.map

package/types/src/calculation/_CloneBoundary.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The clone boundary: a test mode that treats the model/engine crossing as if it were a wire
+ * (DESIGN-CALC-SERVICE §11, goal G1, plan step 6).
+ *
+ * @remarks
+ * Every request into a grid and every {@link ICalcGrid.Results} out of one passes through here.
+ * With the mode `off` - always, outside a test - it is an identity call and costs nothing.
+ *
+ * Two things it finds, and they are different:
+ *
+ * - What a walk can see: a function, a class instance, a value `structuredClone` refuses or
+ *   silently downgrades. Each is recorded as a {@link Violation} with the PATH it sat at, which
+ *   is the point: a payload that degrades silently fails somewhere else entirely, and the path
+ *   is what names the field to convert.
+ * - What only running can see: a reference the two sides SHARE. A walk cannot tell a run array
+ *   the sheet also holds from one minted for the message; a clone does, because the sides stop
+ *   agreeing. That is what `clone` mode is for, and why `audit` alone is not the exit criterion.
+ *
+ * Not a boundary for READS. `getValues`, `getFormulas`, `getSnapshot` and the graph walks answer
+ * synchronously out of engine objects; making them push or await is §11's list, not this one.
+ * This covers what is already message-shaped.
+ *
+ * @internal Test-mode only. Deliberately not exported from the barrel.
+ */
+export declare namespace CloneBoundary {
+    /**
+     * `off` is the default and the only mode outside a test.
+     *
+     * `audit` records what would not survive the crossing and passes the ORIGINAL through, so a
+     * suite stays green and the run produces the list. `clone` substitutes the
+     * `structuredClone` - the real wire - and is the exit criterion for "ready for a worker".
+     */
+    type Mode = 'off' | 'audit' | 'clone';
+    /** What a value at a path does to a `structuredClone`. */
+    type ViolationKind = 
+    /** A function or a symbol: `structuredClone` throws. */
+    'function'
+    /** A class instance: cloned as a plain object, its methods gone, and nothing says so. */
+     | 'live'
+    /** An `Error` subclass: clones to a bare `Error` - the subclass and its own fields are lost. */
+     | 'downgraded';
+    interface Violation {
+        /** Which crossing: `'request:setInputs'`, `'results:onCalculated'`, ... */
+        where: string;
+        /** Where in the payload, with array indices collapsed: `results.formulaInserts[].value`. */
+        path: string;
+        kind: ViolationKind;
+        /** The constructor name, or `'function'` / `'symbol'`. */
+        type: string;
+    }
+    /** Thrown by `clone` mode when the payload cannot be cloned at all. */
+    class BoundaryError extends Error {
+        readonly violations: readonly Violation[];
+        constructor(where: string, violations: readonly Violation[], cause: unknown);
+    }
+    /** Sets the mode. Anything but a known mode (including `undefined`) is `off`. */
+    const setMode: (mode: string | null | undefined) => void;
+    const getMode: () => Mode;
+    /**
+     * Called once per DISTINCT violation (a payload of 50000 cells reports its field once), so a
+     * host can write the run's list somewhere a test runner does not swallow.
+     */
+    const setListener: (listener: ((violation: Violation) => void) | null) => void;
+    /** Every distinct violation seen since the mode was set. */
+    const getViolations: () => readonly Violation[];
+    const clearViolations: () => void;
+    /**
+     * A request on its way to a grid.
+     *
+     * @param where The request's `type`, for the report.
+     */
+    const request: <T>(request: T, where: string) => T;
+    /**
+     * An {@link ICalcGrid.Results} on its way back: a resolution, or a record the engine pushed.
+     *
+     * @param where Which of the two, for the report.
+     */
+    const results: <T>(results: T, where: string) => T;
+}
+//# sourceMappingURL=_CloneBoundary.d.ts.map

package/types/src/calculation/_FormulaToolkit.d.ts

@@ -0,0 +1,9 @@
+/** The formula toolkit's code (`./toolkit`). */
+export type FormulaToolkitModule = typeof import('./toolkit');
+/**
+ * The one loader of the formula toolkit, shared by `FormulaText`, `parseFormulaLiteral` and
+ * `FunctionDeclarations`: each answers from {@link FormulaToolkit.peek} and gives the answer it
+ * gives for text it cannot read until the toolkit is loaded (DESIGN-CALC-SERVICE §13.25).
+ */
+export declare const FormulaToolkit: import('@sheetxl/utils').LazyModule<typeof import("./toolkit")>;
+//# sourceMappingURL=_FormulaToolkit.d.ts.map

package/types/src/calculation/_TableExtent.d.ts

@@ -0,0 +1,60 @@
+import { FormulaError, IRange } from '@sheetxl/primitives';
+import { ITable } from '../table';
+import { ASTNode } from './compiler/ASTTypes';
+import { StructuredReference } from './Types';
+/**
+ * What a structured reference resolves against: a live table, or a snapshot of one taken before it
+ * was removed ({@link snapshotTableExtent}).
+ */
+export interface TableExtent {
+    getRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getDataRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getHeaderRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    getTotalRowRange(): {
+        getCoords(): IRange.Coords;
+    };
+    isShowHeaders(): boolean;
+    isShowTotals(): boolean;
+    getColumnById(id: string): {
+        getIndex(): number;
+    } | null;
+    getWorksheet(): {
+        getId(): string;
+    } | null | undefined;
+}
+/**
+ * The column a structured reference's column id (`_<tableStableId>:<rawColumnId>`) names in `table`,
+ * or `null` when the table no longer has it.
+ */
+export declare function tableColumnOf(table: TableExtent, columnId: string): {
+    getIndex(): number;
+} | null;
+/**
+ * Whether a column `structuredReference` names is gone from `table`. Excel then writes `#REF!` in
+ * place of the whole reference, for an endpoint of a column range as much as for a lone column; a
+ * column deleted strictly between the endpoints leaves the reference as it was.
+ */
+export declare function namesDeadColumn(structuredReference: StructuredReference, table: TableExtent): boolean;
+/**
+ * The cells `structuredReference` designates in `table`, for a formula in `row`.
+ */
+export declare function structuredReferenceCoords(structuredReference: StructuredReference, row: number, table: TableExtent): IRange.FixableCoords | FormulaError.Known;
+/**
+ * `table`'s extent as plain data, so its references can still be resolved after it is removed.
+ */
+export declare function snapshotTableExtent(table: ITable): TableExtent;
+/**
+ * The absolute address a structured reference designates, as a reference node: `Sheet1!$A$2:$C$4`.
+ *
+ * @remarks
+ * A this-row reference keeps its row relative (`Sheet1!$A2`), so every cell of a block still reads
+ * its own row.
+ */
+export declare function structuredReferenceAddress(reference: StructuredReference, extent: TableExtent): ASTNode;
+//# sourceMappingURL=_TableExtent.d.ts.map

package/types/src/calculation/_TableRename.d.ts

@@ -0,0 +1,13 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from './ICalculation';
+/**
+ * Re-points every structured reference that names the table `from` at the table `to`. A
+ * reference with no table name is left alone: it names the table it is written in.
+ */
+export declare function renameTableTransform(from: string, to: string): ICalculation.FormulaTransform;
+/**
+ * `text`, parsed at `at`, with its references to the table `from` re-pointed at `to`, or the text
+ * itself when it names no such table or does not parse.
+ */
+export declare function renameTableInText(text: string, at: IRange.CellCoords, from: string, to: string): string;
+//# sourceMappingURL=_TableRename.d.ts.map

package/types/src/calculation/compiler/ASTTypes.d.ts

@@ -43,6 +43,38 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * @see {@link ICalculation.FormulaToken.evalIndex}
      */
     evalIndex?: number;
+    /**
+     * Compile-time: the implicit-intersection MODE this call is evaluated in — `true` VALUE mode
+     * (a multi-cell reference at a single-value slot intersects with the formula cell), `false`
+     * ARRAY mode (it reads its first cell). Set on `Function` and `Call` nodes by
+     * `CompilerUtils.annotateImplicitIntersect` (DESIGN-IMPLICIT-INTERSECTION §2).
+     */
+    implicitIntersect?: boolean;
+    /**
+     * Compile-time: under a first-cell DEMAND (a block whose every cell is its own 1x1 array-entered
+     * extent — a conditional-format body), only element `[0,0]` of this node's result is ever read,
+     * so a lift or an operator here builds that one element. Set on every node reachable from the
+     * root through elementwise positions by `CompilerUtils.annotateFirstCell`
+     * (DESIGN-LIFT-AND-DEMAND §2); inert unless the block evaluating the formula demands it.
+     */
+    firstCell?: boolean;
+    /**
+     * Compile-time: this `+`/`-` is the root of a formula body — the formula's own root or a
+     * `LAMBDA`'s body — so a cancelling result snaps to 0 (`Operators.RootInfix`). Set by
+     * `CompilerUtils.compileAST`.
+     */
+    snapsCancellation?: boolean;
+    /**
+     * The ROOT only: the formula came from a LEGACY cell, so `annotateImplicitIntersect` gives its
+     * WHOLE tree value mode instead of deriving a mode per node. Carried in from the reader's
+     * transform (`ICalculation.FormulaNode.legacyIntersect`); never persisted.
+     */
+    legacyIntersect?: boolean;
+    /**
+     * Compile-time memo: whether this expression is statically array-valued (a range, an array
+     * literal, an array-returning call, an operator over one). Read by the mode annotation.
+     */
+    arrayValued?: boolean;
     /**
      * For live editing. We may need to add original start/end offsets to align?
      *
@@ -91,6 +123,13 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * converts the sentinel to blank.
      */
     rawFrameRead?: boolean;
+    /**
+     * Set by the binder pass on an `IF`/`IFERROR`/`IFNA` call whose answer can reach `ISOMITTED`
+     * — its direct argument, a `LET` binding's value, or such a call's own argument. The call
+     * passes an EMPTY argument on as the OMITTED sentinel (`ISOMITTED(IF(TRUE,))` is TRUE), where
+     * an unstamped call reads it as blank.
+     */
+    passOmitted?: boolean;
     /**
      * Set by the compiler on a `named` node INSIDE a `LAMBDA` body: resolved at apply time, not in
      * the eager reference pass.
@@ -102,6 +141,38 @@ export interface ASTNode<T extends TokenType = TokenType, V = any> {
      * accepted cost — design §3.4); only the eager VALUE resolution is skipped.
      */
     deferredResolve?: boolean;
+    /**
+     * Set by the compiler on an argument node that binds to a `Lazy` parameter: the ENGINE hands the
+     * body a handle over this subtree instead of its value.
+     *
+     * @remarks
+     * The subtree is absent from the eager execution list (the same carve-out a `LAMBDA` body gets)
+     * and is evaluated only if the call's answer turns out to be the handle. An `Empty` argument is
+     * never marked — an omitted comma is a value the caller supplied, and it marshals as one.
+     */
+    lazyArg?: boolean;
+    /**
+     * Set by the compiler on every node WITHIN a lazy argument's subtree, the root included. What
+     * the execution-list carve-out reads.
+     */
+    inLazy?: boolean;
+    /**
+     * Set by the compiler on a call node that has at least one {@link lazyArg} — so the hot argument
+     * loop pays one boolean for a feature almost no call uses.
+     */
+    hasLazyArgs?: boolean;
+    /**
+     * Set by the compiler on the ROOT of a deferred subtree — a `LAMBDA` body or a {@link lazyArg} —
+     * to the post-order execution list of that subtree, the root included: the same shape as
+     * `CompiledFormula.executions`, for the piece of the formula the eager pass leaves out.
+     *
+     * @remarks
+     * A nested root's nodes are on the nested list, not this one (its root node is here, and
+     * evaluating it closes over or defers what is underneath). A bound name executes wherever it
+     * sits; an unbound name (`deferredResolve`) is on the list too, since the eager reference pass
+     * skips it and resolving it is what the deferral is for.
+     */
+    deferred?: ASTNode[];
     /**
      * If ast had an error.
      *