@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.2

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

@@ -1,6 +1,111 @@
 import { Scalar, FormulaError, IRange } from '@sheetxl/primitives';
 import { ISpatialMap } from '../../collections';
 import { PrecedentSpatialValue, FormulaSpatialValue } from '../spatial';
+/**
+ * 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 {
+    /**
+     * 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}.
+     */
+    spillDependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
+    /**
+     * 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.
+     */
+    spillRowEnd: number;
+    spillColEnd: number;
+    /**
+     * The extent of the array-entered (Ctrl+Shift+Enter) block this node anchors, or `null` for an
+     * ordinary formula. Absolute, unscoped.
+     *
+     * @remarks
+     * 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.
+     */
+    fixedRef: IRange.Coords | null;
+    pendingPromise: Promise<any> | null;
+    /**
+     * The demand evaluation's result — finalized for the cell, or a pending promise — which
+     * `doEvaluate` consumes in place of an `evaluateAt` of its own. Cleared once consumed.
+     * Meaningful only while `CalcState.Circular` is set.
+     */
+    demandValue: any;
+    /**
+     * Identifies the cycle a `CycleRole.Member` belongs to (and the one a `CycleRole.Downstream`
+     * node read). `0` for none. Slices that share a node share an id. Reset every mark phase.
+     */
+    cycleGroup: number;
+    /**
+     * For a `CycleRole.Member`: the member this one READ that continues the cycle — the next step
+     * of the walk `ICircularReference.getPath` answers. A cycle of one points at itself. Written
+     * from the `Circular` slice (whose stack order is the read order) and rewritten whenever the
+     * cycle is detected again; stale otherwise, so a walk checks each step is still a live member.
+     */
+    cycleNext: CalcNode | null;
+    /**
+     * 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
+     * `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;
@@ -16,21 +121,41 @@ export interface CalcNode {
      */
     dependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
     /**
-     * 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.
+     * 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.
      */
-    inputs: (Scalar | IRange | IRange.Coords | undefined)[];
+    inputsAt: number;
     /**
-     * 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.
+     * 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)[];
+    precedents: (IRange.Coords | FormulaError.Known)[] | null;
     /**
      * The cached value of the cell after evaluation.
      *
@@ -38,31 +163,32 @@ export interface CalcNode {
      * This is `undefined` if not calculated.
      */
     cachedValue: Scalar | IRange | undefined;
-    pendingPromise: Promise<any> | null;
     /**
-     * The demand evaluation's result — finalized for the cell, or a pending promise — which
-     * `doEvaluate` consumes in place of an `evaluateAt` of its own. Cleared once consumed.
-     * Meaningful only while `CalcState.Circular` is set.
+     * 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.
      */
-    demandValue: any;
+    numFmt: string | null;
     /**
-     * Identifies the cycle a `CycleRole.Member` belongs to (and the one a `CycleRole.Downstream`
-     * node read). `0` for none. Slices that share a node share an id. Reset every mark phase.
+     * 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
+     * plan id and the container's static epoch; `-1` until first stamped.
      */
-    cycleGroup: number;
+    orderIndex: number;
     /**
-     * For a `CycleRole.Member`: the member this one READ that continues the cycle — the next step
-     * of the walk `ICircularReference.getPath` answers. A cycle of one points at itself. Written
-     * from the `Circular` slice (whose stack order is the read order) and rewritten whenever the
-     * cycle is detected again; stale otherwise, so a walk checks each step is still a live member.
+     * Id of the Kahn pass that stamped {@link orderIndex}; `0` = never stamped. Stamps from
+     * different passes are NOT mutually comparable — the fast path requires every affected node to
+     * carry the executor's `_lastPlanId`.
      */
-    cycleNext: CalcNode | null;
+    planId: number;
+    /** The container's `staticEpoch` when {@link orderIndex} was stamped; stale under a newer epoch. */
+    planEpoch: number;
     /**
-     * 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}.
+     * The container's `precedentEpoch` when {@link dependents} was last computed
+     * (CALC-PERFORMANCE-PLAN.md §1.3). Discovery reuses the cached array while this matches;
+     * `0` = never computed.
      */
-    shownGroup: number;
+    dependentsEpoch: number;
     /**
      * Bit mask, laid out by `CalcState`: the pending flags, `Skip`, `Circular`, and the
      * `DemandState`/`CycleRole` fields of the current pass.
@@ -74,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,43 @@ 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`), a position (`getRow`, `getColumn`, `getFormulaAt`,
+     * `getSheetIndex`, a reference's `getCoords`), 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;
+    /**
+     * 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,8 @@ export declare const CalcState: {
      */
     readonly Circular: number;
     /**
-     * A `Waiting` node the evaluation in progress has read under iterative calculation — it is in
+     * 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 +52,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

@@ -1,4 +1,4 @@
-import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IRuntime } from '@sheetxl/primitives';
+import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IFunctionArguments, IRuntime } from '@sheetxl/primitives';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../../transaction';
 import { IFunctionCollection } from '../../scripting';
@@ -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 something PER CELL — a position — so its
+     * answer cannot stand in for another cell's (`CalcScope.perCellRead`). 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;
@@ -99,22 +111,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,13 +185,15 @@ 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.parseAsLiteral */
     parseAsLiteral(text: string): boolean | FormulaError.Known | undefined;
     /** @inheritdoc IFormulaContext.toText */
     toText(value: Scalar | undefined): string;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.getArgs */
+    getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }