@univerjs-pro/engine-formula 1.0.0-alpha.2 → 1.0.0-alpha.4

package/lib/types/controllers/external-reference-resource.controller.d.ts

@@ -0,0 +1,6 @@
+import { Disposable, IResourceManagerService } from '@univerjs/core';
+import { ExternalReferenceOverlayModel } from '../models/external-reference-overlay.model';
+import { ExternalReferenceModel } from '../models/external-reference.model';
+export declare class ExternalReferenceResourceController extends Disposable {
+    constructor(resourceManagerService: IResourceManagerService, externalReferenceModel: ExternalReferenceModel, externalReferenceOverlayModel: ExternalReferenceOverlayModel);
+}

package/lib/types/controllers/formula-reference-data-rpc.controller.d.ts

@@ -0,0 +1,7 @@
+import { Disposable } from '@univerjs/core';
+import { IRPCChannelService } from '@univerjs/rpc';
+import { IFormulaReferenceDataService } from '../services/formula-reference-data.service';
+export declare const FORMULA_REFERENCE_DATA_RPC_CHANNEL = "univer-pro.formula.reference-data";
+export declare class FormulaReferenceDataRpcController extends Disposable {
+    constructor(rpcChannelService: IRPCChannelService, referenceDataService: IFormulaReferenceDataService);
+}

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

@@ -85,6 +85,7 @@ export declare class DependencyEngine {
      */
     reset(): void;
     encodeCell(unitId: string, sheetId: string, row: number, col: number): CellId;
+    reserveDependencyCapacity(minNodeCapacity: number, minRangeCapacity?: number): void;
     decodeCell(cell: CellId): IDecodedCell;
     encodeFeatureCalculationId(unitId: string, sheetId: string, formulaId: string): string;
     decodeFeatureCalculationId(id: ExternalNodeId): IDecodedFeatureCalculationId;
@@ -95,6 +96,12 @@ export declare class DependencyEngine {
         markDirty?: boolean;
         mode?: 'replace' | 'merge';
     }): ISetNodeResult;
+    setNewCellFormulaDeps(cell: CellId, deps: ICalcNodeDeps): ISetNodeResult;
+    setNewCellFormulaNodeOnly(cell: CellId): ISetNodeResult;
+    setNewCellFormulaNodeOnlyRange(unitId: string, sheetId: string, range: IRefRange['range'], skip?: {
+        row: number;
+        col: number;
+    }): CalcNodeIndex[];
     setOtherFormulaDeps(id: ExternalNodeId, deps: ICalcNodeDeps, options?: {
         checkCycle?: boolean;
         markDirty?: boolean;
@@ -279,7 +286,9 @@ export declare class DependencyEngine {
     private _isEmptyCalcNodeDeps;
     private _unregisterCompressedSharedFormulaGroupByNode;
     private _markCompressedSharedFormulaMembership;
+    private _markCompressedSharedFormulaMembershipByNodeIndices;
     private _clearCompressedSharedFormulaMembership;
+    private _clearCompressedSharedFormulaMembershipByNodeIndices;
     private _getCompressedSharedSourceCoverage;
     private _forEachCompressedSharedDependentByRange;
     private _forEachActiveCellFormulaInRange;
@@ -289,6 +298,7 @@ export declare class DependencyEngine {
     private _getCompressedSharedPrecedentCell;
     private _getCompressedSharedPrecedentRange;
     private _addNodeDepsOnly;
+    private _addNewNodeDepsOnly;
     private _removeNodeDepsOnly;
     private _collectDynamicResolveResult;
     private _addRuntimeDepsOnly;
@@ -297,6 +307,7 @@ export declare class DependencyEngine {
     private _detachPrecedentFromDependent;
     private _detachRuntimePrecedentFromDependent;
     private _addDirectEdge;
+    private _addDirectEdgeForNewNode;
     private _removeDirectEdge;
     private _addRuntimeDirectEdge;
     private _removeRuntimeDirectEdge;

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

@@ -14,6 +14,7 @@ export declare class FormulaCellIndex {
     private readonly _colBuckets;
     constructor(_codec: CellCodec, _indexToNodeId: ExternalNodeId[]);
     addFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
+    addFormulaCellByPosition(sheetKey: number, row: number, col: number, nodeIndex: CalcNodeIndex): void;
     removeFormulaCell(formulaCell: number, nodeIndex: CalcNodeIndex): void;
     forEachFormulaInRange(rangeInput: IRefRange, cb: (nodeIndex: CalcNodeIndex) => boolean | void): boolean;
     private _scanRows;

package/lib/types/engine/dependency-engine/range-index.d.ts

@@ -36,6 +36,7 @@ export declare class RangeIndex {
     private readonly _nodeToWholeColKeys;
     private readonly _nodeToWholeRowKeys;
     constructor(_codec: CellCodec, initialCapacity: number, _maxIndexedSpan: number);
+    reserveCapacity(minCapacity: number): void;
     addRange(nodeIndex: CalcNodeIndex, rangeInput: IRefRange): void;
     removeNode(nodeIndex: CalcNodeIndex): void;
     /**

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

@@ -109,6 +109,7 @@ export interface ICompressedSharedFormulaGroup {
     groupId: string;
     fillRange: IRefRange;
     patterns: ICompressedSharedFormulaPattern[];
+    memberNodeIndices?: CalcNodeIndex[];
 }
 export interface IDynamicDependency {
     id: DynamicDependencyId;

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

@@ -1,6 +1,6 @@
 import type { IUnitRange, Nullable } from '@univerjs/core';
 import type { BaseAstNode, IFormulaDataItem, IFormulaDependencyTree, IFormulaDependencyTreeJson, IUnitData } from '@univerjs/engine-formula';
-import type { DynamicResolver } from './dependency-engine';
+import type { DynamicResolver } from './dependency-engine/types';
 import type { ISharedFormulaCompressionMetrics } from './shared-formula-group-analyzer';
 import { FormulaDependencyGenerator, FormulaDependencyTree, FormulaDependencyTreeType } from '@univerjs/engine-formula';
 export interface IFormulaCalculationTree {
@@ -37,14 +37,14 @@ export declare class FormulaDependencyProGenerator extends FormulaDependencyGene
     clearCachedCalculationNodeData(): void;
     clearCachedCalculationTree(): void;
     getCachedCalculationNodeData(nodeIndex: number): IFormulaCalculationNodeData | undefined;
-    getCalculationOrder(): import("./dependency-engine").ICalculationOrderResult;
+    getCalculationOrder(): import("./dependency-engine/types").ICalculationOrderResult;
     getSharedFormulaCompressionMetrics(): ISharedFormulaCompressionMetrics;
     hasDynamicDepsByIndex(nodeIndex: number): boolean;
     refreshDynamicDepsByIndex(nodeIndex: number, resolver: DynamicResolver): boolean;
     hasUncalculatedDirtyPrecedentByIndex(nodeIndex: number, calculatedNodeIndices: ReadonlySet<number>): boolean;
     getAllDependencyJson(): Promise<IFormulaDependencyTreeJson[]>;
     generatePro(isCalculateTreeModel?: boolean): Promise<{
-        calculationOrderResult: import("./dependency-engine").ICalculationOrderResult;
+        calculationOrderResult: import("./dependency-engine/types").ICalculationOrderResult;
         dependencyTree: Map<number, IFormulaCalculationTree>;
     }>;
     /**
@@ -66,9 +66,12 @@ export declare class FormulaDependencyProGenerator extends FormulaDependencyGene
     private _normalizeSharedFormulaRange;
     private _recordCompressedSharedFormulaGroupMetrics;
     private _recordExpandedSharedFormulaGroupMetrics;
+    private _shouldEagerCacheCalculationTrees;
+    private _hasAnyDirtyMapValue;
     private _markDirtyDependenciesPro;
     private _markForcedRecalculationNodesPro;
     private _markDirtyDefinedNameDependenciesPro;
+    private _markDirtySuperTableDependenciesPro;
     private _cacheCalculationTree;
     private _cacheCompressedVirtualCalculationTree;
     private _getOffsetRangeList;
@@ -78,13 +81,36 @@ export declare class FormulaDependencyProGenerator extends FormulaDependencyGene
     private _releaseDependencyTree;
     private _hasDirtyDefinedNames;
     private _syncForcedRecalculationNodeIndex;
-    private _syncCompressedVirtualForcedRecalculationNodeIndex;
+    private _hasForcedRecalculationFunction;
     private _detectForcedRecalculationNodePro;
     private _includeDirtyDefinedNamePro;
+    private _includeDirtySuperTablePro;
     private _ensureTreeInitializedForDependencies;
-    private _ensureTreeNodeForCalculation;
     private _getFeatureFormulaDependencyNodes;
     private _rangesIntersectAny;
     private _initialAstNodeAndRanges;
+    private _initialDependencyRanges;
+    private _tryInitialStaticReferenceRanges;
+    private _replaceDoubleQuotedStrings;
+    private _replaceQuotedSheetNames;
+    private _hasOnlyStaticReferenceSafeIdentifiers;
+    private _looksLikeA1ReferenceAt;
+    private _looksLikeColumnReferencePart;
+    private _isStaticReferenceTokenBoundarySafe;
+    private _tryCreateStaticReferenceRange;
+    private _tryCreateStaticColumnReferenceRange;
+    private _tryExtractStaticOffsetRanges;
+    private _tryCreateStaticOffsetRange;
+    private _tryInferOffsetRowSpan;
+    private _tryInferPositiveInteger;
+    private _tryParseInteger;
+    private _tryParseSingleStaticReference;
+    private _extractFunctionCalls;
+    private _findMatchingParen;
+    private _splitTopLevelArguments;
+    private _getStaticReferenceSheetSize;
+    private _dedupeStaticReferenceRanges;
+    private _columnNameToIndex;
+    private _nextNonSpaceChar;
     protected _createFDtree(unitId: string, sheetId: string, row: number, column: number, unitData: IUnitData, formulaDataItem: IFormulaDataItem): FormulaDependencyTree;
 }

package/lib/types/index.d.ts

@@ -1,5 +1,23 @@
-export { FormulaDependencyProGenerator } from './engine/formula-dependency';
+export { ExternalReferenceDataProvidersController } from './controllers/external-reference-data-providers.controller';
+export { ExternalReferenceRenameController } from './controllers/external-reference-rename.controller';
+export { ExternalReferenceResourceController } from './controllers/external-reference-resource.controller';
+export { FORMULA_REFERENCE_DATA_RPC_CHANNEL, FormulaReferenceDataRpcController } from './controllers/formula-reference-data-rpc.controller';
+export { ExternalReferenceOverlayModel } from './models/external-reference-overlay.model';
+export type { IExternalOverlayCellState } from './models/external-reference-overlay.model';
+export { createEmptyExternalReferenceResource, createExternalSyntheticUnitId, EXTERNAL_REFERENCE_SCHEMA_VERSION, ExternalReferenceModel, SHEET_EXTERNAL_DATA_PLUGIN, } from './models/external-reference.model';
+export type { ExternalReferenceBindingResult, IExternalReferenceCachedCell, IExternalReferenceCachedSheet, IExternalReferenceCoverage, IExternalReferenceLink, IExternalReferenceResource, IExternalReferenceTable, IExternalReferenceTableColumn, } from './models/external-reference.model';
 export { UniverProFormulaEnginePlugin } from './plugin';
-export { CalculateFormulaProService } from './services/calculate-formula.service';
-export { DependencyManagerProService } from './services/dependency-manager.service';
-export * from '@univerjs/engine-formula';
+export { ExternalCacheReferenceDataProvider } from './services/external-cache-reference-data.provider';
+export { ExternalReferencePrefetchPlanner } from './services/external-reference-prefetch-planner';
+export { ExternalReferencePrefetchService } from './services/external-reference-prefetch.service';
+export type { IExternalReferencePrefetchLimits, IExternalReferencePrefetchResult, } from './services/external-reference-prefetch.service';
+export { ExternalFormulaUnitReferenceResolver } from './services/external-unit-reference-resolver.service';
+export { createUnavailableReferenceDataResponse, FormulaReferenceDataProviderRegistry, IFormulaReferenceDataProviderRegistry, IFormulaReferenceDataService, } from './services/formula-reference-data.service';
+export type { FormulaReferenceDataFreshness, FormulaReferenceDataSource, IFormulaReferenceDataCell, IFormulaReferenceDataProvider, IFormulaReferenceDataRangeRequest, IFormulaReferenceDataRequest, IFormulaReferenceDataResponse, IFormulaReferenceDataSheet, } from './services/formula-reference-data.service';
+export { MainFormulaReferenceDataService } from './services/main-formula-reference-data.service';
+export { RemoveSuperTableMutation, SetFormulaCalculationResultMutation, SetFormulaCalculationStartMutation, SetSuperTableMutation, SetTriggerFormulaCalculationStartMutation, } from '@univerjs/engine-formula';
+export type { ISetFormulaCalculationResultMutation, ISetFormulaCalculationStartMutation, ISuperTable, } from '@univerjs/engine-formula';
+export { SetFormulaDataMutation } from '@univerjs/engine-formula';
+export { refactorFormulaUnitQualifier } from '@univerjs/engine-formula';
+export type { IUniverEngineFormulaConfig } from '@univerjs/engine-formula';
+export { FormulaCalculationTriggerService, FormulaDataModel, IActiveDirtyManagerService, ISuperTableService, } from '@univerjs/engine-formula';

package/lib/types/models/external-reference-overlay.model.d.ts

@@ -0,0 +1,41 @@
+import type { IRange, IUnitRange } from '@univerjs/core';
+import type { IFormulaDatasetConfig } from '@univerjs/engine-formula';
+import type { IFormulaReferenceDataRequest, IFormulaReferenceDataResponse } from '../services/formula-reference-data.service';
+import { Disposable } from '@univerjs/core';
+import { ISuperTableService } from '@univerjs/engine-formula';
+import { ExternalReferenceModel } from './external-reference.model';
+export interface IExternalOverlayCellState {
+    covered: boolean;
+    value: unknown;
+}
+export declare class ExternalReferenceOverlayModel extends Disposable {
+    private readonly _externalReferenceModel;
+    private readonly _superTableService;
+    private readonly _units;
+    private readonly _pendingDirtyRanges;
+    constructor(_externalReferenceModel: ExternalReferenceModel, _superTableService: ISuperTableService);
+    apply(request: IFormulaReferenceDataRequest, response: IFormulaReferenceDataResponse): Array<{
+        sheetId: string;
+        range: IRange;
+    }>;
+    materialize(config: IFormulaDatasetConfig): void;
+    getCellState(unitId: string, sheetId: string, row: number, column: number): IExternalOverlayCellState;
+    isRangeCovered(unitId: string, sheetNameOrId: string | undefined, range: IRange): boolean;
+    enforceLimits(maxCells: number, maxBytes: number): number;
+    invalidateHost(hostUnitId: string): IUnitRange[];
+    invalidateSyntheticUnit(unitId: string): IUnitRange[];
+    invalidateSourceRange(targetUnitIdOrName: string, sheetNameOrId: string, range: IRange): IUnitRange[];
+    invalidateSourceMetadata(targetUnitIdOrName: string): IUnitRange[];
+    drainDirtyRanges(): IUnitRange[];
+    getUnitCount(): number;
+    dispose(): void;
+    private _unitRanges;
+    private _queueDirty;
+    private _mergeSheet;
+    private _oldestCoverage;
+    private _coveredCellCount;
+    private _estimatedBytes;
+    private _writeCoverageMisses;
+    private _createUnavailableSheets;
+    private _registerTables;
+}

package/lib/types/models/external-reference.model.d.ts

@@ -0,0 +1,91 @@
+import type { FormulaUnitType } from '@univerjs/engine-formula';
+import { Disposable } from '@univerjs/core';
+export declare const SHEET_EXTERNAL_DATA_PLUGIN = "SHEET_EXTERNAL_DATA_PLUGIN";
+export declare const EXTERNAL_REFERENCE_SCHEMA_VERSION: 1;
+export interface IExternalReferenceCoverage {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+}
+export interface IExternalReferenceCachedCell {
+    row: number;
+    column: number;
+    value: unknown;
+    valueType?: number;
+}
+export interface IExternalReferenceCachedSheet {
+    name: string;
+    sheetId?: string;
+    rowCount?: number;
+    columnCount?: number;
+    coverage: IExternalReferenceCoverage[];
+    cells: IExternalReferenceCachedCell[];
+}
+export interface IExternalReferenceTableColumn {
+    id?: string;
+    name: string;
+}
+export interface IExternalReferenceTable {
+    id?: string;
+    name: string;
+    sheetName?: string;
+    columns: IExternalReferenceTableColumn[];
+    range?: IExternalReferenceCoverage;
+    /** Base virtual tables start with records at row 0; Sheet tables default to a physical header. */
+    showHeader?: boolean;
+}
+export interface IExternalReferenceLink {
+    /** Host-local OOXML slot. Slots are one-based and order is preserved. */
+    slot: number;
+    name: string;
+    target: {
+        name: string;
+        unitType: FormulaUnitType;
+        uri?: string;
+        liveUnitId?: string;
+    };
+    sheetNames: Array<{
+        name: string;
+        sheetId?: string;
+    }>;
+    definedNames: Array<{
+        name: string;
+        formulaOrRefString: string;
+    }>;
+    tables: IExternalReferenceTable[];
+    cache?: {
+        revision?: string;
+        freshness: 'fresh' | 'stale';
+        complete: boolean;
+        sheets: IExternalReferenceCachedSheet[];
+    };
+}
+export interface IExternalReferenceResource {
+    schemaVersion: typeof EXTERNAL_REFERENCE_SCHEMA_VERSION;
+    links: IExternalReferenceLink[];
+}
+export type ExternalReferenceBindingResult = {
+    status: 'resolved';
+    link: IExternalReferenceLink;
+} | {
+    status: 'missing' | 'ambiguous';
+};
+export declare function createEmptyExternalReferenceResource(): IExternalReferenceResource;
+export declare function createExternalSyntheticUnitId(hostUnitId: string, slot: number): string;
+export declare class ExternalReferenceModel extends Disposable {
+    private readonly _resources;
+    private readonly _loadErrors;
+    load(hostUnitId: string, value: unknown): boolean;
+    set(hostUnitId: string, resource: IExternalReferenceResource): boolean;
+    serialize(hostUnitId: string): IExternalReferenceResource;
+    get(hostUnitId: string): IExternalReferenceResource | undefined;
+    getLoadError(hostUnitId: string): 'invalid-resource' | 'unsupported-version' | undefined;
+    resolveBinding(hostUnitId: string, qualifier: string): ExternalReferenceBindingResult;
+    renameLiveTarget(unitId: string, oldName: string, newName: string): Array<{
+        hostUnitId: string;
+        slot: number;
+    }>;
+    remove(hostUnitId: string): void;
+    dispose(): void;
+}

package/lib/types/plugin.d.ts

@@ -1,6 +1,14 @@
+import type { Dependency } from '@univerjs/core';
 import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
 export declare class UniverProFormulaEnginePlugin extends UniverFormulaEnginePlugin {
     static packageName: string;
     static version: string;
+    /**
+     * Allows execution backends to replace individual formula services before
+     * they are registered. Keeping one registration pass avoids duplicate DI
+     * bindings when a backend only swaps the calculator.
+     */
+    protected _extendFormulaExecutionDependencies(_dependencies: Dependency[]): void;
     protected _initializeWithOverride(): void;
+    onReady(): void;
 }

package/lib/types/services/calculate-formula.service.d.ts

@@ -1,14 +1,25 @@
 import type { IFormulaDatasetConfig } from '@univerjs/engine-formula';
-import type { CalcNodeIndex, DynamicResolver, ICalculationOrderResult } from '../engine/dependency-engine';
+import type { CalcNodeIndex, DynamicResolver, ICalculationOrderResult } from '../engine/dependency-engine/types';
 import type { IFormulaCalculationTree } from '../engine/formula-dependency';
-import { CalculateFormulaService } from '@univerjs/engine-formula';
+import { IConfigService } from '@univerjs/core';
+import { AstTreeBuilder, CalculateFormulaService, IFormulaCurrentConfigService, IFormulaDependencyGenerator, IFormulaRuntimeService, Interpreter, Lexer } from '@univerjs/engine-formula';
+import { ExternalReferencePrefetchPlanner } from './external-reference-prefetch-planner';
+import { ExternalReferencePrefetchService } from './external-reference-prefetch.service';
 export declare class CalculateFormulaProService extends CalculateFormulaService {
+    private readonly _externalPrefetchPlanner;
+    private readonly _externalPrefetchService;
     private _dynamicRuntimeRanges;
+    private _externalFormulaDatasetConfig;
+    private _externalPrefetchedNodes;
+    constructor(configService: IConfigService, lexer: Lexer, currentConfigService: IFormulaCurrentConfigService, runtimeService: IFormulaRuntimeService, formulaDependencyGenerator: IFormulaDependencyGenerator, interpreter: Interpreter, astTreeBuilder: AstTreeBuilder, _externalPrefetchPlanner: ExternalReferencePrefetchPlanner, _externalPrefetchService: ExternalReferencePrefetchService);
     execute(formulaDatasetConfig: IFormulaDatasetConfig): Promise<void>;
     protected _executeStep(cycleReferenceCount?: number): Promise<true | undefined>;
     protected _apply(isArrayFormulaState?: boolean, cycleReferenceCount?: number): Promise<import("@univerjs/engine-formula").IAllRuntimeData | undefined>;
+    private _setFormulaExecuteStage;
+    private _setTotalFormulasToCalculate;
     private _shouldRescheduleAfterDynamicChange;
-    protected _forEachCalculationPlanTree(calculationOrderResult: Pick<ICalculationOrderResult, 'calculationForest'>, dependencyTree: Map<CalcNodeIndex, IFormulaCalculationTree>, cycleReferenceCount: number, visitor: (tree: IFormulaCalculationTree, nodeIndex: CalcNodeIndex, cycleIndex?: number) => Promise<boolean | void>): Promise<void>;
+    protected _forEachCalculationPlanTree(calculationOrderResult: Pick<ICalculationOrderResult, 'calculationForest'>, dependencyTree: Map<CalcNodeIndex, IFormulaCalculationTree>, cycleReferenceCount: number, visitor: (tree: IFormulaCalculationTree, nodeIndex: CalcNodeIndex, cycleIndex?: number, shouldPreserveCycleTree?: boolean) => Promise<boolean | void>): Promise<void>;
+    private _calculationPlanHasSelfReference;
     protected _getCalculationPlanTreeCount(calculationOrderResult: Pick<ICalculationOrderResult, 'calculationForest'>, dependencyTree: Map<CalcNodeIndex, IFormulaCalculationTree>, cycleReferenceCount: number): number;
     protected _getDynamicResolver(): DynamicResolver | undefined;
     private _refreshDynamicDepsAfterCalculate;
@@ -17,5 +28,11 @@ export declare class CalculateFormulaProService extends CalculateFormulaService
     private _getRangeSignature;
     private _waitForExecutionSlot;
     private _calculateDependencyTree;
+    private _prefetchDynamicExternalReferences;
+    private _collectAddressFunctionRuntimeReferences;
+    private _setFunctionRefInfoForTree;
+    private _formulaReferencesTreeCell;
+    private _isReferenceMetadataFunctionArgument;
+    private _parseA1Reference;
     private _getCalculationNodeData;
 }

package/lib/types/services/dependency-manager.service.d.ts

@@ -1,6 +1,6 @@
 import type { IUnitRange } from '@univerjs/core';
 import type { FormulaDependencyTree, IDirtyUnitFeatureMap, IDirtyUnitOtherFormulaMap, IDirtyUnitSheetNameMap, IFormulaDependencyTree } from '@univerjs/engine-formula';
-import type { DynamicResolver, ICalcNodeRef, ICompressedSharedFormulaGroup } from '../engine/dependency-engine';
+import type { DynamicResolver, ICalcNodeRef, ICompressedSharedFormulaGroup } from '../engine/dependency-engine/types';
 import { DependencyManagerBaseService } from '@univerjs/engine-formula';
 export declare class DependencyManagerProService extends DependencyManagerBaseService {
     private _dependencyEngineCache;
@@ -16,8 +16,13 @@ export declare class DependencyManagerProService extends DependencyManagerBaseSe
     clearFeatureFormulaDependency(unitId: string, sheetId?: string): void;
     getFeatureFormulaDependencyPro(unitId: string, sheetId: string, featureId: string): number | undefined;
     getFeatureFormulaDependencyNodePro(unitId: string, sheetId: string, featureId: string): ICalcNodeRef;
+    reserveFormulaDependencyCapacity(minNodeCapacity: number, minRangeCapacity?: number): void;
     addFormulaDependencyPro(unitId: string, sheetId: string, row: number, column: number, dependencyTree: IFormulaDependencyTree, featureNodes?: ICalcNodeRef[], mode?: 'replace' | 'merge'): number;
     addFormulaDependencyNodeOnlyPro(unitId: string, sheetId: string, row: number, column: number): number;
+    addFormulaDependencyNodeOnlyRangePro(unitId: string, sheetId: string, range: IUnitRange['range'], skip?: {
+        row: number;
+        col: number;
+    }): number[];
     registerCompressedSharedFormulaGroup(group: ICompressedSharedFormulaGroup): void;
     clearCompressedSharedFormulaGroups(unitId?: string, sheetId?: string): void;
     removeFormulaDependency(unitId: string, sheetId: string, row: number, column: number): void;
@@ -45,5 +50,5 @@ export declare class DependencyManagerProService extends DependencyManagerBaseSe
     prepareDynamicDependencies(resolver: DynamicResolver): boolean;
     getCalculationOrder(options?: {
         detectCycles?: boolean;
-    }): import("../engine/dependency-engine").ICalculationOrderResult;
+    }): import("../engine/dependency-engine/types").ICalculationOrderResult;
 }

package/lib/types/services/external-cache-reference-data.provider.d.ts

@@ -0,0 +1,10 @@
+import type { IFormulaReferenceDataProvider, IFormulaReferenceDataRequest, IFormulaReferenceDataResponse } from './formula-reference-data.service';
+import { ExternalReferenceModel } from '../models/external-reference.model';
+export declare class ExternalCacheReferenceDataProvider implements IFormulaReferenceDataProvider {
+    private readonly _externalReferenceModel;
+    readonly id = "ooxml-external-cache";
+    readonly priority = -100;
+    constructor(_externalReferenceModel: ExternalReferenceModel);
+    canRead(request: IFormulaReferenceDataRequest): boolean;
+    readData(request: IFormulaReferenceDataRequest): Promise<IFormulaReferenceDataResponse | undefined>;
+}

package/lib/types/services/external-reference-prefetch-planner.d.ts

@@ -0,0 +1,18 @@
+import type { IFormulaDatasetConfig } from '@univerjs/engine-formula';
+import type { IFormulaReferenceDataRangeRequest, IFormulaReferenceDataRequest } from './formula-reference-data.service';
+import { ExternalReferenceModel } from '../models/external-reference.model';
+export declare class ExternalReferencePrefetchPlanner {
+    private readonly _externalReferenceModel;
+    private _calculationCounter;
+    private _requestCounter;
+    constructor(_externalReferenceModel: ExternalReferenceModel);
+    plan(config: IFormulaDatasetConfig): IFormulaReferenceDataRequest[];
+    planDynamic(hostUnitId: string, references: Array<{
+        unitId: string;
+        sheetName: string;
+        range: IFormulaReferenceDataRangeRequest['range'];
+    }>): IFormulaReferenceDataRequest[];
+    private _collectA1;
+    private _collectTables;
+    private _addRange;
+}

package/lib/types/services/external-reference-prefetch.service.d.ts

@@ -0,0 +1,38 @@
+import type { IUnitRange } from '@univerjs/core';
+import type { IFormulaDatasetConfig } from '@univerjs/engine-formula';
+import type { IFormulaReferenceDataRequest, IFormulaReferenceDataResponse } from './formula-reference-data.service';
+import { Disposable } from '@univerjs/core';
+import { FormulaDataModel } from '@univerjs/engine-formula';
+import { ExternalReferenceOverlayModel } from '../models/external-reference-overlay.model';
+import { IFormulaReferenceDataService } from './formula-reference-data.service';
+export interface IExternalReferencePrefetchLimits {
+    maxCells: number;
+    maxBytes: number;
+    concurrency: number;
+    timeoutMs: number;
+}
+export interface IExternalReferencePrefetchResult {
+    responses: IFormulaReferenceDataResponse[];
+    dirtyRanges: Array<{
+        unitId: string;
+        sheetId: string;
+        range: NonNullable<IFormulaReferenceDataRequest['ranges'][number]['range']>;
+    }>;
+    discarded: number;
+}
+export declare class ExternalReferencePrefetchService extends Disposable {
+    private readonly _referenceDataService;
+    private readonly _overlayModel;
+    private readonly _formulaDataModel;
+    private readonly _inflight;
+    private readonly _latestCalculation;
+    constructor(_referenceDataService: IFormulaReferenceDataService, _overlayModel: ExternalReferenceOverlayModel, _formulaDataModel: FormulaDataModel);
+    prefetch(requests: IFormulaReferenceDataRequest[], config: IFormulaDatasetConfig, limits?: Partial<IExternalReferencePrefetchLimits>): Promise<IExternalReferencePrefetchResult>;
+    cancelHost(hostUnitId: string, nextCalculationId: string): void;
+    getInflightCount(): number;
+    drainDirtyRanges(): IUnitRange[];
+    dispose(): void;
+    private _hydrateLiveUnits;
+    private _hasWorkerLiveUnit;
+    private _readWithInflight;
+}

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

@@ -0,0 +1,8 @@
+import type { IFormulaUnitReferenceResolution, IFormulaUnitReferenceResolveInput } from '@univerjs/engine-formula';
+import { ErrorType, FormulaUnitReferenceResolver, IFormulaCurrentConfigService } from '@univerjs/engine-formula';
+import { ExternalReferenceModel } from '../models/external-reference.model';
+export declare class ExternalFormulaUnitReferenceResolver extends FormulaUnitReferenceResolver {
+    private readonly _externalReferenceModel;
+    constructor(currentConfigService: IFormulaCurrentConfigService, _externalReferenceModel: ExternalReferenceModel);
+    resolve(input: IFormulaUnitReferenceResolveInput): IFormulaUnitReferenceResolution | ErrorType;
+}

package/lib/types/services/formula-reference-data.service.d.ts

@@ -0,0 +1,71 @@
+import type { ICellData, IDisposable, IRange } from '@univerjs/core';
+import type { FormulaUnitType } from '@univerjs/engine-formula';
+import { Disposable } from '@univerjs/core';
+export type FormulaReferenceDataSource = 'worker-live' | 'main-live' | 'provider' | 'ooxml-cache' | 'unavailable';
+export type FormulaReferenceDataFreshness = 'fresh' | 'stale' | 'unavailable';
+export interface IFormulaReferenceDataRangeRequest {
+    sheetName?: string;
+    sheetId?: string;
+    tableName?: string;
+    range?: IRange;
+}
+export interface IFormulaReferenceDataRequest {
+    requestId: string;
+    calculationId: string;
+    hostUnitId: string;
+    bindingSlot: number;
+    syntheticUnitId: string;
+    target: {
+        name: string;
+        unitType: FormulaUnitType;
+        uri?: string;
+        liveUnitId?: string;
+    };
+    ranges: IFormulaReferenceDataRangeRequest[];
+    /** Defaults to true. Set false only when the caller explicitly accepts cached stale values. */
+    requireFresh?: boolean;
+}
+export interface IFormulaReferenceDataCell {
+    row: number;
+    column: number;
+    cell: ICellData;
+}
+export interface IFormulaReferenceDataSheet {
+    name: string;
+    sheetId: string;
+    rowCount: number;
+    columnCount: number;
+    coverage: IRange[];
+    cells: IFormulaReferenceDataCell[];
+}
+export interface IFormulaReferenceDataResponse {
+    requestId: string;
+    calculationId: string;
+    source: FormulaReferenceDataSource;
+    freshness: FormulaReferenceDataFreshness;
+    revision?: string;
+    sheets: IFormulaReferenceDataSheet[];
+    error?: '#N/A' | '#REF!' | '#CYCLE!';
+}
+export interface IFormulaReferenceDataService {
+    readData(request: IFormulaReferenceDataRequest): Promise<IFormulaReferenceDataResponse>;
+}
+export declare const IFormulaReferenceDataService: import("@wendellhu/redi").IdentifierDecorator<IFormulaReferenceDataService>;
+export interface IFormulaReferenceDataProvider {
+    readonly id: string;
+    readonly priority?: number;
+    canRead(request: IFormulaReferenceDataRequest): boolean;
+    readData(request: IFormulaReferenceDataRequest): Promise<IFormulaReferenceDataResponse | undefined>;
+}
+export interface IFormulaReferenceDataProviderRegistry {
+    register(provider: IFormulaReferenceDataProvider): IDisposable;
+    getProviders(request: IFormulaReferenceDataRequest): IFormulaReferenceDataProvider[];
+}
+export declare const IFormulaReferenceDataProviderRegistry: import("@wendellhu/redi").IdentifierDecorator<IFormulaReferenceDataProviderRegistry>;
+export declare class FormulaReferenceDataProviderRegistry extends Disposable implements IFormulaReferenceDataProviderRegistry {
+    private readonly _providers;
+    register(provider: IFormulaReferenceDataProvider): IDisposable;
+    getProviders(request: IFormulaReferenceDataRequest): IFormulaReferenceDataProvider[];
+    dispose(): void;
+}
+export declare function createUnavailableReferenceDataResponse(request: IFormulaReferenceDataRequest, error?: '#N/A' | '#REF!' | '#CYCLE!'): IFormulaReferenceDataResponse;

package/lib/types/services/main-formula-reference-data.service.d.ts

@@ -0,0 +1,12 @@
+import type { IFormulaReferenceDataRequest, IFormulaReferenceDataResponse, IFormulaReferenceDataService } from './formula-reference-data.service';
+import { FormulaDataModel, ISuperTableService } from '@univerjs/engine-formula';
+import { IFormulaReferenceDataProviderRegistry } from './formula-reference-data.service';
+export declare class MainFormulaReferenceDataService implements IFormulaReferenceDataService {
+    private readonly _formulaDataModel;
+    private readonly _superTableService;
+    private readonly _providerRegistry;
+    constructor(_formulaDataModel: FormulaDataModel, _superTableService: ISuperTableService, _providerRegistry: IFormulaReferenceDataProviderRegistry);
+    readData(request: IFormulaReferenceDataRequest): Promise<IFormulaReferenceDataResponse>;
+    private _readLiveSheets;
+    private _resolveLiveRange;
+}

package/lib/umd/facade.js

@@ -1 +1 @@
-function _0xae46(_0xc61b3b,_0x1ab20f){_0xc61b3b=_0xc61b3b-0x14b;var _0x6d171a=_0x6d17();var _0xae4607=_0x6d171a[_0xc61b3b];return _0xae4607;}(function(_0x5c68b1,_0x3aa87b){var _0x191e94=_0xae46,_0x201c42=_0x5c68b1();while(!![]){try{var _0x27ed55=-parseInt(_0x191e94(0x156))/0x1*(-parseInt(_0x191e94(0x14f))/0x2)+parseInt(_0x191e94(0x152))/0x3+parseInt(_0x191e94(0x15b))/0x4+-parseInt(_0x191e94(0x155))/0x5*(parseInt(_0x191e94(0x160))/0x6)+-parseInt(_0x191e94(0x15f))/0x7*(-parseInt(_0x191e94(0x14d))/0x8)+-parseInt(_0x191e94(0x153))/0x9*(-parseInt(_0x191e94(0x14b))/0xa)+-parseInt(_0x191e94(0x158))/0xb;if(_0x27ed55===_0x3aa87b)break;else _0x201c42['push'](_0x201c42['shift']());}catch(_0x278375){_0x201c42['push'](_0x201c42['shift']());}}}(_0x6d17,0x85e2f),function(_0x1b2c38,_0x3152c2){var _0x27aea4=_0xae46;typeof exports==_0x27aea4(0x154)&&typeof module<'u'?_0x3152c2(exports,require('@univerjs/engine-formula/facade')):typeof define==_0x27aea4(0x15a)&&define[_0x27aea4(0x14c)]?define([_0x27aea4(0x14e),_0x27aea4(0x157)],_0x3152c2):(_0x1b2c38=typeof globalThis<'u'?globalThis:_0x1b2c38||self,_0x3152c2(_0x1b2c38[_0x27aea4(0x159)]={},_0x1b2c38[_0x27aea4(0x151)]));}(this,function(_0x46a933,_0x1e51ca){var _0xd43bb1=_0xae46;Object[_0xd43bb1(0x15c)](_0x46a933,Symbol[_0xd43bb1(0x150)],{'value':_0xd43bb1(0x15d)}),Object[_0xd43bb1(0x15c)](_0x46a933,_0xd43bb1(0x15e),{'enumerable':!0x0,'get':function(){var _0x5662e6=_0xd43bb1;return _0x1e51ca[_0x5662e6(0x15e)];}});}));function _0x6d17(){var _0x22ea04=['561406zqfEYm','toStringTag','UniverEngineFormulaFacade','1173423eyILoy','16857qIpbGf','object','15scIOZG','2gNUvgy','@univerjs/engine-formula/facade','17198313BrgCsR','UniverProEngineFormulaFacade','function','3258360QDYMiE','defineProperty','Module','FFormula','4360748GqbHEx','1807602jcgDrf','3340yVmibu','amd','8DrQXMU','exports'];_0x6d17=function(){return _0x22ea04;};return _0x6d17();}
+(function(_0x30d002,_0x1c7b8b){var _0x4a4ad8=_0x6e44,_0x296f80=_0x30d002();while(!![]){try{var _0xf5e00e=-parseInt(_0x4a4ad8(0x1e3))/0x1*(parseInt(_0x4a4ad8(0x1e5))/0x2)+-parseInt(_0x4a4ad8(0x1ea))/0x3+-parseInt(_0x4a4ad8(0x1e6))/0x4+-parseInt(_0x4a4ad8(0x1e7))/0x5+parseInt(_0x4a4ad8(0x1e1))/0x6+-parseInt(_0x4a4ad8(0x1e2))/0x7+parseInt(_0x4a4ad8(0x1ec))/0x8;if(_0xf5e00e===_0x1c7b8b)break;else _0x296f80['push'](_0x296f80['shift']());}catch(_0x10d9ff){_0x296f80['push'](_0x296f80['shift']());}}}(_0xd1dd,0xa8f2d),function(_0x27da3d,_0x5d4420){var _0x5f4928=_0x6e44;typeof exports=='object'&&typeof module<'u'?_0x5d4420(exports,require('@univerjs/engine-formula/facade')):typeof define=='function'&&define['amd']?define(['exports','@univerjs/engine-formula/facade'],_0x5d4420):(_0x27da3d=typeof globalThis<'u'?globalThis:_0x27da3d||self,_0x5d4420(_0x27da3d['UniverProEngineFormulaFacade']={},_0x27da3d[_0x5f4928(0x1e4)]));}(this,function(_0x1f2103,_0xebe3c1){var _0x8b67fa=_0x6e44;Object[_0x8b67fa(0x1e8)](_0x1f2103,Symbol[_0x8b67fa(0x1e0)],{'value':_0x8b67fa(0x1eb)}),Object[_0x8b67fa(0x1e8)](_0x1f2103,_0x8b67fa(0x1e9),{'enumerable':!0x0,'get':function(){var _0x3e5faa=_0x8b67fa;return _0xebe3c1[_0x3e5faa(0x1e9)];}});}));function _0x6e44(_0x55216e,_0x33ca1b){_0x55216e=_0x55216e-0x1e0;var _0xd1dd60=_0xd1dd();var _0x6e444a=_0xd1dd60[_0x55216e];return _0x6e444a;}function _0xd1dd(){var _0x540c1c=['8381198wJUsGM','69583ywNHdH','UniverEngineFormulaFacade','32iTFTTc','4135028dTVsVo','6286820LzVkIY','defineProperty','FFormula','2264994mAcQEQ','Module','37601096teeTQJ','toStringTag','8091822krKGqk'];_0xd1dd=function(){return _0x540c1c;};return _0xd1dd();}