Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

fix(engine-formula): support changeset snapshot calculation (#7860)

wpxp123456301e357e5df2
diff --git a/packages/engine-formula/src/basics/common.ts b/packages/engine-formula/src/basics/common.ts
index 82e09d2c16..64666c1f18 100644
--- a/packages/engine-formula/src/basics/common.ts
+++ b/packages/engine-formula/src/basics/common.ts
@@ -251,6 +251,10 @@ export interface IUnitRowData {
}
export interface IFormulaDatasetConfig {
+ /** 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;
diff --git a/packages/engine-formula/src/index.ts b/packages/engine-formula/src/index.ts
index 494011e67f..e2153ce64b 100644
--- a/packages/engine-formula/src/index.ts
+++ b/packages/engine-formula/src/index.ts
@@ -304,7 +304,8 @@ export {
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';
diff --git a/packages/engine-formula/src/services/__tests__/formula-calculation-trigger.service.spec.ts b/packages/engine-formula/src/services/__tests__/formula-calculation-trigger.service.spec.ts
index dd34185bc6..584e62b031 100644
--- a/packages/engine-formula/src/services/__tests__/formula-calculation-trigger.service.spec.ts
+++ b/packages/engine-formula/src/services/__tests__/formula-calculation-trigger.service.spec.ts
@@ -69,6 +69,36 @@ describe('FormulaCalculationTriggerService', () => {
vi.restoreAllMocks();
});
+ it('does not debounce reconstructed snapshot inputs and resumes for subsequent local edits', async () => {
+ const testBed = createTestBed();
+ try {
+ testBed.service.runWithoutTriggering(() => testBed.emit({
+ id: SetTriggerFormulaCalculationStartMutation.id,
+ params: { forceCalculation: true },
+ }));
+ await vi.advanceTimersByTimeAsync(10);
+ expect(testBed.executed).toEqual([]);
+ expect(() => testBed.service.runWithoutTriggering(() => {
+ throw new Error('load failed');
+ })).toThrow('load failed');
+ testBed.emit({
+ id: SetTriggerFormulaCalculationStartMutation.id,
+ params: { dirtyRanges: [{ unitId: 'unit', sheetId: 'sheet', range: {
+ startRow: 0,
+ endRow: 0,
+ startColumn: 1,
+ endColumn: 1,
+ } }] },
+ });
+ await vi.advanceTimersByTimeAsync(10);
+ expect(testBed.executed).toHaveLength(1);
+ expect(testBed.executed[0].params).toMatchObject({ dirtyRanges: [{ unitId: 'unit' }] });
+ expect(testBed.executed[0].params).not.toHaveProperty('preserveCircularUnits');
+ } finally {
+ testBed.service.dispose();
+ }
+ });
+
it('batches formula registrations without changing payloads or completed session maps', async () => {
const testBed = createTestBed();
const payload = Object.freeze({
diff --git a/packages/engine-formula/src/services/calculate-formula.service.ts b/packages/engine-formula/src/services/calculate-formula.service.ts
index ba25fd61b7..6a37fcc879 100644
--- a/packages/engine-formula/src/services/calculate-formula.service.ts
+++ b/packages/engine-formula/src/services/calculate-formula.service.ts
@@ -61,6 +61,7 @@ import { FORMULA_REF_TO_ARRAY_CACHE } from '../engine/reference-object/base-refe
import { generateAstNode } from '../engine/utils/generate-ast-node';
import { ErrorValueObjectCache } from '../engine/value-object/base-value-object';
import { StringValueObjectCache } from '../engine/value-object/primitive-object';
+import { FUNCTION_NAMES_LOOKUP } from '../functions/lookup/function-names';
import { IFormulaCurrentConfigService } from './current-data.service';
import { FormulaExecuteStageType, IFormulaRuntimeService } from './runtime.service';
@@ -97,6 +98,7 @@ export class CalculateFormulaService extends Disposable implements ICalculateFor
protected _isCalculateTreeModel: boolean = false;
protected _workbookCalculationSettings: Record<string, IWorkbookCalculationSettings> = {};
+ protected _preserveCircularUnits = new Set<string>();
private readonly _normalizedCalculationSettings = new Map<string, IWorkbookCalculationSettings>();
protected _loadCalculationSettings(settings?: Record<string, IWorkbookCalculationSettings>): void {
@@ -120,11 +122,34 @@ export class CalculateFormulaService extends Disposable implements ICalculateFor
return cell.v == null ? { v: 0, t: CellValueType.NUMBER } : cell;
}
- protected async* _iterateCalculationGroup<T extends { unitId: string; subUnitId: string; row: number; column: number }>(
+ protected async* _iterateCalculationGroup<T extends { unitId: string; subUnitId: string; row: number; column: number; formula?: string }>(
group: T[],
groupId: string
) {
const settings = group.map((item) => this._getCalculationSettings(item.unitId));
+ if (group.every((item, i) => {
+ const cell = this._currentConfigService.getUnitData()[item.unitId]?.[item.subUnitId]?.cellData.getValue(item.row, item.column);
+ const formula = (item.formula ?? cell?.f ?? '').toUpperCase();
+ // Match native materialization: INDEX can narrow a static self-containing
+ // range to another cell, while classic LOOKUP retains cache-backed cycles.
+ const requiresRecalculation = formula.includes(`${FUNCTION_NAMES_LOOKUP.INDEX}(`) &&
+ !(formula.includes(`${FUNCTION_NAMES_LOOKUP.LOOKUP}(`) && !formula.includes(`${FUNCTION_NAMES_LOOKUP.XLOOKUP}(`));
+ return settings[i].iterativeCalculation && this._preserveCircularUnits.has(item.unitId) &&
+ cell?.v != null && !requiresRecalculation;
+ })) {
+ for (const tree of group) {
+ yield { tree, preserve: true, iteration: 0 };
+ }
+ this._runtimeService.recordCircularReferences(group.map((item) => ({
+ unitId: item.unitId,
+ sheetId: item.subUnitId,
+ row: item.row,
+ column: item.column,
+ groupId,
+ iterations: 0,
+ })));
+ return;
+ }
const limit = settings.reduce((limit, setting) => Math.max(limit, setting.iterativeCalculation ? setting.maxIterations : 0), 1);
let converged = false;
let iterations = 0;
@@ -244,6 +269,7 @@ export class CalculateFormulaService extends Disposable implements ICalculateFor
this._runtimeService.reset();
this._loadCalculationSettings(formulaDatasetConfig.calculationSettings);
+ this._preserveCircularUnits = new Set(formulaDatasetConfig.preserveCircularUnits);
this._runtimeService.beginCircularReferences();
this._isCalculateTreeModel = formulaDatasetConfig.isCalculateTreeModel || false;
await this._executeStep();
diff --git a/packages/engine-formula/src/services/formula-calculation-trigger.service.ts b/packages/engine-formula/src/services/formula-calculation-trigger.service.ts
index c2a8a79c72..09f48ed44a 100644
--- a/packages/engine-formula/src/services/formula-calculation-trigger.service.ts
+++ b/packages/engine-formula/src/services/formula-calculation-trigger.service.ts
@@ -49,6 +49,7 @@ export class FormulaCalculationTriggerService extends Disposable {
private _executionInProgress = false;
private _hasPendingCalculation = false;
private _stopRequested = false;
+ private _suppressed = false;
constructor(
@ICommandService private readonly _commandService: ICommandService,
@@ -68,6 +69,17 @@ export class FormulaCalculationTriggerService extends Disposable {
this._scheduleFlush();
}
+ /** Snapshot reconstruction calculates these synchronous mutations in its isolated runtime. */
+ runWithoutTriggering<T>(operation: () => T): T {
+ const previous = this._suppressed;
+ this._suppressed = true;
+ try {
+ return operation();
+ } finally {
+ this._suppressed = previous;
+ }
+ }
+
override dispose(): void {
clearTimeout(this._timer);
this._waitingCommandQueue = [];
@@ -89,7 +101,7 @@ export class FormulaCalculationTriggerService extends Disposable {
}
const conversion = this._activeDirtyManagerService.get(command.id);
- if (!conversion) {
+ if (!conversion || this._suppressed) {
return;
}
if (conversion.shouldTrigger?.(command, options) === false) {
@@ -213,7 +225,7 @@ function createEmptyDirtyData(): IFormulaDirtyData {
};
}
-function mergeDirtyData(left: IFormulaDirtyData, right: Partial<IFormulaDirtyData>): IFormulaDirtyData {
+export function mergeDirtyData(left: Partial<IFormulaDirtyData>, right: Partial<IFormulaDirtyData>): IFormulaDirtyData {
const result = createEmptyDirtyData();
const rangeKeys = new Set<string>();
appendDirtyData(result, left, rangeKeys);
diff --git a/packages/engine-formula/src/services/formula-changeset-calculation.service.ts b/packages/engine-formula/src/services/formula-changeset-calculation.service.ts
new file mode 100644
index 0000000000..5aa038c4a3
--- /dev/null
+++ b/packages/engine-formula/src/services/formula-changeset-calculation.service.ts
@@ -0,0 +1,40 @@
+/**
+ * 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';
+import { createIdentifier } 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 const IFormulaChangesetCalculationService = createIdentifier<IFormulaChangesetCalculationService>(
+ 'engine-formula.changeset-calculation.service'
+);