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

package/lib/types/engine/reference-object/base-reference-object.d.ts

@@ -1,5 +1,5 @@
-import { ICellData, IRange, Nullable } from '@univerjs/core';
-import { IRuntimeUnitDataType, IUnitData, IUnitSheetNameMap, IUnitStylesData } from '../../basics/common';
+import { ICellData, IRange, Nullable, ObjectMatrix } from '@univerjs/core';
+import { IArrayFormulaRangeType, IRuntimeUnitDataType, IUnitData, IUnitSheetNameMap, IUnitStylesData } from '../../basics/common';
 import { BaseValueObject } from '../value-object/base-value-object';
 import { FormulaAstLRU } from '../../basics/cache-lru';
 import { ObjectClassType } from '../../basics/object-class-type';
@@ -20,7 +20,9 @@ export declare class BaseReferenceObject extends ObjectClassType {
     private _forcedUnitId;
     private _runtimeData;
     private _arrayFormulaCellData;
+    private _arrayFormulaRange;
     private _runtimeArrayFormulaCellData;
+    private _runtimeArrayFormulaRange;
     private _runtimeFeatureCellData;
     private _refOffsetX;
     private _refOffsetY;
@@ -65,8 +67,12 @@ export declare class BaseReferenceObject extends ObjectClassType {
     setRuntimeData(runtimeData: IRuntimeUnitDataType): void;
     getArrayFormulaCellData(): IRuntimeUnitDataType;
     setArrayFormulaCellData(unitData: IRuntimeUnitDataType): void;
+    getArrayFormulaRange(): IArrayFormulaRangeType;
+    setArrayFormulaRange(rangeData: IArrayFormulaRangeType): void;
     getRuntimeArrayFormulaCellData(): IRuntimeUnitDataType;
     setRuntimeArrayFormulaCellData(unitData: IRuntimeUnitDataType): void;
+    getRuntimeArrayFormulaRange(): IArrayFormulaRangeType;
+    setRuntimeArrayFormulaRange(rangeData: IArrayFormulaRangeType): void;
     getRuntimeFeatureCellData(): {
         [featureId: string]: IRuntimeUnitDataType;
     };
@@ -95,9 +101,11 @@ export declare class BaseReferenceObject extends ObjectClassType {
     getCellByColumn(column: number): BaseValueObject;
     getCurrentActiveSheetData(): import('../../basics/common').ISheetItem;
     getCurrentStylesData(): import('@univerjs/core').Styles;
-    getCurrentRuntimeSheetData(): import('@univerjs/core').ObjectMatrix<Nullable<ICellData>> | undefined;
-    getCurrentActiveArrayFormulaCellData(): import('@univerjs/core').ObjectMatrix<Nullable<ICellData>> | undefined;
-    getCurrentRuntimeActiveArrayFormulaCellData(): import('@univerjs/core').ObjectMatrix<Nullable<ICellData>> | undefined;
+    getCurrentRuntimeSheetData(): ObjectMatrix<Nullable<ICellData>> | undefined;
+    getCurrentActiveArrayFormulaCellData(): ObjectMatrix<Nullable<ICellData>> | undefined;
+    getCurrentRuntimeActiveArrayFormulaCellData(): ObjectMatrix<Nullable<ICellData>> | undefined;
+    getCurrentActiveArrayFormulaRange(): import('@univerjs/core').IObjectMatrixPrimitiveType<IRange> | undefined;
+    getCurrentRuntimeActiveArrayFormulaRange(): import('@univerjs/core').IObjectMatrixPrimitiveType<IRange> | undefined;
     getCellData(row: number, column: number): Nullable<ICellData>;
     getRuntimeFeatureCellValue(row: number, column: number): ICellData | undefined;
     getCellByPosition(rowRaw?: number, columnRaw?: number): BaseValueObject;

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

@@ -1,5 +1,5 @@
 import { IDisposable, IUnitRange, ICommandService, IConfigService, Injector } from '@univerjs/core';
-import { FormulaExecutedStateType, IExecutionInProgressParams, IExprTreeNode, IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaDependentsAndInRangeResults, IFormulaExecuteResultMap, IFormulaStringMap, ISequenceNode, ISetFormulaCalculationResultMutation, IDefinedNamesService, IFunctionService, ISuperTableService, LexerTreeBuilder } from '@univerjs/engine-formula';
+import { FormulaExecutedStateType, IExecutionInProgressParams, IExprTreeNode, IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaDependentsAndInRangeResults, IFormulaExecuteResultMap, IFormulaStringMap, ISequenceNode, IDefinedNamesService, IFunctionService, ISuperTableService, LexerTreeBuilder } from '@univerjs/engine-formula';
 import { FBase } from '@univerjs/core/facade';
 /**
  * This interface class provides methods to modify the behavior of the operation formula.
@@ -136,59 +136,6 @@ export declare class FFormula extends FBase {
      * ```
      */
     setMaxIteration(maxIteration: number): void;
-    /**
-     * 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(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
-    /**
-     * 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(): Promise<void>;
     /**
      * Execute a batch of formulas asynchronously and receive computed results.
      *

package/lib/types/functions/column-like-functions.d.ts

@@ -0,0 +1,2 @@
+import { IFunctionNames } from '../basics/function';
+export declare const COLUMN_LIKE_FUNCTION_NAMES: Set<IFunctionNames>;

package/lib/umd/facade.js

@@ -1 +1 @@
-(function(c,l){typeof exports=="object"&&typeof module<"u"?l(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula"),require("rxjs")):typeof define=="function"&&define.amd?define(["exports","@univerjs/core/facade","@univerjs/core","@univerjs/engine-formula","rxjs"],l):(c=typeof globalThis<"u"?globalThis:c||self,l(c.UniverEngineFormulaFacade={},c.UniverCoreFacade,c.UniverCore,c.UniverEngineFormula,c.rxjs))})(this,(function(c,l,m,n,f){"use strict";var v=Object.getOwnPropertyDescriptor,C=(p,e,i,t)=>{for(var r=t>1?void 0:t?v(e,i):e,o=p.length-1,s;o>=0;o--)(s=p[o])&&(r=s(r)||r);return r},d=(p,e)=>(i,t)=>e(i,t,p);c.FFormula=class extends l.FBase{constructor(e,i,t,r,o,s,a){super(),this._commandService=e,this._injector=i,this._lexerTreeBuilder=t,this._configService=r,this._functionService=o,this._definedNamesService=s,this._superTableService=a,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,i,t,r){return this._lexerTreeBuilder.moveFormulaRefOffset(e,i,t,r)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(n.SetTriggerFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(n.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(i=>{if(i.id===n.SetFormulaCalculationStartMutation.id){const t=i.params;e(t.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(i=>{if(i.id!==n.SetFormulaCalculationNotificationMutation.id)return;const t=i.params;t.functionsExecutedState!==void 0&&e(t.functionsExecutedState)})}whenComputingCompleteAsync(e){const i=this._injector.get(n.GlobalComputingStatusService);return i.computingStatus?Promise.resolve(!0):f.firstValueFrom(f.race(i.computingStatus$.pipe(f.filter(t=>t)),f.timer(e!=null?e:3e4).pipe(f.map(()=>!1))))}onCalculationEnd(){return new Promise((e,i)=>{const t=setTimeout(()=>{i(new Error("Calculation end timeout"))},3e4),r=this.calculationEnd(()=>{clearTimeout(t),r.dispose(),e()})})}calculationProcessing(e){return this._commandService.onCommandExecuted(i=>{if(i.id!==n.SetFormulaCalculationNotificationMutation.id)return;const t=i.params;t.stageInfo!==void 0&&e(t.stageInfo)})}setMaxIteration(e){this._configService.setConfig(n.ENGINE_FORMULA_CYCLE_REFERENCE_COUNT,e)}calculationResultApplied(e){return this._commandService.onCommandExecuted(i=>{if(i.id!==n.SetFormulaCalculationResultMutation.id)return;const t=i.params;t!==void 0&&requestIdleCallback(()=>{e(t)})})}onCalculationResultApplied(){return new Promise((e,i)=>{let t=!1,r=!1;const o=setTimeout(()=>{S(),i(new Error("Calculation end timeout"))},3e4),s=setTimeout(()=>{t||(S(),e())},500),a=this.calculationProcessing(()=>{t||(t=!0,clearTimeout(s))}),u=this.calculationResultApplied(()=>{r||(r=!0,S(),e())});function S(){clearTimeout(o),clearTimeout(s),a.dispose(),u.dispose()}})}executeFormulas(e,i=3e4){return new Promise((t,r)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetFormulaStringBatchCalculationResultMutation.id)return;const u=a.params;clearTimeout(s),o.dispose(),u.result!=null?t(u.result):r(new Error("Formula batch calculation returned no result"))}),s=setTimeout(()=>{o.dispose(),r(new Error("Formula batch calculation timeout"))},i);this._commandService.executeCommand(n.SetFormulaStringBatchCalculationMutation.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((i,t)=>{const r=this._commandService.onCommandExecuted(s=>{if(s.id!==n.SetFormulaDependencyCalculationResultMutation.id)return;const a=s.params;clearTimeout(o),r.dispose(),a.result!=null?i(a.result):i([])}),o=setTimeout(()=>{r.dispose(),t(new Error("Formula dependency calculation timeout"))},e);this._commandService.executeCommand(n.SetFormulaDependencyCalculationMutation.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,i=3e4){return new Promise((t,r)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetCellFormulaDependencyCalculationResultMutation.id)return;const u=a.params;clearTimeout(s),o.dispose(),t(u.result)}),s=setTimeout(()=>{o.dispose(),r(new Error("Cell dependency calculation timeout"))},i);this._commandService.executeCommand(n.SetCellFormulaDependencyCalculationMutation.id,e,{onlyLocal:!0})})}getRangeDependents(e,i=3e4){return new Promise((t,r)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetQueryFormulaDependencyResultMutation.id)return;const u=a.params;clearTimeout(s),o.dispose(),u.result!=null?t(u.result):t([])}),s=setTimeout(()=>{o.dispose(),r(new Error("Range dependents calculation timeout"))},i);this._commandService.executeCommand(n.SetQueryFormulaDependencyMutation.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,i=3e4){return new Promise((t,r)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetQueryFormulaDependencyResultMutation.id)return;const u=a.params;clearTimeout(s),o.dispose(),u.result!=null?t(u.result):t([])}),s=setTimeout(()=>{o.dispose(),r(new Error("In-range formulas calculation timeout"))},i);this._commandService.executeCommand(n.SetQueryFormulaDependencyMutation.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(n.ENGINE_FORMULA_RETURN_DEPENDENCY_TREE,e)}getFormulaExpressTree(e,i){return this._lexerTreeBuilder.getFormulaExprTree(e,i,this._functionService.hasExecutor.bind(this._functionService),this._definedNamesService.getValueByName.bind(this._definedNamesService),this._superTableService.getTable.bind(this._superTableService))}getRangeDependentsAndInRangeFormulas(e,i=3e4){return new Promise((t,r)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==n.SetQueryFormulaDependencyAllResultMutation.id)return;const u=a.params;clearTimeout(s),o.dispose(),u.result!=null?t(u.result):t({dependents:[],inRanges:[]})}),s=setTimeout(()=>{o.dispose(),r(new Error("Range dependents calculation timeout"))},i);this._commandService.executeCommand(n.SetQueryFormulaDependencyAllMutation.id,{unitRanges:e},{onlyLocal:!0})})}},c.FFormula=C([d(0,m.Inject(m.ICommandService)),d(1,m.Inject(m.Injector)),d(2,m.Inject(n.LexerTreeBuilder)),d(3,m.IConfigService),d(4,n.IFunctionService),d(5,n.IDefinedNamesService),d(6,n.ISuperTableService)],c.FFormula);class h extends l.FUniver{getFormula(){return this._injector.createInstance(c.FFormula)}}l.FUniver.extend(h),Object.defineProperty(c,Symbol.toStringTag,{value:"Module"})}));
+(function(u,l){typeof exports=="object"&&typeof module<"u"?l(exports,require("@univerjs/core/facade"),require("@univerjs/core"),require("@univerjs/engine-formula"),require("rxjs")):typeof define=="function"&&define.amd?define(["exports","@univerjs/core/facade","@univerjs/core","@univerjs/engine-formula","rxjs"],l):(u=typeof globalThis<"u"?globalThis:u||self,l(u.UniverEngineFormulaFacade={},u.UniverCoreFacade,u.UniverCore,u.UniverEngineFormula,u.rxjs))})(this,(function(u,l,m,r,S){"use strict";var f=Object.getOwnPropertyDescriptor,v=(p,e,t,i)=>{for(var n=i>1?void 0:i?f(e,t):e,o=p.length-1,s;o>=0;o--)(s=p[o])&&(n=s(n)||n);return n},d=(p,e)=>(t,i)=>e(t,i,p);u.FFormula=class extends l.FBase{constructor(e,t,i,n,o,s,a){super(),this._commandService=e,this._injector=t,this._lexerTreeBuilder=i,this._configService=n,this._functionService=o,this._definedNamesService=s,this._superTableService=a,this._initialize()}_initialize(){}get lexerTreeBuilder(){return this._lexerTreeBuilder}moveFormulaRefOffset(e,t,i,n){return this._lexerTreeBuilder.moveFormulaRefOffset(e,t,i,n)}sequenceNodesBuilder(e){return this._lexerTreeBuilder.sequenceNodesBuilder(e)||[]}executeCalculation(){this._commandService.executeCommand(r.SetTriggerFormulaCalculationStartMutation.id,{commands:[],forceCalculation:!0},{onlyLocal:!0})}stopCalculation(){this._commandService.executeCommand(r.SetFormulaCalculationStopMutation.id,{})}calculationStart(e){return this._commandService.onCommandExecuted(t=>{if(t.id===r.SetFormulaCalculationStartMutation.id){const i=t.params;e(i.forceCalculation)}})}calculationEnd(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.functionsExecutedState!==void 0&&e(i.functionsExecutedState)})}whenComputingCompleteAsync(e){const t=this._injector.get(r.GlobalComputingStatusService);return t.computingStatus?Promise.resolve(!0):S.firstValueFrom(S.race(t.computingStatus$.pipe(S.filter(i=>i)),S.timer(e!=null?e:3e4).pipe(S.map(()=>!1))))}onCalculationEnd(){return new Promise((e,t)=>{const i=setTimeout(()=>{t(new Error("Calculation end timeout"))},3e4),n=this.calculationEnd(()=>{clearTimeout(i),n.dispose(),e()})})}calculationProcessing(e){return this._commandService.onCommandExecuted(t=>{if(t.id!==r.SetFormulaCalculationNotificationMutation.id)return;const i=t.params;i.stageInfo!==void 0&&e(i.stageInfo)})}setMaxIteration(e){this._configService.setConfig(r.ENGINE_FORMULA_CYCLE_REFERENCE_COUNT,e)}executeFormulas(e,t=3e4){return new Promise((i,n)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==r.SetFormulaStringBatchCalculationResultMutation.id)return;const c=a.params;clearTimeout(s),o.dispose(),c.result!=null?i(c.result):n(new Error("Formula batch calculation returned no result"))}),s=setTimeout(()=>{o.dispose(),n(new Error("Formula batch calculation timeout"))},t);this._commandService.executeCommand(r.SetFormulaStringBatchCalculationMutation.id,{formulas:e},{onlyLocal:!0})})}getAllDependencyTrees(e=3e4){return new Promise((t,i)=>{const n=this._commandService.onCommandExecuted(s=>{if(s.id!==r.SetFormulaDependencyCalculationResultMutation.id)return;const a=s.params;clearTimeout(o),n.dispose(),a.result!=null?t(a.result):t([])}),o=setTimeout(()=>{n.dispose(),i(new Error("Formula dependency calculation timeout"))},e);this._commandService.executeCommand(r.SetFormulaDependencyCalculationMutation.id,void 0,{onlyLocal:!0})})}getCellDependencyTree(e,t=3e4){return new Promise((i,n)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==r.SetCellFormulaDependencyCalculationResultMutation.id)return;const c=a.params;clearTimeout(s),o.dispose(),i(c.result)}),s=setTimeout(()=>{o.dispose(),n(new Error("Cell dependency calculation timeout"))},t);this._commandService.executeCommand(r.SetCellFormulaDependencyCalculationMutation.id,e,{onlyLocal:!0})})}getRangeDependents(e,t=3e4){return new Promise((i,n)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==r.SetQueryFormulaDependencyResultMutation.id)return;const c=a.params;clearTimeout(s),o.dispose(),c.result!=null?i(c.result):i([])}),s=setTimeout(()=>{o.dispose(),n(new Error("Range dependents calculation timeout"))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e},{onlyLocal:!0})})}getInRangeFormulas(e,t=3e4){return new Promise((i,n)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==r.SetQueryFormulaDependencyResultMutation.id)return;const c=a.params;clearTimeout(s),o.dispose(),c.result!=null?i(c.result):i([])}),s=setTimeout(()=>{o.dispose(),n(new Error("In-range formulas calculation timeout"))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyMutation.id,{unitRanges:e,isInRange:!0},{onlyLocal:!0})})}setFormulaReturnDependencyTree(e){this._configService.setConfig(r.ENGINE_FORMULA_RETURN_DEPENDENCY_TREE,e)}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))}getRangeDependentsAndInRangeFormulas(e,t=3e4){return new Promise((i,n)=>{const o=this._commandService.onCommandExecuted(a=>{if(a.id!==r.SetQueryFormulaDependencyAllResultMutation.id)return;const c=a.params;clearTimeout(s),o.dispose(),c.result!=null?i(c.result):i({dependents:[],inRanges:[]})}),s=setTimeout(()=>{o.dispose(),n(new Error("Range dependents calculation timeout"))},t);this._commandService.executeCommand(r.SetQueryFormulaDependencyAllMutation.id,{unitRanges:e},{onlyLocal:!0})})}},u.FFormula=v([d(0,m.Inject(m.ICommandService)),d(1,m.Inject(m.Injector)),d(2,m.Inject(r.LexerTreeBuilder)),d(3,m.IConfigService),d(4,r.IFunctionService),d(5,r.IDefinedNamesService),d(6,r.ISuperTableService)],u.FFormula);class _ extends l.FUniver{getFormula(){return this._injector.createInstance(u.FFormula)}}l.FUniver.extend(_),Object.defineProperty(u,Symbol.toStringTag,{value:"Module"})}));