@univerjs/engine-formula 0.20.1 → 0.21.0

package/lib/es/facade.js

@@ -1 +1,702 @@
-import{FBase as e,FUniver as t}from"@univerjs/core/facade";import{ICommandService as n,IConfigService as r,Inject as i,Injector as a}from"@univerjs/core";import{ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as o,ENGINE_FORMULA_RETURN_DEPENDENCY_TREE as s,GlobalComputingStatusService as c,IDefinedNamesService as l,IFunctionService as u,ISuperTableService as d,LexerTreeBuilder as f,SetCellFormulaDependencyCalculationMutation as p,SetCellFormulaDependencyCalculationResultMutation as m,SetFormulaCalculationNotificationMutation as h,SetFormulaCalculationStartMutation as g,SetFormulaCalculationStopMutation as _,SetFormulaDependencyCalculationMutation as v,SetFormulaDependencyCalculationResultMutation as y,SetFormulaStringBatchCalculationMutation as b,SetFormulaStringBatchCalculationResultMutation as x,SetQueryFormulaDependencyAllMutation as S,SetQueryFormulaDependencyAllResultMutation as C,SetQueryFormulaDependencyMutation as w,SetQueryFormulaDependencyResultMutation as T,SetTriggerFormulaCalculationStartMutation as E}from"@univerjs/engine-formula";import{filter as D,firstValueFrom as O,map as k,race as A,timer as j}from"rxjs";function M(e,t){return function(n,r){t(n,r,e)}}function N(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 P=class extends e{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(E.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(_.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===g.id){let n=t.params;e(n.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==h.id)return;let n=t.params;n.functionsExecutedState!==void 0&&e(n.functionsExecutedState)})}whenComputingCompleteAsync(e){let t=this._injector.get(c);return t.computingStatus?Promise.resolve(!0):O(A(t.computingStatus$.pipe(D(e=>e)),j(e==null?3e4:e).pipe(k(()=>!1))))}onCalculationEnd(){return new Promise((e,t)=>{let n=setTimeout(()=>{t(Error(`Calculation end timeout`))},3e4),r=this.calculationEnd(()=>{clearTimeout(n),r.dispose(),e()})})}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==h.id)return;let n=t.params;n.stageInfo!==void 0&&e(n.stageInfo)})}setMaxIteration(e){this._configService.setConfig(o,e)}executeFormulas(e,t=3e4){return new Promise((n,r)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==x.id)return;let t=e.params;clearTimeout(a),i.dispose(),t.result==null?r(Error(`Formula batch calculation returned no result`)):n(t.result)}),a=setTimeout(()=>{i.dispose(),r(Error(`Formula batch calculation timeout`))},t);this._commandService.executeCommand(b.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((t,n)=>{let r=this._commandService.onCommandExecuted(e=>{if(e.id!==y.id)return;let n=e.params;clearTimeout(i),r.dispose(),n.result==null?t([]):t(n.result)}),i=setTimeout(()=>{r.dispose(),n(Error(`Formula dependency calculation timeout`))},e);this._commandService.executeCommand(v.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,t=3e4){return new Promise((n,r)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==m.id)return;let t=e.params;clearTimeout(a),i.dispose(),n(t.result)}),a=setTimeout(()=>{i.dispose(),r(Error(`Cell dependency calculation timeout`))},t);this._commandService.executeCommand(p.id,e,{onlyLocal:!0})})}getRangeDependents(e,t=3e4){return new Promise((n,r)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==T.id)return;let t=e.params;clearTimeout(a),i.dispose(),t.result==null?n([]):n(t.result)}),a=setTimeout(()=>{i.dispose(),r(Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(w.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,t=3e4){return new Promise((n,r)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==T.id)return;let t=e.params;clearTimeout(a),i.dispose(),t.result==null?n([]):n(t.result)}),a=setTimeout(()=>{i.dispose(),r(Error(`In-range formulas calculation timeout`))},t);this._commandService.executeCommand(w.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(s,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,r)=>{let i=this._commandService.onCommandExecuted(e=>{if(e.id!==C.id)return;let t=e.params;clearTimeout(a),i.dispose(),t.result==null?n({dependents:[],inRanges:[]}):n(t.result)}),a=setTimeout(()=>{i.dispose(),r(Error(`Range dependents calculation timeout`))},t);this._commandService.executeCommand(S.id,{unitRanges:e},{onlyLocal:!0})})}};P=N([M(0,i(n)),M(1,i(a)),M(2,i(f)),M(3,r),M(4,u),M(5,l),M(6,d)],P);var F=class extends t{getFormula(){return this._injector.createInstance(P)}};t.extend(F);export{P as FFormula};
+import { FBase, FUniver } from "@univerjs/core/facade";
+import { ICommandService, IConfigService, Inject, Injector } from "@univerjs/core";
+import { ENGINE_FORMULA_CYCLE_REFERENCE_COUNT, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE, GlobalComputingStatusService, IDefinedNamesService, IFunctionService, ISuperTableService, LexerTreeBuilder, SetCellFormulaDependencyCalculationMutation, SetCellFormulaDependencyCalculationResultMutation, SetFormulaCalculationNotificationMutation, SetFormulaCalculationStartMutation, SetFormulaCalculationStopMutation, SetFormulaDependencyCalculationMutation, SetFormulaDependencyCalculationResultMutation, SetFormulaStringBatchCalculationMutation, SetFormulaStringBatchCalculationResultMutation, SetQueryFormulaDependencyAllMutation, SetQueryFormulaDependencyAllResultMutation, SetQueryFormulaDependencyMutation, SetQueryFormulaDependencyResultMutation, SetTriggerFormulaCalculationStartMutation } from "@univerjs/engine-formula";
+import { filter, firstValueFrom, map, race, timer } from "rxjs";
+
+//#region \0@oxc-project+runtime@0.124.0/helpers/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.124.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/facade/f-formula.ts
+let FFormula = class FFormula extends FBase {
+	constructor(_commandService, _injector, _lexerTreeBuilder, _configService, _functionService, _definedNamesService, _superTableService) {
+		super();
+		this._commandService = _commandService;
+		this._injector = _injector;
+		this._lexerTreeBuilder = _lexerTreeBuilder;
+		this._configService = _configService;
+		this._functionService = _functionService;
+		this._definedNamesService = _definedNamesService;
+		this._superTableService = _superTableService;
+		this._initialize();
+	}
+	/**
+	* @ignore
+	*/
+	_initialize() {}
+	/**
+	* The tree builder for formula string.
+	* @type {LexerTreeBuilder}
+	*/
+	get lexerTreeBuilder() {
+		return this._lexerTreeBuilder;
+	}
+	/**
+	* Offsets the formula
+	* @param {string} formulaString - The formula string to offset
+	* @param {number} refOffsetX - The offset column
+	* @param {number} refOffsetY - The offset row
+	* @param {boolean} [ignoreAbsolute] - Whether to ignore the absolute reference
+	* @returns {string} The offset formula string
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* const result = formulaEngine.moveFormulaRefOffset('=SUM(A1,B2)', 1, 1);
+	* console.log(result);
+	* ```
+	*/
+	moveFormulaRefOffset(formulaString, refOffsetX, refOffsetY, ignoreAbsolute) {
+		return this._lexerTreeBuilder.moveFormulaRefOffset(formulaString, refOffsetX, refOffsetY, ignoreAbsolute);
+	}
+	/**
+	* Resolves the formula string to a 'node' node
+	* @param {string} formulaString - The formula string to resolve
+	* @returns {Array<ISequenceNode | string>} The nodes of the formula string
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* const nodes = formulaEngine.sequenceNodesBuilder('=SUM(A1,B2)');
+	* console.log(nodes);
+	* ```
+	*/
+	sequenceNodesBuilder(formulaString) {
+		return this._lexerTreeBuilder.sequenceNodesBuilder(formulaString) || [];
+	}
+	/**
+	* Start the calculation of the formula.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* formulaEngine.executeCalculation();
+	* ```
+	*/
+	executeCalculation() {
+		this._commandService.executeCommand(SetTriggerFormulaCalculationStartMutation.id, {
+			commands: [],
+			forceCalculation: true
+		}, { onlyLocal: true });
+	}
+	/**
+	* Stop the calculation of the formula.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* formulaEngine.stopCalculation();
+	* ```
+	*/
+	stopCalculation() {
+		this._commandService.executeCommand(SetFormulaCalculationStopMutation.id, {});
+	}
+	/**
+	* Listening calculation starts.
+	* @param {Function} callback - The callback function to be called when the formula calculation starts.
+	* @returns {IDisposable} The disposable instance.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* formulaEngine.calculationStart((forceCalculation) => {
+	*   console.log('Calculation start', forceCalculation);
+	* });
+	* ```
+	*/
+	calculationStart(callback) {
+		return this._commandService.onCommandExecuted((command) => {
+			if (command.id === SetFormulaCalculationStartMutation.id) {
+				const params = command.params;
+				callback(params.forceCalculation);
+			}
+		});
+	}
+	/**
+	* Listening calculation ends.
+	* @param {Function} callback - The callback function to be called when the formula calculation ends.
+	* @returns {IDisposable} The disposable instance.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* formulaEngine.calculationEnd((functionsExecutedState) => {
+	*   console.log('Calculation end', functionsExecutedState);
+	* });
+	* ```
+	*/
+	calculationEnd(callback) {
+		return this._commandService.onCommandExecuted((command) => {
+			if (command.id !== SetFormulaCalculationNotificationMutation.id) return;
+			const params = command.params;
+			if (params.functionsExecutedState !== void 0) callback(params.functionsExecutedState);
+		});
+	}
+	/**
+	* @deprecated Use `onCalculationEnd` instead.
+	*/
+	whenComputingCompleteAsync(timeout) {
+		const gcss = this._injector.get(GlobalComputingStatusService);
+		if (gcss.computingStatus) return Promise.resolve(true);
+		return firstValueFrom(race(gcss.computingStatus$.pipe(filter((computing) => computing)), timer(timeout !== null && timeout !== void 0 ? timeout : 3e4).pipe(map(() => false))));
+	}
+	/**
+	* Waits for the formula calculation to complete.
+	* @returns {Promise<void>} This method returns a promise that resolves when the calculation is complete.
+	*/
+	onCalculationEnd() {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error("Calculation end timeout"));
+			}, 3e4);
+			const disposable = this.calculationEnd(() => {
+				clearTimeout(timer);
+				disposable.dispose();
+				resolve();
+			});
+		});
+	}
+	/**
+	* Listening calculation processing.
+	* @param {Function} callback - The callback function to be called when the formula calculation is in progress.
+	* @returns {IDisposable} The disposable instance.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	* formulaEngine.calculationProcessing((stageInfo) => {
+	*   console.log('Calculation processing', stageInfo);
+	* });
+	* ```
+	*/
+	calculationProcessing(callback) {
+		return this._commandService.onCommandExecuted((command) => {
+			if (command.id !== SetFormulaCalculationNotificationMutation.id) return;
+			const params = command.params;
+			if (params.stageInfo !== void 0) callback(params.stageInfo);
+		});
+	}
+	/**
+	* 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) {
+		this._configService.setConfig(ENGINE_FORMULA_CYCLE_REFERENCE_COUNT, maxIteration);
+	}
+	/**
+	* 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, timeout = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetFormulaStringBatchCalculationResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				if (params.result != null) resolve(params.result);
+				else reject(/* @__PURE__ */ new Error("Formula batch calculation returned no result"));
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("Formula batch calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetFormulaStringBatchCalculationMutation.id, { formulas }, { onlyLocal: true });
+		});
+	}
+	/**
+	* 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 = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetFormulaDependencyCalculationResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				if (params.result != null) resolve(params.result);
+				else resolve([]);
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("Formula dependency calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetFormulaDependencyCalculationMutation.id, void 0, { onlyLocal: true });
+		});
+	}
+	/**
+	* 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, timeout = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetCellFormulaDependencyCalculationResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				resolve(params.result);
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("Cell dependency calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetCellFormulaDependencyCalculationMutation.id, param, { onlyLocal: true });
+		});
+	}
+	/**
+	* 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, timeout = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetQueryFormulaDependencyResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				if (params.result != null) resolve(params.result);
+				else resolve([]);
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("Range dependents calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetQueryFormulaDependencyMutation.id, { unitRanges }, { onlyLocal: true });
+		});
+	}
+	/**
+	* 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, timeout = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetQueryFormulaDependencyResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				if (params.result != null) resolve(params.result);
+				else resolve([]);
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("In-range formulas calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetQueryFormulaDependencyMutation.id, {
+				unitRanges,
+				isInRange: true
+			}, { onlyLocal: true });
+		});
+	}
+	/**
+	* 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) {
+		this._configService.setConfig(ENGINE_FORMULA_RETURN_DEPENDENCY_TREE, value);
+	}
+	/**
+	* 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, unitId) {
+		return this._lexerTreeBuilder.getFormulaExprTree(formulaString, unitId, this._functionService.hasExecutor.bind(this._functionService), this._definedNamesService.getValueByName.bind(this._definedNamesService), this._superTableService.getTable.bind(this._superTableService));
+	}
+	/**
+	* Retrieve **both**:
+	* 1) the full dependency trees of all formulas that **depend on** the specified ranges, and
+	* 2) the dependency trees of all formulas that **physically reside inside** the specified ranges.
+	*
+	* This is a convenience API that combines the behaviors of
+	* `getRangeDependents` and `getInRangeFormulas` into a single call.
+	*
+	* Internally, it triggers a local dependency-calculation command once and
+	* resolves when both result sets are available, avoiding duplicate
+	* calculations and event listeners.
+	*
+	* @param unitRanges An array of workbook/sheet ranges to query. Each range
+	*   includes:
+	*   - `unitId`  The workbook ID.
+	*   - `sheetId` The sheet ID.
+	*   - `range`   The zero-based row/column boundaries.
+	*
+	* @param {number} [timeout]
+	*        Optional timeout in milliseconds. If the dependency calculation does
+	*        not complete within this period, the promise will be rejected.
+	*
+	* @returns {Promise<IFormulaDependentsAndInRangeResults>}
+	*          A promise that resolves with an object containing:
+	*          - `dependents`: Dependency trees of all formulas that depend on the
+	*            specified ranges (upstream consumers).
+	*          - `inRanges`: Dependency trees of all formulas whose definitions
+	*            are located inside the specified ranges.
+	*
+	* @example
+	* ```ts
+	* const formulaEngine = univerAPI.getFormula();
+	*
+	* const result = await formulaEngine.getRangeDependentsAndInRangeFormulas([
+	*   {
+	*     unitId: 'workbook1',
+	*     sheetId: 'sheet1',
+	*     range: { startRow: 0, endRow: 9, startColumn: 0, endColumn: 1 },
+	*   },
+	* ]);
+	*
+	* console.log('Dependent formulas:', result.dependents);
+	* console.log('Formulas inside range:', result.inRanges);
+	* ```
+	*/
+	getRangeDependentsAndInRangeFormulas(unitRanges, timeout = 3e4) {
+		return new Promise((resolve, reject) => {
+			const disposable = this._commandService.onCommandExecuted((command) => {
+				if (command.id !== SetQueryFormulaDependencyAllResultMutation.id) return;
+				const params = command.params;
+				clearTimeout(timer);
+				disposable.dispose();
+				if (params.result != null) resolve(params.result);
+				else resolve({
+					dependents: [],
+					inRanges: []
+				});
+			});
+			const timer = setTimeout(() => {
+				disposable.dispose();
+				reject(/* @__PURE__ */ new Error("Range dependents calculation timeout"));
+			}, timeout);
+			this._commandService.executeCommand(SetQueryFormulaDependencyAllMutation.id, { unitRanges }, { onlyLocal: true });
+		});
+	}
+};
+FFormula = __decorate([
+	__decorateParam(0, Inject(ICommandService)),
+	__decorateParam(1, Inject(Injector)),
+	__decorateParam(2, Inject(LexerTreeBuilder)),
+	__decorateParam(3, IConfigService),
+	__decorateParam(4, IFunctionService),
+	__decorateParam(5, IDefinedNamesService),
+	__decorateParam(6, ISuperTableService)
+], FFormula);
+
+//#endregion
+//#region src/facade/f-univer.ts
+/**
+* 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.
+*/
+var FUniverEngineFormulaMixin = class extends FUniver {
+	getFormula() {
+		return this._injector.createInstance(FFormula);
+	}
+};
+FUniver.extend(FUniverEngineFormulaMixin);
+
+//#endregion
+export { FFormula };