@univerjs/engine-formula 0.6.0 → 0.6.1

package/lib/es/facade.js

@@ -25,41 +25,73 @@ let s = class extends f {
   }
   /**
    * Offsets the formula
-   * @param {string} formulaString
-   * @param {number} refOffsetX
-   * @param {number} refOffsetY
-   * @param {boolean} [ignoreAbsolute] default is false
+   * @param {string} formulaString - The formula string to offset
+   * @param {number} refOffsetX - The offset column
+   * @param {number} refOffsetY - The offset row
+   * @param {boolean} [ignoreAbsolute] - Whether to ignore the absolute reference
+   * @returns {string} The offset formula string
+   *
    * @example
-   * const result = moveFormulaRefOffset('sum(a1,b2)',1,1)
-   * // result  is 'sum(b2,c3)'
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * const result = formulaEngine.moveFormulaRefOffset('=SUM(A1,B2)', 1, 1);
+   * console.log(result);
+   * ```
    */
   moveFormulaRefOffset(e, t, r, i) {
     return this._lexerTreeBuilder.moveFormulaRefOffset(e, t, r, i);
   }
   /**
    * Resolves the formula string to a 'node' node
-   * @param {string} formulaString
-   * @returns {*}  {((string | ISequenceNode)[])}
-   * @memberof FFormula
+   * @param {string} formulaString - The formula string to resolve
+   * @returns {Array<ISequenceNode | string>} The nodes of the formula string
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * const nodes = formulaEngine.sequenceNodesBuilder('=SUM(A1,B2)');
+   * console.log(nodes);
+   * ```
    */
   sequenceNodesBuilder(e) {
     return this._lexerTreeBuilder.sequenceNodesBuilder(e) || [];
   }
   /**
    * Start the calculation of the formula.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.executeCalculation();
+   * ```
    */
   executeCalculation() {
     this._commandService.executeCommand(l.id, { commands: [], forceCalculation: !0 }, { onlyLocal: !0 });
   }
   /**
    * Stop the calculation of the formula.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.stopCalculation();
+   * ```
    */
   stopCalculation() {
     this._commandService.executeCommand(S.id, {});
   }
   /**
    * Listening calculation starts.
-   * @param callback
+   * @param {Function} callback - The callback function to be called when the formula calculation starts.
+   * @returns {IDisposable} The disposable instance.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.calculationStart((forceCalculation) => {
+   *   console.log('Calculation start', forceCalculation);
+   * });
+   * ```
    */
   calculationStart(e) {
     return this._commandService.onCommandExecuted((t) => {
@@ -71,7 +103,16 @@ let s = class extends f {
   }
   /**
    * Listening calculation ends.
-   * @param callback
+   * @param {Function} callback - The callback function to be called when the formula calculation ends.
+   * @returns {IDisposable} The disposable instance.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.calculationEnd((functionsExecutedState) => {
+   *   console.log('Calculation end', functionsExecutedState);
+   * });
+   * ```
    */
   calculationEnd(e) {
     return this._commandService.onCommandExecuted((t) => {
@@ -88,6 +129,14 @@ let s = class extends f {
    * value is 30,000 milliseconds.
    * @returns {Promise<boolean>} This method returns `true` if the computing is complete. If the timeout is reached, this
    * method returns `false`.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.whenComputingCompleteAsync(3000).then((isComplete) => {
+   *   console.log('Computing complete:', isComplete);
+   * });
+   * ```
    */
   whenComputingCompleteAsync(e) {
     const t = this._injector.get(x);
@@ -111,7 +160,16 @@ let s = class extends f {
   }
   /**
    * Listening calculation processing.
-   * @param callback
+   * @param {Function} callback - The callback function to be called when the formula calculation is in progress.
+   * @returns {IDisposable} The disposable instance.
+   *
+   * @example
+   * ```ts
+   * const formulaEngine = univerAPI.getFormula();
+   * formulaEngine.calculationProcessing((stageInfo) => {
+   *   console.log('Calculation processing', stageInfo);
+   * });
+   * ```
    */
   calculationProcessing(e) {
     return this._commandService.onCommandExecuted((t) => {
@@ -123,7 +181,8 @@ let s = class extends f {
   }
   /**
    * When a formula contains a circular reference, set the maximum number of iterations for the formula calculation.
-   * @param maxIteration The maximum number of iterations. The default value is 1.
+   * @param {number} maxIteration The maximum number of iterations. The default value is 1.
+   *
    * @example
    * ```ts
    * // Set the maximum number of iterations for the formula calculation to 5.

package/lib/es/index.js

@@ -3,7 +3,7 @@ var Hu = (i, a, e) => a in i ? Yu(i, a, { enumerable: !0, configurable: !0, writ
 var A = (i, a, e) => Hu(i, typeof a != "symbol" ? a + "" : a, e);
 import { ObjectMatrix as Ce, CommandType as Ie, RANGE_TYPE as Ze, AbsoluteRefType as Se, Tools as ze, createIdentifier as ft, Disposable as Oe, IUniverInstanceService as ra, LRUMap as Gu, hashAlgorithm as Qu, moveRangeByOffset as na, isValidRange as Wu, isFormulaString as bt, isFormulaId as Pt, Rectangle as Wa, cellToRange as qu, Inject as Ve, UniverInstanceType as Dr, LocaleService as Ku, LocaleType as Mr, numfmt as gt, BuildTextUtils as Xu, isRealNum as Q, CellValueType as yt, toDisposable as Zu, Injector as Gi, sortRules as zu, RTree as ys, IConfigService as sa, requestImmediateMacroTask as Ju, ICommandService as ar, BooleanNumber as ec, DataStreamTreeTokenType as ve, DisposableCollection as tc, Optional as rc, Plugin as nc, merge as sc, touchDependencies as ss } from "@univerjs/core";
 import { Subject as cr, BehaviorSubject as Qi, distinctUntilChanged as Wi, combineLatest as ac, map as ic, Observable as oc, shareReplay as uc } from "rxjs";
-import { DEFAULT_TEXT_FORMAT as cc } from "@univerjs/engine-numfmt";
+import { isTextFormat as cc } from "@univerjs/engine-numfmt";
 import { DataSyncPrimaryController as lc } from "@univerjs/rpc";
 var er = /* @__PURE__ */ ((i) => (i.FALSE = "FALSE", i.TRUE = "TRUE", i))(er || {}), xt = /* @__PURE__ */ ((i) => (i[i.SUCCESS = 0] = "SUCCESS", i[i.ERROR = 1] = "ERROR", i))(xt || {}), ot = /* @__PURE__ */ ((i) => (i[i.FRONT = 0] = "FRONT", i[i.BACK = 1] = "BACK", i))(ot || {});
 function fc(i, a, e, t, r) {
@@ -355,6 +355,8 @@ let Ms = class extends Oe {
     super();
     // 18.2.6 definedNames (Defined Names)
     A(this, "_definedNameMap", {});
+    A(this, "_nameCacheMap", {});
+    // Cache for name-to-definition mapping
     A(this, "_update$", new cr());
     A(this, "update$", this._update$.asObservable());
     A(this, "_currentRange", {
@@ -374,7 +376,7 @@ let Ms = class extends Oe {
     this._univerInstanceService = a;
   }
   dispose() {
-    this._definedNameMap = {};
+    this._definedNameMap = {}, this._nameCacheMap = {};
   }
   getWorksheetByRef(a, e) {
     var r;
@@ -383,7 +385,7 @@ let Ms = class extends Oe {
   }
   focusRange(a, e) {
     const t = this.getValueById(a, e);
-    t != null && this._focusRange$.next({ ...t, unitId: a });
+    t !== void 0 && this._focusRange$.next({ ...t, unitId: a });
   }
   setCurrentRange(a) {
     this._currentRange = a, this._currentRange$.next(a);
@@ -395,36 +397,56 @@ let Ms = class extends Oe {
     return hr(this._currentRange.range);
   }
   registerDefinedNames(a, e) {
-    this._definedNameMap[a] = e, this._update();
+    this._definedNameMap[a] = e, this._updateCache(a), this._update();
   }
   registerDefinedName(a, e) {
-    this._definedNameMap[a] == null && (this._definedNameMap[a] = {}), this._definedNameMap[a][e.id] = e, this._update();
+    this._definedNameMap[a] === void 0 && (this._definedNameMap[a] = {}), this._definedNameMap[a][e.id] = e, this._updateCache(a), this._update();
   }
   removeDefinedName(a, e) {
     var t;
-    (t = this._definedNameMap[a]) == null || delete t[e], this._update();
+    (t = this._definedNameMap[a]) == null || delete t[e], this._updateCache(a), this._update();
   }
   removeUnitDefinedName(a) {
-    delete this._definedNameMap[a], this._update();
+    delete this._definedNameMap[a], this._updateCache(a), this._update();
   }
   getDefinedNameMap(a) {
     return this._definedNameMap[a];
   }
   getValueByName(a, e) {
-    var r;
-    const t = this._definedNameMap[a];
-    return t == null ? null : (r = Array.from(Object.values(t)).filter((n) => n.name === e)) == null ? void 0 : r[0];
+    const t = this._nameCacheMap[a];
+    if (t)
+      return t[e] || null;
+    const r = this._definedNameMap[a];
+    if (r === void 0)
+      return null;
+    let n = null;
+    for (const s of Object.values(r))
+      if (s.name === e) {
+        n = s;
+        break;
+      }
+    return n && (this._nameCacheMap[a] = this._nameCacheMap[a] || {}, this._nameCacheMap[a][e] = n), n;
   }
   getValueById(a, e) {
     var t;
     return (t = this._definedNameMap[a]) == null ? void 0 : t[e];
   }
   hasDefinedName(a) {
-    return this._definedNameMap[a] == null ? !1 : (Array.from(Object.values(this._definedNameMap[a])).length || 0) !== 0;
+    return this._definedNameMap[a] === void 0 ? !1 : (Array.from(Object.values(this._definedNameMap[a])).length || 0) !== 0;
   }
   _update() {
     this._update$.next(null);
   }
+  _updateCache(a) {
+    const e = this._definedNameMap[a];
+    if (e === void 0) {
+      delete this._nameCacheMap[a];
+      return;
+    }
+    this._nameCacheMap[a] = {};
+    for (const t of Object.values(e))
+      this._nameCacheMap[a][t.name] = t;
+  }
 };
 Ms = Hc([
   Gc(0, ra)
@@ -6411,7 +6433,7 @@ class Hn extends Tn {
       return g.create(t);
     if (e.t === yt.NUMBER) {
       const r = this._getPatternByCell(e);
-      return r === cc ? j.create(t.toString()) : Yn(t, r);
+      return cc(r) ? j.create(t.toString()) : Yn(t, r);
     }
     return e.t === yt.STRING || e.t === yt.FORCE_STRING ? j.create(t.toString()) : e.t === yt.BOOLEAN ? $n(t) : pt.create(t);
   }

package/lib/types/facade/f-formula.d.ts

@@ -22,38 +22,79 @@ export declare class FFormula extends FBase {
     get lexerTreeBuilder(): LexerTreeBuilder;
     /**
      * Offsets the formula
-     * @param {string} formulaString
-     * @param {number} refOffsetX
-     * @param {number} refOffsetY
-     * @param {boolean} [ignoreAbsolute] default is false
+     * @param {string} formulaString - The formula string to offset
+     * @param {number} refOffsetX - The offset column
+     * @param {number} refOffsetY - The offset row
+     * @param {boolean} [ignoreAbsolute] - Whether to ignore the absolute reference
+     * @returns {string} The offset formula string
+     *
      * @example
-     * const result = moveFormulaRefOffset('sum(a1,b2)',1,1)
-     * // result  is 'sum(b2,c3)'
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * const result = formulaEngine.moveFormulaRefOffset('=SUM(A1,B2)', 1, 1);
+     * console.log(result);
+     * ```
      */
     moveFormulaRefOffset(formulaString: string, refOffsetX: number, refOffsetY: number, ignoreAbsolute?: boolean): string;
     /**
      * Resolves the formula string to a 'node' node
-     * @param {string} formulaString
-     * @returns {*}  {((string | ISequenceNode)[])}
-     * @memberof FFormula
+     * @param {string} formulaString - The formula string to resolve
+     * @returns {Array<ISequenceNode | string>} The nodes of the formula string
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * const nodes = formulaEngine.sequenceNodesBuilder('=SUM(A1,B2)');
+     * console.log(nodes);
+     * ```
      */
     sequenceNodesBuilder(formulaString: string): (string | ISequenceNode)[];
     /**
      * Start the calculation of the formula.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.executeCalculation();
+     * ```
      */
     executeCalculation(): void;
     /**
      * Stop the calculation of the formula.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.stopCalculation();
+     * ```
      */
     stopCalculation(): void;
     /**
      * Listening calculation starts.
-     * @param callback
+     * @param {Function} callback - The callback function to be called when the formula calculation starts.
+     * @returns {IDisposable} The disposable instance.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.calculationStart((forceCalculation) => {
+     *   console.log('Calculation start', forceCalculation);
+     * });
+     * ```
      */
     calculationStart(callback: (forceCalculation: boolean) => void): IDisposable;
     /**
      * Listening calculation ends.
-     * @param callback
+     * @param {Function} callback - The callback function to be called when the formula calculation ends.
+     * @returns {IDisposable} The disposable instance.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.calculationEnd((functionsExecutedState) => {
+     *   console.log('Calculation end', functionsExecutedState);
+     * });
+     * ```
      */
     calculationEnd(callback: (functionsExecutedState: FormulaExecutedStateType) => void): IDisposable;
     /**
@@ -63,6 +104,14 @@ export declare class FFormula extends FBase {
      * value is 30,000 milliseconds.
      * @returns {Promise<boolean>} This method returns `true` if the computing is complete. If the timeout is reached, this
      * method returns `false`.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.whenComputingCompleteAsync(3000).then((isComplete) => {
+     *   console.log('Computing complete:', isComplete);
+     * });
+     * ```
      */
     whenComputingCompleteAsync(timeout?: number): Promise<boolean>;
     /**
@@ -72,12 +121,22 @@ export declare class FFormula extends FBase {
     onCalculationEnd(): Promise<void>;
     /**
      * Listening calculation processing.
-     * @param callback
+     * @param {Function} callback - The callback function to be called when the formula calculation is in progress.
+     * @returns {IDisposable} The disposable instance.
+     *
+     * @example
+     * ```ts
+     * const formulaEngine = univerAPI.getFormula();
+     * formulaEngine.calculationProcessing((stageInfo) => {
+     *   console.log('Calculation processing', stageInfo);
+     * });
+     * ```
      */
     calculationProcessing(callback: (stageInfo: IExecutionInProgressParams) => void): IDisposable;
     /**
      * When a formula contains a circular reference, set the maximum number of iterations for the formula calculation.
-     * @param maxIteration The maximum number of iterations. The default value is 1.
+     * @param {number} maxIteration The maximum number of iterations. The default value is 1.
+     *
      * @example
      * ```ts
      * // Set the maximum number of iterations for the formula calculation to 5.

package/lib/types/services/defined-names.service.d.ts

@@ -38,6 +38,7 @@ export interface IDefinedNamesService {
 export declare class DefinedNamesService extends Disposable implements IDefinedNamesService {
     private readonly _univerInstanceService;
     private _definedNameMap;
+    private _nameCacheMap;
     private readonly _update$;
     readonly update$: Observable<unknown>;
     private _currentRange;
@@ -61,5 +62,6 @@ export declare class DefinedNamesService extends Disposable implements IDefinedN
     getValueById(unitId: string, id: string): IDefinedNamesServiceParam;
     hasDefinedName(unitId: string): boolean;
     private _update;
+    private _updateCache;
 }
 export declare const IDefinedNamesService: import('@wendellhu/redi').IdentifierDecorator<DefinedNamesService>;