@univerjs/engine-formula 0.12.4-experimental.20251208-c4b8a44 → 0.12.4-experimental.20251210-d708bff

package/lib/es/facade.js

@@ -1,13 +1,13 @@
-import { FBase as p, FUniver as d } from "@univerjs/core/facade";
-import { Inject as c, ICommandService as C, Injector as f, IConfigService as S } from "@univerjs/core";
-import { LexerTreeBuilder as _, SetFormulaCalculationStartMutation as u, SetFormulaCalculationStopMutation as v, SetFormulaCalculationNotificationMutation as m, GlobalComputingStatusService as h, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as x, SetFormulaStringBatchCalculationMutation as g, SetFormulaStringBatchCalculationResultMutation as F, SetFormulaDependencyCalculationMutation as E, SetFormulaDependencyCalculationResultMutation as y, SetCellFormulaDependencyCalculationMutation as M, SetCellFormulaDependencyCalculationResultMutation as B } from "@univerjs/engine-formula";
-import { firstValueFrom as T, race as I, filter as D, timer as R, map as L } from "rxjs";
-var N = Object.getOwnPropertyDescriptor, O = (e, t, i, r) => {
-  for (var n = r > 1 ? void 0 : r ? N(t, i) : t, a = e.length - 1, l; a >= 0; a--)
-    (l = e[a]) && (n = l(n) || n);
+import { FBase as h, FUniver as S } from "@univerjs/core/facade";
+import { Inject as c, ICommandService as _, Injector as v, IConfigService as g } from "@univerjs/core";
+import { LexerTreeBuilder as x, SetFormulaCalculationStartMutation as d, SetFormulaCalculationStopMutation as E, SetFormulaCalculationNotificationMutation as p, GlobalComputingStatusService as F, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as T, SetFormulaCalculationResultMutation as y, SetFormulaStringBatchCalculationResultMutation as w, SetFormulaStringBatchCalculationMutation as R, SetFormulaDependencyCalculationResultMutation as M, SetFormulaDependencyCalculationMutation as b, SetCellFormulaDependencyCalculationResultMutation as D, SetCellFormulaDependencyCalculationMutation as I, SetQueryFormulaDependencyResultMutation as f, SetQueryFormulaDependencyMutation as C } from "@univerjs/engine-formula";
+import { firstValueFrom as P, race as B, filter as L, timer as N, map as O } from "rxjs";
+var A = Object.getOwnPropertyDescriptor, j = (e, t, i, r) => {
+  for (var n = r > 1 ? void 0 : r ? A(t, i) : t, a = e.length - 1, o; a >= 0; a--)
+    (o = e[a]) && (n = o(n) || n);
   return n;
-}, o = (e, t) => (i, r) => t(i, r, e);
-let s = class extends p {
+}, u = (e, t) => (i, r) => t(i, r, e);
+let m = class extends h {
   constructor(e, t, i, r) {
     super(), this._commandService = e, this._injector = t, this._lexerTreeBuilder = i, this._configService = r, this._initialize();
   }
@@ -66,7 +66,7 @@ let s = class extends p {
    * ```
    */
   executeCalculation() {
-    this._commandService.executeCommand(u.id, { commands: [], forceCalculation: !0 }, { onlyLocal: !0 });
+    this._commandService.executeCommand(d.id, { commands: [], forceCalculation: !0 }, { onlyLocal: !0 });
   }
   /**
    * Stop the calculation of the formula.
@@ -78,7 +78,7 @@ let s = class extends p {
    * ```
    */
   stopCalculation() {
-    this._commandService.executeCommand(v.id, {});
+    this._commandService.executeCommand(E.id, {});
   }
   /**
    * Listening calculation starts.
@@ -95,7 +95,7 @@ let s = class extends p {
    */
   calculationStart(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id === u.id) {
+      if (t.id === d.id) {
         const i = t.params;
         e(i.forceCalculation);
       }
@@ -116,7 +116,7 @@ let s = class extends p {
    */
   calculationEnd(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== p.id)
         return;
       const i = t.params;
       i.functionsExecutedState !== void 0 && e(i.functionsExecutedState);
@@ -139,10 +139,10 @@ let s = class extends p {
    * ```
    */
   whenComputingCompleteAsync(e) {
-    const t = this._injector.get(h);
-    return t.computingStatus ? Promise.resolve(!0) : T(I(
-      t.computingStatus$.pipe(D((i) => i)),
-      R(e != null ? e : 3e4).pipe(L(() => !1))
+    const t = this._injector.get(F);
+    return t.computingStatus ? Promise.resolve(!0) : P(B(
+      t.computingStatus$.pipe(L((i) => i)),
+      N(e != null ? e : 3e4).pipe(O(() => !1))
     ));
   }
   /**
@@ -173,7 +173,7 @@ let s = class extends p {
    */
   calculationProcessing(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== p.id)
         return;
       const i = t.params;
       i.stageInfo !== void 0 && e(i.stageInfo);
@@ -192,7 +192,85 @@ let s = class extends p {
    * ```
    */
   setMaxIteration(e) {
-    this._configService.setConfig(x, e);
+    this._configService.setConfig(T, e);
+  }
+  /**
+   * 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(e) {
+    return this._commandService.onCommandExecuted((t) => {
+      if (t.id !== y.id)
+        return;
+      const i = t.params;
+      i !== void 0 && requestIdleCallback(() => {
+        e(i);
+      });
+    });
+  }
+  /**
+   * 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() {
+    return new Promise((e, t) => {
+      let i = !1, r = !1;
+      const n = setTimeout(() => {
+        l(), t(new Error("Calculation end timeout"));
+      }, 3e4), a = setTimeout(() => {
+        i || (l(), e());
+      }, 500), o = this.calculationProcessing(() => {
+        i || (i = !0, clearTimeout(a));
+      }), s = this.calculationResultApplied(() => {
+        r || (r = !0, l(), e());
+      });
+      function l() {
+        clearTimeout(n), clearTimeout(a), o.dispose(), s.dispose();
+      }
+    });
   }
   /**
    * Execute a batch of formulas asynchronously and receive computed results.
@@ -221,11 +299,13 @@ let s = class extends p {
    *        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
@@ -257,19 +337,25 @@ let s = class extends p {
    *   },
    * };
    *
-   * const disposer = formulaEngine.executeFormulas(formulas, (result) => {
-   *   console.log(result);
-   * });
-   *
+   * const result = await formulaEngine.executeFormulas(formulas);
+   * console.log(result);
    * ```
    */
-  executeFormulas(e, t) {
-    this._commandService.executeCommand(g.id, { formulas: e }, { onlyLocal: !0 });
-    const i = this._commandService.onCommandExecuted((r) => {
-      if (r.id !== F.id)
-        return;
-      const n = r.params;
-      n.result != null && t(n.result), i.dispose();
+  executeFormulas(e, t = 3e4) {
+    return new Promise((i, r) => {
+      const n = this._commandService.onCommandExecuted((o) => {
+        if (o.id !== w.id)
+          return;
+        const s = o.params;
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : r(new Error("Formula batch calculation returned no result"));
+      }), a = setTimeout(() => {
+        n.dispose(), r(new Error("Formula batch calculation timeout"));
+      }, t);
+      this._commandService.executeCommand(
+        R.id,
+        { formulas: e },
+        { onlyLocal: !0 }
+      );
     });
   }
   /**
@@ -277,28 +363,37 @@ let s = class extends p {
    * 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(e) {
-    this._commandService.executeCommand(E.id, void 0, { onlyLocal: !0 });
-    const t = this._commandService.onCommandExecuted((i) => {
-      if (i.id !== y.id)
-        return;
-      const r = i.params;
-      r.result != null && e(r.result), t.dispose();
+  getAllDependencyTrees(e = 3e4) {
+    return new Promise((t, i) => {
+      const r = this._commandService.onCommandExecuted((a) => {
+        if (a.id !== M.id)
+          return;
+        const o = a.params;
+        clearTimeout(n), r.dispose(), o.result != null ? t(o.result) : t([]);
+      }), n = setTimeout(() => {
+        r.dispose(), i(new Error("Formula dependency calculation timeout"));
+      }, e);
+      this._commandService.executeCommand(
+        b.id,
+        void 0,
+        { onlyLocal: !0 }
+      );
     });
   }
   /**
@@ -312,47 +407,159 @@ let s = class extends p {
    *   - `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(e, t) {
-    this._commandService.executeCommand(M.id, e, { onlyLocal: !0 });
-    const i = this._commandService.onCommandExecuted((r) => {
-      if (r.id !== B.id)
-        return;
-      const n = r.params;
-      n.result !== void 0 && t(n.result), i.dispose();
+  getCellDependencyTree(e, t = 3e4) {
+    return new Promise((i, r) => {
+      const n = this._commandService.onCommandExecuted((o) => {
+        if (o.id !== D.id)
+          return;
+        const s = o.params;
+        clearTimeout(a), n.dispose(), i(s.result);
+      }), a = setTimeout(() => {
+        n.dispose(), r(new Error("Cell dependency calculation timeout"));
+      }, t);
+      this._commandService.executeCommand(
+        I.id,
+        e,
+        { onlyLocal: !0 }
+      );
+    });
+  }
+  /**
+   * 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(e, t = 3e4) {
+    return new Promise((i, r) => {
+      const n = this._commandService.onCommandExecuted((o) => {
+        if (o.id !== f.id)
+          return;
+        const s = o.params;
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : i([]);
+      }), a = setTimeout(() => {
+        n.dispose(), r(new Error("Range dependents calculation timeout"));
+      }, t);
+      this._commandService.executeCommand(
+        C.id,
+        { unitRanges: e },
+        { onlyLocal: !0 }
+      );
+    });
+  }
+  /**
+   * 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(e, t = 3e4) {
+    return new Promise((i, r) => {
+      const n = this._commandService.onCommandExecuted((o) => {
+        if (o.id !== f.id)
+          return;
+        const s = o.params;
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : i([]);
+      }), a = setTimeout(() => {
+        n.dispose(), r(new Error("In-range formulas calculation timeout"));
+      }, t);
+      this._commandService.executeCommand(
+        C.id,
+        { unitRanges: e, isInRange: !0 },
+        { onlyLocal: !0 }
+      );
     });
   }
 };
-s = O([
-  o(0, c(C)),
-  o(1, c(f)),
-  o(2, c(_)),
-  o(3, S)
-], s);
-class b extends d {
+m = j([
+  u(0, c(_)),
+  u(1, c(v)),
+  u(2, c(x)),
+  u(3, g)
+], m);
+class U extends S {
   getFormula() {
-    return this._injector.createInstance(s);
+    return this._injector.createInstance(m);
   }
 }
-d.extend(b);
+S.extend(U);
 export {
-  s as FFormula
+  m as FFormula
 };