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

package/types/src/calculation/state/CalcNode.d.ts

@@ -1,43 +1,56 @@
 import { Scalar, FormulaError, IRange } from '@sheetxl/primitives';
 import { ISpatialMap } from '../../collections';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
-export interface CalcNode {
-    block: FormulaSpatialValue;
-    gridId: string | null;
-    colIndex: number;
-    rowIndex: number;
-    cycleId: number;
-    markId: number;
-    inDegree: number;
-    /**
-     * Cached result of a spatial search: all ISpatialMap.Entry<PrecedentSpatialValue> blocks whose formula ranges
-     * overlap this cell.
-     * Populated once during the mark phase (the BFS upward-walk), then reused by the topological sort to decrement.
-     */
-    dependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
+/**
+ * The fields of a node that only a MINORITY of nodes ever need: the ones a spill anchor, a cycle
+ * node, an async formula or an array-entered block carries. Allocated on first write
+ * ({@link calcNodeExt}) and `null` on every node that is none of those — which, in a real
+ * workbook, is nearly all of them.
+ *
+ * @remarks
+ * One object rather than one per feature. Three nullable pointers (spill, cycle, async) would
+ * cost three slots on every node to save nine, and would put three shapes behind the reads;
+ * one costs a single slot and leaves each `ext.*` site monomorphic, because a site is only
+ * reached once `ext !== null`.
+ *
+ * Every field here keeps the meaning it had on the node, so a reader that has an ext in hand
+ * reads it exactly as before. A reader that does NOT is reading a node with none of these
+ * features, and the defaults in {@link calcNodeExt} are what it would have found.
+ */
+export interface CalcNodeExt {
     /**
-     * Parallel to `precedents`. One slot per static precedent, in formula order.
-     * Populated by the push model: after CalcNode N evaluates, N writes cachedValue into
-     * each dependent D's inputs[entry.value.index]. Range-typed slots are filled by a
-     * mid-cycle ReferenceRange (see doEvaluate range branch). Read by CalculationContext
-     * during evaluateAt() to resolve formula argument values.
-     * Undefined slots mean the precedent is a constant cell — CalculationContext falls back to the grid.
+     * The precedent entries that read this node's spill BODY — its extent minus the anchor cell.
+     * Recomputed by the mark phase, and never cached across passes: it is keyed by an extent the
+     * pass can change.
+     *
+     * @remarks
+     * Body cells hold the anchor's output but no formula of their own, so neither `dependents`
+     * (searched at the anchor cell) nor `formulaSpatial` (which has no body entry) knows their
+     * readers. These entries make the anchor stand in for its whole extent — both for discovery and
+     * for the in-degree/decrement pair, so a reader whose reference never touches the anchor is
+     * still ordered after it. Walked with `visitSpillBodyBlock`, which excludes the anchor cell's
+     * own readers so each edge is counted exactly once. See {@link spillRowEnd}.
      */
-    inputs: (Scalar | IRange | IRange.Coords | undefined)[];
+    spillDependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
     /**
-     * Coordinate ranges for every static precedent in formula order, parallel to `inputs`.
-     * Pre-filled at CalcNode construction from resolvedPrecedentsAt(cellRow, cellCol).
-     * Errors (FormulaError.Known) appear where the reference resolves to an invalid range (#REF! etc.).
-     * Read by CalculationContext for runtime value lookups and by the mark phase for inDegree computation.
+     * The bottom-right of the spill extent {@link spillDependents} was searched over; the top-left
+     * is the node's own position. `-1` whenever that list is empty — a node that does not spill, and
+     * equally one whose body nothing reads.
      */
-    precedents: (IRange.Coords | FormulaError.Known)[];
+    spillRowEnd: number;
+    spillColEnd: number;
     /**
-     * The cached value of the cell after evaluation.
+     * The extent of the array-entered (Ctrl+Shift+Enter) block this node anchors, or `null` for an
+     * ordinary formula. Absolute, unscoped.
      *
      * @remarks
-     * This is `undefined` if not calculated.
+     * Carried on the node, not inferred from the cached value or the spill map: a fixed block's
+     * result is fitted to this extent — 1x1 for the overwhelming majority — so the cached value is a
+     * scalar and never says "spill". The executor's fixed branch selects on this alone; the
+     * `SpillEntry` it writes is the persisted image. Set at load from a `fixed` `formulaArray` entry
+     * and by `setInputs` with a `arrayFixed`; translated with the node when its block moves.
      */
-    cachedValue: Scalar | IRange | undefined;
+    fixedRef: IRange.Coords | null;
     pendingPromise: Promise<any> | null;
     /**
      * The demand evaluation's result — finalized for the cell, or a pending promise — which
@@ -60,9 +73,102 @@ export interface CalcNode {
     /**
      * The cycle the sheet's circular index currently shows this cell in (`0` none) — what the last
      * commit wrote, so the next can write the delta. Persists across passes, unlike
-     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of {@link state}.
+     * {@link cycleGroup}; the role it shows is the `CalcState.ShownRoleMask` field of
+     * `CalcNode.state`.
      */
     shownGroup: number;
+}
+/**
+ * The node's {@link CalcNodeExt}, created on first ask.
+ *
+ * @remarks
+ * Only ever called from a write path — a node acquiring one of the features the ext carries.
+ * A READ must go through `node.ext` and treat `null` as the defaults set here, so that reading a
+ * node never gives it an ext it does not need.
+ */
+export declare const calcNodeExt: (node: CalcNode) => CalcNodeExt;
+/**
+ * The node's static precedent edges, absolute — its own stored list, or the block's template
+ * materialized for its cell.
+ *
+ * @remarks
+ * A templated answer is the BLOCK's buffer and is valid only until the next ask (see
+ * `FormulaSpatialValue.getPrecedentsAt`): read it inside the loop that asked for it, and copy
+ * anything you intend to keep. Every consumer in the engine already does.
+ */
+export declare const nodePrecedents: (node: CalcNode) => (IRange.Coords | FormulaError.Known)[];
+/**
+ * How many input slots the node needs — one per static precedent.
+ *
+ * @remarks
+ * Read off the stored list where there is one, and off the block's template where there is not,
+ * so the count never has to materialize a cell's edges. The two agree: a template contributes one
+ * edge per root reference at every cell.
+ */
+export declare const nodeParamLength: (node: CalcNode) => number;
+export interface CalcNode {
+    block: FormulaSpatialValue;
+    gridId: string | null;
+    colIndex: number;
+    rowIndex: number;
+    cycleId: number;
+    markId: number;
+    inDegree: number;
+    /**
+     * Cached result of a spatial search: all ISpatialMap.Entry<PrecedentSpatialValue> blocks whose formula ranges
+     * overlap this cell.
+     * Populated once during the mark phase (the BFS upward-walk), then reused by the topological sort to decrement.
+     */
+    dependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
+    /**
+     * Where this node's input slots start in the pass's shared arena (`CalcInputs`), or `-1` for a
+     * node with no precedents — and for one no mark phase has reached, whose slots would be read as
+     * empty and fall through to the grid.
+     *
+     * @remarks
+     * One slot per static precedent, in formula order — `precedents.length` of them, the same
+     * parallel the per-node array had. Populated by the push model: after CalcNode N evaluates, N
+     * writes its cached value into each dependent D's slot `entry.value.index`. Range-typed slots
+     * are filled by a mid-cycle ReferenceRange (see doEvaluate range branch). Read by
+     * CalculationContext during evaluateAt() to resolve formula argument values. An empty slot means
+     * the precedent is a constant cell — CalculationContext falls back to the grid.
+     *
+     * The slots live in the arena rather than in an array per node because they are pass scratch:
+     * cleared by the mark phase, written and read within the one pass, and never read between
+     * passes. A million nodes holding a two-element array each is a million allocations, and none
+     * of them survives the pass that fills it.
+     */
+    inputsAt: number;
+    /**
+     * Coordinate ranges for every static precedent in formula order, parallel to the node's arena
+     * slots — or `null` when the block carries a precedent TEMPLATE and the edges are materialized
+     * on demand instead. Read through {@link nodePrecedents}, never directly.
+     *
+     * @remarks
+     * Where it is set, it is pre-filled at CalcNode construction from
+     * `resolvedPrecedentsAt(cellRow, cellCol)`, and errors (FormulaError.Known) appear where the
+     * reference resolves to an invalid range (#REF! etc.). Read by CalculationContext for runtime
+     * value lookups and by the mark phase for inDegree computation.
+     *
+     * `null` is the common case: a formula whose references are plain A1 refs has the same edges at
+     * every cell of its block, at that cell's own offset, so the block keeps ONE relative template
+     * and one buffer rather than an array of fresh coord objects per cell. See
+     * `IFormulaBlock.getPrecedentTemplate`.
+     */
+    precedents: (IRange.Coords | FormulaError.Known)[] | null;
+    /**
+     * The cached value of the cell after evaluation.
+     *
+     * @remarks
+     * This is `undefined` if not calculated.
+     */
+    cachedValue: Scalar | IRange | undefined;
+    /**
+     * The number format a function supplied for this cell's result during its evaluation
+     * (`IFormulaContext.formatResults`), held until the results are written and reported
+     * (`ICalcGrid.Results.formatInserts`); `null` when none did. Cleared by the write.
+     */
+    numFmt: string | null;
     /**
      * Position of this node in the last FULLY-ORDERED plan that stamped it (CALC-PERFORMANCE-PLAN.md
      * §1.2). Meaningful only when {@link planId} and {@link planEpoch} match the executor's current
@@ -94,5 +200,10 @@ export interface CalcNode {
      * pass on purpose.
      */
     state: number;
+    /**
+     * The spill / cycle / async / array-entered fields, or `null` on a node that is none of those.
+     * See {@link CalcNodeExt}; write through {@link calcNodeExt}, read defensively.
+     */
+    ext: CalcNodeExt | null;
 }
 //# sourceMappingURL=CalcNode.d.ts.map

package/types/src/calculation/state/CalcScope.d.ts

@@ -24,6 +24,52 @@ export interface CalcScope {
      * 0 for an ordinary cell. Enforces the LAMBDA recursion limit (Step 14).
      */
     depth: number;
+    /**
+     * The implicit-intersection mode of the call being dispatched — `true` is Excel's VALUE mode,
+     * `false` ARRAY mode. Copied from the call node's compile-time annotation
+     * (`ASTNode.implicitIntersect`) around each dispatch by `FormulaBlock._callFunction`, read
+     * through `IFormulaContext.isImplicitIntersect`.
+     */
+    implicitIntersect: boolean;
+    /**
+     * Whether the call being dispatched is under a first-cell demand: only element `[0,0]` of its
+     * result is read, so a lift builds that one element. `true` only inside a block whose cells are
+     * each their own 1x1 array-entered extent (`FormulaSpatialValue.arrayFirstCell`), for a call the
+     * compiler annotated (`ASTNode.firstCell`). Set around each dispatch by
+     * `FormulaBlock._callFunction` and taken by the typed dispatch on entry
+     * (`CalculationContext._takeFirstCell`), so a body that calls another function directly never
+     * inherits it.
+     */
+    firstCell: boolean;
+    /**
+     * Set when the evaluation read something that is PER CELL rather than a property of its inputs
+     * — a random draw (`IFormulaContext.getRandom`), another cell's formula or sheet
+     * (`getFormulaAt`, `getSheetIndex`), or a reference it computed (a dynamic precedent) — so its
+     * answer cannot stand in for another cell's even when the two cells' inputs are identical.
+     * Cleared by whoever evaluates a cell as the representative of a block's blank region and read
+     * at its finalize (PLAN-WATCHES-BLANK-AWARE §4); a cell evaluated on its own behalf never
+     * reads it.
+     */
+    perCellRead: boolean;
+    /**
+     * Set when the evaluation read its own POSITION — `getRow`, `getColumn`, its own address, a
+     * reference's `getCoords`. Per cell like {@link perCellRead}, but a position is the one per-cell
+     * input whose effect the representative can rule out: when every position read sits under a
+     * boolean test the result does not depend on (`AND(ISODD(ROW()),$A1<>"")` over a blank `A`),
+     * the answer is still shared (`IFormulaBlock.getPositionVariants`). Cleared and read alongside
+     * {@link perCellRead}.
+     */
+    positionRead: boolean;
+    /**
+     * How many draws (`IFormulaContext.getRandom`) this evaluation has taken, from `0`.
+     *
+     * @remarks
+     * A seeded draw is keyed by the cell and the pass, so a cell taking two of them — `RAND()+RAND()`,
+     * or one per element of a `RANDARRAY` — needs something to tell them apart. Reset wherever an
+     * evaluation begins, alongside `rowIndex`/`colIndex`, so a retried cell draws what it drew
+     * before. Ignored when no seed is set.
+     */
+    drawIndex: number;
     /**
      * Stable nameIds currently on the resolution stack — the cycle guard for named
      * formulas. A plain name re-entering itself (`X = X + 1`) is a circular reference.

package/types/src/calculation/state/CalcState.d.ts

@@ -34,7 +34,18 @@ export declare const CalcState: {
      */
     readonly Circular: number;
     /**
-     * A `Waiting` node the evaluation in progress has read under iterative calculation — it is in
+     * The node's last evaluation found it volatile: the formula names a volatile function
+     * (`IFormulaContext.markVolatile`, which the compiled `hasVolatile` spends), it read cells its
+     * text does not name (a dynamic precedent of kind `Reference`: `OFFSET`, `INDIRECT`), or it is
+     * a member of an iterated cycle. Cleared when an evaluation of the node starts, so it answers
+     * for the last one; persists across passes that skip the node. What `isVolatileAt` reports —
+     * the executor's volatile SET is the pass's own worklist, rebuilt every pass, and is not read
+     * for the answer.
+     */
+    readonly Volatile: number;
+    /**
+     * A `Waiting` node — or a finished member of a cycle that is still open — the evaluation in
+     * progress has read under iterative calculation: it is in
      * the executor's hit list already, so a second read of it in the same evaluation adds nothing.
      * Cleared when the list is consumed.
      */
@@ -51,6 +62,26 @@ export declare const CalcState: {
      * clears this when it empties the roster.
      */
     readonly Rostered: number;
+    /**
+     * A `CycleRole.Downstream` node that iterative calculation sweeps with the members, because a
+     * swept node reads it: it lies between two cycles, so it is in neither and still has to move
+     * with them. In the executor's sweep list already.
+     */
+    readonly Swept: number;
+    /**
+     * Pushed onto the demand stack by the PREFETCH of a `NeedsFirst` rather than by a read: the
+     * reader may never read it (an untaken `IF` arm names a cell without reading it), so its own
+     * reads may not decide anything about the reader. A node the prefetch pushes and a read then
+     * asks for loses the flag. Cleared when the node finishes, or when it is put back unevaluated.
+     */
+    readonly Prefetched: number;
+    /**
+     * `Unevaluated` and on the demand stack already, below the node being evaluated: it will be
+     * reached, so a prefetch does not push it again. Cleared when its evaluation starts. May outlive
+     * its entry (a cycle unwinds the stack past queued nodes); that only skips a prefetch, which is
+     * never needed for a right answer.
+     */
+    readonly Queued: number;
     /** What the mark phase resets: everything a single pass decides. `Skip` and the shown role survive. */
     readonly PassMask: number;
 };

package/types/src/calculation/state/CalculationContext.d.ts

@@ -12,6 +12,11 @@ export declare class CalculationContext implements IFormulaContext {
     protected _calcScope: CalcScope;
     protected _functions: IFunctionCollection;
     protected _container: IContextContainer;
+    /** The key parts of a draw that are not the cell itself — see {@link getRandom}. */
+    protected _passSeed: number;
+    protected _passCycleId: number;
+    protected _gridKey: number;
+    protected _gridKeyId: string | null;
     protected _axis: IRange.Axis;
     protected _coerceToNumber: (value: Scalar, fromType: ScalarType, options?: IFormulaContext.ParseNumberOptions) => Scalar;
     protected _functionProviders?: readonly FunctionProvider[];
@@ -31,6 +36,13 @@ export declare class CalculationContext implements IFormulaContext {
      * is seen (DESIGN-CIRCULAR-CALC.md §5); `null` outside a pass.
      */
     protected _dynamicRead: ReadHook | null;
+    /**
+     * Marks the evaluation in progress as having read its position, so its answer stands in for
+     * another cell's only where the position cannot matter (`CalcScope.positionRead`). One closure for the
+     * context's lifetime: every reference it builds is handed this for its `getCoords`, and the
+     * context's own position accessors call it directly.
+     */
+    protected readonly _positionRead: () => void;
     constructor(container: IContextContainer, axis?: IRange.Axis, functionProviders?: readonly FunctionProvider[]);
     /** @hidden */
     _setInstanceScope(instanceScope: any): void;
@@ -80,7 +92,13 @@ export declare class CalculationContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
+    /**
+     * The id of the grid a reference's public coords name: its sheet's, or - unqualified - the grid
+     * being evaluated. `getCoords()` spells a sheet as its name, and the engine's own maps (the
+     * formulas, the hidden runs) are keyed by grid id.
+     */
+    private _gridIdOf;
     /** @inheritdoc IFormulaContext.filterTotals */
     filterTotals(range: IRange): IRange;
     /** @inheritdoc IFormulaContext.getSheetIndex */
@@ -99,22 +117,44 @@ export declare class CalculationContext implements IFormulaContext {
     getSerialDate(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millis?: number): number;
     /** @inheritdoc IFormulaContext.getNow */
     getNow(): number;
+    /** @inheritdoc IFormulaContext.getRandom */
+    getRandom(): number;
     /** @inheritdoc IFormulaContext.compare */
     compare(a: Scalar, b: Scalar, options?: Intl.CollatorOptions): number;
-    protected _fromTuples(boundedTuples: Tuple.BoundedTuples<Scalar>, type?: ScalarType | null, isLiteral?: boolean, isDirectScalar?: boolean): IRange | null;
+    protected _fromTuples(boundedTuples: Tuple.Region<Scalar>, type?: ScalarType | null, isLiteral?: boolean, isDirectScalar?: boolean): IRange | null;
     /** @inheritdoc IFormulaContext.getValueAt */
     getValueAt(rowIndex: number, colIndex: number, sheetName?: string | null, options?: IRange.ValueOptions): Scalar | null;
     /** @inheritdoc IFormulaContext.getSpillAt */
     getSpillAt(rowIndex: number, colIndex: number, sheetName?: string): IReferenceRange | null;
     /** @inheritdoc IFormulaContext.createRange */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /** @inheritdoc IFormulaContext.flattenAreas */
+    flattenAreas(value: IRange | IRange[]): IRange;
     getRange(value: Scalar | Scalar[][], type?: ScalarType | null, isLiteral?: boolean): IRange;
     /** @inheritdoc IFormulaContext.getRow */
     getRow(): number;
     /** @inheritdoc IFormulaContext.getColumn */
     getColumn(): number;
+    /** @inheritdoc IFormulaContext.isImplicitIntersect */
+    isImplicitIntersect(): boolean;
+    /**
+     * Whether the call being dispatched is under a first-cell demand (`CalcScope.firstCell`), and
+     * clears it: the demand is the dispatched call's own, and a body that calls another function
+     * directly must not inherit it. Engine-internal; no body reads it.
+     */
+    _takeFirstCell(): boolean;
     /** @inheritdoc IFormulaContext.getReference */
     getReference(coords: IRange.Coords | string, r1c1?: boolean): IReferenceRange;
+    /**
+     * @internal
+     * A reference whose scope is a 3-D span, as its member areas — one coords per sheet it covers, in
+     * tab order, marked `isSheetSpan` — or `null` for any other value.
+     *
+     * @remarks
+     * The marshaller asks this before its union rules, so a span is flattened, handed whole or refused
+     * exactly where a union would be, and a body that reads the mark (`SHEETS`) still can.
+     */
+    _expandSheetSpan(value: any): IRange.Coords[] | null;
     /** @inheritdoc IFormulaContext.getResizedReference */
     getResizedReference(anchor: Readonly<IRange.Coords>, rowCount: number, colCount: number): IReferenceRange;
     /**
@@ -151,7 +191,14 @@ export declare class CalculationContext implements IFormulaContext {
     parseAsNumber(textOrNumber: Scalar, options?: IFormulaContext.ParseNumberOptions): number;
     parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
     /** @inheritdoc IFormulaContext.createCriteria */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
+    /** @inheritdoc IFormulaContext.createGrouping */
+    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+    /**
+     * A one-column array of `size` rows holding `values[i]` at `rows[i]` and blank elsewhere —
+     * written directly, so a mostly-blank column costs its values, not its size.
+     */
+    private _createSparseColumn;
     /** @inheritdoc IFormulaContext.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */