@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -0,0 +1,205 @@
+import { IRange, FormulaError, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { IListener } from '../../listener';
+import { ListenerEmitter } from '../../listener/ListenerEmitter';
+import { Tuple, ISpatialQuery, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
+import { IContextContainer, CalcNode } from '../state';
+import { SpillEntry, FormulaSpatialValue, ContentfulSpatialValue, PrecedentSpatialValue } from '../spatial';
+import { IFormulaBlock } from '../formula';
+import { ReferenceCoords } from '../Types';
+import { ICalculation } from '../ICalculation';
+import { ICalcGrid } from './ICalcGrid';
+/**
+ * ICalcGrid implementation
+ */
+export declare class CalcGrid implements ICalcGrid {
+    /**
+     * This is MOSTLY set by the user but spills also contribute.
+     * * Trying to keep lookups to a bare minimum.
+     */
+    _values: ISparseGrid<Scalar>;
+    _spillSpatial: ISpatialMap<SpillEntry>;
+    _errorSpatial: ISpatialMap<string>;
+    _pendingSpatial: ISpatialMap<boolean>;
+    _contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
+    _notifyValues: ISpatialMap;
+    _notifySpillsInsert: ISpatialMap.Entry<SpillEntry>[];
+    _notifySpillsRemove: IRange.Coords[];
+    _notifyFormats: ISpatialMap;
+    _notifyPending: ISpatialMap<boolean>;
+    _cloneKey?: CalcGrid;
+    _version: number;
+    _iterationId: number;
+    _gridId: string;
+    _options: CalcGrid.ConstructorOptions;
+    _getEntireCoords: () => IRange.Coords;
+    /**
+     * @see CalcGrid.ConstructorOptions.unanchored
+     */
+    readonly _unanchored: boolean;
+    _container: IContextContainer;
+    _context: IFormulaContext;
+    _calculation: ICalculation | null;
+    protected _emitter: ListenerEmitter<ICalcGrid, ICalcGrid.IListeners> | null;
+    protected _isProcessingJSON: boolean;
+    protected _onCalculated: (results: ICalcGrid.Results) => void;
+    constructor(options?: CalcGrid.ConstructorOptions);
+    /** @inheritdoc ICalcGrid.beginUpdates */
+    beginUpdates(): ICalcGrid.IncrementalUpdates;
+    /** {@inheritDoc ICalcGrid.calculate} */
+    calculate(full?: boolean): Promise<ICalculation.Status>;
+    /** {@inheritDoc ICalcGrid.addListeners} */
+    addListeners(listeners: ICalcGrid.IListeners, options?: IListener.Options): IListener.Remove;
+    /** @inheritdoc ICalcGrid.clone */
+    shift(options: ICalcGrid.ShiftOptions): this;
+    /** @inheritdoc ICalcGrid.clone */
+    clone(cloneKey?: any): this;
+    /** @inheritdoc ICalcGrid.setInputs */
+    setInputs(values: Tuple.BoundedTuples<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null): IRange.Coords[];
+    /** {@inheritDoc ICalcGrid.remove} */
+    remove(range: IRange.Coords): IRange.Coords[];
+    /** {@inheritDoc ICalcGrid.autoFill} */
+    autoFill(template: IRange.Coords | string, destination: IRange.Coords | string): this;
+    /** {@inheritDoc ICalcGrid.getEntireCoords} */
+    delete(): void;
+    /** {@inheritDoc ICalcGrid.markDirtyRegion} */
+    markDirtyRegions(coords: IRange.Coords[]): void;
+    /** @inheritdoc ICalcGrid.getId */
+    getId(): string;
+    /** {@inheritDoc ICalcGrid.getEntireCoords} */
+    getEntireCoords(): IRange.Coords;
+    /** {@inheritDoc ICalcGrid.getBoundingRange} */
+    getBoundingRange(): IRange.Coords | null;
+    /** @inheritdoc ICalcGrid.getValues */
+    getValues(): ISparseGrid<Scalar>;
+    /** {@inheritDoc ICalcGrid.getDirtyRegions} */
+    getDirtyRegions(): ISpatialQuery;
+    /** {@inheritDoc ICalcGrid.getFormulas} */
+    getFormulas(): ISpatialQuery<IFormulaBlock>;
+    /** {@inheritDoc ICalcGrid.getSnapshot} */
+    getSnapshot(options?: ICalcGrid.GetSnapshotOptions): ICalcGrid.ISnapshot;
+    /** {@inheritDoc ICalcGrid.getDirectDependentsAt} */
+    getDirectDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /** {@inheritDoc ICalcGrid.getDirectPrecedentsAt} */
+    getDirectPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    /**
+     * One hop of a transitive walk, taken on whichever GRID the coord names.
+     *
+     * @remarks
+     * `getDirect*At` are grid-local by construction — they search their own grid and answer with
+     * `scope` set only where a neighbor is elsewhere. A walk therefore cannot keep asking `this`:
+     * once it steps onto `Sheet2!C3` the next hop belongs to Sheet2, and asking Sheet1 for `C3`
+     * reads a different cell entirely. Results come back bare-relative to the grid that produced
+     * them, so they are re-expressed against the walk's own anchor before being handed back.
+     * @internal
+     */
+    private _directAcrossGrids;
+    /** {@inheritDoc ICalcGrid.getDependentsAt} */
+    getDependentsAt(coords: IRange.Coords): IRange.Coords[];
+    /** {@inheritDoc ICalcGrid.getPrecedentsAt} */
+    getPrecedentsAt(coords: IRange.Coords): IRange.Coords[];
+    /** {@inheritDoc ICalcGrid.getFormulaBlockAt} */
+    getFormulaBlockAt(row: number, column: number): IFormulaBlock | null;
+    /** {@inheritDoc ICalcGrid.getReferencesAt} */
+    getReferencesAt(row: number, column: number): ReferenceCoords[];
+    /** {@inheritDoc ICalcGrid.setReferenceAt} */
+    setReferenceAt(row: number, column: number, index: number, precedent: IRange.FixableCoords | IRange.FixableCellCoords | FormulaError.Ref): this;
+    /** {@inheritDoc ICalcGrid.isVolatileAt} */
+    isVolatileAt(row: number, column: number): boolean;
+    protected _formulaAt(row: number, column: number): ISpatialMap.Entry<FormulaSpatialValue> | null;
+    /**
+     * Create non error spill entries for move/copy.
+     */
+    protected _createCopySpillEntries(spillSpatial: ISpatialMap<SpillEntry>, from: IRange.Coords, to: IRange.Coords, reuseInserts?: ISpatialMap.Entry<SpillEntry>[] | null, reuseRemoves?: ISpatialMap.Entry<SpillEntry>[] | null): ISpatialMap.Updates;
+    /**
+     * Because the formula we are copying from maybe have been compiled using
+     * a different calculation context we have to serialize back to the formula string.
+     *
+     * @param gridExplicitId The grid context to compile in AND the scope prefix added to unqualified refs.
+     *   For formula-move: the source grid (refs get source-grid prefix). For precedent-move: the
+     *   destination grid (refs get destination-grid prefix).
+     * @param targetScope If provided, the formula entry scope after re-anchoring. Defaults to this._gridId.
+     *   Use from.scope when re-anchoring formulas that stay in the source sheet.
+     *
+     * @remarks
+     * This modifies the insert in place.
+     */
+    protected _reanchorFormulas(inserts: ISpatialMap.Entry<FormulaSpatialValue>[], gridExplicitId?: string | null, targetScope?: string | null, force?: boolean): void;
+    /**
+     * Will copy tiles and invalidate relative precedents that are out
+     * of bounds.
+     */
+    protected _copyTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
+    /**
+     * Will update absolute precedents from precedentEntries relative precedents get shifted
+     */
+    protected _moveTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
+    protected _notifyCalculated(cycleId: number, options: ICalculation.CalculateOptions | boolean): Promise<ICalcGrid.Results>;
+    protected _setInputs(values: Tuple.BoundedTuples<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[] | null, deleteRange?: IRange.Coords): IRange.Coords[];
+    /**
+     * Used before loading a new state
+     */
+    protected _clearAll(): void;
+    /** {@inheritDoc ICalcGrid.fromJSON} */
+    fromJSON(json: ICalcGrid.JSON, options?: ICalcGrid.FromJSONOptions): ICalcGrid.Results | undefined;
+    /** {@inheritDoc ICalcGrid.fromJSON} */
+    toJSON(options?: ICalcGrid.ToJSONOptions): Promise<ICalcGrid.JSON | null>;
+}
+export declare namespace CalcGrid {
+    /**
+     * Options available when creating a CalcGrid.
+     */
+    interface ConstructorOptions {
+        /**
+         * The calculation instance that will be used to calculate the grid.
+         *
+         * @remarks
+         * Required as this will contain the context
+         */
+        context: IFormulaContext;
+        /**
+         * handler for calculation callbacks.
+         *
+         * @remarks
+         * The container contains information shared across all grids
+         */
+        container: IContextContainer;
+        /**
+         * For status listening
+         */
+        calculation: ICalculation | null;
+        /**
+         * A callback that is called when the calculation is completed.
+         *
+         * @remarks
+         * This will persist through clones.
+         */
+        onCalculated?: (results: ICalcGrid.Results) => void;
+        /**
+         * A unique id that never changes for the grid.
+         */
+        uuid?: string;
+        /**
+         * Returns the entire coordinate bounds for this grid.
+         * If not provided, defaults to the maximum sheet dimensions.
+         */
+        getEntireCoords?: () => IRange.Coords;
+        /**
+         * `true` for a grid whose coordinates are a synthetic anchor rather than positions in a real
+         * sheet — a named formula's compilation host, or the editor's temporary formula.
+         *
+         * @remarks
+         * Stamped onto every {@link FormulaSpatialValue} this grid creates; see
+         * `FormulaSpatialValue.unanchored` for what it buys. Defaults to `false` (a sheet).
+         */
+        unanchored?: boolean;
+    }
+}
+interface CalcGridSnapshot {
+    calcGrid: CalcGrid;
+    formulaSpatial: ISpatialMap3D<FormulaSpatialValue>;
+    precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>;
+    volatile: Set<CalcNode> | null;
+}
+export declare function valueCompareValues<T>(a: ISpatialMap.Entry<T>, removing: ISpatialMap.Entry<T>): boolean;
+export {};
+//# sourceMappingURL=CalcGrid.d.ts.map

package/types/src/calculation/grid/CalcGridUtils.d.ts

@@ -0,0 +1,172 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { Tuple, ISparseGrid, ISpatialMap, ISpatialMap3D } from '../../collections';
+import { CalcNode } from '../state';
+import { ContentfulSpatialValue, FormulaSpatialValue, SpillEntry, PrecedentSpatialValue, PrecedentKind } from '../spatial';
+import { ReferenceCoords } from '../Types';
+export declare function anchorCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
+/**
+ * Returns true if `coords` is top left.
+ *
+ * @param rowIndex the row index to compare
+ * @param colIndex the column index to compare
+ * @param range The range to compare
+ */
+export declare function isTopLeft(rowIndex: number, colIndex: number, range: IRange.Coords): boolean;
+/**
+ * Updates contentful and invalidates spills.
+ *
+ * @remarks
+ * This code will inline spill errors but spill results are handled in calculations.
+ */
+export declare function applyContentful(cycleId: number, removes: readonly IRange.Coords[] | null | undefined, inserts: ISpatialMap.Entry[] | null | undefined, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, addDirty?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void, notifyValuesSpatial?: ISpatialMap, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, notifyPending?: ISpatialMap<boolean>, errorSpatial?: ISpatialMap<string>, // notifyErrorSpatial,
+isColumn?: boolean, notifyCalc?: boolean): IRange.Coords | null;
+/**
+ * Creates a map from tuples
+ *
+ * @remarks
+ * This is here because of the ILikeLike dependency.
+ */
+export declare function tuplesToA1Map<T = any>(boundedTuples: Tuple.BoundedTuples<T> | undefined, axis?: IRange.Axis): Map<string, T>;
+/**
+ * Utility used by fromJSON hydration to build the initial dynamic precedent entries for
+ * spill ranges loaded from saved state. Distinct from `container.addDynamicPrecedent`,
+ * which is live-cycle only; this version accumulates into a caller-owned map so the entries
+ * can be bulk-loaded into precedentSpatial in one pass.
+ *
+ * @remarks
+ * Keyed by block and unioned per (block, kind) exactly as the live path does, because that is the
+ * shape the dynamic registry (`IContextContainer.getDynamics`) can express. Anything that replaces
+ * a block — an edit, a named recompile — evicts its dynamics through that map, so a block holding
+ * an unregistered entry would leave it behind in precedentSpatial pointing at the dead block. The
+ * dirty walk still reaches it, collects the dead block's CalcNodes alongside the live replacement's,
+ * and the value builder then sees one cell pushed twice (`OutOfOrderError`).
+ */
+export declare function addDynamicPrecedent(entries: Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>, node: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+/**
+ * Resolves the per-endpoint `$` anchoring of one precedent.
+ *
+ * @remarks
+ * `resolvedPrecedentsAt` reports one flag per AXIS, set when EITHER endpoint is anchored, so it
+ * cannot tell `$A$1:A1` (pinned start, sliding end) from a fully pinned range — see
+ * {@link PrecedentSpatialValue} for what that costs. The stored reference carries the endpoints
+ * separately, and its index space is the one `shiftPrecedents` already feeds back to
+ * `setReferenceAt`, so it can be read alongside the resolved precedent at the same index.
+ *
+ * The refinement is taken only where both sources agree the axis carries SOME anchoring. Anything
+ * else — a named body's precedents, a computed operand, an index the stored list cannot answer for
+ * — keeps the axis flag on both endpoints, which is what the code did before. So a reference that
+ * is wholly relative or wholly anchored resolves exactly as it always has, and only a mixed one
+ * moves.
+ */
+export declare const resolveEndpointAbs: (reference: ReferenceCoords | undefined, $absHorz: boolean, $absVert: boolean, out?: EndpointAbs) => EndpointAbs;
+export interface EndpointAbs {
+    $absColStart: boolean;
+    $absColEnd: boolean;
+    $absRowStart: boolean;
+    $absRowEnd: boolean;
+}
+/**
+ * TODO - CalcGrid.fromJSON has this code
+ */
+export declare function addPrecedents(asEntry: ISpatialMap.Entry<FormulaSpatialValue>, precedentsInsert: ISpatialMap.Entry<PrecedentSpatialValue>[], precedentsRet?: IRange.Coords[] | null): void;
+export interface PrecedentFormulaUpdates {
+    precedents: ISpatialMap.Updates<PrecedentSpatialValue>;
+    formulas: ISpatialMap.Updates<FormulaSpatialValue>;
+}
+/**
+ * Splits precedents at the insertion boundary.
+ *
+ * @remarks
+ * For insert operations: splits at the single edge where the insertion occurs so that
+ * the portion at/after the insertion point can be shifted independently.
+ *
+ * Because precedents hold a back pointer to the formula entry the formula entries will also be split.
+ *
+ * INVARIANT: All resulting formula entries must have logically identical formulas.
+ * The split only divides the spatial extent — it never changes what the formula computes.
+ */
+export declare function splitPrecedentsInsert(precedents: ISpatialMap3D<PrecedentSpatialValue>, coords: IRange.Coords): PrecedentFormulaUpdates | null;
+/**
+ * Splits precedents at both edges of a delete range, with per-row splitting
+ * in partial-overlap zones.
+ *
+ * @remarks
+ * For delete operations, the split is more complex than insert because cells
+ * in "partial-overlap zones" each receive a different amount of shrinkage from
+ * shiftPrecedents. Each such cell must end up in its own single-row (or single-col)
+ * block so that shiftPrecedents can apply the correct clamped delta.
+ *
+ * Zones (row axis, offset r = formula-block-relative row):
+ * - Fully-before: natural range entirely above delete → no change
+ * - Partial-start: natural range straddles delete start → per-row split required
+ * - Fully-inside: natural range entirely within delete → becomes #REF!
+ * - Partial-end: natural range straddles delete end → per-row split required
+ * - Fully-after: natural range entirely below delete → uniform shift
+ *
+ * INVARIANT: All resulting formula entries must have logically identical formulas.
+ */
+export declare function splitPrecedentsDelete(precedents: ISpatialMap3D<PrecedentSpatialValue>, coords: IRange.Coords): PrecedentFormulaUpdates | null;
+/**
+ * Splits precedents at the cut boundary to isolate the moveable sub-block.
+ *
+ * @remarks
+ * For move operations: isolates the sub-block of formula cells whose natural bounds
+ * are fully enclosed by the move coords. The inner piece will be moved; outer pieces stay.
+ *
+ * Natural bounds = the precedent size for a single formula cell.
+ * A formula cell at block-relative offset `r` has natural row range:
+ *   `[P.rowStart + r, P.rowStart + r + nh - 1]`
+ * where `nh = (P.rowEnd - P.rowStart) - (F.rowEnd - F.rowStart) + 1`.
+ *
+ * Excel rule: only move if the natural bounds fit entirely within the cut rect.
+ *
+ * INVARIANT: All resulting formula entries must have logically identical formulas.
+ */
+export declare function splitPrecedentsMove(precedents: ISpatialMap3D<PrecedentSpatialValue>, coords: IRange.Coords): PrecedentFormulaUpdates | null;
+/**
+ * This shifts precedents that cross an intersection boundary.
+ *
+ * @remarks
+ * These should be pre-split
+ * This does not shift the spatial coordinates just the dependency offsets
+ * Checks if out of bounds
+ *
+ * @param precedents The precedent spatial map
+ * @param getDynamicPrecedents A function that returns a map of
+ * @param searchRange The range to search for precedents (may be extended to entireCoords for delete)
+ * @param shiftBy How much to shift each axis (negative = delete, positive = insert)
+ * @param deleteZone For delete operations: the actual delete zone coords (narrower than searchRange).
+ *   Used for #REF! checks. For insert operations, pass undefined — the searchRange is used instead.
+ */
+export declare function shiftPrecedents(getPrecedentSpatial: () => ISpatialMap3D<PrecedentSpatialValue>, getDynamicPrecedents: () => Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>, searchRange: IRange.Coords, shiftBy: IRange.CellCoords, deleteZone?: IRange.Coords): PrecedentFormulaUpdates | null;
+/**
+ * Updates precedent references for formulas OUTSIDE the move range
+ * whose precedent points INTO the moved region.
+ *
+ * @remarks
+ * Pre-condition: splitPrecedentsCut has already been applied so no precedent straddles the boundary.
+ * After split, each precedent is either fully inside or fully outside the `from` region.
+ *
+ * For a move (cut+paste), the data moves rigidly from `from` to `to`.
+ * Both edges of the precedent shift by the same delta — a uniform translation.
+ *
+ * Formulas inside the move range are skipped (they move with their data).
+ */
+export declare function movePrecedents(precedentSpatial: ISpatialMap3D<PrecedentSpatialValue>, getDynamicPrecedents: () => Map<FormulaSpatialValue, ISpatialMap.Entry<PrecedentSpatialValue>[]>, from: IRange.Coords, to: IRange.Coords): PrecedentFormulaUpdates | null;
+/**
+ * TODO - document and/or rationalize with visitDependencyBlock
+ */
+export declare const visitPrecedentBlock: (entryBlock: ISpatialMap.Entry<FormulaSpatialValue>, intersect: IRange.Coords, callbackFn: (calc: CalcNode, rowIndex: number, colIndex: number) => void) => void;
+/**
+ * Finds all spills that intersect a range and removes them for operations.
+ *
+ * restore will behave differently depending on the top/left.
+ *
+ * Outside of intersect: restore will put back to original location.
+ * Inside intersect: Restore will either discard to move to restore Location if provided
+ *
+ * @returns a `restore` function or `null` that will restore spills.
+ */
+export declare function markFixedSpills(intersect: IRange.Coords, spillSpatial: ISpatialMap<SpillEntry>, values: ISparseGrid<Scalar>, contentfulSpatial: ISpatialMap<ContentfulSpatialValue>, notifySpills?: (insert: ISpatialMap.Entry<SpillEntry>, remove: ISpatialMap.Entry<SpillEntry>) => void, isRow?: boolean, skipInsideAnchor?: boolean, notifyValues?: ISpatialMap, addDirtyOnRestore?: (colStart: number, rowStart: number, colEnd: number, rowEnd: number) => void): ((isInsert?: boolean, deltaRowIndex?: number, deltaColIndex?: number) => void) | null;
+export declare function valueCompareValues<T>(a: ISpatialMap.Entry<T>, removing: ISpatialMap.Entry<T>): boolean;
+//# sourceMappingURL=CalcGridUtils.d.ts.map