@univerjs/engine-formula 1.0.3 → 1.1.0

package/lib/types/basics/common.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, Nullable, ObjectMatrix, Styles, UniverInstanceType } from '@univerjs/core';
+import type { ICellData, IColumnData, IObjectArrayPrimitiveType, IObjectMatrixPrimitiveType, IRange, IRowData, IUnitRange, IWorkbookCalculationSettings, Nullable, ObjectMatrix, Styles, UniverInstanceType } from '@univerjs/core';
 import type { sequenceNodeType } from '../engine/utils/sequence';
 import type { IImageFormulaInfo } from '../engine/value-object/primitive-object';
 export declare const ERROR_VALUE_OBJECT_CLASS_TYPE = "errorValueObject";
@@ -243,6 +243,12 @@ export interface IUnitRowData {
     }>;
 }
 export interface IFormulaDatasetConfig {
+    /** Recalculate iteration-sensitive groups and their dependents in these workbooks. */
+    dirtyIterationUnits?: string[];
+    /** Snapshot replay limits calculation to affected cycles and their required precedents. */
+    calculateCircularOnly?: boolean;
+    /** Finalize replay by calculating ordinary formulas without advancing complete circular caches. */
+    preserveCircularUnits?: string[];
     formulaData: IFormulaData;
     arrayFormulaCellData: IArrayFormulaUnitCellType;
     arrayFormulaRange: IArrayFormulaRangeType;
@@ -260,7 +266,7 @@ export interface IFormulaDatasetConfig {
     unitSheetNameMap?: IUnitSheetNameMap;
     unitNameMap?: IFormulaUnitNameMap;
     externalReferences?: IFormulaExternalReferences;
-    maxIteration?: number;
+    calculationSettings?: Record<string, IWorkbookCalculationSettings>;
     isCalculateTreeModel?: boolean;
     rowData?: IUnitRowData;
 }

package/lib/types/commands/mutations/set-formula-calculation.mutation.d.ts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 import type { IExecutionOptions, IMutation, IUnitRange, Nullable } from '@univerjs/core';
-import type { IFormulaExecuteResultMap, IFormulaStringMap, IRuntimeOtherUnitDataType, IRuntimeUnitDataPrimitiveType } from '../../basics/common';
+import type { IFormulaData, IFormulaExecuteResultMap, IFormulaStringMap, IRuntimeOtherUnitDataType, IRuntimeUnitDataPrimitiveType } from '../../basics/common';
 import type { IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaDependentsAndInRangeResults } from '../../engine/dependency/dependency-tree';
 import type { IFormulaDirtyData } from '../../services/current-data.service';
-import type { FormulaExecutedStateType, IExecutionInProgressParams } from '../../services/runtime.service';
+import type { FormulaExecutedStateType, ICircularReference, IExecutionInProgressParams } from '../../services/runtime.service';
 export interface ISetFormulaCalculationStartMutation extends IFormulaDirtyData {
     options: Nullable<IExecutionOptions>;
 }
@@ -67,12 +67,14 @@ export interface ISetFormulaCalculationStopMutation {
 }
 export declare const SetFormulaCalculationStopMutation: IMutation<ISetFormulaCalculationStopMutation>;
 export interface ISetFormulaCalculationNotificationMutation {
+    circularReferences?: ICircularReference[];
     functionsExecutedState?: FormulaExecutedStateType;
     stageInfo?: IExecutionInProgressParams;
 }
 export declare const SetFormulaCalculationNotificationMutation: IMutation<ISetFormulaCalculationNotificationMutation>;
 export interface ISetFormulaCalculationResultMutation {
     unitData: IRuntimeUnitDataPrimitiveType;
+    sourceFormulaData?: IFormulaData;
     unitOtherData: IRuntimeOtherUnitDataType;
 }
 export declare const SetFormulaCalculationResultMutation: IMutation<ISetFormulaCalculationResultMutation>;

package/lib/types/config/config.d.ts

@@ -17,8 +17,6 @@ import type { Ctor } from '@univerjs/core';
 import type { IFunctionNames } from '../basics/function';
 import type { BaseFunction } from '../functions/base-function';
 export declare const ENGINE_FORMULA_PLUGIN_CONFIG_KEY = "engine-formula.config";
-export declare const DEFAULT_CYCLE_REFERENCE_COUNT = 1;
-export declare const ENGINE_FORMULA_CYCLE_REFERENCE_COUNT = "CYCLE_REFERENCE_COUNT";
 export declare const ENGINE_FORMULA_RETURN_DEPENDENCY_TREE = "RETURN_DEPENDENCY_TREE";
 export declare const configSymbol: unique symbol;
 export interface IUniverEngineFormulaConfig {

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

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Returns strongly connected components in dependency order: precedents before their dependents.
+ * Mutually dependent nodes stay together so only their group needs iterative calculation.
+ * Uses iterative Kosaraju traversal to avoid overflowing the call stack on large dependency graphs.
+ */
+export declare function getDependencyGroups<T>(nodes: T[], getId: (node: T) => number, getDependents: (node: T) => Iterable<number>): T[][];

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

@@ -36,6 +36,7 @@ declare class FormulaDependencyTreeCalculator {
     isAdded(): boolean;
     setSkip(): void;
     isSkip(): boolean;
+    cycleGroup?: string;
     treeId: number;
     children: Set<number>;
     parents: Set<number>;

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

@@ -60,7 +60,6 @@ export declare class FormulaDependencyGenerator extends Disposable implements IF
     private _initUnitDispose;
     private _disposeByUnitId;
     generate(isCalculateTreeModel?: boolean): Promise<(FormulaDependencyTree | FormulaDependencyTreeVirtual)[]>;
-    private _isCyclicUtilMap;
     protected _checkIsCycleDependency(treeList: IFormulaDependencyTree[]): boolean;
     protected _getFeatureFormulaTree(featureId: string, treeId: Nullable<number>, params: IFeatureCalculationManagerParam): FormulaDependencyTree;
     protected _registerOtherFormulas(otherFormulaData: IOtherFormulaData, otherFormulaDataKeys: string[], treeList: IFormulaDependencyTree[]): void;
@@ -104,6 +103,7 @@ export declare class FormulaDependencyGenerator extends Disposable implements IF
     protected _updateRangeFlatten(): void;
     private _addFlattenCache;
     private _isPreCalculateNode;
+    private _isStaticReference;
     private _nodeTraversalRef;
     private _nodeTraversalReferenceFunction;
     private _executeNode;

package/lib/types/facade/f-formula.d.ts

@@ -148,19 +148,6 @@ export declare class FFormula extends FBase {
      * ```
      */
     calculationProcessing(callback: (stageInfo: IExecutionInProgressParams) => void): IDisposable;
-    /**
-     * When a formula contains a circular reference, set the maximum number of iterations for the formula calculation.
-     * @param {number} maxIteration The maximum number of iterations. The default value is 1.
-     *
-     * @example
-     * ```ts
-     * // Set the maximum number of iterations for the formula calculation to 5.
-     * // The default value is 1.
-     * const formulaEngine = univerAPI.getFormula();
-     * formulaEngine.setMaxIteration(5);
-     * ```
-     */
-    setMaxIteration(maxIteration: number): void;
     /**
      * Execute a batch of formulas asynchronously and receive computed results.
      *

package/lib/types/functions/lookup/xlookup/index.d.ts

@@ -21,10 +21,8 @@ export declare class Xlookup extends BaseFunction {
     calculate(lookupValue: BaseValueObject, lookupArray: BaseValueObject, returnArray: BaseValueObject, ifNotFound?: BaseValueObject, matchMode?: BaseValueObject, searchMode?: BaseValueObject): BaseValueObject;
     private _getResult;
     private _legacyImplicitLookupValue;
-    private _handleExpandObject;
-    private _handleSingleObject;
-    private _exactSearch;
-    private _exactSearchExpand;
+    private _getLookupResult;
+    private _findPosition;
     private _findExactPosition;
     private _isExactMatch;
     private _blankResultAsZero;

package/lib/types/index.d.ts

@@ -48,7 +48,7 @@ export { RemoveOtherFormulaMutation, SetOtherFormulaMutation } from './commands/
 export type { IRemoveOtherFormulaMutationParams, ISetOtherFormulaMutationParams, } from './commands/mutations/set-other-formula.mutation';
 export { RemoveSuperTableMutation, SetSuperTableMutation, SetSuperTableOptionMutation, } from './commands/mutations/set-super-table.mutation';
 export type { IRemoveSuperTableMutationParam, ISetSuperTableMutationParam, ISetSuperTableMutationSearchParam, } from './commands/mutations/set-super-table.mutation';
-export { DEFAULT_CYCLE_REFERENCE_COUNT, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT, ENGINE_FORMULA_PLUGIN_CONFIG_KEY, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE, } from './config/config';
+export { ENGINE_FORMULA_PLUGIN_CONFIG_KEY, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE, } from './config/config';
 export type { IUniverEngineFormulaConfig } from './config/config';
 export { CalculateController } from './controllers/calculate.controller';
 export { FormulaCalculationSessionController } from './controllers/formula-calculation-session.controller';
@@ -152,7 +152,8 @@ export { IFormulaExternalReferenceDataLoader, NoopFormulaExternalReferenceDataLo
 export type { IFormulaExternalReferenceLoadInput } from './services/external-reference-data-loader.service';
 export { FeatureCalculationManagerService, IFeatureCalculationManagerService, } from './services/feature-calculation-manager.service';
 export type { IFeatureCalculationManagerParam } from './services/feature-calculation-manager.service';
-export { FormulaCalculationTriggerService } from './services/formula-calculation-trigger.service';
+export { FormulaCalculationTriggerService, mergeDirtyData } from './services/formula-calculation-trigger.service';
+export { IFormulaChangesetCalculationService } from './services/formula-changeset-calculation.service';
 export type { IFormulaInfo, IOtherFormulaResult } from './services/formula-common';
 export { FormulaResultStatus } from './services/formula-common';
 export { DescriptionService, IDescriptionService } from './services/formula/description.service';
@@ -186,6 +187,7 @@ export { IOtherFormulaManagerService, OtherFormulaManagerService } from './servi
 export { OtherFormulaBizType, RegisterOtherFormulaService } from './services/register-other-formula.service';
 export { FormulaExecutedStateType, FormulaExecuteStageType, FormulaRuntimeService, IFormulaRuntimeService, } from './services/runtime.service';
 export type { IAllRuntimeData, IExecutionInProgressParams } from './services/runtime.service';
+export type { ICircularReference } from './services/runtime.service';
 export { ISheetRowFilteredService, SheetRowFilteredService } from './services/sheet-row-filtered.service';
 export { ISuperTableService } from './services/super-table.service';
 export { SuperTableService } from './services/super-table.service';

package/lib/types/models/formula-data.model.d.ts

@@ -15,6 +15,7 @@
  */
 import type { ICellData, IObjectMatrixPrimitiveType, IRange, IUnitRange, Nullable } from '@univerjs/core';
 import type { IArrayFormulaRangeType, IArrayFormulaUnitCellType, IFormulaData, IFormulaDataItem, IFormulaUnitNameMap, IRuntimeUnitDataType, IUnitData, IUnitImageFormulaDataType, IUnitRowData, IUnitSheetNameMap, IUnitStylesData } from '../basics/common';
+import type { ICircularReference } from '../services/runtime.service';
 import { Disposable, IUniverInstanceService, ObjectMatrix } from '@univerjs/core';
 import { LexerTreeBuilder } from '../engine/analysis/lexer-tree-builder';
 export interface IRangeChange {
@@ -24,12 +25,16 @@ export interface IRangeChange {
 export declare class FormulaDataModel extends Disposable {
     private readonly _univerInstanceService;
     private readonly _lexerTreeBuilder;
+    private _circularReferences;
     private _formulaIdMapData;
     private _arrayFormulaRange;
     private _arrayFormulaCellData;
     private _unitImageFormulaData;
     constructor(_univerInstanceService: IUniverInstanceService, _lexerTreeBuilder: LexerTreeBuilder);
     dispose(): void;
+    setCircularReferences(cells: ICircularReference[]): void;
+    getCircularReferences(unitId: string): ICircularReference[];
+    isCircularReference(unitId: string, sheetId: string, row: number, column: number): boolean;
     clearPreviousArrayFormulaCellData(clearArrayFormulaCellData: IRuntimeUnitDataType): void;
     mergeArrayFormulaCellData(unitData: IRuntimeUnitDataType): void;
     getFormulaData(): IFormulaData;

package/lib/types/services/active-dirty-manager.service.d.ts

@@ -20,6 +20,7 @@ export interface IDirtyConversionManagerParams {
     commandId: string;
     shouldTrigger?: (command: ICommandInfo, options?: IExecutionOptions) => boolean;
     getDirtyData: (command: ICommandInfo) => {
+        dirtyIterationUnits?: string[];
         forceCalculation?: boolean;
         dirtyRanges?: IUnitRange[];
         dirtyNameMap?: IDirtyUnitSheetNameMap;

package/lib/types/services/calculate-formula.service.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IUnitRange } from '@univerjs/core';
+import type { ICellData, IUnitRange, IWorkbookCalculationSettings } from '@univerjs/core';
 import type { Observable } from 'rxjs';
 import type { IArrayFormulaRangeType, IFeatureDirtyRangeType, IFormulaDatasetConfig, IFormulaExecuteResultMap, IFormulaStringMap, IRuntimeUnitDataType, IUnitExcludedCell, IUnitRowData } from '../basics/common';
 import type { IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaDependentsAndInRangeResults } from '../engine/dependency/dependency-tree';
@@ -28,7 +28,6 @@ import { Interpreter } from '../engine/interpreter/interpreter';
 import { IFormulaCurrentConfigService } from './current-data.service';
 import { IFormulaRuntimeService } from './runtime.service';
 export declare const DEFAULT_INTERVAL_COUNT = 500;
-export declare const CYCLE_REFERENCE_COUNT = "cycleReferenceCount";
 export declare const EVERY_N_FUNCTION_EXECUTION_PAUSE = 100;
 export interface ICalculateFormulaService {
     readonly executionInProgressListener$: Observable<IExecutionInProgressParams>;
@@ -60,6 +59,39 @@ export declare class CalculateFormulaService extends Disposable implements ICalc
     readonly executionCompleteListener$: Observable<IAllRuntimeData>;
     protected _executeLock: AsyncLock;
     protected _isCalculateTreeModel: boolean;
+    protected _workbookCalculationSettings: Record<string, IWorkbookCalculationSettings>;
+    protected _preserveCircularUnits: Set<string>;
+    private readonly _normalizedCalculationSettings;
+    protected _loadCalculationSettings(settings?: Record<string, IWorkbookCalculationSettings>): void;
+    protected _getCalculationSettings(unitId: string): IWorkbookCalculationSettings;
+    protected _getIterationCell(tree: {
+        unitId: string;
+        subUnitId: string;
+        row: number;
+        column: number;
+    }): Pick<ICellData, 'v' | 't'>;
+    protected _iterateCalculationGroup<T extends {
+        unitId: string;
+        subUnitId: string;
+        row: number;
+        column: number;
+        formula?: string;
+    }>(group: T[], groupId: string): AsyncGenerator<{
+        tree: T;
+        preserve: boolean;
+        iteration: number;
+    }, void, unknown>;
+    protected _getCalculationSteps<T extends {
+        cycleGroup?: string;
+        unitId: string;
+        subUnitId: string;
+        row: number;
+        column: number;
+    }>(trees: T[]): AsyncGenerator<{
+        tree: T;
+        preserve: boolean;
+        iteration: number;
+    }, void, unknown>;
     constructor(_configService: IConfigService, _lexer: Lexer, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _formulaDependencyGenerator: IFormulaDependencyGenerator, _interpreter: Interpreter, _astTreeBuilder: AstTreeBuilder);
     dispose(): void;
     /**

package/lib/types/services/current-data.service.d.ts

@@ -13,12 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { IUnitRange, LocaleType, Nullable } from '@univerjs/core';
+import type { IUnitRange, IWorkbookCalculationSettings, LocaleType, Nullable } from '@univerjs/core';
 import type { IArrayFormulaRangeType, IDirtyUnitDefinedNameMap, IDirtyUnitFeatureMap, IDirtyUnitOtherFormulaMap, IDirtyUnitSheetNameMap, IDirtyUnitSuperTableMap, IFormulaData, IFormulaDatasetConfig, IFormulaExternalReferences, IFormulaUnitNameMap, IRuntimeUnitDataType, IUnitData, IUnitExcludedCell, IUnitRowData, IUnitSheetIdToNameMap, IUnitSheetNameMap, IUnitStylesData } from '../basics/common';
 import { DateSystem, Disposable, IUniverInstanceService, LocaleService } from '@univerjs/core';
 import { FormulaDataModel } from '../models/formula-data.model';
 import { ISheetRowFilteredService } from './sheet-row-filtered.service';
 export interface IFormulaDirtyData {
+    dirtyIterationUnits?: string[];
     forceCalculation: boolean;
     dirtyRanges: IUnitRange[];
     dirtyNameMap: IDirtyUnitSheetNameMap;
@@ -27,7 +28,7 @@ export interface IFormulaDirtyData {
     dirtyUnitFeatureMap: IDirtyUnitFeatureMap;
     dirtyUnitOtherFormulaMap: IDirtyUnitOtherFormulaMap;
     clearDependencyTreeCache: IDirtyUnitSheetNameMap;
-    maxIteration?: number;
+    calculationSettings?: Record<string, IWorkbookCalculationSettings>;
     isCalculateTreeModel?: boolean;
     rowData?: IUnitRowData;
     externalReferences?: IFormulaExternalReferences;
@@ -87,6 +88,7 @@ export declare class FormulaCurrentConfigService extends Disposable implements I
     private readonly _localeService;
     private readonly _formulaDataModel;
     private readonly _sheetRowFilteredService;
+    private _dirtyIterationUnits;
     private _unitData;
     private _unitStylesData;
     private _arrayFormulaCellData;

package/lib/types/services/formula-calculation-trigger.service.d.ts

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { IFormulaDirtyData } from './current-data.service';
 import { Disposable, ICommandService } from '@univerjs/core';
 import { IActiveDirtyManagerService } from './active-dirty-manager.service';
 /**
@@ -31,8 +32,11 @@ export declare class FormulaCalculationTriggerService extends Disposable {
     private _executionInProgress;
     private _hasPendingCalculation;
     private _stopRequested;
+    private _suppressed;
     constructor(_commandService: ICommandService, _activeDirtyManagerService: IActiveDirtyManagerService);
     start(): void;
+    /** Snapshot reconstruction calculates these synchronous mutations in its isolated runtime. */
+    runWithoutTriggering<T>(operation: () => T): T;
     dispose(): void;
     private _initialize;
     private _registerGenericDirtyConversions;
@@ -42,3 +46,4 @@ export declare class FormulaCalculationTriggerService extends Disposable {
     private _handleCalculationNotification;
     private _generateDirty;
 }
+export declare function mergeDirtyData(left: Partial<IFormulaDirtyData>, right: Partial<IFormulaDirtyData>): IFormulaDirtyData;

package/lib/types/services/formula-changeset-calculation.service.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2023-present DreamNum Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { IMutationInfo, IWorkbookData } from '@univerjs/core';
+/**
+ * Temporary revision-ordered circular replay for snapshot loading, export, and snapshot generation.
+ * Hosts opt in through begin() and release the replay state with end() after publishing results.
+ * Live collaboration and ordinary local calculation do not call this service.
+ */
+export interface IFormulaChangesetCalculationService {
+    /** Units with an active snapshot replay. */
+    readonly managedUnitIds: string[];
+    /** Capture the base revision; snapshot can precede the already loaded workbook's current revision. */
+    begin(unitId: string, mutations?: IMutationInfo[], snapshot?: IWorkbookData): void;
+    /** Queue one canonical revision; calculate after all mutations, ignoring intermediate cell states. */
+    applyChangeset(unitId: string, revision: number, mutations: IMutationInfo[]): void;
+    /** Drain replay and publish when revisions match; true also calculates ordinary formulas for snapshotting. */
+    flush(unitId: string, calculateOrdinary?: boolean): Promise<void>;
+    /** Release temporary replay state so later local edits use the normal calculation path. */
+    end(unitId: string): void;
+}
+export declare const IFormulaChangesetCalculationService: import("@wendellhu/redi").IdentifierDecorator<IFormulaChangesetCalculationService>;

package/lib/types/services/runtime.service.d.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 import type { Nullable } from '@univerjs/core';
-import type { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IFeatureDirtyRangeType, IRuntimeImageFormulaDataType, IRuntimeOtherUnitDataType, IRuntimeUnitDataType } from '../basics/common';
+import type { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IFeatureDirtyRangeType, IFormulaData, IRuntimeImageFormulaDataType, IRuntimeOtherUnitDataType, IRuntimeUnitDataType } from '../basics/common';
 import type { BaseAstNode } from '../engine/ast-node/base-ast-node';
 import type { IFormulaDependencyTreeJson } from '../engine/dependency/dependency-tree';
 import type { FunctionVariantType } from '../engine/reference-object/base-reference-object';
-import { Disposable } from '@univerjs/core';
+import { Disposable, IUniverInstanceService } from '@univerjs/core';
 import { IFormulaCurrentConfigService } from './current-data.service';
 import { IHyperlinkEngineFormulaService } from './hyperlink-engine-formula.service';
 /**
@@ -42,8 +42,19 @@ export declare enum FormulaExecutedStateType {
     NOT_EXECUTED = 2,
     SUCCESS = 3
 }
+export interface ICircularReference {
+    unitId: string;
+    sheetId: string;
+    row: number;
+    column: number;
+    groupId: string;
+    iterations: number;
+    converged?: boolean;
+}
 export interface IAllRuntimeData {
+    circularReferences?: ICircularReference[];
     unitData: IRuntimeUnitDataType;
+    sourceFormulaData?: IFormulaData;
     arrayFormulaRange: IArrayFormulaRangeType;
     arrayFormulaEmbedded: IArrayFormulaEmbeddedMap;
     unitOtherData: IRuntimeOtherUnitDataType;
@@ -64,6 +75,7 @@ export interface IExecutionInProgressParams {
     completedFormulasCount: number;
     totalArrayFormulasToCalculate: number;
     completedArrayFormulasCount: number;
+    circularReferences?: ICircularReference[];
     formulaCycleIndex: number;
     stage: FormulaExecuteStageType;
 }
@@ -76,6 +88,16 @@ export interface IFormulaRuntimeService {
     currentUnitId: string;
     dispose(): void;
     reset(): void;
+    beginCircularReferences(): void;
+    clearCircularReferenceCells(cells: {
+        unitId: string;
+        subUnitId: string;
+        row: number;
+        column: number;
+    }[]): void;
+    recordCircularReferences(cells: ICircularReference[]): void;
+    completeCircularReferences(): void;
+    preserveCurrentCellData(): void;
     setCurrent(row: number, column: number, rowCount: number, columnCount: number, sheetId: string, unitId: string): void;
     setFunctionRefInfoOverride(rowCount: number, columnCount: number): () => void;
     hasFunctionRefInfoOverride(): boolean;
@@ -129,7 +151,10 @@ export interface IFormulaRuntimeService {
 export declare class FormulaRuntimeService extends Disposable implements IFormulaRuntimeService {
     private readonly _currentConfigService;
     private readonly _hyperlinkEngineFormulaService;
+    private readonly _univerInstanceService;
     private _formulaExecuteStage;
+    private _circularReferences;
+    private _pendingCircularReferences;
     private _stopState;
     private _externalReferenceUnavailable;
     private _currentRow;
@@ -140,6 +165,8 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     private _currentSubUnitId;
     private _currentUnitId;
     private _runtimeData;
+    private _sourceFormulaData;
+    private _currentSourceFormula;
     private _runtimeOtherData;
     private _unitArrayFormulaRange;
     private _unitArrayFormulaEmbeddedMap;
@@ -157,7 +184,7 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     private _formulaCycleIndex;
     private _isCycleDependency;
     private _dependencyTreeModelData;
-    constructor(_currentConfigService: IFormulaCurrentConfigService, _hyperlinkEngineFormulaService: IHyperlinkEngineFormulaService);
+    constructor(_currentConfigService: IFormulaCurrentConfigService, _hyperlinkEngineFormulaService: IHyperlinkEngineFormulaService, _univerInstanceService: IUniverInstanceService);
     get currentRow(): number;
     get currentColumn(): number;
     get currentRowCount(): number;
@@ -188,6 +215,16 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     getFormulaExecuteStage(): FormulaExecuteStageType;
     reset(): void;
     clearReferenceAndNumberformatCache(): void;
+    beginCircularReferences(): void;
+    clearCircularReferenceCells(cells: {
+        unitId: string;
+        subUnitId: string;
+        row: number;
+        column: number;
+    }[]): void;
+    recordCircularReferences(cells: ICircularReference[]): void;
+    completeCircularReferences(): void;
+    preserveCurrentCellData(): void;
     setCurrent(row: number, column: number, rowCount: number, columnCount: number, sheetId: string, unitId: string): void;
     setFunctionRefInfoOverride(rowCount: number, columnCount: number): () => void;
     hasFunctionRefInfoOverride(): boolean;

package/lib/umd/facade.js

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula")):typeof define==`function`&&define.amd?define([`exports`,`@univerjs/core/facade`,`@univerjs/core`,`@univerjs/engine-formula`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.UniverEngineFormulaFacade={},e.UniverCoreFacade,e.UniverCore,e.UniverEngineFormula))})(this,function(e,t,n,r){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});function i(e,t){return function(n,r){t(n,r,e)}}function a(e,t,n,r){var i=arguments.length,a=i<3?t:r===null?r=Object.getOwnPropertyDescriptor(t,n):r,o;if(typeof Reflect==`object`&&typeof Reflect.decorate==`function`)a=Reflect.decorate(e,t,n,r);else for(var s=e.length-1;s>=0;s--)(o=e[s])&&(a=(i<3?o(a):i>3?o(t,n,a):o(t,n))||a);return i>3&&a&&Object.defineProperty(t,n,a),a}let o=class extends t.FBase{constructor(e,t,n,r,i,a,o){super(),this._commandService=e,this._injector=t,this._lexerTreeBuilder=n,this._configService=r,this._functionService=i,this._definedNamesService=a,this._superTableService=o,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,t,n,r){return this._lexerTreeBuilder.moveFormulaRefOffset(e,t,n,r)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(r.SetTriggerFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(r.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===r.SetFormulaCalculationStartMutation.id){let n=t.params;e(n.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;let n=t.params;n.functionsExecutedState!==void 0&&e(n.functionsExecutedState)})}calculationResultApplied(e){let t=this._injector.get(r.FormulaCalculationSessionService).resultApplied$.subscribe(t=>{if(typeof requestIdleCallback==`function`){requestIdleCallback(()=>e(t));return}queueMicrotask(()=>e(t))});return{dispose:()=>t.unsubscribe()}}onCalculationResultApplied(e){return this._injector.get(r.FormulaCalculationSessionService).waitForLatestApplied(e)}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;let n=t.params;n.stageInfo!==void 0&&e(n.stageInfo)})}setMaxIteration(e){this._configService.setConfig(r.ENGINE_FORMULA_CYCLE_REFERENCE_COUNT,e)}executeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetFormulaStringBatchCalculationResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?i(Error(`Formula batch calculation returned no result`)):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(Error(`Formula batch calculation timeout`))},t);this._commandService.executeCommand(r.SetFormulaStringBatchCalculationMutation.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((t,n)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetFormulaDependencyCalculationResultMutation.id)return;let n=e.params;clearTimeout(a),i.dispose(),n.result==null?t([]):t(n.result)}),a=setTimeout(()=>{i.dispose(),n(Error(`Formula dependency calculation timeout`))},e);this._commandService.executeCommand(r.SetFormulaDependencyCalculationMutation.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetCellFormulaDependencyCalculationResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),n(t.result)}),o=setTimeout(()=>{a.dispose(),i(Error(`Cell dependency calculation timeout`))},t);this._commandService.executeCommand(r.SetCellFormulaDependencyCalculationMutation.id,e,{onlyLocal:!0})})}getRangeDependents(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n([]):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n([]):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(Error(`In-range formulas calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(r.ENGINE_FORMULA_RETURN_DEPENDENCY_TREE,e)}getFormulaExpressTree(e,t){return this._lexerTreeBuilder.getFormulaExprTree(e,t,this._functionService.hasExecutor.bind(this._functionService),this._definedNamesService.getValueByName.bind(this._definedNamesService),this._superTableService.getTable.bind(this._superTableService))}getRangeDependentsAndInRangeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyAllResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n({dependents:[],inRanges:[]}):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyAllMutation.id,{unitRanges:e},{onlyLocal:!0})})}};o=a([i(0,(0,n.Inject)(n.ICommandService)),i(1,(0,n.Inject)(n.Injector)),i(2,(0,n.Inject)(r.LexerTreeBuilder)),i(3,n.IConfigService),i(4,r.IFunctionService),i(5,r.IDefinedNamesService),i(6,r.ISuperTableService)],o);var s=class extends t.FUniver{getFormula(){return this._injector.createInstance(o)}};t.FUniver.extend(s),Object.defineProperty(e,"FFormula",{enumerable:!0,get:function(){return o}})});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula")):typeof define==`function`&&define.amd?define([`exports`,`@univerjs/core/facade`,`@univerjs/core`,`@univerjs/engine-formula`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.UniverEngineFormulaFacade={},e.UniverCoreFacade,e.UniverCore,e.UniverEngineFormula))})(this,function(e,t,n,r){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});function i(e,t){return function(n,r){t(n,r,e)}}function a(e,t,n,r){var i=arguments.length,a=i<3?t:r===null?r=Object.getOwnPropertyDescriptor(t,n):r,o;if(typeof Reflect==`object`&&typeof Reflect.decorate==`function`)a=Reflect.decorate(e,t,n,r);else for(var s=e.length-1;s>=0;s--)(o=e[s])&&(a=(i<3?o(a):i>3?o(t,n,a):o(t,n))||a);return i>3&&a&&Object.defineProperty(t,n,a),a}let o=class extends t.FBase{constructor(e,t,n,r,i,a,o){super(),this._commandService=e,this._injector=t,this._lexerTreeBuilder=n,this._configService=r,this._functionService=i,this._definedNamesService=a,this._superTableService=o,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,t,n,r){return this._lexerTreeBuilder.moveFormulaRefOffset(e,t,n,r)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(r.SetTriggerFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(r.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===r.SetFormulaCalculationStartMutation.id){let n=t.params;e(n.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;let n=t.params;n.functionsExecutedState!==void 0&&e(n.functionsExecutedState)})}calculationResultApplied(e){let t=this._injector.get(r.FormulaCalculationSessionService).resultApplied$.subscribe(t=>{typeof requestIdleCallback==`function`?requestIdleCallback(()=>e(t)):queueMicrotask(()=>e(t))});return{dispose:()=>t.unsubscribe()}}onCalculationResultApplied(e){return this._injector.get(r.FormulaCalculationSessionService).waitForLatestApplied(e)}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;let n=t.params;n.stageInfo!==void 0&&e(n.stageInfo)})}executeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetFormulaStringBatchCalculationResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?i(/* @__PURE__ */ Error(`Formula batch calculation returned no result`)):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(/* @__PURE__ */ Error(`Formula batch calculation timeout`))},t);this._commandService.executeCommand(r.SetFormulaStringBatchCalculationMutation.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((t,n)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetFormulaDependencyCalculationResultMutation.id)return;let n=e.params;clearTimeout(a),i.dispose(),n.result==null?t([]):t(n.result)}),a=setTimeout(()=>{i.dispose(),n(/* @__PURE__ */ Error(`Formula dependency calculation timeout`))},e);this._commandService.executeCommand(r.SetFormulaDependencyCalculationMutation.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetCellFormulaDependencyCalculationResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),n(t.result)}),o=setTimeout(()=>{a.dispose(),i(/* @__PURE__ */ Error(`Cell dependency calculation timeout`))},t);this._commandService.executeCommand(r.SetCellFormulaDependencyCalculationMutation.id,e,{onlyLocal:!0})})}getRangeDependents(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n([]):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(/* @__PURE__ */ Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n([]):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(/* @__PURE__ */ Error(`In-range formulas calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(r.ENGINE_FORMULA_RETURN_DEPENDENCY_TREE,e)}getFormulaExpressTree(e,t){return this._lexerTreeBuilder.getFormulaExprTree(e,t,this._functionService.hasExecutor.bind(this._functionService),this._definedNamesService.getValueByName.bind(this._definedNamesService),this._superTableService.getTable.bind(this._superTableService))}getRangeDependentsAndInRangeFormulas(e,t=3e4){return new Promise((n,i)=>{let a=this._commandService.onCommandExecuted(e=>{if(e.id!==r.SetQueryFormulaDependencyAllResultMutation.id)return;let t=e.params;clearTimeout(o),a.dispose(),t.result==null?n({dependents:[],inRanges:[]}):n(t.result)}),o=setTimeout(()=>{a.dispose(),i(/* @__PURE__ */ Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyAllMutation.id,{unitRanges:e},{onlyLocal:!0})})}};o=a([i(0,(0,n.Inject)(n.ICommandService)),i(1,(0,n.Inject)(n.Injector)),i(2,(0,n.Inject)(r.LexerTreeBuilder)),i(3,n.IConfigService),i(4,r.IFunctionService),i(5,r.IDefinedNamesService),i(6,r.ISuperTableService)],o);var s=class extends t.FUniver{getFormula(){return this._injector.createInstance(o)}};t.FUniver.extend(s),Object.defineProperty(e,"FFormula",{enumerable:!0,get:function(){return o}})});