@univerjs/engine-formula 0.12.4-experimental.20251210-8d33c6e → 0.12.4-experimental.20251210-d708bff

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

@@ -226,11 +226,13 @@ export declare class FFormula extends FBase {
      *        Nested structure (unit → sheet → row → column) describing formulas and
      *        their decomposed sub-expressions.
      *
-     * @param {(result: IFormulaExecuteResultMap) => void} callback
-     *        Receives the computed value map mirroring the input structure.
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
      *
-     * @returns {IDisposable}
-     *          A disposer to stop listening for batch results.
+     * @returns {Promise<IFormulaExecuteResultMap>}
+     *          A promise that resolves with the computed value map mirroring
+     *          the input structure.
      *
      * @example
      * ```ts
@@ -262,34 +264,33 @@ export declare class FFormula extends FBase {
      *   },
      * };
      *
-     * const disposer = formulaEngine.executeFormulas(formulas, (result) => {
-     *   console.log(result);
-     * });
-     *
+     * const result = await formulaEngine.executeFormulas(formulas);
+     * console.log(result);
      * ```
      */
-    executeFormulas(formulas: IFormulaStringMap, callback: (result: IFormulaExecuteResultMap) => void): void;
+    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 callback A function invoked with the resulting array of dependency trees.
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
      *
-     * @returns {IDisposable} An object that disposes the internal event listener.
+     * @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 disposable = formulaEngine.getAllDependencyTrees((trees) => {
-     *     console.log('All dependency trees:', trees);
-     * });
-     *
+     * const trees = await formulaEngine.getAllDependencyTrees();
+     * console.log('All dependency trees:', trees);
      * ```
      */
-    getAllDependencyTrees(callback: (result: IFormulaDependencyTreeJson[]) => void): void;
+    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,
@@ -301,23 +302,27 @@ export declare class FFormula extends FBase {
      *   - `row`     The zero-based row index.
      *   - `column`  The zero-based column index.
      *
-     * @param callback A function invoked with the resulting dependency tree or
-     * `undefined` if no dependency tree exists for that cell.
+     * @param {number} [timeout]
+     *        Optional timeout in milliseconds. If no result is received within this
+     *        period, the promise will be rejected.
      *
-     * @returns {IDisposable} An object that disposes the internal event listener.
+     * @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 disposable = formulaEngine.getCellDependencyTree(
-     *     { unitId: 'workbook1', sheetId: 'sheet1', row: 1, column: 1 },
-     *     (tree) => {
-     *         console.log('Cell dependency tree:', tree);
-     *     }
-     * );
+     * const tree = await formulaEngine.getCellDependencyTree({
+     *   unitId: 'workbook1',
+     *   sheetId: 'sheet1',
+     *   row: 1,
+     *   column: 1,
+     * });
      *
+     * console.log('Cell dependency tree:', tree);
      * ```
      */
     getCellDependencyTree(param: {
@@ -325,11 +330,11 @@ export declare class FFormula extends FBase {
         sheetId: string;
         row: number;
         column: number;
-    }, callback: (result: IFormulaDependencyTreeFullJson | undefined) => void): void;
+    }, 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
-     * invokes the callback once the calculation completes.
+     * resolves once the calculation completes.
      *
      * @param unitRanges An array of workbook/sheet ranges to query. Each range
      *   includes:
@@ -337,31 +342,34 @@ export declare class FFormula extends FBase {
      *   - `sheetId` The sheet ID.
      *   - `range`   The row/column boundaries.
      *
-     * @param callback A function invoked with an array of `IFormulaDependencyTreeJson`
-     * results. Each entry represents a formula node and its parent/child
-     * relationships within the dependency graph.
+     * @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.
-     * formulaEngine.getRangeDependents(
-     *     [{ unitId: 'workbook1', sheetId: 'sheet1', range: { startRow: 0, endRow: 9, startColumn: 0, endColumn: 1 } }],
-     *     (result) => {
-     *         console.log('Dependent formulas:', result);
-     *     }
-     * );
+     * 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[], callback: (result: IFormulaDependencyTreeJson[]) => void): void;
+    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 callback is invoked when the results are ready.
+     * `isInRange = true`, and the promise resolves when the results are ready.
      *
      * @param unitRanges An array of workbook/sheet ranges defining the lookup
      *   boundaries:
@@ -369,22 +377,26 @@ export declare class FFormula extends FBase {
      *   - `sheetId` The sheet ID.
      *   - `range`   The zero-based grid range.
      *
-     * @param callback Receives an array of `IFormulaDependencyTreeJson` describing
-     * every formula found in the provided ranges along with their parent/child
-     * relationships.
+     * @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.
-     * formulaEngine.getInRangeFormulas(
-     *     [{ unitId: 'workbook1', sheetId: 'sheet1', range: { startRow: 0, endRow: 19, startColumn: 0, endColumn: 3 } }],
-     *     (result) => {
-     *         console.log('Formulas inside range:', result);
-     *     }
-     * );
+     * 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[], callback: (result: IFormulaDependencyTreeJson[]) => void): void;
+    getInRangeFormulas(unitRanges: IUnitRange[], timeout?: number): Promise<IFormulaDependencyTreeJson[]>;
 }

package/lib/umd/facade.js

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