@univerjs/engine-formula 0.12.4 → 0.13.0-insiders.20251216-1519cb7

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

@@ -1,5 +1,5 @@
-import { IDisposable, ICommandService, IConfigService, Injector } from '@univerjs/core';
-import { FormulaExecutedStateType, IExecutionInProgressParams, ISequenceNode, LexerTreeBuilder } from '@univerjs/engine-formula';
+import { IDisposable, IUnitRange, ICommandService, IConfigService, Injector } from '@univerjs/core';
+import { FormulaExecutedStateType, IExecutionInProgressParams, IExprTreeNode, IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaExecuteResultMap, IFormulaStringMap, ISequenceNode, ISetFormulaCalculationResultMutation, IDefinedNamesService, IFunctionService, ISuperTableService, LexerTreeBuilder } from '@univerjs/engine-formula';
 import { FBase } from '@univerjs/core/facade';
 /**
  * This interface class provides methods to modify the behavior of the operation formula.
@@ -10,7 +10,10 @@ export declare class FFormula extends FBase {
     protected readonly _injector: Injector;
     private _lexerTreeBuilder;
     protected readonly _configService: IConfigService;
-    constructor(_commandService: ICommandService, _injector: Injector, _lexerTreeBuilder: LexerTreeBuilder, _configService: IConfigService);
+    private readonly _functionService;
+    private readonly _definedNamesService;
+    private readonly _superTableService;
+    constructor(_commandService: ICommandService, _injector: Injector, _lexerTreeBuilder: LexerTreeBuilder, _configService: IConfigService, _functionService: IFunctionService, _definedNamesService: IDefinedNamesService, _superTableService: ISuperTableService);
     /**
      * @ignore
      */
@@ -146,4 +149,370 @@ export declare class FFormula extends FBase {
      * ```
      */
     setMaxIteration(maxIteration: number): void;
+    /**
+     * Listens for the moment when formula-calculation results are applied.
+     *
+     * This event fires after the engine completes a calculation cycle and
+     * dispatches a `SetFormulaCalculationResultMutation`.
+     * The callback is invoked during an idle frame to avoid blocking UI updates.
+     *
+     * @param {Function} callback - A function called with the calculation result payload
+     * once the result-application mutation is emitted.
+     * @returns {IDisposable} A disposable used to unsubscribe from the event.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * const dispose = formulaEngine.calculationResultApplied((result) => {
+     *   console.log('Calculation results applied:', result);
+     * });
+     *
+     * // Later…
+     * dispose.dispose();
+     * ```
+     */
+    calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
+    /**
+     * Waits for formula-calculation results to be applied.
+     *
+     * This method resolves under three conditions:
+     * 1. A real calculation runs and the engine emits a "calculation started" signal,
+     *    followed by a "calculation result applied" signal.
+     * 2. No calculation actually starts within 500 ms — the method assumes there is
+     *    nothing to wait for and resolves automatically.
+     * 3. A global 30 s timeout triggers, in which case the promise rejects.
+     *
+     * The API internally listens to both “calculation in progress” events and
+     * “calculation result applied” events, ensuring it behaves correctly whether
+     * formulas are recalculated or skipped due to cache/state.
+     *
+     * @returns {Promise<void>} A promise that resolves when calculation results are applied
+     * or when no calculation occurs within the start-detection window.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Wait for formula updates to apply before reading values.
+     * await formulaEngine.onCalculationResultApplied();
+     *
+     * const value = sheet.getRange("C24").getValue();
+     * console.log("Updated value:", value);
+     * ```
+     */
+    onCalculationResultApplied(): Promise<void>;
+    /**
+     * Execute a batch of formulas asynchronously and receive computed results.
+     *
+     * Each formula cell is represented as a string array:
+     *   [fullFormula, ...subFormulas]
+     *
+     * Where:
+     *   - fullFormula (index 0) is the complete formula expression written in the cell.
+     *     Example: "=SUM(A1:A10) + SQRT(D7)".
+     *
+     *   - subFormulas (index 1+) are **optional decomposed expressions** extracted from
+     *     the full formula. Each of them can be independently computed by the formula engine.
+     *
+     *     These sub-expressions can include:
+     *       - Single-cell references:  "A2", "B2", "C5"
+     *       - Range references:        "A1:A10"
+     *       - Function calls:          "SQRT(D7)", "ABS(A2-B2)"
+     *       - Any sub-formula that was parsed out of the original formula and can be
+     *         evaluated on its own.
+     *
+     *     The batch execution engine may use these sub-formulas for dependency resolution,
+     *     incremental computation, or performance optimizations.
+     *
+     * @param {IFormulaStringMap} formulas
+     *        Nested structure (unit → sheet → row → column) describing formulas and
+     *        their decomposed sub-expressions.
+     *
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
+     *
+     * @returns {Promise<IFormulaExecuteResultMap>}
+     *          A promise that resolves with the computed value map mirroring
+     *          the input structure.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * const formulas = {
+     *   Book1: {
+     *     Sheet1: {
+     *       2: {
+     *         3: [
+     *           // Full formula:
+     *           "=SUM(A1:A10) + SQRT(D7)",
+     *
+     *           // Decomposed sub-formulas (each one can be evaluated independently):
+     *           "SUM(A1:A10)",   // sub-formula 1
+     *           "SQRT(D7)",      // sub-formula 2
+     *           "A1:A10",        // range reference
+     *           "D7",            // single-cell reference
+     *         ],
+     *       },
+     *       4: {
+     *         5: [
+     *           "=A2 + B2 + SQRT(C5)",
+     *           "A2",
+     *           "B2",
+     *           "SQRT(C5)",
+     *         ],
+     *       }
+     *     },
+     *   },
+     * };
+     *
+     * const result = await formulaEngine.executeFormulas(formulas);
+     * console.log(result);
+     * ```
+     */
+    executeFormulas(formulas: IFormulaStringMap, timeout?: number): Promise<IFormulaExecuteResultMap>;
+    /**
+     * Retrieve all formula dependency trees that were produced during the latest
+     * dependency-analysis run. This triggers a local dependency-calculation command
+     * and returns the complete set of dependency trees once the calculation finishes.
+     *
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
+     *
+     * @returns {Promise<IFormulaDependencyTreeJson[]>}
+     *          A promise that resolves with the array of dependency trees.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Fetch all dependency trees generated for the current workbook.
+     * const trees = await formulaEngine.getAllDependencyTrees();
+     * console.log('All dependency trees:', trees);
+     * ```
+     */
+    getAllDependencyTrees(timeout?: number): Promise<IFormulaDependencyTreeJson[]>;
+    /**
+     * Retrieve the dependency tree of a specific cell. This triggers a local
+     * dependency-calculation command for the given unit, sheet, and cell location,
+     * and returns the computed dependency tree when the calculation is completed.
+     *
+     * @param param The target cell location:
+     *   - `unitId`  The workbook ID.
+     *   - `sheetId` The sheet ID.
+     *   - `row`     The zero-based row index.
+     *   - `column`  The zero-based column index.
+     *
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
+     *
+     * @returns {Promise<IFormulaDependencyTreeFullJson | undefined>}
+     *          A promise that resolves with the dependency tree or `undefined`
+     *          if no tree exists for that cell.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Query the dependency tree for cell B2 in a specific sheet.
+     * const tree = await formulaEngine.getCellDependencyTree({
+     *   unitId: 'workbook1',
+     *   sheetId: 'sheet1',
+     *   row: 1,
+     *   column: 1,
+     * });
+     *
+     * console.log('Cell dependency tree:', tree);
+     * ```
+     */
+    getCellDependencyTree(param: {
+        unitId: string;
+        sheetId: string;
+        row: number;
+        column: number;
+    }, timeout?: number): Promise<IFormulaDependencyTreeFullJson | undefined>;
+    /**
+     * Retrieve the full dependency trees for all formulas that *depend on* the
+     * specified ranges. This triggers a local dependency-calculation command and
+     * resolves once the calculation completes.
+     *
+     * @param unitRanges An array of workbook/sheet ranges to query. Each range
+     *   includes:
+     *   - `unitId`  The workbook ID.
+     *   - `sheetId` The sheet ID.
+     *   - `range`   The row/column boundaries.
+     *
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
+     *
+     * @returns {Promise<IFormulaDependencyTreeJson[]>}
+     *          A promise that resolves with an array of `IFormulaDependencyTreeJson`
+     *          representing formulas and their relationships within the dependency graph.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Query all formulas that depend on A1:B10 in Sheet1.
+     * const dependents = await formulaEngine.getRangeDependents([
+     *   { unitId: 'workbook1', sheetId: 'sheet1', range: { startRow: 0, endRow: 9, startColumn: 0, endColumn: 1 } }
+     * ]);
+     *
+     * console.log('Dependent formulas:', dependents);
+     * ```
+     */
+    getRangeDependents(unitRanges: IUnitRange[], timeout?: number): Promise<IFormulaDependencyTreeJson[]>;
+    /**
+     * Retrieve the dependency trees of all formulas *inside* the specified ranges.
+     * Unlike `getRangeDependents`, this API only returns formulas whose definitions
+     * physically reside within the queried ranges.
+     *
+     * Internally this triggers the same dependency-calculation command but with
+     * `isInRange = true`, and the promise resolves when the results are ready.
+     *
+     * @param unitRanges An array of workbook/sheet ranges defining the lookup
+     *   boundaries:
+     *   - `unitId`  The workbook ID.
+     *   - `sheetId` The sheet ID.
+     *   - `range`   The zero-based grid range.
+     *
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
+     *
+     * @returns {Promise<IFormulaDependencyTreeJson[]>}
+     *          A promise that resolves with an array of `IFormulaDependencyTreeJson`
+     *          describing every formula found in the provided ranges along with
+     *          their parent/child relationships.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Query all formulas that lie within A1:D20 in Sheet1.
+     * const formulasInRange = await formulaEngine.getInRangeFormulas([
+     *   { unitId: 'workbook1', sheetId: 'sheet1', range: { startRow: 0, endRow: 19, startColumn: 0, endColumn: 3 } }
+     * ]);
+     *
+     * console.log('Formulas inside range:', formulasInRange);
+     * ```
+     */
+    getInRangeFormulas(unitRanges: IUnitRange[], timeout?: number): Promise<IFormulaDependencyTreeJson[]>;
+    /**
+     * Enable or disable emitting formula dependency trees after each formula calculation.
+     *
+     * When enabled, the formula engine will emit the dependency trees produced by
+     * each completed formula calculation through the internal command system.
+     * Consumers can obtain the result by listening for the corresponding
+     * calculation-result command.
+     *
+     * When disabled, dependency trees will not be emitted.
+     *
+     * This option only controls whether dependency trees are exposed.
+     * It does not affect formula calculation behavior.
+     *
+     * @param {boolean} value
+     *        Whether to emit formula dependency trees after calculation.
+     *        - `true`: Emit dependency trees after each calculation.
+     *        - `false`: Do not emit dependency trees (default behavior).
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * // Enable dependency tree emission
+     * formulaEngine.setFormulaReturnDependencyTree(true);
+     *
+     * // Listen for dependency trees produced by formula calculation
+     * const trees = await new Promise<IFormulaDependencyTreeJson[]>((resolve, reject) => {
+     *   const timer = setTimeout(() => {
+     *     disposable.dispose();
+     *     reject(new Error('Timeout waiting for formula dependency trees'));
+     *   }, 30_000);
+     *
+     *   const disposable = commandService.onCommandExecuted((command) => {
+     *     if (command.id !== SetFormulaDependencyCalculationResultMutation.id) {
+     *       return;
+     *     }
+     *
+     *     clearTimeout(timer);
+     *     disposable.dispose();
+     *
+     *     const params = command.params as ISetFormulaDependencyCalculationResultMutation;
+     *     resolve(params.result ?? []);
+     *   });
+     * });
+     *
+     * console.log('Dependency trees:', trees);
+     * ```
+     */
+    setFormulaReturnDependencyTree(value: boolean): void;
+    /**
+     * Parse a formula string and return its **formula expression tree**.
+     *
+     * This API analyzes the syntactic structure of a formula and builds an
+     * expression tree that reflects how the formula is composed (functions,
+     * operators, ranges, and nested expressions), without performing calculation
+     * or dependency evaluation.
+     *
+     * The returned tree is suitable for:
+     * - Formula structure visualization
+     * - Explaining complex formulas (e.g. LET / LAMBDA)
+     * - Debugging or inspecting formula composition
+     * - Building advanced formula tooling
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     *
+     * const formula = '=LET(x,SUM(A1,B1,A1:B10),y,OFFSET(A1:B10,0,1),SUM(x,y)+x)+1';
+     *
+     * const exprTree = formulaEngine.getFormulaExpressTree(formula);
+     *
+     * console.log(exprTree);
+     * ```
+     *
+     * Example output (simplified):
+     *
+     * ```json
+     * {
+     *   "value": "let(x,sum(A1,B1,A1:B10),y,offset(A1:B10,0,1),sum(x,y)+x)+1",
+     *   "children": [
+     *     {
+     *       "value": "let(x,sum(A1,B1,A1:B10),y,offset(A1:B10,0,1),sum(x,y)+x)",
+     *       "children": [
+     *         {
+     *           "value": "sum(A1,B1,A1:B10)",
+     *           "children": [
+     *             {
+     *               "value": "A1:B10",
+     *               "children": []
+     *             }
+     *           ]
+     *         },
+     *         {
+     *           "value": "offset(A1:B10,0,1)",
+     *           "children": [
+     *             {
+     *               "value": "A1:B10",
+     *               "children": []
+     *             }
+     *           ]
+     *         }
+     *       ]
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * @param formulaString The formula string to parse (with or without leading `=`)
+     * @returns A formula expression tree describing the hierarchical structure of the formula
+     */
+    getFormulaExpressTree(formulaString: string, unitId: string): IExprTreeNode | null;
 }

package/lib/types/index.d.ts

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export type { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IArrayFormulaUnitCellType, IDirtyUnitFeatureMap, IDirtyUnitOtherFormulaMap, IDirtyUnitSheetDefinedNameMap, IDirtyUnitSheetNameMap, IFeatureDirtyRangeType, IFormulaData, IFormulaDataItem, IFormulaDatasetConfig, IRuntimeImageFormulaDataType, IRuntimeUnitDataType, ISheetData, IUnitData, IUnitImageFormulaDataType, IUnitSheetNameMap, } from './basics/common';
+export type { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IArrayFormulaUnitCellType, IDirtyUnitFeatureMap, IDirtyUnitOtherFormulaMap, IDirtyUnitSheetDefinedNameMap, IDirtyUnitSheetNameMap, IFeatureDirtyRangeType, IFormulaData, IFormulaDataItem, IFormulaDatasetConfig, IFormulaExecuteResultMap, IFormulaStringMap, IRuntimeImageFormulaDataType, IRuntimeUnitDataType, ISheetData, IUnitData, IUnitImageFormulaDataType, IUnitSheetNameMap, } from './basics/common';
 export { BooleanValue } from './basics/common';
 export { type IOtherFormulaData } from './basics/common';
-export { type IUnitRowData } from './basics/common';
+export type { IExprTreeNode, ISuperTable, IUnitRowData } from './basics/common';
 export { isInDirtyRange } from './basics/dirty';
 export { ERROR_TYPE_SET, ErrorType } from './basics/error-type';
 export { type ISheetFormulaError } from './basics/error-type';
@@ -33,14 +33,14 @@ export { type ISetArrayFormulaDataMutationParams, SetArrayFormulaDataMutation }
 export { type ISetDefinedNameMutationParam, type ISetDefinedNameMutationSearchParam, RemoveDefinedNameMutation, SetDefinedNameMutation } from './commands/mutations/set-defined-name.mutation';
 export { SetDefinedNameMutationFactory } from './commands/mutations/set-defined-name.mutation';
 export { RemoveFeatureCalculationMutation, SetFeatureCalculationMutation } from './commands/mutations/set-feature-calculation.mutation';
-export { type ISetFormulaCalculationNotificationMutation, type ISetFormulaCalculationResultMutation, type ISetFormulaCalculationStartMutation, SetFormulaCalculationNotificationMutation, SetFormulaCalculationResultMutation, SetFormulaCalculationStartMutation, SetFormulaCalculationStopMutation, } from './commands/mutations/set-formula-calculation.mutation';
+export { type ISetCellFormulaDependencyCalculationResultMutation, type ISetFormulaCalculationNotificationMutation, type ISetFormulaCalculationResultMutation, type ISetFormulaCalculationStartMutation, type ISetFormulaDependencyCalculationMutation, type ISetFormulaDependencyCalculationResultMutation, type ISetFormulaStringBatchCalculationResultMutation, type ISetQueryFormulaDependencyResultMutation, SetCellFormulaDependencyCalculationMutation, SetCellFormulaDependencyCalculationResultMutation, SetFormulaCalculationNotificationMutation, SetFormulaCalculationResultMutation, SetFormulaCalculationStartMutation, SetFormulaCalculationStopMutation, SetFormulaDependencyCalculationMutation, SetFormulaDependencyCalculationResultMutation, SetFormulaStringBatchCalculationMutation, SetFormulaStringBatchCalculationResultMutation, SetQueryFormulaDependencyMutation, SetQueryFormulaDependencyResultMutation, } from './commands/mutations/set-formula-calculation.mutation';
 export { type ISetFormulaDataMutationParams, SetFormulaDataMutation } from './commands/mutations/set-formula-data.mutation';
 export { type ISetImageFormulaDataMutationParams, SetImageFormulaDataMutation } from './commands/mutations/set-image-formula-data.mutation';
 export { type IRemoveOtherFormulaMutationParams, type ISetOtherFormulaMutationParams, RemoveOtherFormulaMutation, SetOtherFormulaMutation } from './commands/mutations/set-other-formula.mutation';
 export { RemoveSuperTableMutation, SetSuperTableMutation, SetSuperTableOptionMutation } from './commands/mutations/set-super-table.mutation';
 export type { ISetSuperTableMutationParam, ISetSuperTableMutationSearchParam } from './commands/mutations/set-super-table.mutation';
 export { CalculateController } from './controller/calculate.controller';
-export { ENGINE_FORMULA_CYCLE_REFERENCE_COUNT, ENGINE_FORMULA_PLUGIN_CONFIG_KEY, type IUniverEngineFormulaConfig } from './controller/config.schema';
+export { ENGINE_FORMULA_CYCLE_REFERENCE_COUNT, ENGINE_FORMULA_PLUGIN_CONFIG_KEY, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE, type IUniverEngineFormulaConfig } from './controller/config.schema';
 export { Lexer } from './engine/analysis/lexer';
 export { LexerNode } from './engine/analysis/lexer-node';
 export { LexerTreeBuilder } from './engine/analysis/lexer-tree-builder';
@@ -56,7 +56,7 @@ export { ReferenceNodeFactory } from './engine/ast-node/reference-node';
 export { SuffixNodeFactory } from './engine/ast-node/suffix-node';
 export { UnionNodeFactory } from './engine/ast-node/union-node';
 export { ValueNodeFactory } from './engine/ast-node/value-node';
-export { FormulaDependencyTree, type IFormulaDependencyTree } from './engine/dependency/dependency-tree';
+export { FormulaDependencyTree, FormulaDependencyTreeModel, type IFormulaDependencyTree, type IFormulaDependencyTreeFullJson, type IFormulaDependencyTreeJson } from './engine/dependency/dependency-tree';
 export { FormulaDependencyTreeType } from './engine/dependency/dependency-tree';
 export { FormulaDependencyTreeVirtual } from './engine/dependency/dependency-tree';
 export { FormulaDependencyGenerator, IFormulaDependencyGenerator } from './engine/dependency/formula-dependency';
@@ -71,7 +71,7 @@ export { generateAstNode } from './engine/utils/generate-ast-node';
 export { strip, stripErrorMargin } from './engine/utils/math-kit';
 export { handleNumfmtInCell } from './engine/utils/numfmt-kit';
 export { deserializeRangeForR1C1 } from './engine/utils/r1c1-reference';
-export { deserializeRangeWithSheet, getAbsoluteRefTypeWithSingleString, getAbsoluteRefTypeWitString, getRangeWithRefsString, type IAbsoluteRefTypeForRange, isReferenceStrings, isReferenceStringWithEffectiveColumn, needsQuoting, quoteSheetName, serializeRange, serializeRangeToRefString, serializeRangeWithSheet, serializeRangeWithSpreadsheet, singleReferenceToGrid, unquoteSheetName, } from './engine/utils/reference';
+export { deserializeRangeWithSheet, getAbsoluteRefTypeWithSingleString, getAbsoluteRefTypeWitString, getRangeWithRefsString, type IAbsoluteRefTypeForRange, isReferenceStrings, isReferenceStringWithEffectiveColumn, needsQuoting, quoteSheetName, serializeRange, serializeRangeToRefString, serializeRangeWithSheet, serializeRangeWithSpreadsheet, singleReferenceToGrid, splitTableStructuredRef, unquoteSheetName, } from './engine/utils/reference';
 export { handleRefStringInfo } from './engine/utils/reference';
 export { deserializeRangeWithSheetWithCache } from './engine/utils/reference-cache';
 export { generateStringWithSequence, type ISequenceNode, sequenceNodeType } from './engine/utils/sequence';

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

@@ -1,10 +1,11 @@
+import { IUnitRange, Disposable, IConfigService } from '@univerjs/core';
 import { Observable, Subject } from 'rxjs';
-import { IFeatureDirtyRangeType, IFormulaDatasetConfig, IRuntimeUnitDataType } from '../basics/common';
+import { IFeatureDirtyRangeType, IFormulaDatasetConfig, IFormulaExecuteResultMap, IFormulaStringMap, IRuntimeUnitDataType, IUnitRowData } from '../basics/common';
+import { IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson } from '../engine/dependency/dependency-tree';
+import { FunctionVariantType } from '../engine/reference-object/base-reference-object';
 import { IAllRuntimeData, IExecutionInProgressParams, IFormulaRuntimeService } from './runtime.service';
-import { Disposable, IConfigService } from '@univerjs/core';
 import { Lexer } from '../engine/analysis/lexer';
 import { AstTreeBuilder } from '../engine/analysis/parser';
-import { ErrorNode } from '../engine/ast-node/base-ast-node';
 import { IFormulaDependencyGenerator } from '../engine/dependency/formula-dependency';
 import { Interpreter } from '../engine/interpreter/interpreter';
 import { IFormulaCurrentConfigService } from './current-data.service';
@@ -19,6 +20,11 @@ export interface ICalculateFormulaService {
     execute(formulaDatasetConfig: IFormulaDatasetConfig): Promise<void>;
     stopFormulaExecution(): void;
     calculate(formulaString: string, transformSuffix?: boolean): void;
+    executeFormulas(formulas: IFormulaStringMap, rowData?: IUnitRowData): Promise<IFormulaExecuteResultMap>;
+    getAllDependencyJson(rowData?: IUnitRowData): Promise<IFormulaDependencyTreeJson[]>;
+    getCellDependencyJson(unitId: string, sheetId: string, row: number, column: number, rowData?: IUnitRowData): Promise<IFormulaDependencyTreeFullJson | undefined>;
+    getRangeDependents(unitRanges: IUnitRange[]): Promise<IFormulaDependencyTreeJson[]>;
+    getInRangeFormulas(unitRanges: IUnitRange[]): Promise<IFormulaDependencyTreeJson[]>;
 }
 export declare const ICalculateFormulaService: import('@wendellhu/redi').IdentifierDecorator<ICalculateFormulaService>;
 export declare class CalculateFormulaService extends Disposable implements ICalculateFormulaService {
@@ -34,6 +40,7 @@ export declare class CalculateFormulaService extends Disposable implements ICalc
     protected readonly _executionCompleteListener$: Subject<IAllRuntimeData>;
     readonly executionCompleteListener$: Observable<IAllRuntimeData>;
     private _executeLock;
+    protected _isCalculateTreeModel: boolean;
     constructor(_configService: IConfigService, _lexer: Lexer, _currentConfigService: IFormulaCurrentConfigService, _runtimeService: IFormulaRuntimeService, _formulaDependencyGenerator: IFormulaDependencyGenerator, _interpreter: Interpreter, _astTreeBuilder: AstTreeBuilder);
     dispose(): void;
     /**
@@ -53,5 +60,10 @@ export declare class CalculateFormulaService extends Disposable implements ICalc
     private _executeStep;
     private _getArrayFormulaDirtyRangeAndExcludedRange;
     protected _apply(isArrayFormulaState?: boolean): Promise<IAllRuntimeData | undefined>;
-    calculate(formulaString: string, transformSuffix?: boolean): ErrorNode | undefined;
+    executeFormulas(formulas: IFormulaStringMap, rowData?: IUnitRowData): Promise<IFormulaExecuteResultMap>;
+    calculate(formulaString: string): Promise<FunctionVariantType | undefined>;
+    getAllDependencyJson(): Promise<IFormulaDependencyTreeJson[]>;
+    getCellDependencyJson(unitId: string, sheetId: string, row: number, column: number): Promise<IFormulaDependencyTreeFullJson | undefined>;
+    getRangeDependents(unitRanges: IUnitRange[]): Promise<IFormulaDependencyTreeJson[]>;
+    getInRangeFormulas(unitRanges: IUnitRange[]): Promise<IFormulaDependencyTreeJson[]>;
 }

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

@@ -11,6 +11,7 @@ export interface IFormulaDirtyData {
     dirtyUnitOtherFormulaMap: IDirtyUnitOtherFormulaMap;
     clearDependencyTreeCache: IDirtyUnitSheetNameMap;
     maxIteration?: number;
+    isCalculateTreeModel?: boolean;
     rowData?: IUnitRowData;
 }
 export interface IFormulaCurrentConfigService {
@@ -55,6 +56,7 @@ export interface IFormulaCurrentConfigService {
     };
     getFilteredOutRows(unitId: string, sheetId: string, startRow: number, endRow: number): number[];
     setSheetNameMap(sheetIdToNameMap: IUnitSheetIdToNameMap): void;
+    loadDataLite(rowData?: IUnitRowData): void;
 }
 export declare class FormulaCurrentConfigService extends Disposable implements IFormulaCurrentConfigService {
     private readonly _univerInstanceService;
@@ -113,6 +115,7 @@ export declare class FormulaCurrentConfigService extends Disposable implements I
     };
     getFilteredOutRows(unitId: string, sheetId: string, startRow: number, endRow: number): number[];
     load(config: IFormulaDatasetConfig): void;
+    loadDataLite(rowData?: IUnitRowData): void;
     getDirtyData(): IFormulaDirtyData;
     loadDirtyRangesAndExcludedCell(dirtyRanges: IUnitRange[], excludedCell?: IUnitExcludedCell): void;
     registerUnitData(unitData: IUnitData): void;

package/lib/types/services/defined-names.service.d.ts

@@ -64,6 +64,7 @@ export declare class DefinedNamesService extends Disposable implements IDefinedN
     getValueById(unitId: string, id: string): IDefinedNamesServiceParam;
     hasDefinedName(unitId: string): boolean;
     getAllDefinedNames(): IDefinedNameMap;
+    getDefinedNameByRefString(unitId: string, formulaOrRefString: string): IDefinedNamesServiceParam | undefined;
     private _update;
     private _updateCache;
 }

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

@@ -1,6 +1,7 @@
 import { Nullable, Disposable } from '@univerjs/core';
 import { IArrayFormulaEmbeddedMap, IArrayFormulaRangeType, IFeatureDirtyRangeType, IRuntimeImageFormulaDataType, IRuntimeOtherUnitDataType, IRuntimeUnitDataType } from '../basics/common';
 import { BaseAstNode } from '../engine/ast-node/base-ast-node';
+import { IFormulaDependencyTreeJson } from '../engine/dependency/dependency-tree';
 import { FunctionVariantType } from '../engine/reference-object/base-reference-object';
 import { IFormulaCurrentConfigService } from './current-data.service';
 import { IHyperlinkEngineFormulaService } from './hyperlink-engine-formula.service';
@@ -40,6 +41,7 @@ export interface IAllRuntimeData {
     runtimeFeatureCellData: {
         [featureId: string]: IRuntimeUnitDataType;
     };
+    dependencyTreeModelData: IFormulaDependencyTreeJson[];
 }
 export interface IExecutionInProgressParams {
     totalFormulasToCalculate: number;
@@ -100,6 +102,8 @@ export interface IFormulaRuntimeService {
     setUnitArrayFormulaEmbeddedMap(): void;
     clearArrayObjectCache(): void;
     getRuntimeImageFormulaData(): IRuntimeImageFormulaDataType[];
+    setDependencyTreeModelData(data: IFormulaDependencyTreeJson[]): void;
+    getDependencyTreeModelData(): IFormulaDependencyTreeJson[];
 }
 export declare class FormulaRuntimeService extends Disposable implements IFormulaRuntimeService {
     private readonly _currentConfigService;
@@ -129,6 +133,7 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     private _completedArrayFormulasCount;
     private _formulaCycleIndex;
     private _isCycleDependency;
+    private _dependencyTreeModelData;
     constructor(_currentConfigService: IFormulaCurrentConfigService, _hyperlinkEngineFormulaService: IHyperlinkEngineFormulaService);
     get currentRow(): number;
     get currentColumn(): number;
@@ -182,6 +187,8 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
         [featureId: string]: IRuntimeUnitDataType;
     };
     setRuntimeFeatureCellData(featureId: string, featureData: IRuntimeUnitDataType): void;
+    setDependencyTreeModelData(data: IFormulaDependencyTreeJson[]): void;
+    getDependencyTreeModelData(): IFormulaDependencyTreeJson[];
     getRuntimeImageFormulaData(): IRuntimeImageFormulaDataType[];
     getAllRuntimeData(): IAllRuntimeData;
     getRuntimeState(): IExecutionInProgressParams;

package/lib/types/services/super-table.service.d.ts

@@ -12,6 +12,7 @@ export interface ISuperTableService {
     registerTableOptionMap(tableOption: string, tableOptionType: TableOptionType): void;
     remove(unitId: string, tableName: string): void;
     update$: Observable<unknown>;
+    getTable(unitId: string, tableName: string): Nullable<ISuperTable>;
 }
 export declare class SuperTableService extends Disposable implements ISuperTableService {
     private _tableMap;
@@ -25,6 +26,7 @@ export declare class SuperTableService extends Disposable implements ISuperTable
     getTableOptionMap(): Map<string, TableOptionType>;
     registerTable(unitId: string, tableName: string, reference: ISuperTable): void;
     registerTableOptionMap(tableOption: string, tableOptionType: TableOptionType): void;
+    getTable(unitId: string, tableName: string): Nullable<ISuperTable>;
     private _update;
 }
 export declare const ISuperTableService: import('@wendellhu/redi').IdentifierDecorator<ISuperTableService>;

package/lib/umd/facade.js

@@ -1 +1 @@
-(function(r,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula"),require("rxjs")):typeof define=="function"&&define.amd?define(["exports","@univerjs/core/facade","@univerjs/core","@univerjs/engine-formula","rxjs"],o):(r=typeof globalThis<"u"?globalThis:r||self,o(r.UniverEngineFormulaFacade={},r.UniverCoreFacade,r.UniverCore,r.UniverEngineFormula,r.rxjs))})(this,(function(r,o,u,a,s){"use strict";var f=Object.getOwnPropertyDescriptor,v=(c,e,t,i)=>{for(var n=i>1?void 0:i?f(e,t):e,d=c.length-1,m;d>=0;d--)(m=c[d])&&(n=m(n)||n);return n},l=(c,e)=>(t,i)=>e(t,i,c);r.FFormula=class extends o.FBase{constructor(e,t,i,n){super(),this._commandService=e,this._injector=t,this._lexerTreeBuilder=i,this._configService=n,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,t,i,n){return this._lexerTreeBuilder.moveFormulaRefOffset(e,t,i,n)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(a.SetFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(a.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===a.SetFormulaCalculationStartMutation.id){const i=t.params;e(i.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==a.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.functionsExecutedState!==void 0&&e(i.functionsExecutedState)})}whenComputingCompleteAsync(e){const t=this._injector.get(a.GlobalComputingStatusService);return t.computingStatus?Promise.resolve(!0):s.firstValueFrom(s.race(t.computingStatus$.pipe(s.filter(i=>i)),s.timer(e!=null?e:3e4).pipe(s.map(()=>!1))))}onCalculationEnd(){return new Promise((e,t)=>{const i=setTimeout(()=>{t(new Error("Calculation end timeout"))},3e4),n=this.calculationEnd(()=>{clearTimeout(i),n.dispose(),e()})})}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==a.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.stageInfo!==void 0&&e(i.stageInfo)})}setMaxIteration(e){this._configService.setConfig(a.ENGINE_FORMULA_CYCLE_REFERENCE_COUNT,e)}},r.FFormula=v([l(0,u.Inject(u.ICommandService)),l(1,u.Inject(u.Injector)),l(2,u.Inject(a.LexerTreeBuilder)),l(3,u.IConfigService)],r.FFormula);class C extends o.FUniver{getFormula(){return this._injector.createInstance(r.FFormula)}}o.FUniver.extend(C),Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));
+(function(u,l){typeof exports=="object"&&typeof module<"u"?l(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula"),require("rxjs")):typeof define=="function"&&define.amd?define(["exports","@univerjs/core/facade","@univerjs/core","@univerjs/engine-formula","rxjs"],l):(u=typeof globalThis<"u"?globalThis:u||self,l(u.UniverEngineFormulaFacade={},u.UniverCoreFacade,u.UniverCore,u.UniverEngineFormula,u.rxjs))})(this,(function(u,l,m,n,f){"use strict";var v=Object.getOwnPropertyDescriptor,C=(p,e,t,i)=>{for(var r=i>1?void 0:i?v(e,t):e,o=p.length-1,a;o>=0;o--)(a=p[o])&&(r=a(r)||r);return r},d=(p,e)=>(t,i)=>e(t,i,p);u.FFormula=class extends l.FBase{constructor(e,t,i,r,o,a,s){super(),this._commandService=e,this._injector=t,this._lexerTreeBuilder=i,this._configService=r,this._functionService=o,this._definedNamesService=a,this._superTableService=s,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,t,i,r){return this._lexerTreeBuilder.moveFormulaRefOffset(e,t,i,r)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(n.SetFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(n.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===n.SetFormulaCalculationStartMutation.id){const i=t.params;e(i.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==n.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.functionsExecutedState!==void 0&&e(i.functionsExecutedState)})}whenComputingCompleteAsync(e){const t=this._injector.get(n.GlobalComputingStatusService);return t.computingStatus?Promise.resolve(!0):f.firstValueFrom(f.race(t.computingStatus$.pipe(f.filter(i=>i)),f.timer(e!=null?e:3e4).pipe(f.map(()=>!1))))}onCalculationEnd(){return new Promise((e,t)=>{const i=setTimeout(()=>{t(new Error("Calculation end timeout"))},3e4),r=this.calculationEnd(()=>{clearTimeout(i),r.dispose(),e()})})}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==n.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.stageInfo!==void 0&&e(i.stageInfo)})}setMaxIteration(e){this._configService.setConfig(n.ENGINE_FORMULA_CYCLE_REFERENCE_COUNT,e)}calculationResultApplied(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==n.SetFormulaCalculationResultMutation.id)return;const i=t.params;i!==void 0&&requestIdleCallback(()=>{e(i)})})}onCalculationResultApplied(){return new Promise((e,t)=>{let i=!1,r=!1;const o=setTimeout(()=>{S(),t(new Error("Calculation end timeout"))},3e4),a=setTimeout(()=>{i||(S(),e())},500),s=this.calculationProcessing(()=>{i||(i=!0,clearTimeout(a))}),c=this.calculationResultApplied(()=>{r||(r=!0,S(),e())});function S(){clearTimeout(o),clearTimeout(a),s.dispose(),c.dispose()}})}executeFormulas(e,t=3e4){return new Promise((i,r)=>{const o=this._commandService.onCommandExecuted(s=>{if(s.id!==n.SetFormulaStringBatchCalculationResultMutation.id)return;const c=s.params;clearTimeout(a),o.dispose(),c.result!=null?i(c.result):r(new Error("Formula batch calculation returned no result"))}),a=setTimeout(()=>{o.dispose(),r(new Error("Formula batch calculation timeout"))},t);this._commandService.executeCommand(n.SetFormulaStringBatchCalculationMutation.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((t,i)=>{const r=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetFormulaDependencyCalculationResultMutation.id)return;const s=a.params;clearTimeout(o),r.dispose(),s.result!=null?t(s.result):t([])}),o=setTimeout(()=>{r.dispose(),i(new Error("Formula dependency calculation timeout"))},e);this._commandService.executeCommand(n.SetFormulaDependencyCalculationMutation.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,t=3e4){return new Promise((i,r)=>{const o=this._commandService.onCommandExecuted(s=>{if(s.id!==n.SetCellFormulaDependencyCalculationResultMutation.id)return;const c=s.params;clearTimeout(a),o.dispose(),i(c.result)}),a=setTimeout(()=>{o.dispose(),r(new Error("Cell dependency calculation timeout"))},t);this._commandService.executeCommand(n.SetCellFormulaDependencyCalculationMutation.id,e,{onlyLocal:!0})})}getRangeDependents(e,t=3e4){return new Promise((i,r)=>{const o=this._commandService.onCommandExecuted(s=>{if(s.id!==n.SetQueryFormulaDependencyResultMutation.id)return;const c=s.params;clearTimeout(a),o.dispose(),c.result!=null?i(c.result):i([])}),a=setTimeout(()=>{o.dispose(),r(new Error("Range dependents calculation timeout"))},t);this._commandService.executeCommand(n.SetQueryFormulaDependencyMutation.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,t=3e4){return new Promise((i,r)=>{const o=this._commandService.onCommandExecuted(s=>{if(s.id!==n.SetQueryFormulaDependencyResultMutation.id)return;const c=s.params;clearTimeout(a),o.dispose(),c.result!=null?i(c.result):i([])}),a=setTimeout(()=>{o.dispose(),r(new Error("In-range formulas calculation timeout"))},t);this._commandService.executeCommand(n.SetQueryFormulaDependencyMutation.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(n.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))}},u.FFormula=C([d(0,m.Inject(m.ICommandService)),d(1,m.Inject(m.Injector)),d(2,m.Inject(n.LexerTreeBuilder)),d(3,m.IConfigService),d(4,n.IFunctionService),d(5,n.IDefinedNamesService),d(6,n.ISuperTableService)],u.FFormula);class h extends l.FUniver{getFormula(){return this._injector.createInstance(u.FFormula)}}l.FUniver.extend(h),Object.defineProperty(u,Symbol.toStringTag,{value:"Module"})}));