@univerjs-pro/engine-formula 0.22.1 → 0.23.0

package/lib/types/engine/dependency-engine/dependency-engine.d.ts

@@ -0,0 +1,341 @@
+import type { CalcNodeIndex, CellId, DepList, ExternalNodeId, ICalcNodeDeps, ICalcNodeRef, ICalculationOrderResult, ICompressedSharedFormulaGroup, IDecodedCell, IDecodedFeatureCalculationId, IDecodedOtherFormulaId, IDependencyEngineOptions, IDynamicResolver, IRefRange, ISetNodeResult } from './types';
+import { CellCodec } from './cell-codec';
+import { RangeIndex } from './range-index';
+/**
+ * Incremental dependency cache for formula calculation.
+ *
+ * The public API accepts direct cells, ranges, and explicit calc-node
+ * dependencies. Internally the graph direction is always
+ * `precedent -> dependent`, which makes dirty propagation and topological
+ * sorting cheap after changes.
+ */
+export declare class DependencyEngine {
+    readonly codec: CellCodec;
+    private readonly _maxIndexedSpan;
+    private readonly _pointScanCellLimit;
+    private readonly _initialNodeCapacity;
+    private readonly _initialRangeCapacity;
+    /**
+     * Direct cell precedent -> dependent calculation nodes.
+     */
+    directDeps: Map<CellId, DepList>;
+    /**
+     * Explicit calc-node precedent -> dependent calculation nodes.
+     */
+    nodeDeps: Map<CalcNodeIndex, DepList>;
+    rangeIndex: RangeIndex;
+    /**
+     * CellFormula id -> internal node index.
+     */
+    cellFormulaToIndex: Map<CellId, CalcNodeIndex>;
+    /**
+     * OtherFormula id -> internal node index.
+     */
+    otherFormulaToIndex: Map<ExternalNodeId, CalcNodeIndex>;
+    /**
+     * FeatureCalculation id -> internal node index.
+     */
+    featureCalculationToIndex: Map<ExternalNodeId, CalcNodeIndex>;
+    /**
+     * Internal node index -> raw external id.
+     */
+    indexToNodeId: ExternalNodeId[];
+    dirty: Uint8Array;
+    inQueue: Uint8Array;
+    private _indexToNodeType;
+    private _cellPrecedents;
+    private _rangePrecedents;
+    private _nodePrecedents;
+    private _dynamicDeps;
+    private _dynamicSignature;
+    private _runtimeDirectDeps;
+    private _runtimeNodeDeps;
+    private _runtimeRangeIndex;
+    private _runtimeCellPrecedents;
+    private _runtimeRangePrecedents;
+    private _runtimeNodePrecedents;
+    private _activeNode;
+    private _seenNodeEpoch;
+    private _visitNodeEpoch;
+    private _edgeSeenEpoch;
+    private _tarjanSeenEpoch;
+    private _tarjanIndexArr;
+    private _tarjanLowArr;
+    private _tarjanOnStack;
+    private _emitEpoch;
+    private _visitEpoch;
+    private _edgeEpoch;
+    private _tarjanEpoch;
+    private readonly _propQueue;
+    private readonly _dirtyList;
+    private _activeNodeCount;
+    private _dirtyNodeCount;
+    private _directPointIndex;
+    private _runtimeDirectPointIndex;
+    private _formulaCellIndex;
+    private _sharedFormulaGroups;
+    private _sharedFormulaGroupIndexById;
+    private _sharedFormulaMembershipByNode;
+    private _sharedFormulaSourceEntries;
+    private _sharedFormulaSourceRangeIndex;
+    constructor(options: IDependencyEngineOptions);
+    /**
+     * Clears all graph data and recreates large internal storage at the initial
+     * capacity so old arrays, maps, and indexes can be reclaimed by GC.
+     */
+    reset(): void;
+    encodeCell(unitId: string, sheetId: string, row: number, col: number): CellId;
+    decodeCell(cell: CellId): IDecodedCell;
+    encodeFeatureCalculationId(unitId: string, sheetId: string, formulaId: string): string;
+    decodeFeatureCalculationId(id: ExternalNodeId): IDecodedFeatureCalculationId;
+    encodeOtherFormulaId(unitId: string, sheetId: string, formulaId: string, refOffsetX: number, refOffsetY: number): string;
+    decodeOtherFormulaId(id: ExternalNodeId): IDecodedOtherFormulaId;
+    setCellFormulaDeps(cell: CellId, deps: ICalcNodeDeps, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult;
+    setOtherFormulaDeps(id: ExternalNodeId, deps: ICalcNodeDeps, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult;
+    setFeatureCalculationDeps(id: ExternalNodeId, deps: ICalcNodeDeps, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult;
+    /**
+     * Adds or replaces dependencies for any calculation node type.
+     */
+    setCalcNodeDeps(node: ICalcNodeRef, deps: ICalcNodeDeps, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult;
+    registerCompressedSharedFormulaGroup(groupInput: ICompressedSharedFormulaGroup): void;
+    unregisterCompressedSharedFormulaGroup(groupId: string): void;
+    clearCompressedSharedFormulaGroups(unitId?: string, sheetId?: string): void;
+    private _setCalcNodeDepsByType;
+    setManyCalcNodeDeps(changes: Array<{
+        node: ICalcNodeRef;
+        deps: ICalcNodeDeps;
+    }>, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult[];
+    setManyCellFormulaDeps(changes: Array<{
+        cell: CellId;
+        deps: ICalcNodeDeps;
+    }>, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult[];
+    setManyOtherFormulaDeps(changes: Array<{
+        id: ExternalNodeId;
+        deps: ICalcNodeDeps;
+    }>, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult[];
+    setManyFeatureCalculationDeps(changes: Array<{
+        id: ExternalNodeId;
+        deps: ICalcNodeDeps;
+    }>, options?: {
+        checkCycle?: boolean;
+        markDirty?: boolean;
+        mode?: 'replace' | 'merge';
+    }): ISetNodeResult[];
+    removeCellFormula(cell: CellId, options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    removeOtherFormula(id: ExternalNodeId, options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    removeFeatureCalculation(id: ExternalNodeId, options?: {
+        markDependentsDirty?: boolean;
+        detachDependents?: boolean;
+    }): void;
+    removeCellFormulas(cells: CellId[], options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    removeOtherFormulas(ids: ExternalNodeId[], options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    removeFeatureCalculations(ids: ExternalNodeId[], options?: {
+        markDependentsDirty?: boolean;
+        detachDependents?: boolean;
+    }): void;
+    removeCalcNodes(nodes: ICalcNodeRef[], options?: {
+        markDependentsDirty?: boolean;
+        detachDependents?: boolean;
+    }): void;
+    clearCellFormulas(unitId: string, sheetId?: string, options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    clearOtherFormulas(unitId: string, sheetId?: string, formulaIds?: string[], refOffsetX?: number, refOffsetY?: number, options?: {
+        markDependentsDirty?: boolean;
+    }): void;
+    private _includesFormulaId;
+    clearFeatureCalculations(unitId: string, sheetId?: string, options?: {
+        markDependentsDirty?: boolean;
+        detachDependents?: boolean;
+    }): void;
+    private _tryDecodeFeatureCalculationId;
+    private _tryDecodeOtherFormulaId;
+    private _removeCalcNodeIds;
+    private _removeCalcNodeIndices;
+    removeCalcNode(node: ICalcNodeRef, options?: {
+        markDependentsDirty?: boolean;
+        detachDependents?: boolean;
+    }): void;
+    private _removeCalcNodeByType;
+    private _removeCalcNodeByIndex;
+    /**
+     * Marks dependents of a changed value cell dirty. The changed cell itself
+     * is not marked unless it is reached as a dependent.
+     */
+    markCellChanged(cell: CellId): void;
+    markCellsChanged(cells: Iterable<CellId>): void;
+    /**
+     * Marks dependents of a changed range dirty without expanding all cells.
+     */
+    markRangeChanged(rangeInput: IRefRange, options?: {
+        includeFormulaCells?: boolean;
+        coalesce?: boolean;
+    }): void;
+    /**
+     * Batch range-change entry point for paste, fill, clear, and import.
+     */
+    markRangesChanged(rangeInputs: IRefRange[], options?: {
+        includeFormulaCells?: boolean;
+        coalesce?: boolean;
+    }): void;
+    markCellFormulaChanged(cell: CellId): void;
+    markOtherFormulaChanged(id: ExternalNodeId): void;
+    markOtherFormulasChanged(unitId: string, sheetId?: string, formulaIds?: string[]): void;
+    markFeatureCalculationChanged(id: ExternalNodeId): void;
+    markCalcNodeChanged(node: ICalcNodeRef): void;
+    private _markCalcNodeChangedByType;
+    markCalcNodesChanged(nodes: ICalcNodeRef[]): void;
+    markAllDirty(): void;
+    hasDynamicDeps(node: ICalcNodeRef): boolean;
+    refreshDynamicDeps(node: ICalcNodeRef, resolver: IDynamicResolver): boolean;
+    prepareDynamicDependencies(resolver: IDynamicResolver): boolean;
+    /**
+     * Returns the current dirty-node calculation order without clearing dirty.
+     */
+    getCalculationOrder(options?: {
+        detectCycles?: boolean;
+    }): ICalculationOrderResult;
+    clearCalculatedDirty(indices: CalcNodeIndex[]): void;
+    private _compactDirtyList;
+    clearAllDirty(): void;
+    getDirtyNodeIndices(): CalcNodeIndex[];
+    getDirtyNodes(): ICalcNodeRef[];
+    forEachDependentByCell(cell: CellId, cb: (node: ICalcNodeRef, nodeIndex: CalcNodeIndex) => void): void;
+    forEachDependentByRange(range: IRefRange, cb: (node: ICalcNodeRef, nodeIndex: CalcNodeIndex) => void): void;
+    forEachDependentByNode(node: ICalcNodeRef, cb: (dependentNode: ICalcNodeRef, dependentIndex: CalcNodeIndex) => void): void;
+    forEachDependentByIndex(nodeIndex: CalcNodeIndex, cb: (dependentNode: ICalcNodeRef, dependentIndex: CalcNodeIndex) => void): void;
+    /**
+     * Diagnostic query for precedent calculation nodes of one node.
+     */
+    forEachPrecedentNode(node: ICalcNodeRef, cb: (precedentNode: ICalcNodeRef, precedentIndex: CalcNodeIndex) => void): void;
+    forEachPrecedentNodeByIndex(nodeIndex: CalcNodeIndex, cb: (precedentNode: ICalcNodeRef, precedentIndex: CalcNodeIndex) => void): void;
+    hasUncalculatedDirtyPrecedentByIndex(nodeIndex: CalcNodeIndex, calculatedNodeIndices: ReadonlySet<CalcNodeIndex>): boolean;
+    wouldCreateCycle(node: ICalcNodeRef, deps: ICalcNodeDeps): boolean;
+    private _normalizeCalcNodeDeps;
+    private _collectStaticDeps;
+    private _mergeDynamicDeps;
+    private _setNodeDynamicDeps;
+    private _isSameDynamicDeps;
+    private _normalizeRangeDeps;
+    private _mergeSortedUniqueNumbers;
+    private _mergeRangeDeps;
+    private _containsRange;
+    private _isSameRange;
+    /**
+     * Checks reachability through the dependent graph.
+     */
+    canReachNode(startNode: ICalcNodeRef, targetNode: ICalcNodeRef): boolean;
+    hasCellFormula(cell: CellId): boolean;
+    hasOtherFormula(id: ExternalNodeId): boolean;
+    hasFeatureCalculation(id: ExternalNodeId): boolean;
+    getNodeIndex(node: ICalcNodeRef): CalcNodeIndex | undefined;
+    private _getNodeIndexByType;
+    getNodeRefByIndex(nodeIndex: CalcNodeIndex): ICalcNodeRef;
+    markCalcNodeIndicesChanged(indices: CalcNodeIndex[], options?: {
+        onlySelf?: boolean;
+    }): void;
+    private _markCalcNodeIndicesChanged;
+    private _getOrCreateNodeIndex;
+    private _getOrCreateNodeIndexByType;
+    private _ensureNodeCapacity;
+    private _growIntThirtyTwoArray;
+    private _resolveExplicitNodeDeps;
+    private _isEmptyCalcNodeDeps;
+    private _unregisterCompressedSharedFormulaGroupByNode;
+    private _markCompressedSharedFormulaMembership;
+    private _clearCompressedSharedFormulaMembership;
+    private _getCompressedSharedSourceCoverage;
+    private _forEachCompressedSharedDependentByRange;
+    private _forEachActiveCellFormulaInRange;
+    private _reverseMapCompressedSharedPattern;
+    private _intersectRanges;
+    private _forEachCompressedSharedPrecedent;
+    private _getCompressedSharedPrecedentCell;
+    private _getCompressedSharedPrecedentRange;
+    private _addNodeDepsOnly;
+    private _removeNodeDepsOnly;
+    private _collectDynamicResolveResult;
+    private _addRuntimeDepsOnly;
+    private _removeRuntimeDepsOnly;
+    private _detachDependentsFromNode;
+    private _detachPrecedentFromDependent;
+    private _detachRuntimePrecedentFromDependent;
+    private _addDirectEdge;
+    private _removeDirectEdge;
+    private _addRuntimeDirectEdge;
+    private _removeRuntimeDirectEdge;
+    private _addExplicitNodeEdge;
+    private _removeExplicitNodeEdge;
+    private _addRuntimeExplicitNodeEdge;
+    private _removeRuntimeExplicitNodeEdge;
+    private _forEachDependentIndexByCellRaw;
+    private _forEachDependentOfNodeRaw;
+    private _markNodeIndexDirty;
+    private _isEveryActiveNodeDirty;
+    private _propagateDirtyQueue;
+    private _getDirtyNodeIndicesSnapshot;
+    private _forEachDependentOfNodeDeduped;
+    private _forEachPrecedentNodeIndex;
+    private _wouldCreateCycleForNewDeps;
+    private _canReachNodeIndex;
+    private _buildDirtyCalculationGraph;
+    private _tryBuildAcyclicDirtyCalculationGraph;
+    private _addAcyclicExactPrecedentEdges;
+    private _addAcyclicRangePrecedentGroups;
+    private _getOrCreateAcyclicRangeGroup;
+    private _appendAcyclicCalculationNode;
+    private _getCurrentDirtyOrdinal;
+    private _buildDirtyCalculationGraphWithScc;
+    private _toposortComponents;
+    private _insertComponentByRank;
+    private _buildCalculationForest;
+    private _appendCalculationNodePlanItem;
+    private _findCalculationForestRoot;
+    private _unionCalculationForestComponents;
+    private _createCalculationPlanItem;
+    private _getDirtySccEnd;
+    private _findDirtySccs;
+    private _hasSelfLoop;
+    private _nextEmitEpoch;
+    private _emitNodeOnce;
+    private _emitNodeOnceAndMarkDirty;
+    private _nextVisitEpoch;
+    private _nextEdgeEpoch;
+    private _nextTarjanEpoch;
+}

package/lib/types/engine/dependency-engine/formula-cell-index.d.ts

@@ -0,0 +1,23 @@
+import type { CellCodec } from './cell-codec';
+import type { CalcNodeIndex, ExternalNodeId, IRefRange } from './types';
+/**
+ * Spatial index for active `CellFormula` nodes.
+ *
+ * Range precedents use this index to discover formula cells inside a range
+ * for topological ordering, cycle checks, and `includeFormulaCells` dirty
+ * marking.
+ */
+export declare class FormulaCellIndex {
+    private readonly _codec;
+    private readonly _indexToNodeId;
+    private readonly _rowBuckets;
+    private readonly _colBuckets;
+    constructor(_codec: CellCodec, _indexToNodeId: ExternalNodeId[]);
+    addFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
+    removeFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
+    forEachFormulaInRange(rangeInput: IRefRange, cb: (nodeIndex: CalcNodeIndex) => boolean | void): boolean;
+    private _scanRows;
+    private _scanCols;
+    private _scanRowBucket;
+    private _scanColBucket;
+}

package/lib/types/engine/dependency-engine/helpers.d.ts

@@ -0,0 +1,32 @@
+import type { CalcNodeIndex, DepList, ExternalNodeId, ICalcNodeRef, IDecodedCell, IRefRange } from './types';
+/**
+ * Shared low-level helpers for dependency storage.
+ *
+ * These utilities are intentionally small and allocation-aware because the
+ * dependency engine calls them in hot paths such as paste, fill, and dirty
+ * propagation.
+ */
+export declare function assertCellNodeId(id: ExternalNodeId): asserts id is number;
+export declare function normalizeRange(r: IRefRange): IRefRange;
+export declare function rangeRowCount(r: IRefRange): number;
+export declare function rangeColCount(r: IRefRange): number;
+export declare function rangeContainsCell(r: IRefRange, d: IDecodedCell): boolean;
+export declare function uniqueSortedNumbers(values: readonly number[] | undefined): number[];
+export declare function pushToArrayMap<K>(map: Map<K, number[]>, key: K, value: number): void;
+export declare function removeFromArraySwap(arr: number[], value: number): boolean;
+export declare function removeFromArrayMap<K>(map: Map<K, number[]>, key: K, value: number): void;
+export declare function depListAdd(list: DepList | undefined, value: CalcNodeIndex): DepList;
+export declare function depListRemove(list: DepList | undefined, value: CalcNodeIndex): DepList | undefined;
+export declare function forEachDepList(list: DepList | undefined, cb: (nodeIndex: CalcNodeIndex) => void): void;
+export declare function addToDepMap<K>(map: Map<K, DepList>, key: K, nodeIndex: CalcNodeIndex): void;
+export declare function removeFromDepMap<K>(map: Map<K, DepList>, key: K, nodeIndex: CalcNodeIndex): void;
+export declare function growUintEightArray(oldArr: Uint8Array, minCapacity: number): Uint8Array;
+export declare function growUintThirtyTwoArray(oldArr: Uint32Array, minCapacity: number): Uint32Array;
+export declare function uniqueNodeRefs(values: readonly ICalcNodeRef[] | undefined): ICalcNodeRef[];
+/**
+ * Coalesce only ranges with the same row span or the same column span.
+ *
+ * We do not merge L-shaped areas into a larger rectangle because that would
+ * create too many false-positive dependents.
+ */
+export declare function coalesceAlignedRanges(rangeInputs: IRefRange[]): IRefRange[];

package/lib/types/engine/dependency-engine/node-helpers.d.ts

@@ -0,0 +1,7 @@
+import type { CellId, ExternalNodeId, ICalcNodeRef } from './types';
+/**
+ * Public helpers for creating calculation node references.
+ */
+export declare function cellFormulaNode(cell: CellId): ICalcNodeRef;
+export declare function otherFormulaNode(id: ExternalNodeId): ICalcNodeRef;
+export declare function featureCalculationNode(id: ExternalNodeId): ICalcNodeRef;

package/lib/types/engine/dependency-engine/point-subscription-index.d.ts

@@ -0,0 +1,24 @@
+import type { CellCodec } from './cell-codec';
+import type { CellId, IRefRange } from './types';
+/**
+ * Index of direct precedent cells subscribed by formula dependencies.
+ *
+ * It is used when a changed range needs to find only the direct precedent
+ * cells that are actually subscribed, without keeping a full sheet-sized cell
+ * index.
+ */
+export declare class PointSubscriptionIndex {
+    private readonly _codec;
+    private readonly _pointScanCellLimit;
+    private readonly _rowCells;
+    private readonly _colCells;
+    constructor(_codec: CellCodec, _pointScanCellLimit: number);
+    add(cell: CellId): void;
+    remove(cell: CellId): void;
+    forEachCellInRange(rangeInput: IRefRange, cb: (cell: CellId) => void): void;
+    private _isSmallArea;
+    private _scanRows;
+    private _scanCols;
+    private _scanRowBucket;
+    private _scanColBucket;
+}

package/lib/types/engine/dependency-engine/range-index.d.ts

@@ -0,0 +1,66 @@
+import type { CellCodec } from './cell-codec';
+import type { CalcNodeIndex, IRefRange } from './types';
+/**
+ * Reverse index from precedent ranges to dependent calculation nodes.
+ *
+ * The index does not expand ranges into cells. Whole rows / columns / sheets
+ * are stored in dedicated maps, normal ranges are indexed by their shorter
+ * side, and very large ranges use a fallback list.
+ */
+export declare class RangeIndex {
+    private readonly _codec;
+    private readonly _maxIndexedSpan;
+    private readonly _wholeSheet;
+    private readonly _wholeCol;
+    private readonly _wholeRow;
+    /**
+     * Normal ranges enter either row buckets or column buckets, never both.
+     */
+    private readonly _rowBuckets;
+    private readonly _colBuckets;
+    private readonly _largeRangeIds;
+    private _sheetArr;
+    private _startRowArr;
+    private _endRowArr;
+    private _startColArr;
+    private _endColArr;
+    private _nodeArr;
+    private _kindArr;
+    private _activeArr;
+    private _rangeSeenEpochArr;
+    private _rangeEpoch;
+    private _nextRangeId;
+    private readonly _freeRangeIds;
+    private readonly _nodeToRangeIds;
+    private readonly _nodeToWholeSheetKeys;
+    private readonly _nodeToWholeColKeys;
+    private readonly _nodeToWholeRowKeys;
+    constructor(_codec: CellCodec, initialCapacity: number, _maxIndexedSpan: number);
+    addRange(nodeIndex: CalcNodeIndex, rangeInput: IRefRange): void;
+    removeNode(nodeIndex: CalcNodeIndex): void;
+    /**
+     * Finds range-dependent nodes when one cell changes.
+     */
+    forEachPoint(unitId: string, sheetId: string, row: number, col: number, cb: (nodeIndex: CalcNodeIndex) => void): void;
+    forEachRangeIntersecting(changedInput: IRefRange, cb: (nodeIndex: CalcNodeIndex) => void): void;
+    /**
+     * Finds range-dependent nodes intersecting a batch of changed ranges.
+     *
+     * A single range epoch deduplicates normal range IDs across the batch.
+     */
+    forEachRangesIntersecting(changedInputs: IRefRange[], cb: (nodeIndex: CalcNodeIndex) => void): void;
+    private _allocRangeId;
+    private _ensureRangeCapacity;
+    private _setRangeMeta;
+    private _removeRangeId;
+    private _nextRangeEpoch;
+    private _wasRangeSeen;
+    private _markRangeSeen;
+    private _scanWholeCols;
+    private _scanWholeRows;
+    private _scanRowIndexedRanges;
+    private _scanColIndexedRanges;
+    private _scanRangeIdBucket;
+    private _rangeContainsPoint;
+    private _rangeIntersectsInput;
+}