@univerjs/engine-formula 0.12.4 → 0.13.0

package/lib/facade.js

@@ -1,15 +1,15 @@
-import { FBase as f, FUniver as d } from "@univerjs/core/facade";
-import { Inject as c, ICommandService as p, Injector as _, IConfigService as C } from "@univerjs/core";
-import { LexerTreeBuilder as v, SetFormulaCalculationStartMutation as l, SetFormulaCalculationStopMutation as S, SetFormulaCalculationNotificationMutation as m, GlobalComputingStatusService as x, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as h } from "@univerjs/engine-formula";
-import { firstValueFrom as g, race as E, filter as F, timer as B, map as I } from "rxjs";
-var T = Object.getOwnPropertyDescriptor, N = (e, t, r, i) => {
-  for (var o = i > 1 ? void 0 : i ? T(t, r) : t, a = e.length - 1, u; a >= 0; a--)
-    (u = e[a]) && (o = u(o) || o);
-  return o;
-}, n = (e, t) => (r, i) => t(r, i, e);
-let s = class extends f {
-  constructor(e, t, r, i) {
-    super(), this._commandService = e, this._injector = t, this._lexerTreeBuilder = r, this._configService = i, this._initialize();
+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;
+}, 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();
   }
   /**
    * @ignore
@@ -38,8 +38,8 @@ let s = class extends f {
    * 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 s = class extends f {
    * ```
    */
   executeCalculation() {
-    this._commandService.executeCommand(l.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 f {
    * ```
    */
   stopCalculation() {
-    this._commandService.executeCommand(S.id, {});
+    this._commandService.executeCommand(E.id, {});
   }
   /**
    * Listening calculation starts.
@@ -95,9 +95,9 @@ let s = class extends f {
    */
   calculationStart(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id === l.id) {
-        const r = t.params;
-        e(r.forceCalculation);
+      if (t.id === d.id) {
+        const i = t.params;
+        e(i.forceCalculation);
       }
     });
   }
@@ -116,10 +116,10 @@ let s = class extends f {
    */
   calculationEnd(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== p.id)
         return;
-      const r = t.params;
-      r.functionsExecutedState !== void 0 && e(r.functionsExecutedState);
+      const i = t.params;
+      i.functionsExecutedState !== void 0 && e(i.functionsExecutedState);
     });
   }
   /**
@@ -139,10 +139,10 @@ let s = class extends f {
    * ```
    */
   whenComputingCompleteAsync(e) {
-    const t = this._injector.get(x);
-    return t.computingStatus ? Promise.resolve(!0) : g(E(
-      t.computingStatus$.pipe(F((r) => r)),
-      B(e != null ? e : 3e4).pipe(I(() => !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))
     ));
   }
   /**
@@ -151,10 +151,10 @@ let s = class extends f {
    */
   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();
       });
     });
   }
@@ -173,10 +173,10 @@ let s = class extends f {
    */
   calculationProcessing(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== m.id)
+      if (t.id !== p.id)
         return;
-      const r = t.params;
-      r.stageInfo !== void 0 && e(r.stageInfo);
+      const i = t.params;
+      i.stageInfo !== void 0 && e(i.stageInfo);
     });
   }
   /**
@@ -192,21 +192,374 @@ let s = class extends f {
    * ```
    */
   setMaxIteration(e) {
-    this._configService.setConfig(h, 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.
+   *
+   * 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(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 }
+      );
+    });
+  }
+  /**
+   * 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(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 }
+      );
+    });
+  }
+  /**
+   * 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(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 = N([
-  n(0, c(p)),
-  n(1, c(_)),
-  n(2, c(v)),
-  n(3, C)
-], s);
-class O 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(O);
+S.extend(U);
 export {
-  s as FFormula
+  m as FFormula
 };