← All packages

API reference

@searsuite/sear-domain-formula-engine

Host-neutral formula values, evaluation contracts, registries, references, and external-service boundaries.

175 exportsderived from source

namespaceIAggregationCachesource ↗
IAggregationCache: unknown
variablesymbol
symbol: typeof symbol
namespaceIDependencyGraphsource ↗
IDependencyGraph: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaCalculationTraceProvidersource ↗
IFormulaCalculationTraceProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for resolving IFormulaCalculationTraceProvider.

namespaceIFormulaDateSystemProvidersource ↗
IFormulaDateSystemProvider: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaEvaluatorsource ↗
IFormulaEvaluator: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaExternalServiceProvidersource ↗
IFormulaExternalServiceProvider: unknown
variablesymbol
symbol: symbol
namespaceIFormulaIterationSettingsProvidersource ↗
IFormulaIterationSettingsProvider: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaLocaleProvidersource ↗
IFormulaLocaleProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for resolving IFormulaLocaleProvider.

namespaceIFormulaParsersource ↗
IFormulaParser: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaResultProvidersource ↗
IFormulaResultProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for resolving IFormulaResultProvider.

namespaceIFormulaRichResultProvidersource ↗
IFormulaRichResultProvider: unknown
variablesymbol
symbol: typeof symbol
namespaceIFormulaSourceProvidersource ↗
IFormulaSourceProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for resolving IFormulaSourceProvider.

namespaceIFormulaStatusProvidersource ↗
IFormulaStatusProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for resolving IFormulaStatusProvider.

namespaceIFormulaTextServiceProvidersource ↗
IFormulaTextServiceProvider: unknown
variablesymbol
symbol: typeof symbol

DI token for host adapters that supply text-formula services.

namespaceIFunctionRegistrysource ↗
IFunctionRegistry: unknown
variablesymbol
symbol: typeof symbol
classFormulaFunctionArgumentssource ↗
class FormulaFunctionArguments

Public coercion and argument-reading SDK for built-in and third-party formula functions.

constructorconstructor
FormulaFunctionArguments(args: readonly FormulaArg[], context: EvalContext): FormulaFunctionArguments
args: readonly FormulaArg[]
context: EvalContext
methodboolean
boolean(index: number, fallback?: boolean): boolean | FormulaError

Reads a boolean argument from booleans, numbers, or TRUE/FALSE text.

index: number
fallback: boolean
methodinteger
integer(index: number, fallback?: number): number | FormulaError

Reads a truncated integer argument.

index: number
fallback: number
methodisMissing
isMissing(index: number): boolean

Returns whether an argument was omitted.

index: number
methodnumber
number(index: number, fallback?: number): number | FormulaError

Reads and coerces one argument to a finite number.

index: number
fallback: number
methodreference
reference(index: number): FormulaError | ResolvedFormulaRange

Reads a reference argument without materializing it.

index: number
methodtext
text(index: number, fallback?: string): string | FormulaError

Reads and coerces one argument to text using spreadsheet-compatible scalar rules.

index: number
fallback: string
methodvalue
value(index: number): FormulaValue

Reads one scalar argument while preserving formula errors.

index: number
interfaceCellChangesource ↗
interface CellChange

Value transition for one formula-visible cell.

propertycol
col: number
propertykey
key: number
propertynewVal
newVal: FormulaValue
propertyoldVal
oldVal: FormulaValue
propertyrow
row: number
interfaceEvalContextsource ↗
interface EvalContext

Host-provided services and data readers used during formula evaluation.

propertyaggregationCache
aggregationCache?: IAggregationCache
propertyarrayFormulaMode
arrayFormulaMode?: "dynamic" | "legacy"
propertybudget
budget?: FormulaEvaluationBudget
propertycurrentCell
currentCell?: FormulaCellPosition
propertydateSystem
dateSystem?: FormulaDateSystem
propertydateTimeLocale
dateTimeLocale?: FormulaDateTimeLocale
propertyexternalServices
externalServices?: FormulaExternalServiceReader
propertyformulaSource
formulaSource?: IFormulaSourceProvider
propertylanguageService
languageService?: FormulaLanguageService
propertymetadata
metadata?: FormulaMetadataReader
propertyphoneticReader
phoneticReader?: FormulaPhoneticReader
propertyreferenceResolver
referenceResolver?: FormulaReferenceResolver
propertyregisterDynamicDependency
registerDynamicDependency?: FormulaDynamicDependencyRegistrar
propertyscope
scope?: FormulaEvaluationScope
propertytextLocale
textLocale?: FormulaTextLocale
propertyxmlXPath
xmlXPath?: XmlXPathEvaluator
methodcurrentDateTime
currentDateTime(): number
methodevaluateArrayFormula
evaluateArrayFormula(ast: FormulaAST, scope?: FormulaEvaluationScope): FormulaValue
ast: FormulaAST
scope: FormulaEvaluationScope
methodevaluateFormula
evaluateFormula(ast: FormulaAST, scope?: FormulaEvaluationScope): FormulaValue
ast: FormulaAST
scope: FormulaEvaluationScope
methodforFormulaCell
forFormulaCell(cell: FormulaCellPosition): EvalContext
cell: FormulaCellPosition
methodgetCellValue
getCellValue(row: number, col: number): FormulaValue
row: number
col: number
methodgetSheetShape
getSheetShape(): [rowCount: number, colCount: number]
methodgetWorkbookCellValue
getWorkbookCellValue(sheetName: string, row: number, col: number): FormulaValue
sheetName: string
row: number
col: number
methodisCellInBounds
isCellInBounds(row: number, col: number): boolean
row: number
col: number
methodisCellOccupied
isCellOccupied(row: number, col: number): boolean
row: number
col: number
methoditerateRange
iterateRange(startRow: number, startCol: number, endRow: number, endCol: number): Iterable<FormulaValue>
startRow: number
startCol: number
endRow: number
endCol: number
methoditerateRangeCells
iterateRangeCells(startRow: number, startCol: number, endRow: number, endCol: number): Iterable<FormulaRangeCell>
startRow: number
startCol: number
endRow: number
endCol: number
methoditerateWorkbookRange
iterateWorkbookRange(sheetName: string, startRow: number, startCol: number, endRow: number, endCol: number): Iterable<FormulaValue>
sheetName: string
startRow: number
startCol: number
endRow: number
endCol: number
methoditerateWorkbookRangeCells
iterateWorkbookRangeCells(sheetName: string, startRow: number, startCol: number, endRow: number, endCol: number): Iterable<FormulaRangeCell>
sheetName: string
startRow: number
startCol: number
endRow: number
endCol: number
methodrandom
random(): number
methodreadReference
readReference(reference: ResolvedFormulaRange): FormulaValue
reference: ResolvedFormulaRange
interfaceEvalResultsource ↗
interface EvalResult

One result produced during formula batch evaluation.

propertykey
key: number
propertyvalue
value: FormulaValue
interfaceFormulaAddInRegistrationRequestsource ↗
interface FormulaAddInRegistrationRequest

Identifies one procedure exposed by a host-managed add-in.

propertymodule
readonly module: string
propertyprocedure
readonly procedure: string
propertytypeText
readonly typeText?: string
interfaceFormulaAddInServicesource ↗
interface FormulaAddInService

Host-owned native add-in boundary used by CALL and REGISTER.ID. Implementations must enforce authorization and isolation outside formula evaluation.

methodcall
call(request: FormulaAddInCall): FormulaServiceCacheResult<FormulaValue>
request: FormulaAddInCall
methodresolveRegistration
resolveRegistration(request: FormulaAddInRegistrationRequest): FormulaServiceCacheResult<number>
request: FormulaAddInRegistrationRequest
interfaceFormulaBatchFlushedEventsource ↗
interface FormulaBatchFlushedEvent extends FormulaCalculationTraceEventBase

Event emitted when one batch of derived results is flushed.

propertygeneration
readonly generation: number
propertypendingCount
readonly pendingCount: number
propertyresults
readonly results: readonly FormulaFlushedCellResult[]
propertytype
readonly type: "formula.batchFlushed"
Inherited members 1

Inherited from FormulaCalculationTraceEventBase.

interfaceFormulaCalculationTraceEventBasesource ↗
interface FormulaCalculationTraceEventBase

Shared metadata attached to every calculation trace event.

propertysequence
readonly sequence: number
interfaceFormulaCellMetadatasource ↗
interface FormulaCellMetadata

Read-only cell facts consumed by information formulas.

propertyformula
readonly formula?: string
propertylocked
readonly locked?: boolean
propertynumberFormat
readonly numberFormat?: string
propertyreference
readonly reference: FormulaMetadataCellReference
propertysource
readonly source: FormulaCellSource
propertyvalue
readonly value: FormulaValue
propertywidth
readonly width?: number
interfaceFormulaCellPositionsource ↗
interface FormulaCellPosition

Position of the formula currently being evaluated.

propertycol
readonly col: number
propertyrow
readonly row: number
propertysheetId
readonly sheetId?: string
propertysheetName
readonly sheetName?: string
interfaceFormulaCellStatussource ↗
interface FormulaCellStatus

Read-only formula status snapshot for one sheet cell.

propertycol
readonly col: number
propertydependencies
readonly dependencies: readonly Dependency[]
propertydependents
readonly dependents: readonly number[]
propertydirty
readonly dirty: boolean
propertyerrorCode
readonly errorCode: FormulaErrorCode | undefined
propertyformula
readonly formula: string | undefined
propertyisFormulaCell
readonly isFormulaCell: boolean
propertyresult
readonly result: FormulaValue | undefined
propertyrow
readonly row: number
interfaceFormulaCubeMemberValuesource ↗
interface FormulaCubeMemberValue

CUBE member or tuple identity with its display caption.

propertycaption
readonly caption: string
propertyconnection
readonly connection: string
propertyexpression
readonly expression: string
propertykind
readonly kind: "cube-member"
interfaceFormulaCubeServicesource ↗
interface FormulaCubeService

Host-owned synchronous OLAP cache view. Loading and connection I/O stay outside evaluation.

methodload
load(query: FormulaCubeQuery): Promise<void>
query: FormulaCubeQuery
methodread
read(query: FormulaCubeQuery): FormulaServiceCacheResult<FormulaCubeResult>
query: FormulaCubeQuery
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaCubeSetValuesource ↗
interface FormulaCubeSetValue

CUBE set identity with its display caption.

propertycaption
readonly caption: string
propertyconnection
readonly connection: string
propertycount
readonly count?: number
propertyexpression
readonly expression: string
propertykind
readonly kind: "cube-set"
interfaceFormulaDateTimeLocalesource ↗
interface FormulaDateTimeLocale

Locale-specific date/time parsing and formatting used by formulas.

propertylocale
readonly locale: string
propertysymbols
readonly symbols?: FormulaDateTimeSymbols
methodformatDateTime
formatDateTime(serial: number, pattern?: string): string
serial: number
pattern: string
methodparseDateTime
parseDateTime(value: unknown, options?: FormulaDateTimeParseOptions): FormulaDateTimeParseResult | null
value: unknown
options: FormulaDateTimeParseOptions
interfaceFormulaDateTimeMeridiemSymbolsource ↗
interface FormulaDateTimeMeridiemSymbol

Locale-specific AM/PM token.

propertyperiod
readonly period: "am" | "pm"
propertytext
readonly text: string
interfaceFormulaDateTimeMonthSymbolsource ↗
interface FormulaDateTimeMonthSymbol

Locale-specific month-name token.

propertymonth
readonly month: number
propertytext
readonly text: string
interfaceFormulaDateTimeParseOptionssource ↗
interface FormulaDateTimeParseOptions

Options passed to locale-aware formula date/time parsers.

propertycurrentDateTime
readonly currentDateTime?: number
interfaceFormulaDateTimeParseResultsource ↗
interface FormulaDateTimeParseResult

Parsed Excel-compatible date/time serial and source components.

propertyhasDate
readonly hasDate: boolean
propertyhasTime
readonly hasTime: boolean
propertyserial
readonly serial: number
interfaceFormulaDateTimeSymbolssource ↗
interface FormulaDateTimeSymbols

Locale-specific symbols consumed by the shared date/time parser.

propertymeridiems
readonly meridiems?: readonly FormulaDateTimeMeridiemSymbol[]
propertymonths
readonly months?: readonly FormulaDateTimeMonthSymbol[]
propertyunits
readonly units?: FormulaDateTimeUnitSymbols
interfaceFormulaDateTimeUnitSymbolssource ↗
interface FormulaDateTimeUnitSymbols

Locale-specific date-unit tokens.

propertyday
readonly day?: readonly string[]
propertymonth
readonly month?: readonly string[]
propertyyear
readonly year?: readonly string[]
interfaceFormulaDependenciesChangedEventsource ↗
interface FormulaDependenciesChangedEvent extends FormulaCalculationTraceEventBase

Event emitted when one formula cell's dependency edges change.

propertycol
readonly col: number
propertydependencies
readonly dependencies: readonly Dependency[]
propertykey
readonly key: number
propertypreviousDependencies
readonly previousDependencies: readonly Dependency[]
propertyrow
readonly row: number
propertytype
readonly type: "formula.dependenciesChanged"
Inherited members 1

Inherited from FormulaCalculationTraceEventBase.

interfaceFormulaDirectAddInCallsource ↗
interface FormulaDirectAddInCall extends FormulaAddInRegistrationRequest

Invokes a host-authorized procedure by module signature.

propertyarguments
readonly arguments: readonly FormulaValue[]
propertykind
readonly kind: "direct"
propertytypeText
readonly typeText: string
Inherited members 2

Inherited from FormulaAddInRegistrationRequest.

interfaceFormulaEnvironmentMetadatasource ↗
interface FormulaEnvironmentMetadata

Optional host facts exposed without leaking platform-native APIs.

propertycalculationMode
readonly calculationMode?: "Automatic" | "Manual"
propertydirectory
readonly directory?: string
propertyoperatingSystem
readonly operatingSystem?: string
propertysystem
readonly system?: string
propertyversion
readonly version?: string
interfaceFormulaErrorsource ↗
interface FormulaError

Serializable formula error value.

propertycode
code: FormulaErrorCode
propertykind
kind: "error"
interfaceFormulaErrorChangedEventsource ↗
interface FormulaErrorChangedEvent extends FormulaCalculationTraceEventBase

Event emitted when one formula cell's error code changes.

propertycol
readonly col: number
propertyerrorCode
readonly errorCode: FormulaErrorCode | undefined
propertygeneration
readonly generation: number
propertykey
readonly key: number
propertypreviousErrorCode
readonly previousErrorCode: FormulaErrorCode | undefined
propertyrow
readonly row: number
propertytype
readonly type: "formula.errorChanged"
Inherited members 1

Inherited from FormulaCalculationTraceEventBase.

interfaceFormulaEvaluationBudgetsource ↗
interface FormulaEvaluationBudget

Host-neutral execution budget for formula evaluation.

propertymaxSteps
readonly maxSteps: number
methodconsumeStep
consumeStep(): boolean
interfaceFormulaEvaluationScopesource ↗
interface FormulaEvaluationScope

Lexical scope for formula-local names.

propertyparent
readonly parent?: FormulaEvaluationScope
methodget
get(name: string): FormulaValue | undefined
name: string
methodset
set(name: string, value: FormulaValue): void
name: string
value: FormulaValue
interfaceFormulaExternalServiceDefinitionsource ↗
interface FormulaExternalServiceDefinition<T>

Typed identity for one synchronous service view consumed by formulas.

propertyid
readonly id: string
propertysubscribeInvalidation
readonly subscribeInvalidation?: (service: T, listener: (): void): (): void
propertytype
readonly type?: T
interfaceFormulaExternalServiceReadersource ↗
interface FormulaExternalServiceReader

Read-only external-service view exposed during formula evaluation.

methodget
get<T>(definition: FormulaExternalServiceDefinition<T>): T | undefined
definition: FormulaExternalServiceDefinition<T>
interfaceFormulaFlushedCellResultsource ↗
interface FormulaFlushedCellResult

One cell result written during a formula batch flush.

propertycol
readonly col: number
propertyerrorCode
readonly errorCode: FormulaErrorCode | undefined
propertykey
readonly key: number
propertypreviousResult
readonly previousResult: FormulaValue | undefined
propertyresult
readonly result: FormulaValue
propertyrow
readonly row: number
interfaceFormulaFunctionsource ↗
interface FormulaFunction

Runtime contract implemented by built-in and third-party formula functions.

propertyallowReferencesOutsideHostShape
allowReferencesOutsideHostShape?: boolean

Pass reference coordinates to the function even when outside the host's materialized sheet shape.

propertydescriptor
descriptor?: FormulaFunctionDescriptor
propertylazy
lazy?: boolean
propertyname
name: string
propertynamedConstants
namedConstants?: Readonly<Record<string, FormulaValue>>
propertyvolatile
volatile?: boolean
methodevaluate
evaluate(args: FormulaArg[], context: EvalContext): FormulaValue
args: FormulaArg[]
context: EvalContext
methodincrementalUpdate
incrementalUpdate(prevResult: FormulaValue, changedCells: CellChange[], args: FormulaAST[], context: EvalContext): FormulaValue
prevResult: FormulaValue
changedCells: CellChange[]
args: FormulaAST[]
context: EvalContext
interfaceFormulaFunctionDescriptorsource ↗
interface FormulaFunctionDescriptor

Versioned presentation-neutral formula function metadata.

propertycategory
readonly category: string
propertyexample
readonly example: string
propertyexternalServices
readonly externalServices?: readonly string[]
propertymaxArguments
readonly maxArguments?: number

Authoritative upper argument bound. Omit for variadic or illustrative signatures.

propertyminArguments
readonly minArguments?: number

Authoritative lower argument bound. Omit when a signature is illustrative only.

propertyparameters
readonly parameters: readonly FormulaFunctionParameterDescriptor[]
propertyreturnKind
readonly returnKind?: "array" | "scalar" | "scalar-or-array"
propertysummary
readonly summary: string
propertyversion
readonly version: 1
interfaceFormulaFunctionParameterDescriptorsource ↗
interface FormulaFunctionParameterDescriptor

One function parameter exposed to formula-authoring tools.

propertyaccepts
readonly accepts?: readonly FormulaFunctionArgumentKind[]
propertydescription
readonly description: string
propertyname
readonly name: string
propertyoptional
readonly optional?: boolean
propertyrepeating
readonly repeating?: boolean
interfaceFormulaGoogleRequestsource ↗
interface FormulaGoogleRequest

Serializable request used by host-backed Google-compatible formulas.

propertyarguments
readonly arguments: readonly FormulaValue[]
propertyfunctionName
readonly functionName: string
interfaceFormulaGoogleServicesource ↗
interface FormulaGoogleService

Synchronous cache view. Hosts load values outside formula evaluation.

methodread
read(request: FormulaGoogleRequest): FormulaServiceCacheResult<FormulaValue>
request: FormulaGoogleRequest
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaHyperlinkResultsource ↗
interface FormulaHyperlinkResult

Host-neutral hyperlink result projected by a formula renderer.

propertykind
readonly kind: "hyperlink"
propertylabel
readonly label: string
propertytarget
readonly target: string
interfaceFormulaHyperlinkServicesource ↗
interface FormulaHyperlinkService

Host policy for validating and normalizing hyperlink targets.

methodnormalizeTarget
normalizeTarget(target: string): string | undefined
target: string
interfaceFormulaImageResourcesource ↗
interface FormulaImageResource

Host-neutral image resource returned by an image loader.

propertyassetId
readonly assetId: string
propertyintrinsicHeight
readonly intrinsicHeight?: number
propertyintrinsicWidth
readonly intrinsicWidth?: number
propertysource
readonly source: string
interfaceFormulaImageResultsource ↗
interface FormulaImageResult

Host-neutral image result projected by a formula renderer.

propertyaltText
readonly altText?: string
propertyheight
readonly height?: number
propertykind
readonly kind: "image"
propertyresource
readonly resource: FormulaImageResource
propertysizing
readonly sizing?: number
propertywidth
readonly width?: number
interfaceFormulaImageServicesource ↗
interface FormulaImageService

Host-owned image loader used by IMAGE.

methodload
load(source: string): Promise<void>
source: string
methodread
read(source: string): FormulaServiceCacheResult<FormulaImageResource>
source: string
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaIterationSettingssource ↗
interface FormulaIterationSettings

Per-editor calculation policy for circular formula dependencies.

propertyenabled
enabled: boolean
propertymaxChange
maxChange: number
propertymaxIterations
maxIterations: number
interfaceFormulaLanguageServicesource ↗
interface FormulaLanguageService

Synchronous cache view for host-managed language services.

propertydefaultTargetLanguage
readonly defaultTargetLanguage?: string
methoddetectLanguage
detectLanguage(text: string): FormulaLanguageServiceResult
text: string
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
methodtranslate
translate(text: string, sourceLanguage: string | undefined, targetLanguage: string): FormulaLanguageServiceResult
text: string
sourceLanguage: string | undefined
targetLanguage: string
interfaceFormulaMetadataCellReferencesource ↗
interface FormulaMetadataCellReference

Platform-neutral identity of one cell visible to formula evaluation.

propertycol
readonly col: number
propertyrow
readonly row: number
propertysheetName
readonly sheetName?: string
interfaceFormulaMetadataReadersource ↗
interface FormulaMetadataReader

Host-owned, synchronous metadata projection consumed during formula evaluation.

methodreadCell
readCell(reference: FormulaMetadataCellReference): FormulaCellMetadata | undefined
reference: FormulaMetadataCellReference
methodreadEnvironment
readEnvironment(): FormulaEnvironmentMetadata | undefined
methodreadWorkbook
readWorkbook(): FormulaWorkbookMetadata | undefined
interfaceFormulaPhoneticReadersource ↗
interface FormulaPhoneticReader

Reads persisted phonetic text without coupling formulas to a cell schema.

methodgetCellPhonetic
getCellPhonetic(row: number, col: number): string | undefined
row: number
col: number
methodgetWorkbookCellPhonetic
getWorkbookCellPhonetic(sheetName: string, row: number, col: number): string | undefined
sheetName: string
row: number
col: number
interfaceFormulaPivotDataQuerysource ↗
interface FormulaPivotDataQuery

Query passed to a host-owned pivot data provider.

propertydataField
readonly dataField: string
propertyfilters
readonly filters: readonly { field: string; item: string }[]
propertypivotReference
readonly pivotReference: string
interfaceFormulaPivotDataServicesource ↗
interface FormulaPivotDataService

Host service used by GETPIVOTDATA.

methodgetData
getData(query: FormulaPivotDataQuery): FormulaValue
query: FormulaPivotDataQuery
interfaceFormulaRangeCellsource ↗
interface FormulaRangeCell

One range cell with optional visibility and source metadata.

propertycol
readonly col: number
propertyfiltered
readonly filtered?: boolean
propertyformulaName
readonly formulaName?: string
propertyhidden
readonly hidden?: boolean
propertyrow
readonly row: number
propertysource
readonly source?: "value" | "empty" | "formula"
propertyvalue
readonly value: FormulaValue
interfaceFormulaRangeMovesource ↗
interface FormulaRangeMove

Inclusive source bounds and displacement for reference-preserving cell movement.

propertycolumnOffset
readonly columnOffset: number
propertyend
readonly end: readonly [number, number]
propertyincludeUnqualified
readonly includeUnqualified?: boolean

False when inspecting qualified references from a different sheet.

propertyrowOffset
readonly rowOffset: number
propertysheetName
readonly sheetName?: string

When supplied, qualified references to this sheet also follow the move.

propertystart
readonly start: readonly [number, number]
interfaceFormulaRecalculationCompletedEventsource ↗
interface FormulaRecalculationCompletedEvent extends FormulaCalculationTraceEventBase

Event emitted when one recalculation generation completes.

propertybatchCount
readonly batchCount: number
propertyflushedCellCount
readonly flushedCellCount: number
propertygeneration
readonly generation: number
propertypendingCount
readonly pendingCount: 0
propertytype
readonly type: "formula.recalculationCompleted"
Inherited members 1

Inherited from FormulaCalculationTraceEventBase.

interfaceFormulaReferenceArgumentsource ↗
interface FormulaReferenceArgument

A function argument that intentionally retains reference identity.

propertykind
readonly kind: "reference"
propertyreference
readonly reference: ResolvedFormulaRange
interfaceFormulaReferenceResolutionOptionssource ↗
interface FormulaReferenceResolutionOptions

Options used when resolving text, names, or dynamic references.

propertycurrentCell
readonly currentCell?: FormulaCellPosition
propertystyle
readonly style?: FormulaReferenceStyle
interfaceFormulaReferenceResolversource ↗
interface FormulaReferenceResolver

Host-owned resolver for names and text references.

methodresolve
resolve(referenceText: string, options?: FormulaReferenceResolutionOptions): FormulaError | ResolvedFormulaRange
referenceText: string
options: FormulaReferenceResolutionOptions
interfaceFormulaReferenceValuesource ↗
interface FormulaReferenceValue

Reference identity returned by reference-preserving functions.

propertykind
readonly kind: "reference"
propertyreference
readonly reference: ResolvedFormulaRange
interfaceFormulaRegisteredAddInCallsource ↗
interface FormulaRegisteredAddInCall

Invokes a procedure previously resolved by REGISTER.ID.

propertyarguments
readonly arguments: readonly FormulaValue[]
propertykind
readonly kind: "registered"
propertyregistrationId
readonly registrationId: number
interfaceFormulaRtdKeysource ↗
interface FormulaRtdKey

Stable key used to read one RTD subscription.

propertyprogId
readonly progId: string
propertyserver
readonly server?: string
propertytopics
readonly topics: readonly string[]
interfaceFormulaRtdServicesource ↗
interface FormulaRtdService

Host-owned RTD service.

methodload
load(key: FormulaRtdKey): Promise<void>
key: FormulaRtdKey
methodread
read(key: FormulaRtdKey): FormulaServiceCacheResult<FormulaValue>
key: FormulaRtdKey
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaSheetMetadatasource ↗
interface FormulaSheetMetadata

Stable workbook sheet identity and one-based display position.

propertyid
readonly id: string
propertyindex
readonly index: number
propertyname
readonly name: string
propertyvisible
readonly visible?: boolean
interfaceFormulaStockHistoryRequestsource ↗
interface FormulaStockHistoryRequest

Normalized request key for a historical market-data lookup.

propertyendDate
readonly endDate?: number
propertyheaders
readonly headers: 0 | 1 | 2
propertyinterval
readonly interval: 0 | 1 | 2
propertyproperties
readonly properties: readonly number[]
propertystartDate
readonly startDate: number
propertystock
readonly stock: string
interfaceFormulaStockHistoryServicesource ↗
interface FormulaStockHistoryService

Synchronous view over historical market data loaded outside formula evaluation.

methodread
read(request: FormulaStockHistoryRequest): FormulaServiceCacheResult<FormulaError | FormulaValue[][]>
request: FormulaStockHistoryRequest
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaStructureMoveOptionssource ↗
interface FormulaStructureMoveOptions

Selects the reference namespace rewritten by a structure permutation.

propertyincludeUnqualified
readonly includeUnqualified?: boolean
propertysheetName
readonly sheetName?: string
interfaceFormulaTextsource ↗
interface FormulaText

Text value carrying an explicit numeric coercion policy.

propertykind
kind: "text"
propertynumericCoercion
numericCoercion: "allow" | "deny"
propertyvalue
value: string
interfaceFormulaTextLocalesource ↗
interface FormulaTextLocale

Locale-specific byte and width transforms for legacy text functions.

propertycurrencySymbol
readonly currencySymbol?: string
propertylocale
readonly locale: string
methodbyteLength
byteLength(text: string): number
text: string
methodcalculationModeLabel
calculationModeLabel(mode: "Automatic" | "Manual"): string
mode: "Automatic" | "Manual"
methodcharacterCode
characterCode(text: string): number
text: string
methodcharacterFromCode
characterFromCode(code: number): string | undefined
code: number
methodcompareText
compareText(left: string, right: string): number
left: string
right: string
methodfindByBytes
findByBytes(text: string, search: string, startByte: number, caseSensitive: boolean): number
text: string
search: string
startByte: number
caseSensitive: boolean
methodformatCurrency
formatCurrency(number: number, decimals: number): string
number: number
decimals: number
methodreplaceByBytes
replaceByBytes(text: string, startByte: number, byteLength: number, replacement: string): string
text: string
startByte: number
byteLength: number
replacement: string
methodsliceByBytes
sliceByBytes(text: string, startByte: number, byteLength: number): string
text: string
startByte: number
byteLength: number
methodtoFullWidth
toFullWidth(text: string): string
text: string
methodtoHalfWidth
toHalfWidth(text: string): string
text: string
methodtoJis
toJis(text: string): string
text: string
interfaceFormulaTupleValuesource ↗
interface FormulaTupleValue

Tuple expression preserving the identity of its items.

propertyitems
readonly items: readonly FormulaValue[]
propertykind
readonly kind: "tuple"
interfaceFormulaWebServicesource ↗
interface FormulaWebService

Synchronous view of HTTP response text loaded explicitly by the host.

methodread
read(url: string): FormulaServiceCacheResult<string | FormulaError>
url: string
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
interfaceFormulaWorkbookMetadatasource ↗
interface FormulaWorkbookMetadata

Read-only workbook facts consumed by information formulas.

propertycurrentSheetId
readonly currentSheetId?: string
propertycurrentSheetName
readonly currentSheetName?: string
propertysheets
readonly sheets: readonly FormulaSheetMetadata[]
interfaceIAggregationCachesource ↗
interface IAggregationCache

Public contract for IAggregationCache.

methodclear
clear(): void

Clears all caches.

methodenforceCommandBoundary
enforceCommandBoundary(isCommandExecuting: (): boolean): void

Binds cache writes to the owning editor command dispatch after initialization.

isCommandExecuting: (): boolean
methodgetCount
getCount(startRow: number, startCol: number, endRow: number, endCol: number): number

Gets the COUNT for a range, meaning the number of numeric cells.

Uses the same cache and incremental strategy as getSum.

startRow: number
startCol: number
endRow: number
endCol: number
methodgetSum
getSum(startRow: number, startCol: number, endRow: number, endCol: number): number

Gets the SUM for a range.

Cache hit returns directly in O(1). Cache miss requires a full O(N) scan on the first call.

Called by FormulaEvaluator while evaluating SUM, not exposed directly to users.

startRow: number

Start row (0-based).

startCol: number

Start column (0-based).

endRow: number

End row (0-based).

endCol: number

End column (0-based).

methodonCellChanged
onCellChanged(row: number, col: number, oldVal: FormulaValue, newVal: FormulaValue): void

Notifies the cache that one cell value changed.

Finds every cached range covering the cell and updates incrementally:

  • newSum = oldSum - oldVal + newVal
  • FormulaError oldVal/newVal values are treated as non-numeric and do not affect sum.
row: number

Changed row (0-based).

col: number

Changed column (0-based).

oldVal: FormulaValue

Previous value.

newVal: FormulaValue

New value.

methodonStructureChanged
onStructureChanged(): void

Notifies the cache that rows or columns were inserted or deleted.

Structural changes invalidate all range caches because range coordinates have changed, so the cache must be cleared.

methodsetCount
setCount(startRow: number, startCol: number, endRow: number, endCol: number, count: number): void

Stores a successfully calculated COUNT for a rectangular range.

startRow: number
startCol: number
endRow: number
endCol: number
count: number
methodsetSum
setSum(startRow: number, startCol: number, endRow: number, endCol: number, sum: number): void

Stores a successfully calculated SUM for a rectangular range.

startRow: number
startCol: number
endRow: number
endCol: number
sum: number
interfaceIDependencyGraphsource ↗
interface IDependencyGraph

Public contract for IDependencyGraph.

propertypendingCount
readonly pendingCount: number

Number of dirty formulas still waiting for evaluation.

propertysize
readonly size: number

Total number of formula cells currently in the graph.

methodclear
clear(): void

Clears all graph data.

methodenforceCommandBoundary
enforceCommandBoundary(isCommandExecuting: (): boolean): void

Binds mutations to the owning editor command dispatch after initialization.

isCommandExecuting: (): boolean
methodgetDependencies
getDependencies(formulaKey: number): readonly Dependency[]

Gets the range-level dependencies owned by one formula cell.

Returned dependencies are defensive copies and must not expose mutable graph internals. Non-formula cells return an empty array.

ReturnsRange-level Dependency list used by the formula.

formulaKey: number

CellKey for the formula cell.

methodgetDependents
getDependents(key: number): number[]

Gets every formula that depends on one cell.

Uses three reverse-lookup indexes:

  1. Per-cell reverse dependencies (cellRevDeps) — O(1)
  2. Column-grouped interval lookup (columnRanges) — O(log N + K)
  3. Overflow-list linear scan (overflowRanges) — O(M)

ReturnsCellKeys for all formulas that depend on that cell.

key: number

CellKey for the referenced cell.

methodgetFormulaKeys
getFormulaKeys(): readonly number[]

Gets formula cells currently registered in the graph.

The returned array is a stable snapshot for diagnostics and host status views. Mutating it must not affect graph internals.

ReturnsCellKeys for every formula cell with registered dependencies.

methodgetLastCycleKeys
getLastCycleKeys(): number[]

Cycle nodes detected by the last markDirty call.

Formulas in a cycle should display the #REF! error. markDirty detects cycles by topological elimination: repeatedly remove ready nodes; the remaining nodes are part of cycles.

methodgetNextReadyBatch
getNextReadyBatch(viewport: Set<number>, maxCount: number): number[]

Gets currently dirty formulas that can be evaluated immediately.

"Ready" means all dependencies for the formula are clean and there are no dirty dependencies. Viewport formulas are returned first so visible results update before off-screen ones.

ReturnsCellKeys for formulas that can be evaluated immediately.

viewport: Set<number>

CellKeys currently inside the viewport.

maxCount: number

Maximum number of formulas to return.

methodisDirty
isDirty(key: number): boolean

Reports whether one formula cell is currently dirty.

Non-formula cells and clean formula cells return false.

ReturnsTrue when the formula is waiting for recalculation.

key: number

CellKey for the formula to inspect.

methodmarkClean
markClean(key: number): void

Marks one formula clean after evaluation completes.

Unlocks downstream dependencies by decrementing dirtyDepCount for each dirty formula that depends on key. When dirtyDepCount reaches 0, that formula becomes ready and can be returned by getNextReadyBatch.

key: number

CellKey for the formula that has finished evaluating.

methodmarkDirty
markDirty(changedKeys: number[]): void

Marks all affected formulas dirty.

Starts from changedKeys and propagates dirty marks along reverse-dependency edges using BFS. Complexity is O(affected formulas + edges), with no topological sort.

Cycle detection records nodes inside the cycle in lastCycleKeys, which can be read through getLastCycleKeys().

changedKeys: number[]

CellKeys for cells whose values changed.

methodonStructureChanged
onStructureChanged(changes: StructureChange[]): void

Notifies the graph about structural changes.

Called for row/column insertions and deletions, and updates range coordinates in spatial indexes. Large change sets may choose lazy rebuilds by clearing indexes and rebuilding on the next query.

changes: StructureChange[]

Structural change list.

methodremoveCell
removeCell(formulaKey: number): void

Removes one formula cell.

Clears the formula's:

  • forward dependencies (deps Map)
  • reverse indexes (cellRevDeps + columnRanges + overflowRanges)
  • dirty state (dirtySet + dirtyDepCount)
formulaKey: number
methodupdateCell
updateCell(formulaKey: number, deps: Dependency[]): void

Registers or updates dependencies for one formula cell.

deps is a range-level Dependency list and is not expanded per cell. Existing formula-cell dependencies are removed before the new set is registered.

formulaKey: number

CellKey for the formula cell.

deps: Dependency[]

Range-level Dependency list used by the formula.

interfaceIFormulaCalculationTraceProvidersource ↗
interface IFormulaCalculationTraceProvider

Read-only subscription provider for formula calculation trace events.

Hosts should subscribe through the command surface, while plugins can inject this provider directly during the editor lifecycle. Events are local runtime trace and do not participate in OT or persistence.

methodsubscribeFormulaCalculationTrace
subscribeFormulaCalculationTrace(listener: FormulaCalculationTraceListener): (): void

Subscribes to formula calculation trace events for one editor instance.

ReturnsFunction that removes the listener; calling it more than once is safe.

listener: FormulaCalculationTraceListener

Callback invoked for future calculation trace events.

interfaceIFormulaDateSystemProvidersource ↗
interface IFormulaDateSystemProvider

Editor-local source for the workbook date serial system.

methodgetDateSystem
getDateSystem(): FormulaDateSystem
interfaceIFormulaEvaluatorsource ↗
interface IFormulaEvaluator

Public contract for IFormulaEvaluator.

methodevaluate
evaluate(ast: FormulaAST, context: EvalContext): FormulaValue

Evaluates one AST.

Recursively traverses the AST, performs operations, and handles error propagation:

  • Any FormulaError operand -> result is that error.
  • Division by zero -> #DIV/0!.
  • Type mismatch -> #VALUE!.
  • Unknown function name -> #NAME?.

ReturnsCalculated result.

ast: FormulaAST

Parsed formula AST.

context: EvalContext

Evaluation context that provides cell-value reads.

methodevaluateBatch
evaluateBatch(asts: { ast: FormulaAST; key: number }[], context: EvalContext): EvalResult[]

Batch evaluation.

The TS implementation can call evaluate one by one. A WASM implementation can process all ASTs on the Rust side in one pass, avoiding 100K JS <-> WASM boundary crossings.

ReturnsEvaluation result list.

asts: { ast: FormulaAST; key: number }[]

AST list to evaluate; each item contains a CellKey and its AST.

context: EvalContext

Evaluation context.

methodregisterFunction
registerFunction(fn: FormulaFunction): void

Registers a custom function.

After registration, formulas can call the function by name. For example, registering AVERAGE allows =AVERAGE(A1:A10).

fn: FormulaFunction
interfaceIFormulaExternalServiceProvidersource ↗
interface IFormulaExternalServiceProvider extends FormulaExternalServiceReader

Editor-owned registry used by hosts to publish services and cache invalidation.

methoddestroy
destroy(ownerToken?: object): void
ownerToken: object
methodenforceCommandBoundary
enforceCommandBoundary(isCommandExecuting: (): boolean, dispatchRemoval: (id: number): void): void
isCommandExecuting: (): boolean
dispatchRemoval: (id: number): void
methodenforceTeardownBoundary
enforceTeardownBoundary(ownerToken: object): void
ownerToken: object
methodinvalidate
invalidate<T>(definition: FormulaExternalServiceDefinition<T>): void
definition: FormulaExternalServiceDefinition<T>
methodregister
register<T>(definition: FormulaExternalServiceDefinition<T>, service: T): (): void
definition: FormulaExternalServiceDefinition<T>
service: T
methodsubscribeInvalidation
subscribeInvalidation(listener: (serviceIds: readonly string[]): void): (): void
listener: (serviceIds: readonly string[]): void
methodunregisterRegistration
unregisterRegistration(id: number): void
id: number
Inherited members 1

Inherited from FormulaExternalServiceReader.

interfaceIFormulaIterationSettingsProvidersource ↗
interface IFormulaIterationSettingsProvider

Optional editor-local provider for circular formula calculation.

methodgetSettings
getSettings(): FormulaIterationSettings
interfaceIFormulaLocaleProvidersource ↗
interface IFormulaLocaleProvider

Editor-local locale provider consumed by formula evaluation hosts.

methodgetDateTimeLocale
getDateTimeLocale(): FormulaDateTimeLocale

Returns the current date/time locale strategy for formula functions.

methodgetTextLocale
getTextLocale(): FormulaTextLocale

Returns the current text byte/width locale strategy for formula functions.

interfaceIFormulaParsersource ↗
interface IFormulaParser

Public contract for IFormulaParser.

methodextractDependencies
extractDependencies(ast: FormulaAST): Dependency[]

Extracts all dependencies from an AST.

Traverses all cell and range nodes in the AST and returns a Dependency list. Returned dependencies stay range-level and are not expanded per cell.

Example
// =SUM(A1:C100) + D5
extractDependencies(ast) → [
  { kind: FormulaNodeKind.Range, start: [0,0], end: [99,2] },
  { kind: FormulaNodeKind.Cell, row: 4, col: 3 }
]
ast: FormulaAST
methodparse
parse(formula: string): FormulaAST

Parses a formula string into an AST.

Input is a formula string with a leading '=', such as "=A1+B1". Uses recursive-descent parsing and supports the full operator precedence.

ReturnsParsed AST.

ThrowsWhen parsing fails because syntax is invalid.

formula: string

Formula string including the leading '='.

methodshiftReferences
shiftReferences(ast: FormulaAST, changes: StructureChange[]): FormulaAST

Shifts references.

Rewrites row/column references inside an AST after structural changes such as row/column insertions and deletions. Uses immutable updates: creates a new AST and never mutates the original AST.

Rules:

  • Absolute references ($A$1) are unaffected.
  • Relative references shift according to insertion/deletion position.
  • Deleted referenced rows/columns produce an AST carrying #REF!.
Example
A formula =B3 in A2, after inserting one row below row 1, becomes =B4.
A formula =SUM(A1:A3) in A4, after deleting row 2, becomes =SUM(A1:#REF!).
ast: FormulaAST
changes: StructureChange[]
interfaceIFormulaResultProvidersource ↗
interface IFormulaResultProvider

Read-only provider for calculated formula results.

Rendering and other consumers use this interface to read per-client derived formula values without depending on a concrete formula plugin implementation.

methodforEachFormulaResultInRange
forEachFormulaResultInRange(startRow: number, startColumn: number, endRow: number, endColumn: number, visit: (row: number, column: number): void): void

Visits calculated result coordinates in an inclusive range. Providers that project results into cells without persisted data must implement this so range consumers can discover those cells without probing empty positions.

startRow: number
startColumn: number
endRow: number
endColumn: number
visit: (row: number, column: number): void
methodgetFormulaResult
getFormulaResult(row: number, col: number): FormulaValue | undefined

Gets the calculated result for a formula anchor or one of its dynamic-array spill cells.

ReturnsFormulaValue, or undefined when not calculated or not a formula cell.

row: number

Row index (0-based).

col: number

Column index (0-based).

interfaceIFormulaRichResultProvidersource ↗
interface IFormulaRichResultProvider

Read-only provider for non-text visual results produced by formula cells.

methodgetFormulaRichResult
getFormulaRichResult(row: number, col: number): FormulaRichResult | undefined
row: number
col: number
interfaceIFormulaSourceProvidersource ↗
interface IFormulaSourceProvider

Read-only provider for the formula source text shown while editing.

methodgetFormulaSource
getFormulaSource(row: number, col: number): string | undefined

Gets the formula source that should be presented to the user for one cell.

Providers may return undefined when they do not own the queried cell. The default sheet formula provider returns the persisted formula text, while workbook-aware providers can return display text formatted from stable workbook bindings and the current sheet names.

row: number
col: number
interfaceIFormulaStatusProvidersource ↗
interface IFormulaStatusProvider

Read-only provider for formula result, source, dependency, and dirty status.

Hosts should prefer the command surface that delegates to this provider, while plugins can inject the provider directly when they run inside the editor lifecycle.

methodgetFormulaCellStatus
getFormulaCellStatus(row: number, col: number): FormulaCellStatus

Gets a stable formula status snapshot for one sheet cell.

ReturnsFormula status with defensive copies of dependency arrays.

row: number

Row index (0-based).

col: number

Column index (0-based).

interfaceIFormulaTextServiceProvidersource ↗
interface IFormulaTextServiceProvider

Optional editor-local providers for metadata- and service-backed text formulas.

methodenforceCommandBoundary
enforceCommandBoundary(isCommandExecuting: (): boolean, dispatchRemoval: (id: number): void): void
isCommandExecuting: (): boolean
dispatchRemoval: (id: number): void
methodgetLanguageService
getLanguageService(): FormulaLanguageService | undefined
methodgetPhoneticReader
getPhoneticReader(): FormulaPhoneticReader | undefined
methodregisterLanguageService
registerLanguageService(service: FormulaLanguageService): (): void
service: FormulaLanguageService
methodregisterPhoneticReader
registerPhoneticReader(reader: FormulaPhoneticReader): (): void
reader: FormulaPhoneticReader
methodsubscribeInvalidation
subscribeInvalidation(listener: (): void): (): void
listener: (): void
methodunregisterRegistration
unregisterRegistration(id: number): void
id: number
interfaceIFunctionRegistrysource ↗
interface IFunctionRegistry

Public contract for IFunctionRegistry.

methodenforceCommandBoundary
enforceCommandBoundary(isCommandExecuting: (): boolean, dispatchRemoval: (id: number): void): void

Requires post-initialization writes to occur during the owning editor's command dispatch.

isCommandExecuting: (): boolean
dispatchRemoval: (id: number): void
methodget
get(name: string): FormulaFunction | undefined

Gets a function definition by name.

ReturnsFunction definition, or undefined when it is not registered.

name: string

Function name, case-insensitive.

methodhas
has(name: string): boolean

Checks whether a function has been registered.

name: string

Function name, case-insensitive.

methodlist
list(): string[]

Lists all registered function names.

ReturnsFunction names in uppercase.

methodregister
register(fn: FormulaFunction): (): void

Registers a formula function.

fn: FormulaFunction

Function definition; name is stored in uppercase automatically.

methodregisterMany
registerMany(functions: readonly FormulaFunction[]): (): void

Registers a group of formula functions and publishes one combined change notification.

functions: readonly FormulaFunction[]

Function definitions in registration precedence order.

methodsubscribe
subscribe(listener: (functionNames: readonly string[]): void): (): void

Subscribes to registrations and removals that can change formula results.

listener: (functionNames: readonly string[]): void
methodunregisterRegistration
unregisterRegistration(id: number): void

Removes one tokenized registration; disposal may dispatch an owner command.

id: number
interfaceResolvedFormulaRangesource ↗
interface ResolvedFormulaRange

Concrete finite range resolved against sheet bounds.

propertyendCol
readonly endCol: number
propertyendRow
readonly endRow: number
propertysource
readonly source: FormulaRangeSource
propertystartCol
readonly startCol: number
propertystartRow
readonly startRow: number
interfaceShiftedStructureCoordinatesource ↗
interface ShiftedStructureCoordinate

Result of shifting one coordinate through structure changes.

propertydeleted
readonly deleted: boolean
propertyvalue
readonly value: number
interfaceStructureMoveChangesource ↗
interface StructureMoveChange

Formula-aware row or column move.

propertyfromIndex
fromIndex: number
propertytoIndex
toIndex: number
propertytype
type: RowMove | ColMove
typeBinaryOpsource ↗
type BinaryOp = "+" | "-" | "*" | "/" | "^" | "&" | "=" | "<>" | "<" | ">" | "<=" | ">="

Supported binary formula operators.

typeCellKeysource ↗
type CellKey = number

Numeric key encoding one cell coordinate.

typeDependencysource ↗
type Dependency = { col: number; kind: typeof FormulaNodeKind.Cell; row: number } | { end: [number, number]; kind: typeof FormulaNodeKind.Range; start: [number, number] } | { col: number; kind: typeof FormulaNodeKind.WorkbookCell; row: number; sheetName: string } | { end: [number, number]; kind: typeof FormulaNodeKind.WorkbookRange; sheetName: string; start: [number, number] } | { endCol: number; kind: typeof FormulaNodeKind.ColumnRange; startCol: number } | { endRow: number; kind: typeof FormulaNodeKind.RowRange; startRow: number }

Formula dependency preserving cell and range reference semantics.

typeErrorCodesource ↗
type ErrorCode = FormulaErrorCode

Standard Excel-compatible error code.

typeFormulaAddInCallsource ↗
type FormulaAddInCall = FormulaRegisteredAddInCall | FormulaDirectAddInCall

Supported host add-in invocation request.

typeFormulaAddInRegistrationIdsource ↗
type FormulaAddInRegistrationId = number

Stable numeric handle for one host-authorized add-in procedure.

typeFormulaArgsource ↗
type FormulaArg = { kind: "value"; sourceAst?: FormulaAST; sourceKind?: FormulaNodeKind; value: FormulaValue } | { ast: FormulaAST; kind: "expression" } | { kind: "missing" } | { col: number; kind: typeof FormulaNodeKind.Cell; row: number } | { end: [number, number]; kind: typeof FormulaNodeKind.Range; start: [number, number] } | { col: number; kind: typeof FormulaNodeKind.WorkbookCell; row: number; sheetName: string } | { end: [number, number]; kind: typeof FormulaNodeKind.WorkbookRange; sheetName: string; start: [number, number] } | { endCol: number; kind: typeof FormulaNodeKind.ColumnRange; startCol: number } | { endRow: number; kind: typeof FormulaNodeKind.RowRange; startRow: number } | FormulaReferenceArgument

Function argument preserving lazy reference and expression semantics.

typeFormulaArraysource ↗
type FormulaArray = FormulaValue[][]

Rectangular two-dimensional formula result represented as nested rows.

typeFormulaASTsource ↗
type FormulaAST = { kind: typeof FormulaNodeKind.Number; value: number } | { kind: typeof FormulaNodeKind.String; value: string } | { kind: typeof FormulaNodeKind.Boolean; value: boolean } | { code: FormulaErrorCode; kind: typeof FormulaNodeKind.Error } | { kind: typeof FormulaNodeKind.Name; name: string } | { items: FormulaAST[]; kind: typeof FormulaNodeKind.Tuple } | { kind: typeof FormulaNodeKind.Intersection; left: FormulaAST; right: FormulaAST } | { kind: typeof FormulaNodeKind.Array; rows: FormulaAST[][] } | { kind: typeof FormulaNodeKind.Missing } | { absCol: boolean; absRow: boolean; col: number; kind: typeof FormulaNodeKind.Cell; row: number } | { absEndCol: boolean; absEndRow: boolean; absStartCol: boolean; absStartRow: boolean; end: [number, number]; kind: typeof FormulaNodeKind.Range; start: [number, number] } | { absCol: boolean; absRow: boolean; col: number; kind: typeof FormulaNodeKind.WorkbookCell; row: number; sheetName: string } | { absEndCol: boolean; absEndRow: boolean; absStartCol: boolean; absStartRow: boolean; end: [number, number]; kind: typeof FormulaNodeKind.WorkbookRange; sheetName: string; start: [number, number] } | { absEndCol: boolean; absStartCol: boolean; endCol: number; kind: typeof FormulaNodeKind.ColumnRange; startCol: number } | { absEndRow: boolean; absStartRow: boolean; endRow: number; kind: typeof FormulaNodeKind.RowRange; startRow: number } | { args: FormulaAST[]; kind: typeof FormulaNodeKind.Call; name: string } | { args: FormulaAST[]; callee: FormulaAST; kind: typeof FormulaNodeKind.Invoke } | { kind: typeof FormulaNodeKind.Binary; left: FormulaAST; op: BinaryOp; right: FormulaAST } | { kind: typeof FormulaNodeKind.Unary; op: UnaryOp; operand: FormulaAST }

Serializable formula abstract syntax tree.

typeFormulaCalculationTraceEventsource ↗
type FormulaCalculationTraceEvent = FormulaBatchFlushedEvent | FormulaRecalculationCompletedEvent | FormulaErrorChangedEvent | FormulaDependenciesChangedEvent

Formula calculation trace event union.

typeFormulaCalculationTraceEventPayloadsource ↗
type FormulaCalculationTraceEventPayload = conditional

Trace event payload before the provider assigns its sequence number.

typeFormulaCalculationTraceListenersource ↗
type FormulaCalculationTraceListener = (event: FormulaCalculationTraceEvent): void

Listener invoked synchronously for calculation trace events.

typeFormulaCellSourcesource ↗
type FormulaCellSource = "empty" | "value" | "formula"

Origin of a persisted cell, kept distinct from its calculated value.

typeFormulaCubeKpiPropertysource ↗
type FormulaCubeKpiProperty = typeof FormulaCubeKpiProperty[keyof typeof FormulaCubeKpiProperty]

Type contract carried by the canonical FormulaCubeKpiProperty value.

typeFormulaCubeMemberExpressionsource ↗
type FormulaCubeMemberExpression = string | FormulaCubeMemberValue | readonly FormulaCubeMemberExpression[]

Serializable member or tuple expression accepted by CUBE services.

typeFormulaCubeQuerysource ↗
type FormulaCubeQuery = { caption?: string; connection: string; kind: "kpi-member"; kpiName: string; property: FormulaCubeKpiProperty } | { caption?: string; connection: string; expression: FormulaCubeMemberExpression; kind: "member" } | { connection: string; kind: "member-property"; member: FormulaCubeMemberExpression; property: string } | { caption?: string; connection: string; kind: "ranked-member"; rank: number; set: string | FormulaCubeSetValue } | { caption?: string; connection: string; expression: string; kind: "set"; sortBy?: string; sortOrder?: number } | { kind: "set-count"; set: FormulaCubeSetValue } | { connection: string; kind: "value"; members: readonly FormulaCubeMemberExpression[] }

Serializable query handled by a host-owned CUBE service.

typeFormulaCubeResultsource ↗
type FormulaCubeResult = FormulaValue | FormulaCubeMemberValue | FormulaCubeSetValue | FormulaError

Value returned from a host-owned CUBE service.

typeFormulaDateSystemsource ↗
type FormulaDateSystem = typeof FormulaDateSystem[keyof typeof FormulaDateSystem]

Workbook date serial systems supported by formula evaluation.

typeFormulaDynamicDependencyRegistrarsource ↗
type FormulaDynamicDependencyRegistrar = (reference: ResolvedFormulaRange): void

Callback used to publish dynamic formula dependency edges.

typeFormulaErrorCodesource ↗
type FormulaErrorCode = typeof FormulaErrorCode[keyof typeof FormulaErrorCode]

Type contract carried by the canonical FormulaErrorCode value.

typeFormulaFunctionArgumentKindsource ↗
type FormulaFunctionArgumentKind = "any" | "number" | "text" | "boolean" | "cell" | "range" | "array" | "reference" | "function" | "rich"

Coarse argument kinds stable across formula-engine implementations.

typeFormulaLanguageServiceResultsource ↗
type FormulaLanguageServiceResult = FormulaServiceCacheResult<string>

Synchronous result exposed by a host-managed language-service cache.

typeFormulaNodeKindsource ↗
type FormulaNodeKind = typeof FormulaNodeKind[keyof typeof FormulaNodeKind]

Type contract carried by the canonical FormulaNodeKind value.

typeFormulaRangeSourcesource ↗
type FormulaRangeSource = { kind: typeof FormulaRangeSourceKind.CurrentSheet } | { kind: typeof FormulaRangeSourceKind.WorkbookSheet; sheetName: string }

Source owner for a resolved formula range.

typeFormulaRangeSourceKindsource ↗
type FormulaRangeSourceKind = typeof FormulaRangeSourceKind[keyof typeof FormulaRangeSourceKind]

Type contract carried by the canonical FormulaRangeSourceKind value.

typeFormulaReferenceNodesource ↗
type FormulaReferenceNode = Extract<FormulaAST, { kind: typeof FormulaNodeKind.Cell | typeof FormulaNodeKind.Range | typeof FormulaNodeKind.WorkbookCell | typeof FormulaNodeKind.WorkbookRange | typeof FormulaNodeKind.RowRange | typeof FormulaNodeKind.ColumnRange }>

Reference leaves shared by immutable formula transformations.

typeFormulaReferenceStylesource ↗
type FormulaReferenceStyle = "A1" | "R1C1"

Reference notation accepted by a reference resolver.

typeFormulaRichResultsource ↗
type FormulaRichResult = FormulaHyperlinkResult | FormulaImageResult

Host-neutral result projected by a formula cell renderer.

typeFormulaServiceCacheResultsource ↗
type FormulaServiceCacheResult = { status: typeof FormulaServiceCacheStatus.Ready; value: T } | { status: typeof FormulaServiceCacheStatus.Pending | typeof FormulaServiceCacheStatus.Unavailable }

Synchronous cache result; asynchronous work stays outside formula evaluation.

typeFormulaValuesource ↗
type FormulaValue = null | number | string | boolean | FormulaText | FormulaError | FormulaReferenceValue | FormulaTupleValue | FormulaCubeMemberValue | FormulaCubeSetValue | FormulaValue[]

Scalar, collection, error, or reference result produced by formulas.

typeStructureChangesource ↗
type StructureChange = StructureInsertDeleteChange | StructureMoveChange

Public contract for one formula-aware structure change.

typeStructureChangeAxissource ↗
type StructureChangeAxis = typeof StructureChangeAxis[keyof typeof StructureChangeAxis]

Type contract carried by StructureChangeAxis.

typeStructureChangeKindsource ↗
type StructureChangeKind = typeof StructureChangeKind[keyof typeof StructureChangeKind]

Type contract carried by StructureChangeKind.

typeStructureChangeTypesource ↗
type StructureChangeType = MatrixOTActionName.RowInsert | MatrixOTActionName.RowDelete | MatrixOTActionName.RowMove | MatrixOTActionName.ColInsert | MatrixOTActionName.ColDelete | MatrixOTActionName.ColMove

Matrix structure action understood by formula reference transforms.

typeUnaryOpsource ↗
type UnaryOp = "-" | "+" | "%" | "NOT"

Supported unary formula operators.

variableFormulaAddInServiceDefinitionsource ↗
FormulaAddInServiceDefinition: FormulaExternalServiceDefinition<FormulaAddInService>

Typed identity used to publish a host-specific add-in implementation.

variableFormulaBatchFlushedEventTypesource ↗
FormulaBatchFlushedEventType: "formula.batchFlushed"

Stable event id for a formula batch flush.

variableFormulaCalculationTraceEventTypesource ↗
FormulaCalculationTraceEventType: { BatchFlushed: "formula.batchFlushed"; DependenciesChanged: "formula.dependenciesChanged"; ErrorChanged: "formula.errorChanged"; RecalculationCompleted: "formula.recalculationCompleted" }

Stable formula calculation trace event ids.

variableFormulaCubeKpiPropertysource ↗
FormulaCubeKpiProperty: { KPICurrentTimeMember: 6; KPIGoal: 2; KPIStatus: 3; KPITrend: 4; KPIValue: 1; KPIWeight: 5 }

Stable CUBE KPI property identifiers.

variableFormulaCubeServiceDefinitionsource ↗
FormulaCubeServiceDefinition: FormulaExternalServiceDefinition<FormulaCubeService>

Typed identity used to publish a host-specific CUBE implementation.

variableFormulaDateSystemsource ↗
FormulaDateSystem: { Excel1900: 1900; Excel1904: 1904 }

Workbook date serial systems supported by formula evaluation.

variableFormulaDependenciesChangedEventTypesource ↗
FormulaDependenciesChangedEventType: "formula.dependenciesChanged"

Stable event id for a formula dependency transition.

variableFormulaErrorChangedEventTypesource ↗
FormulaErrorChangedEventType: "formula.errorChanged"

Stable event id for a formula error transition.

variableFormulaErrorCodesource ↗
FormulaErrorCode: { DivisionByZero: "#DIV/0!"; Name: "#NAME?"; NotAvailable: "#N/A"; NullIntersection: "#NULL!"; Number: "#NUM!"; Reference: "#REF!"; Spill: "#SPILL!"; Value: "#VALUE!" }

Canonical Excel-compatible formula error code values.

variableFormulaGoogleServiceDefinitionsource ↗
FormulaGoogleServiceDefinition: FormulaExternalServiceDefinition<FormulaGoogleService>

Host-neutral service identity shared by Google-compatible cached formulas.

variableFormulaHyperlinkServiceDefinitionsource ↗
FormulaHyperlinkServiceDefinition: FormulaExternalServiceDefinition<FormulaHyperlinkService>

Typed identity for the host hyperlink service.

variableFormulaImageServiceDefinitionsource ↗
FormulaImageServiceDefinition: FormulaExternalServiceDefinition<FormulaImageService>

Typed identity for the host image service.

variableFormulaLanguageServiceDefinitionsource ↗
FormulaLanguageServiceDefinition: FormulaExternalServiceDefinition<FormulaLanguageService>

Canonical service identity used by cached language formulas and their hosts.

variableFormulaNodeKindsource ↗
FormulaNodeKind: { Array: "array"; Binary: "binary"; Boolean: "boolean"; Call: "call"; Cell: "cell"; ColumnRange: "columnRange"; Error: "error"; Intersection: "intersection"; … }

Stable discriminants used by formula AST nodes.

variableFormulaPivotDataServiceDefinitionsource ↗
FormulaPivotDataServiceDefinition: FormulaExternalServiceDefinition<FormulaPivotDataService>

Typed identity for the host pivot-data service.

variableFormulaRangeSourceKindsource ↗
FormulaRangeSourceKind: { CurrentSheet: "currentSheet"; WorkbookSheet: "workbookSheet" }

Stable source kinds for resolved formula ranges.

variableFormulaRecalculationCompletedEventTypesource ↗
FormulaRecalculationCompletedEventType: "formula.recalculationCompleted"

Stable event id for formula recalculation completion.

variableFormulaRtdServiceDefinitionsource ↗
FormulaRtdServiceDefinition: FormulaExternalServiceDefinition<FormulaRtdService>

Typed identity for the host RTD service.

variableFormulaServiceCacheStatussource ↗
FormulaServiceCacheStatus: { Pending: "pending"; Ready: "ready"; Unavailable: "unavailable" }

Canonical states of a host-managed formula service cache.

variableFormulaStockHistoryServiceDefinitionsource ↗
FormulaStockHistoryServiceDefinition: FormulaExternalServiceDefinition<FormulaStockHistoryService>

Stable external-service identity used by STOCKHISTORY and host caches.

variableFormulaStructureChangeActionNamessource ↗
FormulaStructureChangeActionNames: readonly StructureChangeType[]

Matrix OT action names that participate in formula reference rebasing.

variableFormulaWebLimitssource ↗
FormulaWebLimits: Readonly<{ textLength: 32767; urlLength: 2048 }>

Excel limits applied independently of the host's transport/security policy.

variableFormulaWebServiceDefinitionsource ↗
FormulaWebServiceDefinition: FormulaExternalServiceDefinition<FormulaWebService>

Shared identity for WEBSERVICE cache registration and recalculation.

variableStructureChangeAxissource ↗
StructureChangeAxis: { Col: "col"; Row: "row" }

Axis affected by one formula structure change.

variableStructureChangeKindsource ↗
StructureChangeKind: { Delete: "delete"; Insert: "insert"; Move: "move" }

Semantic kind of one formula structure change.

functionassertSupportedStructureChangesource ↗
assertSupportedStructureChange(change: StructureChange): void

Validates indices on a formula structure change before rebasing.

change: StructureChange
functioncreateFormulaErrorsource ↗
createFormulaError<T>(code: T): FormulaError & { code: T }

Creates a validated serializable formula error value.

code: T
functiondefineFormulaExternalServicesource ↗
defineFormulaExternalService<T>(id: string, options?: Pick<FormulaExternalServiceDefinition<T>, "subscribeInvalidation">): FormulaExternalServiceDefinition<T>

Creates a stable external-service definition shared by hosts and plugins.

id: string
options: Pick<FormulaExternalServiceDefinition<T>, "subscribeInvalidation">
functiongetStructureChangeAxissource ↗
getStructureChangeAxis(change: StructureChange): StructureChangeAxis | undefined

Returns the axis affected by one structure change.

change: StructureChange
functiongetStructureChangeKindsource ↗
getStructureChangeKind(change: StructureChange): StructureChangeKind | undefined

Returns whether one structure change inserts, deletes, or moves coordinates.

change: StructureChange
functionisFormulaArgumentKindsource ↗
isFormulaArgumentKind<K>(arg: FormulaArgumentLike | null | undefined, ...kinds: readonly K[]): arg

Narrows a formula argument to one or more discriminant kinds.

arg: FormulaArgumentLike | null | undefined
kinds: readonly K[]
functionisFormulaErrorsource ↗
isFormulaError(value: unknown): value

Returns whether a formula value is an error value.

value: unknown
functionisFormulaErrorCodesource ↗
isFormulaErrorCode(code: unknown): code

Reports whether a runtime value is a canonical formula error code.

code: unknown
functionmapFormulaReferenceNodessource ↗
mapFormulaReferenceNodes(ast: FormulaAST, map: (node: FormulaReferenceNode): FormulaAST): FormulaAST

Traverses expression containers while preserving unchanged node identities.

ast: FormulaAST
map: (node: FormulaReferenceNode): FormulaAST
functionmatrixOperationsToStructureChangessource ↗
matrixOperationsToStructureChanges(operations: readonly OTOperation[]): StructureChange[]

Converts Matrix OT operations into formula structure changes.

operations: readonly OTOperation[]
functionmatrixOperationToStructureChangesource ↗
matrixOperationToStructureChange(operation: OTOperation): StructureChange | null

Converts one Matrix OT structure operation into a formula structure change.

operation: OTOperation
functionmoveFormulaReferencessource ↗
moveFormulaReferences(ast: FormulaAST, move: FormulaRangeMove): FormulaAST

Moves referenced identities, including absolute references, without rebasing unrelated references.

ast: FormulaAST
move: FormulaRangeMove
functionreorderFormulaReferencessource ↗
reorderFormulaReferences(ast: FormulaAST, changes: readonly StructureMoveChange[], options?: FormulaStructureMoveOptions): FormulaAST

Reorders reference identities (including absolute references) through the entire permutation.

ast: FormulaAST
changes: readonly StructureMoveChange[]
options: FormulaStructureMoveOptions
functionshiftStructureCoordinatesource ↗
shiftStructureCoordinate(input: { absolute?: boolean; axis: StructureChangeAxis; changes: readonly StructureChange[]; coordinate: number }): ShiftedStructureCoordinate

Shifts one coordinate through formula structure changes.

input: { absolute?: boolean; axis: StructureChangeAxis; changes: readonly StructureChange[]; coordinate: number }
variableFormulaCubeKpiPropertyValuesource ↗
FormulaCubeKpiPropertyValue: { KPICurrentTimeMember: 6; KPIGoal: 2; KPIStatus: 3; KPITrend: 4; KPIValue: 1; KPIWeight: 5 }

Stable CUBE KPI property identifiers.