@univerjs/engine-formula 0.12.4-insiders.20251213-692494c → 0.13.0-insiders.20251215-64041bb

package/lib/facade.js

@@ -1,15 +1,15 @@
-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--)
+import { FBase as C, FUniver as _ } from "@univerjs/core/facade";
+import { Inject as l, ICommandService as h, Injector as v, IConfigService as E } from "@univerjs/core";
+import { LexerTreeBuilder as g, IFunctionService as T, IDefinedNamesService as x, ISuperTableService as F, SetFormulaCalculationStartMutation as d, SetFormulaCalculationStopMutation as y, SetFormulaCalculationNotificationMutation as p, GlobalComputingStatusService as R, ENGINE_FORMULA_CYCLE_REFERENCE_COUNT as b, SetFormulaCalculationResultMutation as w, SetFormulaStringBatchCalculationResultMutation as D, SetFormulaStringBatchCalculationMutation as I, SetFormulaDependencyCalculationResultMutation as N, SetFormulaDependencyCalculationMutation as M, SetCellFormulaDependencyCalculationResultMutation as P, SetCellFormulaDependencyCalculationMutation as B, SetQueryFormulaDependencyResultMutation as f, SetQueryFormulaDependencyMutation as S, ENGINE_FORMULA_RETURN_DEPENDENCY_TREE as L } from "@univerjs/engine-formula";
+import { firstValueFrom as O, race as A, filter as U, timer as j, map as q } from "rxjs";
+var G = Object.getOwnPropertyDescriptor, z = (e, t, i, r) => {
+  for (var n = r > 1 ? void 0 : r ? G(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();
+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
@@ -78,7 +78,7 @@ let m = class extends h {
    * ```
    */
   stopCalculation() {
-    this._commandService.executeCommand(E.id, {});
+    this._commandService.executeCommand(y.id, {});
   }
   /**
    * Listening calculation starts.
@@ -139,10 +139,10 @@ let m = class extends h {
    * ```
    */
   whenComputingCompleteAsync(e) {
-    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))
+    const t = this._injector.get(R);
+    return t.computingStatus ? Promise.resolve(!0) : O(A(
+      t.computingStatus$.pipe(U((i) => i)),
+      j(e != null ? e : 3e4).pipe(q(() => !1))
     ));
   }
   /**
@@ -192,7 +192,7 @@ let m = class extends h {
    * ```
    */
   setMaxIteration(e) {
-    this._configService.setConfig(T, e);
+    this._configService.setConfig(b, e);
   }
   /**
    * Listens for the moment when formula-calculation results are applied.
@@ -219,7 +219,7 @@ let m = class extends h {
    */
   calculationResultApplied(e) {
     return this._commandService.onCommandExecuted((t) => {
-      if (t.id !== y.id)
+      if (t.id !== w.id)
         return;
       const i = t.params;
       i !== void 0 && requestIdleCallback(() => {
@@ -259,15 +259,15 @@ let m = class extends h {
     return new Promise((e, t) => {
       let i = !1, r = !1;
       const n = setTimeout(() => {
-        l(), t(new Error("Calculation end timeout"));
+        c(), t(new Error("Calculation end timeout"));
       }, 3e4), a = setTimeout(() => {
-        i || (l(), e());
+        i || (c(), e());
       }, 500), o = this.calculationProcessing(() => {
         i || (i = !0, clearTimeout(a));
       }), s = this.calculationResultApplied(() => {
-        r || (r = !0, l(), e());
+        r || (r = !0, c(), e());
       });
-      function l() {
+      function c() {
         clearTimeout(n), clearTimeout(a), o.dispose(), s.dispose();
       }
     });
@@ -344,7 +344,7 @@ let m = class extends h {
   executeFormulas(e, t = 3e4) {
     return new Promise((i, r) => {
       const n = this._commandService.onCommandExecuted((o) => {
-        if (o.id !== w.id)
+        if (o.id !== D.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"));
@@ -352,7 +352,7 @@ let m = class extends h {
         n.dispose(), r(new Error("Formula batch calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        R.id,
+        I.id,
         { formulas: e },
         { onlyLocal: !0 }
       );
@@ -382,7 +382,7 @@ let m = class extends h {
   getAllDependencyTrees(e = 3e4) {
     return new Promise((t, i) => {
       const r = this._commandService.onCommandExecuted((a) => {
-        if (a.id !== M.id)
+        if (a.id !== N.id)
           return;
         const o = a.params;
         clearTimeout(n), r.dispose(), o.result != null ? t(o.result) : t([]);
@@ -390,7 +390,7 @@ let m = class extends h {
         r.dispose(), i(new Error("Formula dependency calculation timeout"));
       }, e);
       this._commandService.executeCommand(
-        b.id,
+        M.id,
         void 0,
         { onlyLocal: !0 }
       );
@@ -433,7 +433,7 @@ let m = class extends h {
   getCellDependencyTree(e, t = 3e4) {
     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(), i(s.result);
@@ -441,7 +441,7 @@ let m = class extends h {
         n.dispose(), r(new Error("Cell dependency calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        I.id,
+        B.id,
         e,
         { onlyLocal: !0 }
       );
@@ -489,7 +489,7 @@ let m = class extends h {
         n.dispose(), r(new Error("Range dependents calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        C.id,
+        S.id,
         { unitRanges: e },
         { onlyLocal: !0 }
       );
@@ -541,25 +541,145 @@ let m = class extends h {
         n.dispose(), r(new Error("In-range formulas calculation timeout"));
       }, t);
       this._commandService.executeCommand(
-        C.id,
+        S.id,
         { unitRanges: e, isInRange: !0 },
         { onlyLocal: !0 }
       );
     });
   }
+  /**
+   * Enable or disable emitting formula dependency trees after each formula calculation.
+   *
+   * When enabled, the formula engine will emit the dependency trees produced by
+   * each completed formula calculation through the internal command system.
+   * Consumers can obtain the result by listening for the corresponding
+   * calculation-result command.
+   *
+   * When disabled, dependency trees will not be emitted.
+   *
+   * This option only controls whether dependency trees are exposed.
+   * It does not affect formula calculation behavior.
+   *
+   * @param {boolean} value
+   *        Whether to emit formula dependency trees after calculation.
+   *        - `true`: Emit dependency trees after each calculation.
+   *        - `false`: Do not emit dependency trees (default behavior).
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   *
+   * // Enable dependency tree emission
+   * formulaEngine.setFormulaReturnDependencyTree(true);
+   *
+   * // Listen for dependency trees produced by formula calculation
+   * const trees = await new Promise<IFormulaDependencyTreeJson[]>((resolve, reject) => {
+   *   const timer = setTimeout(() => {
+   *     disposable.dispose();
+   *     reject(new Error('Timeout waiting for formula dependency trees'));
+   *   }, 30_000);
+   *
+   *   const disposable = commandService.onCommandExecuted((command) => {
+   *     if (command.id !== SetFormulaDependencyCalculationResultMutation.id) {
+   *       return;
+   *     }
+   *
+   *     clearTimeout(timer);
+   *     disposable.dispose();
+   *
+   *     const params = command.params as ISetFormulaDependencyCalculationResultMutation;
+   *     resolve(params.result ?? []);
+   *   });
+   * });
+   *
+   * console.log('Dependency trees:', trees);
+   * ```
+   */
+  setFormulaReturnDependencyTree(e) {
+    this._configService.setConfig(L, e);
+  }
+  /**
+   * Parse a formula string and return its **formula expression tree**.
+   *
+   * This API analyzes the syntactic structure of a formula and builds an
+   * expression tree that reflects how the formula is composed (functions,
+   * operators, ranges, and nested expressions), without performing calculation
+   * or dependency evaluation.
+   *
+   * The returned tree is suitable for:
+   * - Formula structure visualization
+   * - Explaining complex formulas (e.g. LET / LAMBDA)
+   * - Debugging or inspecting formula composition
+   * - Building advanced formula tooling
+   *
+   * ---
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   *
+   * const formula = '=LET(x,SUM(A1,B1,A1:B10),y,OFFSET(A1:B10,0,1),SUM(x,y)+x)+1';
+   *
+   * const exprTree = formulaEngine.getFormulaExpressTree(formula);
+   *
+   * console.log(exprTree);
+   * ```
+   *
+   * Example output (simplified):
+   *
+   * ```json
+   * {
+   *   "value": "let(x,sum(A1,B1,A1:B10),y,offset(A1:B10,0,1),sum(x,y)+x)+1",
+   *   "children": [
+   *     {
+   *       "value": "let(x,sum(A1,B1,A1:B10),y,offset(A1:B10,0,1),sum(x,y)+x)",
+   *       "children": [
+   *         {
+   *           "value": "sum(A1,B1,A1:B10)",
+   *           "children": [
+   *             {
+   *               "value": "A1:B10",
+   *               "children": []
+   *             }
+   *           ]
+   *         },
+   *         {
+   *           "value": "offset(A1:B10,0,1)",
+   *           "children": [
+   *             {
+   *               "value": "A1:B10",
+   *               "children": []
+   *             }
+   *           ]
+   *         }
+   *       ]
+   *     }
+   *   ]
+   * }
+   * ```
+   *
+   * @param formulaString The formula string to parse (with or without leading `=`)
+   * @returns A formula expression tree describing the hierarchical structure of the formula
+   */
+  getFormulaExpressTree(e, t) {
+    return this._lexerTreeBuilder.getFormulaExprTree(e, t, this._functionService.hasExecutor.bind(this._functionService), this._definedNamesService.getValueByName.bind(this._definedNamesService), this._superTableService.getTable.bind(this._superTableService));
+  }
 };
-m = j([
-  u(0, c(_)),
-  u(1, c(v)),
-  u(2, c(x)),
-  u(3, g)
+m = z([
+  u(0, l(h)),
+  u(1, l(v)),
+  u(2, l(g)),
+  u(3, E),
+  u(4, T),
+  u(5, x),
+  u(6, F)
 ], m);
-class U extends S {
+class Q extends _ {
   getFormula() {
     return this._injector.createInstance(m);
   }
 }
-S.extend(U);
+_.extend(Q);
 export {
   m as FFormula
 };