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

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 _, FUniver as C } from "@univerjs/core/facade";
+import { Inject as u, ICommandService as v, Injector as h, IConfigService as x } from "@univerjs/core";
+import { LexerTreeBuilder as g, SetFormulaCalculationStartMutation as m, SetFormulaCalculationStopMutation as F, SetFormulaCalculationNotificationMutation as d, GlobalComputingStatusService as E, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as y, SetFormulaCalculationResultMutation as T, SetFormulaStringBatchCalculationMutation as R, SetFormulaStringBatchCalculationResultMutation as M, SetFormulaDependencyCalculationMutation as D, SetFormulaDependencyCalculationResultMutation as I, SetCellFormulaDependencyCalculationMutation as b, SetCellFormulaDependencyCalculationResultMutation as B, SetQueryFormulaDependencyMutation as p, SetQueryFormulaDependencyResultMutation as f } from "@univerjs/engine-formula";
+import { firstValueFrom as L, race as P, filter as w, timer as N, map as O } from "rxjs";
+var j = Object.getOwnPropertyDescriptor, A = (e, t, i, r) => {
+  for (var n = r > 1 ? void 0 : r ? j(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 {
+}, s = (e, t) => (i, r) => t(i, r, e);
+let c = class extends _ {
   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(m.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(F.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 === m.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 !== d.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(E);
+    return t.computingStatus ? Promise.resolve(!0) : L(P(
+      t.computingStatus$.pipe(w((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 !== d.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(y, 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 !== T.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.
@@ -264,9 +342,9 @@ let s = class extends p {
    * ```
    */
   executeFormulas(e, t) {
-    this._commandService.executeCommand(g.id, { formulas: e }, { onlyLocal: !0 });
+    this._commandService.executeCommand(R.id, { formulas: e }, { onlyLocal: !0 });
     const i = this._commandService.onCommandExecuted((r) => {
-      if (r.id !== F.id)
+      if (r.id !== M.id)
         return;
       const n = r.params;
       n.result != null && t(n.result), i.dispose();
@@ -293,9 +371,9 @@ let s = class extends p {
    * ```
    */
   getAllDependencyTrees(e) {
-    this._commandService.executeCommand(E.id, void 0, { onlyLocal: !0 });
+    this._commandService.executeCommand(D.id, void 0, { onlyLocal: !0 });
     const t = this._commandService.onCommandExecuted((i) => {
-      if (i.id !== y.id)
+      if (i.id !== I.id)
         return;
       const r = i.params;
       r.result != null && e(r.result), t.dispose();
@@ -332,7 +410,7 @@ let s = class extends p {
    * ```
    */
   getCellDependencyTree(e, t) {
-    this._commandService.executeCommand(M.id, e, { onlyLocal: !0 });
+    this._commandService.executeCommand(b.id, e, { onlyLocal: !0 });
     const i = this._commandService.onCommandExecuted((r) => {
       if (r.id !== B.id)
         return;
@@ -340,19 +418,96 @@ let s = class extends p {
       n.result !== void 0 && t(n.result), i.dispose();
     });
   }
+  /**
+   * 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.
+   *
+   * @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 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.
+   *
+   * @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);
+   *     }
+   * );
+   * ```
+   */
+  getRangeDependents(e, t) {
+    this._commandService.executeCommand(p.id, { unitRanges: 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();
+    });
+  }
+  /**
+   * 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.
+   *
+   * @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 callback Receives 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);
+   *     }
+   * );
+   * ```
+   */
+  getInRangeFormulas(e, t) {
+    this._commandService.executeCommand(p.id, { unitRanges: e, isInRange: !0 }, { 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();
+    });
+  }
 };
-s = O([
-  o(0, c(C)),
-  o(1, c(f)),
-  o(2, c(_)),
-  o(3, S)
-], s);
-class b extends d {
+c = A([
+  s(0, u(v)),
+  s(1, u(h)),
+  s(2, u(g)),
+  s(3, x)
+], c);
+class U extends C {
   getFormula() {
-    return this._injector.createInstance(s);
+    return this._injector.createInstance(c);
   }
 }
-d.extend(b);
+C.extend(U);
 export {
-  s as FFormula
+  c as FFormula
 };