@univerjs/engine-formula 0.15.3-insiders.20260131-b9b8805 → 0.15.3

package/lib/es/facade.js

@@ -1,15 +1,15 @@
-import { FBase as _, FUniver as S } from "@univerjs/core/facade";
-import { Inject as c, ICommandService as f, Injector as C, IConfigService as h } from "@univerjs/core";
-import { LexerTreeBuilder as v, SetTriggerFormulaCalculationStartMutation as g, SetFormulaCalculationStopMutation as E, SetFormulaCalculationStartMutation as x, SetFormulaCalculationNotificationMutation as m, GlobalComputingStatusService as F, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as T, SetFormulaStringBatchCalculationResultMutation as y, SetFormulaStringBatchCalculationMutation as R, SetFormulaDependencyCalculationResultMutation as b, SetFormulaDependencyCalculationMutation as w, SetCellFormulaDependencyCalculationResultMutation as D, SetCellFormulaDependencyCalculationMutation as M, SetQueryFormulaDependencyResultMutation as d, SetQueryFormulaDependencyMutation as p, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE as I, SetQueryFormulaDependencyAllResultMutation as N, SetQueryFormulaDependencyAllMutation as B, IFunctionService as P, IDefinedNamesService as L, ISuperTableService as O } from "@univerjs/engine-formula";
-import { firstValueFrom as A, race as U, filter as j, timer as Q, map as G } from "rxjs";
-var q = Object.getOwnPropertyDescriptor, z = (e, t, r, i) => {
-  for (var n = i > 1 ? void 0 : i ? q(t, r) : t, a = e.length - 1, o; a >= 0; a--)
+import { FBase as C, FUniver as f } from "@univerjs/core/facade";
+import { Inject as c, ICommandService as _, Injector as h, IConfigService as v } from "@univerjs/core";
+import { LexerTreeBuilder as g, IFunctionService as E, IDefinedNamesService as T, ISuperTableService as x, SetTriggerFormulaCalculationStartMutation as F, SetFormulaCalculationStopMutation as y, SetFormulaCalculationStartMutation as R, SetFormulaCalculationNotificationMutation as d, GlobalComputingStatusService as b, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as w, SetFormulaCalculationResultMutation as D, SetFormulaStringBatchCalculationResultMutation as M, SetFormulaStringBatchCalculationMutation as I, SetFormulaDependencyCalculationResultMutation as N, SetFormulaDependencyCalculationMutation as P, SetCellFormulaDependencyCalculationResultMutation as B, SetCellFormulaDependencyCalculationMutation as L, SetQueryFormulaDependencyResultMutation as p, SetQueryFormulaDependencyMutation as S, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE as A, SetQueryFormulaDependencyAllResultMutation as O, SetQueryFormulaDependencyAllMutation as U } from "@univerjs/engine-formula";
+import { firstValueFrom as j, race as Q, filter as q, timer as G, map as z } from "rxjs";
+var V = Object.getOwnPropertyDescriptor, Y = (e, t, i, r) => {
+  for (var n = r > 1 ? void 0 : r ? V(t, i) : t, a = e.length - 1, o; a >= 0; a--)
     (o = e[a]) && (n = o(n) || n);
   return n;
-}, u = (e, t) => (r, i) => t(r, i, e);
-let l = class extends _ {
-  constructor(e, t, r, i, n, a, o) {
-    super(), this._commandService = e, this._injector = t, this._lexerTreeBuilder = r, this._configService = i, this._functionService = n, this._definedNamesService = a, this._superTableService = o, this._initialize();
+}, u = (e, t) => (i, r) => t(i, r, e);
+let m = class extends C {
+  constructor(e, t, i, r, n, a, o) {
+    super(), this._commandService = e, this._injector = t, this._lexerTreeBuilder = i, this._configService = r, this._functionService = n, this._definedNamesService = a, this._superTableService = o, this._initialize();
   }
   /**
    * @ignore
@@ -38,8 +38,8 @@ let l = class extends _ {
    * console.log(result);
    * ```
    */
-  moveFormulaRefOffset(e, t, r, i) {
-    return this._lexerTreeBuilder.moveFormulaRefOffset(e, t, r, i);
+  moveFormulaRefOffset(e, t, i, r) {
+    return this._lexerTreeBuilder.moveFormulaRefOffset(e, t, i, r);
   }
   /**
    * Resolves the formula string to a 'node' node
@@ -66,7 +66,7 @@ let l = class extends _ {
    * ```
    */
   executeCalculation() {
-    this._commandService.executeCommand(g.id, { commands: [], forceCalculation: !0 }, { onlyLocal: !0 });
+    this._commandService.executeCommand(F.id, { commands: [], forceCalculation: !0 }, { onlyLocal: !0 });
   }
   /**
    * Stop the calculation of the formula.
@@ -78,7 +78,7 @@ let l = class extends _ {
    * ```
    */
   stopCalculation() {
-    this._commandService.executeCommand(E.id, {});
+    this._commandService.executeCommand(y.id, {});
   }
   /**
    * Listening calculation starts.
@@ -95,9 +95,9 @@ let l = class extends _ {
    */
   calculationStart(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id === x.id) {
-        const r = t.params;
-        e(r.forceCalculation);
+      if (t.id === R.id) {
+        const i = t.params;
+        e(i.forceCalculation);
       }
     });
   }
@@ -116,20 +116,20 @@ let l = class extends _ {
    */
   calculationEnd(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== d.id)
         return;
-      const r = t.params;
-      r.functionsExecutedState !== void 0 && e(r.functionsExecutedState);
+      const i = t.params;
+      i.functionsExecutedState !== void 0 && e(i.functionsExecutedState);
     });
   }
   /**
    * @deprecated Use `onCalculationEnd` instead.
    */
   whenComputingCompleteAsync(e) {
-    const t = this._injector.get(F);
-    return t.computingStatus ? Promise.resolve(!0) : A(U(
-      t.computingStatus$.pipe(j((r) => r)),
-      Q(e != null ? e : 3e4).pipe(G(() => !1))
+    const t = this._injector.get(b);
+    return t.computingStatus ? Promise.resolve(!0) : j(Q(
+      t.computingStatus$.pipe(q((i) => i)),
+      G(e != null ? e : 3e4).pipe(z(() => !1))
     ));
   }
   /**
@@ -138,10 +138,10 @@ let l = class extends _ {
    */
   onCalculationEnd() {
     return new Promise((e, t) => {
-      const r = setTimeout(() => {
+      const i = setTimeout(() => {
         t(new Error("Calculation end timeout"));
-      }, 3e4), i = this.calculationEnd(() => {
-        clearTimeout(r), i.dispose(), e();
+      }, 3e4), r = this.calculationEnd(() => {
+        clearTimeout(i), r.dispose(), e();
       });
     });
   }
@@ -160,10 +160,10 @@ let l = class extends _ {
    */
   calculationProcessing(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== d.id)
         return;
-      const r = t.params;
-      r.stageInfo !== void 0 && e(r.stageInfo);
+      const i = t.params;
+      i.stageInfo !== void 0 && e(i.stageInfo);
     });
   }
   /**
@@ -179,7 +179,85 @@ let l = class extends _ {
    * ```
    */
   setMaxIteration(e) {
-    this._configService.setConfig(T, e);
+    this._configService.setConfig(w, 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 !== D.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.
@@ -251,17 +329,17 @@ let l = class extends _ {
    * ```
    */
   executeFormulas(e, t = 3e4) {
-    return new Promise((r, i) => {
+    return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== y.id)
+        if (o.id !== M.id)
           return;
         const s = o.params;
-        clearTimeout(a), n.dispose(), s.result != null ? r(s.result) : i(new Error("Formula batch calculation returned no result"));
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : r(new Error("Formula batch calculation returned no result"));
       }), a = setTimeout(() => {
-        n.dispose(), i(new Error("Formula batch calculation timeout"));
+        n.dispose(), r(new Error("Formula batch calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        R.id,
+        I.id,
         { formulas: e },
         { onlyLocal: !0 }
       );
@@ -289,17 +367,17 @@ let l = class extends _ {
    * ```
    */
   getAllDependencyTrees(e = 3e4) {
-    return new Promise((t, r) => {
-      const i = this._commandService.onCommandExecuted((a) => {
-        if (a.id !== b.id)
+    return new Promise((t, i) => {
+      const r = this._commandService.onCommandExecuted((a) => {
+        if (a.id !== N.id)
           return;
         const o = a.params;
-        clearTimeout(n), i.dispose(), o.result != null ? t(o.result) : t([]);
+        clearTimeout(n), r.dispose(), o.result != null ? t(o.result) : t([]);
       }), n = setTimeout(() => {
-        i.dispose(), r(new Error("Formula dependency calculation timeout"));
+        r.dispose(), i(new Error("Formula dependency calculation timeout"));
       }, e);
       this._commandService.executeCommand(
-        w.id,
+        P.id,
         void 0,
         { onlyLocal: !0 }
       );
@@ -340,17 +418,17 @@ let l = class extends _ {
    * ```
    */
   getCellDependencyTree(e, t = 3e4) {
-    return new Promise((r, i) => {
+    return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== D.id)
+        if (o.id !== B.id)
           return;
         const s = o.params;
-        clearTimeout(a), n.dispose(), r(s.result);
+        clearTimeout(a), n.dispose(), i(s.result);
       }), a = setTimeout(() => {
-        n.dispose(), i(new Error("Cell dependency calculation timeout"));
+        n.dispose(), r(new Error("Cell dependency calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        M.id,
+        L.id,
         e,
         { onlyLocal: !0 }
       );
@@ -388,17 +466,17 @@ let l = class extends _ {
    * ```
    */
   getRangeDependents(e, t = 3e4) {
-    return new Promise((r, i) => {
+    return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== d.id)
+        if (o.id !== p.id)
           return;
         const s = o.params;
-        clearTimeout(a), n.dispose(), s.result != null ? r(s.result) : r([]);
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : i([]);
       }), a = setTimeout(() => {
-        n.dispose(), i(new Error("Range dependents calculation timeout"));
+        n.dispose(), r(new Error("Range dependents calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        p.id,
+        S.id,
         { unitRanges: e },
         { onlyLocal: !0 }
       );
@@ -440,17 +518,17 @@ let l = class extends _ {
    * ```
    */
   getInRangeFormulas(e, t = 3e4) {
-    return new Promise((r, i) => {
+    return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== d.id)
+        if (o.id !== p.id)
           return;
         const s = o.params;
-        clearTimeout(a), n.dispose(), s.result != null ? r(s.result) : r([]);
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : i([]);
       }), a = setTimeout(() => {
-        n.dispose(), i(new Error("In-range formulas calculation timeout"));
+        n.dispose(), r(new Error("In-range formulas calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        p.id,
+        S.id,
         { unitRanges: e, isInRange: !0 },
         { onlyLocal: !0 }
       );
@@ -505,7 +583,7 @@ let l = class extends _ {
    * ```
    */
   setFormulaReturnDependencyTree(e) {
-    this._configService.setConfig(I, e);
+    this._configService.setConfig(A, e);
   }
   /**
    * Parse a formula string and return its **formula expression tree**.
@@ -619,38 +697,38 @@ let l = class extends _ {
    * ```
    */
   getRangeDependentsAndInRangeFormulas(e, t = 3e4) {
-    return new Promise((r, i) => {
+    return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== N.id)
+        if (o.id !== O.id)
           return;
         const s = o.params;
-        clearTimeout(a), n.dispose(), s.result != null ? r(s.result) : r({ dependents: [], inRanges: [] });
+        clearTimeout(a), n.dispose(), s.result != null ? i(s.result) : i({ dependents: [], inRanges: [] });
       }), a = setTimeout(() => {
-        n.dispose(), i(new Error("Range dependents calculation timeout"));
+        n.dispose(), r(new Error("Range dependents calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        B.id,
+        U.id,
         { unitRanges: e },
         { onlyLocal: !0 }
       );
     });
   }
 };
-l = z([
-  u(0, c(f)),
-  u(1, c(C)),
-  u(2, c(v)),
-  u(3, h),
-  u(4, P),
-  u(5, L),
-  u(6, O)
-], l);
-class V extends S {
+m = Y([
+  u(0, c(_)),
+  u(1, c(h)),
+  u(2, c(g)),
+  u(3, v),
+  u(4, E),
+  u(5, T),
+  u(6, x)
+], m);
+class W extends f {
   getFormula() {
-    return this._injector.createInstance(l);
+    return this._injector.createInstance(m);
   }
 }
-S.extend(V);
+f.extend(W);
 export {
-  l as FFormula
+  m as FFormula
 };