@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,440 @@
+import { IRange, IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+import { FunctionProvider } from '@sheetxl/scripting';
+import { AbstractModel, IModel } from '../model';
+import { IStringCollection } from '../string';
+import { IFunctionCollection } from '../scripting';
+import { ISpatialMap, ISpatialMap3D } from '../collections';
+import { INamed, INamedCollection } from '../named';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { FormulaBlockResolvers } from './formula';
+import { IFormulaCompiler } from './compiler';
+import { CalculationContext, IContextContainer, CalcNode } from './state';
+import { FormulaSpatialValue, PrecedentSpatialValue } from './spatial';
+import { CalcGrid, ICalcGrid } from './grid';
+import { CalcExecutor } from './executor';
+import { ICalculation } from './ICalculation';
+import { NamedFormulaCollection } from './NamedFormulaCollection';
+import { INamedFormulasCollection } from './INamedFormulasCollection';
+/**
+ * Implementation for {@link ICalculation}.
+ */
+export declare class Calculation extends AbstractModel<State, ICalculation.JSON, CommitView, ICalculation.IListeners> implements ICalculation {
+    protected _container: IContextContainer;
+    protected _context: CalculationContext & IFormulaContext;
+    protected _status: ICalculation.Status;
+    protected _statusTransition: Promise<void> | null;
+    protected _runtime: IRuntime;
+    protected _functions: IFunctionCollection;
+    protected _namedFormulas: NamedFormulaCollection;
+    /** `json.names` held from construction until {@link hydrateNames} — see it for why. */
+    protected _pendingNames: INamed.JSON[] | null;
+    protected _compiler: IFormulaCompiler;
+    protected _compilerEditing: IFormulaCompiler;
+    protected _compilerEditingSig: string;
+    protected _compilerModule: typeof import('./compiler/FormulaCompiler');
+    protected _getActiveCell: () => IRange.CellCoords | null;
+    protected _getRange: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
+    protected _getRanges: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
+    protected _calcExecutor: CalcExecutor;
+    protected _cycleId: number;
+    protected _volatiles: Set<CalcNode>;
+    protected _calculatedCommitId: string | null;
+    protected _pendingActions: (() => Promise<unknown>)[] | null;
+    protected _pendingPriority: (() => Promise<unknown>)[] | null;
+    protected _draining: boolean;
+    protected _drainScheduled: boolean;
+    protected _removeNamedItemsListeners: (() => void) | null;
+    protected _namedDependents: Map<string, IRange.Coords[]> | null;
+    protected _namedDependentsOf: ISpatialMap3D<FormulaSpatialValue> | null;
+    /**
+     * Resolver callbacks passed to every {@link FormulaBlock} at creation time.
+     * Populated from {@link Calculation.ConstructorOptions} during `_initialize`.
+     */
+    protected _resolvers: FormulaBlockResolvers | null;
+    constructor(options?: Calculation.ConstructorOptions);
+    protected _initialize(options?: Calculation.ConstructorOptions): void;
+    /**
+     * Reverse-invalidates only the formulas that reference any of `changedIds` — the stable name/table
+     * fake ids reported by `IndirectSymbolProvider.reconcile()` (add/heal, delete, rename).
+     *
+     * @remarks
+     * Replaces the old `isFullCalcRequired` blanket. `bind()` assigns a stable fake id at compile time
+     * regardless of whether the symbol resolves, and reconcile() reports that same id — so matching a
+     * formula's `getReferencedSymbolIds()` catches the "heal" case (`#NAME?`/`#REF!` → valid) that a
+     * precedent-range markDirty can't, because an unresolved reference has no precedent range.
+     *
+     * Marking the direct referencers is not enough where the referencer is another NAME. Downstream
+     * of a cell, the dependency graph carries transitivity for free; downstream of a name it carries
+     * nothing, because a name registers no precedent range for the formulas that mention it. So the
+     * ids are first expanded over the symbol graph ({@link _namedTargets}), and only from the cells
+     * that land in are the ordinary edges left to do the rest.
+     *
+     * O(formulas) all3D scan — same cost/scale as `recompileNamed`.
+     *
+     * @returns `true` if any formula was marked dirty.
+     */
+    protected _markDirtyReferencing(changedIds: Set<string>): boolean;
+    /**
+     * {@inheritDoc IContextContainer.getNamedDependents}
+     *
+     * @remarks
+     * The memo is keyed on the formula spatial's IDENTITY, which is the whole invalidation story:
+     * the map is copy-on-write (`getFormulas().clone()` before any mutation, `setFormulas` to
+     * publish), so a formula added, removed, shifted or recompiled necessarily replaces it — and an
+     * undo, which restores an earlier map, replaces it too. Nothing has to remember to clear this.
+     *
+     * The sweep is the same `all3D` walk `recompileNamed` and {@link _markDirtyReferencing} already
+     * do, done once for every name instead of once per name.
+     */
+    protected _getNamedDependents(nameId: string): readonly IRange.Coords[];
+    /**
+     * {@inheritDoc IContextContainer.getNamedDependentNames}
+     *
+     * @remarks
+     * A block that depends on a name and lives on a VIRTUAL grid is another name's BODY, and that
+     * grid's id is that name's id — `add` binds the two together and `delete` keeps the grid rather
+     * than dropping it. So the hop is a bucket lookup on the id itself; a sheet grid id is never a
+     * name id, which is what {@link NamedFormulaCollection.getById} is asked to confirm before the
+     * walk continues through one.
+     *
+     * Expands each id once. That is the cycle guard (`A = B+1`, `B = A+1` reaches `A` again on its
+     * second hop) and the diamond guard both.
+     */
+    protected _getNamedDependentNames(nameId: string): ReadonlySet<string>;
+    /**
+     * `changedIds` widened to everything a change to them reaches through the SYMBOL graph: each id
+     * plus, for the names among them, every name transitively referencing it.
+     *
+     * @remarks
+     * The one expansion both `recompileNamed` and {@link _markDirtyReferencing} apply before their
+     * all3D scan, so a formula naming an intermediate name is matched by the same pass that matches
+     * one naming the changed name directly. Ids that are not names (a table's) expand to themselves.
+     */
+    protected _namedTargets(changedIds: Set<string>): ReadonlySet<string>;
+    /** @inheritdoc ICalculation.start */
+    start(): Promise<void>;
+    /**
+     * Queues an action to run at the next safe point, and schedules that point.
+     *
+     * @remarks
+     * Callers need no precondition: queuing schedules its own drain. There is no state the engine can
+     * be in where an action queued here is silently dropped.
+     *
+     * - `Starting` — held for `start()`'s drain, which always follows and loops until empty.
+     * - Inside a drain — picked up by the loop already running.
+     * - `Ready` and settled — a microtask drain is posted (see {@link _scheduleDrain}).
+     *
+     * That last case is why this is no longer called `whenStarting`. It only ever handled work that
+     * arrived while starting: queuing scheduled nothing, and the array was pumped as a side effect of
+     * `start`/`ready`/`calculate` — so an action queued on a settled engine waited for a calculation
+     * that might never come and was dropped for the life of the workbook, not merely run late. Since
+     * any cell write drains as a side effect of `Sheet._calculate`, that failed only for changes that
+     * write no cells: `recompileNamed` after defining a name nothing yet references left
+     * `A1 = SUM(Sales)` at `#NAME?` indefinitely.
+     *
+     * What callers still owe: an action must be safe to run at an arbitrary microtask boundary, not
+     * only inside a calculation. The drain is a safe point, not a synchronization point.
+     */
+    _whenSafe(action: () => Promise<unknown>, priority?: boolean): void;
+    /**
+     * Posts a microtask drain, if one is not already coming.
+     *
+     * @remarks
+     * A no-op in the two cases where a drain is already guaranteed to reach this action:
+     *
+     * - not `Ready` — `start()` drains at the tail of its transition, and does so inline so
+     *   `await start()` covers the queued work. Posting here would race that.
+     * - already draining — `_drainPending` loops until the queue is empty, so an action appended
+     *   during a drain is picked up by the pass in flight.
+     *
+     * A microtask rather than a task: it is the earliest point at which the synchronous work that
+     * queued the action (a commit, a name definition) has finished, which is the whole reason these
+     * actions are deferred at all. Waiting for a macrotask would leave the workbook observably wrong
+     * across a turn of the event loop for no gain.
+     */
+    protected _scheduleDrain(): void;
+    /**
+     * A drain with nothing after it: the queue, then the calculation the queue is owed.
+     *
+     * @remarks
+     * Every other drain site is *followed* by a calculation — that is what a drain site was. The
+     * queue was only ever pumped by `start`/`ready`/`calculate`, so an action always ran with a pass
+     * behind it, and could dirty freely knowing something would pick it up. `recompileNamed` is built
+     * on exactly that: it re-derives its dependents by writing their formula text back through
+     * `grid.setInputs`, which marks dirty and stops there. Unlike a cell write there is no sheet layer
+     * above it to notice and call `calculate()` (`Sheet._calculate`).
+     *
+     * So a drain that nothing scheduled a calculation for has to be the whole unit, or it is not a
+     * faithful substitute for the drain an action used to get: the repro recompiles against the newly
+     * wired name and still displays the `#NAME?` it evaluated to before.
+     *
+     * This is deliberately not folded into {@link _drainPending}. The other three sites would then
+     * calculate twice, and `start()` would calculate mid-load — which is the thing `isLoading()`
+     * exists to prevent.
+     */
+    protected _drainStandalone(): Promise<void>;
+    /**
+     * Runs queued actions until the queue is empty. The one drain, used by every site that drains.
+     *
+     * @remarks
+     * Draining only runs the actions. Something has to calculate what they dirtied, and each of the
+     * four sites answers that for itself: `_calculate` runs the pass it drained for, `ready()`
+     * calculates its dirty grids, `start()` leaves it to the load path, and the microtask drain has
+     * nothing after it so it calculates itself ({@link _drainStandalone}).
+     *
+     * Loops rather than taking a single snapshot, because a drained action can enqueue more: wiring a
+     * name enqueues the `recompileNamed` that re-derives its dependents' precedents. A snapshot pass
+     * left that follow-up for whoever drained next, so a formula referencing a name wired in the same
+     * pass evaluated against a not-yet-compiled body and stuck at `#NAME?`. `ready()` had exactly that
+     * shape, and got away with it only because it goes on to call `grid.calculate()` per dirty grid —
+     * which loop-drains. It held if something was dirty and did not if nothing was.
+     *
+     * `_draining` is restored rather than cleared, so a nested drain (an action that calculates)
+     * leaves the outer one's window intact.
+     *
+     * **Call this under `if (this._pendingActions?.length)`, not unconditionally.** `await` on an
+     * async call yields to the microtask queue even when the callee does nothing, and a calculation
+     * with an empty queue has no other await in it — it runs to completion synchronously, so a
+     * `setValue` is followed by a `getValue` that reads the calculated value with nothing awaited in
+     * between. An unconditional drain here pushes the whole pass past a microtask boundary and that
+     * read returns the raw text instead (`use-signs.test.ts`).
+     */
+    protected _drainPending(): Promise<void>;
+    /** @inheritdoc ICalculation.calculate */
+    calculate(options?: ICalculation.CalculateOptions | boolean): Promise<ICalculation.Status>;
+    /**
+     * @returns The status the engine is in once the pass has run — `Starting` if the request was
+     *          deferred to the start-up drain, and whatever non-`Ready` status turned it away
+     *          otherwise. Never `undefined`: it used to resolve that on every path including the
+     *          successful one (the tail simply fell off the end), and two call sites cast the result
+     *          to `Status` to satisfy {@link ICalculation.calculate}.
+     */
+    protected _calculate(options?: ICalculation.CalculateOptions, gridId?: string): Promise<ICalculation.Status>;
+    protected _createCalcGrid(options?: CalcGrid.ConstructorOptions): ICalcGrid;
+    protected _registerGrid(grid: ICalcGrid): void;
+    protected _unregisterGrid(gridId: string): void;
+    /** @inheritdoc ICalculation.stop */
+    stop(): Promise<void>;
+    /** @inheritdoc ICalculation.getStatus */
+    getStatus(): ICalculation.Status;
+    /** @inheritdoc ICalculation.ready */
+    ready(options?: ICalculation.CalculateOptions): Promise<ICalculation.Status>;
+    /**
+     * The locale-aware editing compiler, (re)built when the workbook locale (separators, Plane 1) or
+     * active spreadsheet-language pack (boolean literals, Plane 3) has changed since it was last built.
+     * Only the editing path uses locale-specific separators; the calc path (`_compiler`) is always
+     * canonical because it only ever parses stored/API text.
+     */
+    protected _getEditingCompiler(): IFormulaCompiler;
+    /** @inheritdoc ICalculation.createFormula */
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    /** {@inheritDoc ICalculation.evaluate} */
+    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    /** @inheritdoc ICalculation.getFunctions */
+    getFunctions(): IFunctionCollection;
+    /** @inheritdoc ICalculation.getNamedFormulas */
+    getNamedFormulas(): INamedFormulasCollection;
+    /**
+     * Loads the `json.names` supplied at construction. Idempotent; a no-op when there were none.
+     *
+     * @internal
+     *
+     * @remarks
+     * Hydration has two preconditions, and the constructor can only meet one of them.
+     *
+     * 1. The named-formula symbol provider must be registered — `add()` binds each name the symbol id
+     *    that IS the virtual grid it compiles into, so hydrating earlier loads names that list but
+     *    never resolve. The constructor does satisfy this.
+     * 2. **The sheets must exist.** A name carries the scope it is private to, and that scope is a
+     *    SHEET, resolved to the sheet's stableId on the way in (see `NamedFormula.getScope`) so a
+     *    later rename carries it. `Workbook` builds its sheets *after* constructing the calculation,
+     *    so during the constructor the sheet lookup does not merely miss — it throws — and every
+     *    hydrated name would be left holding a display name that goes stale on the first rename.
+     *
+     * So the workbook calls this once its sheets are in place. A calculation constructed standalone
+     * (tests, a headless engine) has no sheets to wait for and hydrates at the tail of `start()`.
+     */
+    hydrateNames(): void;
+    /** @inheritdoc IFormulaContext.getRuntime */
+    getRuntime(): IRuntime;
+    protected _checkReady(): void;
+    protected _statusMessage(): string;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+/**
+ * Interfaces for creating `Calculation` items.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link Calculation}
+ */
+export declare namespace Calculation {
+    /**
+     * Options available when creating a Calculation Service.
+     */
+    interface ConstructorOptions extends IModel.ConstructorOptions<ICalculation.JSON> {
+        /**
+         * Callback for the runtime.
+         */
+        runtime?: IRuntime;
+        /**
+         * Additional custom formula function providers, bound after the built-ins (so they override
+         * built-ins on name collision). Each provider is the `initialize` binder produced by the
+         * FormulaCompiler (`@sheetxl/scripting`) for a folder of formula sources.
+         *
+         * @see {@link FunctionProvider}
+         */
+        functions?: readonly FunctionProvider[];
+        /**
+         * Returns the active cell — the current selection anchor — with its sheet id as `scope`.
+         * Supplies the default scope for temporary / named-formula resolution, and the default
+         * defining cell when a named formula is added without an explicit `cell` (mirrors Excel).
+         */
+        getActiveCell?: () => IRange.CellCoords | null;
+        /**
+         * Returns a sheet handle given an id.
+         */
+        /**
+         * `getRange`/`getRanges` are OPTIONAL and structural on purpose — this keeps `Calculation` decoupled
+         * from `ISheet` while letting a real sheet hand over its own address resolvers. A temporary formula
+         * anchored to that sheet uses them so an unscoped (same-sheet) reference resolves THERE rather than
+         * against the workbook's active sheet. See `createFormula`.
+         */
+        getSheetById?: (sheetId: string) => {
+            getId(): string;
+            getName(): string;
+            getEntireCoords: () => IRange.Coords | null;
+            getRange?: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
+            getRanges?: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
+        } | null;
+        /**
+         * Returns a sheet handle given a name.
+         */
+        getSheetByName?: (sheetName: string) => {
+            getId(): string;
+            getName(): string;
+            getEntireCoords: () => IRange.Coords | null;
+        } | null;
+        /**
+         * Named item collection shared with the workbook.
+         *
+         * @remarks
+         * Used to resolve table symbols (and later named formulas) by name and id.
+         * {@link IndirectSymbolProvider} subscribes to `onCollectionChange` to keep
+         * proxy references current and trigger dirty-marking of dependent formula nodes.
+         */
+        namedCollection?: INamedCollection;
+        /**
+         * Defined names to hydrate at construction, in `IWorkbook.JSON.names` form.
+         *
+         * @remarks
+         * The engine owns defined names, so they load directly here rather than into an
+         * `INamedCollection` that would then have to project them across. Taken at construction so the
+         * engine has no pre-load lifecycle state.
+         */
+        names?: INamed.JSON[];
+        /**
+         * A structural transform applied to each hydrated name's expression as it compiles — the READ
+         * half of the format-dialect hook (see `IWorkbook.ConstructorOptions.formulaTransform`).
+         * Applies only to {@link names}; formulas added later compile without it.
+         */
+        formulaTransform?: ICalculation.FormulaTransform;
+        getRanges?: (address: ICellRanges.Address, options?: ICellRange.GetRangeOptions) => ICellRanges;
+        getRange?: (address: ICellRange.Address, options?: ICellRange.GetRangeOptions) => ICellRange;
+        /**
+         * Builds ONE `ICellRanges` graph answer out of cell coords plus defined-name nodes.
+         *
+         * @internal
+         *
+         * @remarks
+         * The seam that keeps the layers apart: the calculation layer knows WHICH names belong in a
+         * precedents/dependents answer, the range layer knows how a name rides in one (an anchored
+         * `INamedRange` — see DESIGN-NAMED-FORMULAS.md §4). Structural like `getRange`/`getRanges`,
+         * and like them supplied by the workbook. Without it, graph answers fall back to cells only.
+         */
+        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+        getSheetIndex?: (sheetName?: string) => number;
+        getSheetCount?: () => number;
+        strings?: IStringCollection;
+        /**
+         * Whether to perform iterative calculations when there are circular dependencies.
+         *
+         * @defaultValue false
+         */
+        enableIterativeCalculations?: boolean;
+        /**
+         * The maximum number of iterations to perform when calculating.
+         *
+         * @defaultValue 100
+         */
+        maxIterations?: number;
+        /**
+         * The maximum change allowed between iterations when performing iterative calculations.
+         *
+         * @defaultValue 0.001
+         */
+        maxIterateChange?: number;
+    }
+}
+/**
+ * Transaction State for Calculation
+ */
+interface State extends AbstractModel.State {
+    /**
+     * Top down evaluation and marking dirty.
+     * This is the only spatial map that is completely updated via api.
+     *
+     * @remarks
+     * For top down evaluation and marking formulas dirty.
+     */
+    formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
+    /**
+     * Tracks the inputs to formulas.
+     *
+     * @remarks
+     * * For bottom up marking dirty.
+     * * Contains a back-pointer to the formula.
+     *
+     */
+    precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
+    /**
+     * Tracks dynamic precedents by block.
+     * Used to remove old dynamic precedents when a block is re-evaluated and to add new ones after evaluation.
+     */
+    dynamicByBlock: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>;
+    /**
+     * Dirty regions
+     */
+    dirtySpatial: ISpatialMap3D;
+    /**
+     * If true, the next calculation will be a full calc regardless of dirty state. Used for example when the engine detects a circular dependency and needs to fallback to iterative calculation or when the user explicitly requests a full calc.
+     */
+    isFullCalcRequired: boolean;
+    /**
+     * All registered grids.
+     */
+    gridsAll: Map<string, ICalcGrid>;
+    /**
+     * Listeners to individual named items
+     */
+    itemRemoveListeners: (() => void)[];
+    /**
+     * Indicates if calculation will do iterative calcs
+     */
+    iterate: boolean;
+    /**
+     * The maximum number of iterations to perform when calculating.
+     */
+    maxIterations: number;
+    /**
+     * The maximum change allowed between iterations when performing iterative calculations.
+     */
+    maxIterateChange: number;
+}
+interface CommitView extends AbstractModel.CommitView {
+}
+export {};
+//# sourceMappingURL=Calculation.d.ts.map

package/types/src/calculation/Calculation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Calculation.d.ts","sourceRoot":"","sources":["../../../../src/calculation/Calculation.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,18 @@
+import { Scalar } from '@sheetxl/primitives';
+/**
+ * Parses formula text that is exactly ONE literal — a number (optionally signed), a quoted
+ * string, `TRUE`/`FALSE`, or an error label — to its value.
+ *
+ * @param text The formula text, without a leading `=`.
+ * @returns The literal's value, or `undefined` when the text is anything else — a reference, a
+ * function call, an expression, or text that does not lex at all.
+ *
+ * @remarks
+ * Backed by the calculation compiler's own lexer and literal actions (canonical locale: `.`
+ * decimal, English booleans, canonical error labels), so what counts as a literal here is exactly
+ * what counts as one in a formula. The IO borders use this to fold OOXML `<formula>` operands
+ * (`cellIs` / data-validation bounds) into condition params — a parallel grammar that drifted
+ * from the compiler's would corrupt exactly the operands it was meant to preserve.
+ */
+export declare function parseFormulaLiteral(text: string): Scalar | undefined;
+//# sourceMappingURL=FormulaLiterals.d.ts.map

package/types/src/calculation/FormulaLiterals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormulaLiterals.d.ts","sourceRoot":"","sources":["../../../../src/calculation/FormulaLiterals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAOlD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA+CpE"}