@univerjs/engine-formula 1.0.0-rc.0 → 1.0.1

package/lib/types/basics/common.d.ts

@@ -237,7 +237,9 @@ export interface IUnitExcludedCell {
 }
 export interface IUnitRowData {
     [unitId: string]: Nullable<{
-        [sheetId: string]: IObjectArrayPrimitiveType<Partial<IRowData>>;
+        [sheetId: string]: IObjectArrayPrimitiveType<Partial<IRowData> & {
+            filtered?: boolean;
+        }>;
     }>;
 }
 export interface IFormulaDatasetConfig {

package/lib/types/basics/inverted-index-cache.d.ts

@@ -33,6 +33,7 @@ export declare class InvertedIndexCache {
      * }
      */
     private _cache;
+    private _rowValues;
     private _continueBuildingCache;
     set(unitId: string, sheetId: string, column: number, value: ValueTypeWithNullUndefined, row: number, isForceUpdate?: boolean): void;
     getCellValuePositions(unitId: string, sheetId: string, column: number): Map<ValueTypeWithSymbol, Set<number>> | undefined;

package/lib/types/basics/regex.d.ts

@@ -18,19 +18,19 @@ export declare const UNIT_NAME_REGEX_PRECOMPILING: RegExp;
 export declare const SHEET_NAME_REGEX = "((?![\\[\\]\\/?*\\\\]).)*!";
 export declare const ABSOLUTE_SYMBOL = "$";
 export declare const RANGE_SYMBOL = "\\s*?:\\s*?";
-export declare const UNIT_NAME_SHEET_NAME_REGEX = "'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?";
+export declare const UNIT_NAME_SHEET_NAME_REGEX = "(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?";
 export declare const SIMPLE_SINGLE_RANGE_REGEX = "\\$?[A-Za-z]+\\$?[1-9][0-9]*";
-export declare const REFERENCE_MULTIPLE_RANGE_REGEX = "^(@)?'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[A-Za-z]+\\$?[1-9][0-9]*\\s*?:\\s*?\\$?[A-Za-z]+\\$?[1-9][0-9]*$";
+export declare const REFERENCE_MULTIPLE_RANGE_REGEX = "^(@)?(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[A-Za-z]+\\$?[1-9][0-9]*\\s*?:\\s*?\\$?[A-Za-z]+\\$?[1-9][0-9]*$";
 export declare const REFERENCE_MULTIPLE_RANGE_REGEX_PRECOMPILING: RegExp;
-export declare const REFERENCE_SINGLE_RANGE_REGEX = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[A-Za-z]+\\$?[1-9][0-9]*(#)?$";
+export declare const REFERENCE_SINGLE_RANGE_REGEX = "^(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[A-Za-z]+\\$?[1-9][0-9]*(#)?$";
 export declare const REFERENCE_SINGLE_RANGE_REGEX_PRECOMPILING: RegExp;
-export declare const REFERENCE_REGEX_ROW = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[1-9][0-9]*\\s*?:\\s*?\\$?[1-9][0-9]*$";
+export declare const REFERENCE_REGEX_ROW = "^(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[1-9][0-9]*\\s*?:\\s*?\\$?[1-9][0-9]*$";
 export declare const REFERENCE_REGEX_ROW_PRECOMPILING: RegExp;
-export declare const REFERENCE_REGEX_COLUMN = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[A-Za-z]+\\s*?:\\s*?\\$?[A-Za-z]+$";
+export declare const REFERENCE_REGEX_COLUMN = "^(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\$?[A-Za-z]+\\s*?:\\s*?\\$?[A-Za-z]+$";
 export declare const REFERENCE_REGEX_COLUMN_PRECOMPILING: RegExp;
-export declare const REFERENCE_REGEX_SINGLE_ROW = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[1-9][0-9]*$";
+export declare const REFERENCE_REGEX_SINGLE_ROW = "^(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[1-9][0-9]*$";
 export declare const REFERENCE_REGEX_SINGLE_ROW_PRECOMPILING: RegExp;
-export declare const REFERENCE_REGEX_SINGLE_COLUMN = "^'?(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[A-Za-z]+$";
+export declare const REFERENCE_REGEX_SINGLE_COLUMN = "^(?:'(?:[^'\\[]|'')*[\\\\/]|'?)(\\[([^\\[\\]\\/?:\"<>|*\\\\]+)\\])?(((?![\\[\\]\\/?*\\\\]).)*!)?'?\\s*?\\$?[A-Za-z]+$";
 export declare const REFERENCE_REGEX_SINGLE_COLUMN_PRECOMPILING: RegExp;
 export declare const REFERENCE_TABLE_ALL_COLUMN_REGEX = "^(?:(?:\\[(?:[^\\]]|\\]\\])+\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[(?:[^\\]]|\\]\\])+\\])?((?![~!@#$%^&*()+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+$";
 export declare const REFERENCE_TABLE_SINGLE_COLUMN_REGEX = "^(?:(?:\\[(?:[^\\]]|\\]\\])+\\]|'(?:[^']|'')+'|[^\\s!\\[\\]]+)!)?(?:\\[(?:[^\\]]|\\]\\])+\\])?((?![~!@#$%^&*()+<>?:,./;\u2019\uFF0C\u3002\u3001\u2018\uFF1A\u201C\u300A\u300B\uFF1F~\uFF01@#\uFFE5%\u2026\u2026\uFF08\uFF09\u3010\u3011\\[\\]\\/\\\\]).)+(\\[[^#]*#?\\]|\\[\\[#.+\\]\\s*?,\\s*?\\[[^#]*#?\\]\\])+$";

package/lib/types/basics/runtime.d.ts

@@ -13,6 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { Nullable } from '@univerjs/core';
 import type { IArrayFormulaUnitCellType, IRuntimeUnitDataPrimitiveType, IRuntimeUnitDataType } from './common';
 export declare function convertUnitDataToRuntime(unitData: IArrayFormulaUnitCellType): IRuntimeUnitDataType;
 export declare function convertRuntimeToUnitData(unitData: IRuntimeUnitDataType): IRuntimeUnitDataPrimitiveType;
+/** Copy the unit and sheet dictionaries without retaining inherited identifier keys. */
+export declare function copyUnitData<T>(data: {
+    [unitId: string]: Nullable<{
+        [sheetId: string]: T;
+    }>;
+}): {
+    [unitId: string]: {
+        [sheetId: string]: T;
+    };
+};

package/lib/types/engine/ast-node/prefix-node.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { Nullable } from '@univerjs/core';
+import type { IUnitRange, Nullable } from '@univerjs/core';
 import type { BaseFunction } from '../../functions/base-function';
 import { DateSystem } from '@univerjs/core';
 import { IFunctionService } from '../../services/function.service';
@@ -26,10 +26,13 @@ export declare class PrefixNode extends BaseAstNode {
     private _runtimeService;
     private _operatorString;
     private _functionExecutor?;
+    private _referenceRanges;
+    getReferenceRanges(): IUnitRange[] | null;
     constructor(_runtimeService: IFormulaRuntimeService, _operatorString: string, _functionExecutor?: Nullable<BaseFunction>);
     get nodeType(): NodeType;
     execute(dateSystem?: DateSystem): void;
     private _handlerAT;
+    private _getReferencedCell;
     private _preserveAtRangeForFormula2LookupArray;
 }
 export declare class PrefixNodeFactory extends BaseAstNodeFactory {

package/lib/types/engine/ast-node/reference-node.d.ts

@@ -31,7 +31,7 @@ interface ITableReferenceDescriptor {
     columnStruct: string | undefined;
 }
 type ReferenceNodeCurrentConfigService = Pick<IFormulaCurrentConfigService, 'getArrayFormulaCellData' | 'getArrayFormulaRange' | 'getSheetNameMap' | 'getUnitData' | 'getUnitStylesData'>;
-type ReferenceNodeRuntimeService = Pick<IFormulaRuntimeService, 'currentColumn' | 'currentRow' | 'currentSubUnitId' | 'currentUnitId' | 'getRuntimeArrayFormulaCellData' | 'getRuntimeFeatureCellData' | 'getUnitArrayFormula' | 'getUnitData'>;
+type ReferenceNodeRuntimeService = Pick<IFormulaRuntimeService, 'markExternalReferenceUnavailable' | 'currentColumn' | 'currentRow' | 'currentSubUnitId' | 'currentUnitId' | 'getRuntimeArrayFormulaCellData' | 'getRuntimeFeatureCellData' | 'getUnitArrayFormula' | 'getUnitData'>;
 type ReferenceNodeSuperTableService = Pick<ISuperTableService, 'getTableMap' | 'getTableOptionMap'>;
 export declare class ReferenceNode extends BaseAstNode {
     private _currentConfigService;

package/lib/types/engine/dependency/formula-dependency.d.ts

@@ -16,8 +16,8 @@
 import type { IRange, IUnitRange, Nullable } from '@univerjs/core';
 import type { IFeatureDirtyRangeType, IFormulaData, IFormulaDataItem, IOtherFormulaData, IUnitData } from '../../basics/common';
 import type { IFeatureCalculationManagerParam } from '../../services/feature-calculation-manager.service';
-import type { FunctionNode } from '../ast-node';
 import type { BaseAstNode } from '../ast-node/base-ast-node';
+import type { FunctionNode } from '../ast-node/function-node';
 import type { IExecuteAstNodeData } from '../utils/ast-node-tool';
 import type { IFormulaDependencyTree, IFormulaDependencyTreeFullJson, IFormulaDependencyTreeJson, IFormulaDependentsAndInRangeResults } from './dependency-tree';
 import { Disposable, IUniverInstanceService, RTree } from '@univerjs/core';

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

@@ -105,6 +105,7 @@ export declare class TableReferenceObject extends BaseReferenceObject {
     private _findColonAtTopLevel;
     /** Column title → column index; returns -1 if not found (caller should handle as parse error) */
     private _titleToIndex;
+    private _unescapeColumnName;
     /** Resolve #This Row's row number; takes first data row (tableStartRow+1) when no context available */
     private _resolveThisRow;
 }

package/lib/types/engine/utils/compare.d.ts

@@ -31,8 +31,9 @@ export declare enum ArrayOrderSearchType {
 }
 export declare function getCompare(): (x: string, y: string) => number;
 export declare function isWildcard(str: string): boolean;
+export declare function normalizeTextForComparison(value: string): string;
 export declare function isMatchWildcard(currentValue: string, value: string): boolean;
 export declare function replaceWildcard(value: string): string;
-export declare function compareWithWildcard(currentValue: string, value: string, operator: compareToken): boolean;
+export declare function compareWithWildcard(currentValue: string, value: string, operator: compareToken, isCaseSensitive?: boolean): boolean;
 export declare function getMatchModeValue(matchModeValue: number): ArrayOrderSearchType;
 export declare function getSearchModeValue(searchModeValue: number): ArrayBinarySearchType;

package/lib/types/engine/utils/object-compare.d.ts

@@ -17,6 +17,7 @@ import type { DateSystem } from '@univerjs/core';
 import type { ArrayValueObject } from '../value-object/array-value-object';
 import type { BaseValueObject } from '../value-object/base-value-object';
 import { compareToken } from '../../basics/token';
+export declare function createCriteriaValueObject(content: string, dateSystem?: DateSystem): BaseValueObject;
 export declare function findCompareToken(str: string, dateSystem?: DateSystem): [compareToken, BaseValueObject];
 /**
  * When it contains both comparison characters and wildcard characters

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

@@ -124,10 +124,14 @@ export declare class FFormula extends FBase {
     calculationEnd(callback: (functionsExecutedState: FormulaExecutedStateType) => void): IDisposable;
     /**
      * Listens for formula results after every affected model has applied them.
+     * @param {(result: ISetFormulaCalculationResultMutation) => void} callback Receives each applied formula result asynchronously.
+     * @returns {IDisposable} A disposable that unsubscribes from future result notifications.
      */
     calculationResultApplied(callback: (result: ISetFormulaCalculationResultMutation) => void): IDisposable;
     /**
      * Waits until the latest formula-calculation results have been applied.
+     * @param {number} [timeout] Maximum wait in milliseconds. Omit to wait without an overall timeout.
+     * @returns {Promise<void>} Resolves when the latest calculation results have been applied; rejects if the supplied timeout expires.
      */
     onCalculationResultApplied(timeout?: number): Promise<void>;
     /**

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

@@ -19,6 +19,15 @@ import { FFormula } from './f-formula';
  * @ignore
  */
 export interface IFUniverEngineFormulaMixin {
+    /**
+     * Gets the formula engine facade for calculation, parsing, and dependency queries.
+     * @returns {FFormula} The formula engine facade.
+     * @example
+     * ```ts
+     * const formula = univerAPI.getFormula();
+     * await formula.onCalculationResultApplied();
+     * ```
+     */
     getFormula(): FFormula;
 }
 export declare class FUniverEngineFormulaMixin extends FUniver implements IFUniverEngineFormulaMixin {

package/lib/types/services/current-data.service.d.ts

@@ -95,6 +95,7 @@ export declare class FormulaCurrentConfigService extends Disposable implements I
     private _sheetNameMap;
     private _unitNameMap;
     private _externalReferences;
+    private _calculationRowData;
     private _calculationGeneration;
     private _forceCalculate;
     private _clearDependencyTreeCache;

package/lib/types/services/runtime.service.d.ts

@@ -81,6 +81,7 @@ export interface IFormulaRuntimeService {
     hasFunctionRefInfoOverride(): boolean;
     registerFunctionDefinitionPrivacyVar(lambdaId: string, lambdaVar: Map<string, Nullable<BaseAstNode>>): void;
     getFunctionDefinitionPrivacyVar(lambdaId: string): Nullable<Map<string, Nullable<BaseAstNode>>>;
+    markExternalReferenceUnavailable(): void;
     setRuntimeData(functionVariant: FunctionVariantType): void;
     getUnitData(): IRuntimeUnitDataType;
     getUnitArrayFormula(): IArrayFormulaRangeType;
@@ -130,6 +131,7 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     private readonly _hyperlinkEngineFormulaService;
     private _formulaExecuteStage;
     private _stopState;
+    private _externalReferenceUnavailable;
     private _currentRow;
     private _currentColumn;
     private _currentRowCount;
@@ -193,6 +195,7 @@ export declare class FormulaRuntimeService extends Disposable implements IFormul
     registerFunctionDefinitionPrivacyVar(lambdaId: string, lambdaVar: Map<string, Nullable<BaseAstNode>>): void;
     getFunctionDefinitionPrivacyVar(lambdaId: string): Nullable<Map<string, Nullable<BaseAstNode>>>;
     setRuntimeOtherData(formulaId: string, x: number, y: number, functionVariant: FunctionVariantType): void;
+    markExternalReferenceUnavailable(): void;
     setRuntimeData(functionVariant: FunctionVariantType): void;
     private _getValueObjectOfRuntimeData;
     getUnitData(): IRuntimeUnitDataType;

package/lib/types/services/sheet-row-filtered.service.d.ts

@@ -13,19 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { IDisposable } from '@univerjs/core';
 import { Disposable } from '@univerjs/core';
 type CallbackFunction = (unitId: string, subUnitId: string, row: number) => boolean;
 /**
  * The service that gets the row filter status
  */
 export interface ISheetRowFilteredService {
-    register(callback: CallbackFunction): void;
+    register(callback: CallbackFunction): IDisposable;
     getRowFiltered(unitId: string, subUnitId: string, row: number): boolean;
 }
 export declare class SheetRowFilteredService extends Disposable implements ISheetRowFilteredService {
-    private _getRowFilteredCallback;
-    register(callback: CallbackFunction): void;
+    private _getRowFilteredCallbacks;
+    register(callback: CallbackFunction): IDisposable;
     getRowFiltered(unitId: string, subUnitId: string, row: number): boolean;
+    dispose(): void;
 }
 export declare const ISheetRowFilteredService: import("@wendellhu/redi").IdentifierDecorator<ISheetRowFilteredService>;
 export {};

package/lib/types/services/unit-reference-resolver.service.d.ts

@@ -21,6 +21,8 @@ export interface IFormulaUnitReferenceResolveInput {
     hostUnitId: string;
     qualifier: string;
     referenceKind: FormulaUnitReferenceKind;
+    /** Called only when the source workbook cannot be resolved. */
+    onUnavailable?: () => void;
 }
 export interface IFormulaUnitReferenceResolution {
     unitId: string;
@@ -40,6 +42,6 @@ export declare function normalizeFormulaUnitName(name: string): string;
 export declare class FormulaUnitReferenceResolver implements IFormulaUnitReferenceResolver {
     protected readonly _currentConfigService: IFormulaCurrentConfigService;
     constructor(_currentConfigService: IFormulaCurrentConfigService);
-    resolve({ hostUnitId, qualifier, referenceKind, }: IFormulaUnitReferenceResolveInput): IFormulaUnitReferenceResolution | ErrorType;
+    resolve({ hostUnitId, qualifier, referenceKind, onUnavailable, }: IFormulaUnitReferenceResolveInput): IFormulaUnitReferenceResolution | ErrorType;
     private _validateReferenceKind;
 }