Skip to content
SumOfficeSumOfficeSumOffice

Types: formulas and calculation

Compute Contract type definitions — recalculation, dependencies, auditing, names, and what-if analysis. Names: 69.

Definitions of the names from the “TypeScript type” column on the operation pages.

Other dictionary topics: session, workbook, and sheets · cells and ranges · formulas and calculation · formatting · data and sheet objects · pivot tables · charts and graphics · printing and page layout · Power Query · VBA and macros · protection and review · general and utility.

Types on this page — 69
interface ContractArrayFormulaTrustMetadata {
kind: "legacy_array_formula" | "dynamic_array_formula" | string;
role: "anchor" | "follower" | string;
refRange?: string | null;
formulaTextAvailable: boolean;
}
interface ContractCalcChainTrustMetadata {
order: number;
cellRef: string;
sheetId?: string | null;
}
interface ContractCalculationCommandState {
enabled: boolean;
active: boolean;
reasonCode?: string | null;
}
interface ContractCalculationCommandStates {
automatic: ContractCalculationCommandState;
automaticExceptDataTables: ContractCalculationCommandState;
manual: ContractCalculationCommandState;
calculateNow: ContractCalculationCommandState;
calculateSheet: ContractCalculationCommandState;
}
type ContractCalculationDataTablePolicy = "excluded_unsupported";
type ContractCalculationOptionsHistoryAction = "set" | "undo" | "redo";
interface ContractCalculationPolicySnapshot {
status: ContractCalculationStatus;
calculationMode: ContractWorkbookCalculationMode;
dataTablePolicy: ContractCalculationDataTablePolicy;
recalcNeeded: boolean;
supportedFormulaCount: number;
dirtyFormulaCount: number;
staleCachedFormulaCount: number;
unsupportedFormulaCount: number;
commandStates: ContractCalculationCommandStates;
note: string;
}
interface ContractCalculationPropertiesSnapshot {
calculationMode: ContractWorkbookCalculationMode;
recalculateBeforeSave?: boolean | null;
fullCalculationOnLoad?: boolean | null;
forceFullCalculation?: boolean | null;
iterativeSettings: ContractIterativeCalculationSettings;
calculationId?: number | null;
calculationCompleted?: boolean | null;
fullPrecision?: boolean | null;
}
type ContractCalculationScope = { kind: "workbook" } | { kind: "sheet"; sheetKey: string };
type ContractCalculationStatus = "clean" | "dirty" | "calculating" | "canceled" | "blocked" | "unsupported";
interface ContractCalculationTrust {
state: ContractCalculationTrustState;
formulaText: string;
cachedDisplayValue: string | null;
workbookCalcMode: ContractWorkbookCalculationMode;
cachedValueFreshness: ContractFormulaCachedValueFreshness;
recalcRequiredReasons: ContractRecalcRequiredReason[];
directPrecedentKeys: string[];
unsupportedReferences: string[];
spillObstructionKind?:
| "occupied_cell"
| "out_of_bounds"
| "merged_range"
| "table"
| "protected_cell"
| string
| null;
spillObstructionCellKey?: string | null;
spillObstructionDetail?: string | null;
structuredReferences?: ContractStructuredReferenceTrustMetadata[];
externalReferences?: Array<
| ContractExternalWorkbookReferenceTrustMetadata
| ContractExternalReferenceTrustMetadata
>;
note: string;
}
type ContractCalculationTrustState =
| "live_calculated"
| "imported_cached"
| "dirty_recalc_needed"
| "stale_cache_recalc_required"
| "unsupported_function"
| "unsupported_reference_shape"
| "unsupported_shared_formula_shape"
| "unsupported_array_shape"
| "unsupported_dynamic_array_shape"
| "unsupported_defined_name_shape"
| "unsupported_structured_ref_shape"
| "unsupported_shape"
| "depends_on_unsupported"
| "volatile_boundary"
| "external_cached_unresolved"
| "external_link_missing"
| "external_link_blocked"
| "external_ref_unsupported_shape"
| "external_ref_cached_stale"
| "depends_on_external_unresolved";
interface ContractDataCleanupAudit {
schemaVersion: 1;
operationKind:
"text_to_columns" | "remove_duplicates" | "remove_duplicates_copy";
mutationMode: "in_place" | "copy_output";
sourceRange: CellRange;
outputRange: CellRange;
sourceRowCount: number;
sourceColCount: number;
resultRowCount: number;
resultColCount: number;
duplicateCount: number;
remainingCount: number;
headerRowCount: number;
totalsRowCount: number;
plannedChangeCount: number;
duplicateRowSpans: ContractDataCleanupRowSpan[];
cellPayloadPolicy: string;
coordinateArtifactPolicy: string;
}
type ContractDefinedNameKind = "range" | "constant" | "formula" | "lambda" | "invalid";
interface ContractDefinedNameReferenceBase {
sheetKey: string;
row: number;
col: number;
}
type ContractDefinedNameScope = "workbook" | "sheet";
interface ContractDefinedNameSelectionEdges {
top?: boolean;
left?: boolean;
bottom?: boolean;
right?: boolean;
}
interface ContractDefinedNameTrustMetadata {
name: string;
scope: string;
shape: string;
targetSheetKey?: string | null;
targetRange?: string | null;
resolutionState: string;
}
interface ContractDefinedNameValue {
name: string;
scope: string;
ownerSheetKey?: string | null;
value: string;
ok: boolean;
error?: string | null;
}
interface ContractDefinedNameView {
identity: string;
name: string;
scope: ContractDefinedNameScope;
localSheetId?: number | null;
scopeSheetKey?: string | null;
scopeSheetName?: string | null;
refersTo: string;
comment?: string | null;
kind: ContractDefinedNameKind;
hidden: boolean;
editable: boolean;
editBlockReason?: string | null;
resolvedRange?: CellRange | null;
resolvedValue?: string | null;
valueError?: string | null;
visibleOnActiveSheet: boolean;
shadowedOnActiveSheet: boolean;
}
type ContractDefinedNamesIntent =
| { action: "list"; activeSheetKey?: string
| null }
| ({ action: "create"; name: string; refersTo: string; relativeTo?: ContractDefinedNameReferenceBase
| null; scope: ContractDefinedNameScope; scopeSheetKey?: string
| null; comment?: string
| null; } & DefinedNamesMutationGuard)
| ({ action: "update";
previousName: string;
previousScope: ContractDefinedNameScope;
previousScopeSheetKey?: string
| null; name: string; refersTo: string; relativeTo?: ContractDefinedNameReferenceBase
| null; scope: ContractDefinedNameScope; scopeSheetKey?: string
| null; comment?: string
| null; } & DefinedNamesMutationGuard)
| ({ action: "delete"; name: string; scope: ContractDefinedNameScope; scopeSheetKey?: string
| null; } & DefinedNamesMutationGuard)
| ({ action: "create_from_selection";
selection: CellRange;
edges: ContractDefinedNameSelectionEdges;
scope: ContractDefinedNameScope;
} & DefinedNamesMutationGuard)
| ({ action: "define_selection";
name: string;
selection: CellRange;
scope: ContractDefinedNameScope;
} & DefinedNamesMutationGuard)
| ({ action: "undo" } & DefinedNamesMutationGuard)
| ({ action: "redo" } & DefinedNamesMutationGuard);
interface ContractDefinedNamesResult {
status:
| "listed"
| "created"
| "updated"
| "deleted"
| "created_from_selection"
| "undone"
| "redone";
revision: number;
entries: ContractDefinedNameView[];
undoDepth: number;
redoDepth: number;
mutatedCount: number;
activeSheetKey?: string | null;
}
interface ContractDependencyGraphSnapshot {
queryNodes: string[];
queryEdges: ContractQueryDependencyEdge[];
paramNodes: string[];
paramEdges: ContractParamEdge[];
topoOrder?: string[] | null;
topoBlockedReason?: string | null;
}
type ContractFormatNonGoal = (typeof CONTRACT_FORMAT_NON_GOAL_IDS)[number];
interface ContractFormulaAuditActions {
ignoreError: boolean;
restoreIgnored: boolean;
applyFix: boolean;
resetIgnored: boolean;
addWatch: boolean;
removeWatch: boolean;
clearWatches: boolean;
}
interface ContractFormulaAuditCellProjection {
workbookId?: string;
workbookSessionId?: string;
cellKey: string;
sheetKey: string;
sheetName: string;
sheetOrder: number;
row: number;
col: number;
address: string;
formula: string | null;
formulaHidden: boolean;
value: ContractFormulaEvaluationValue;
valueType: string;
errorCode: string | null;
calculationState: ContractCalculationTrustState;
workbookCalcMode: ContractWorkbookCalculationMode;
cachedValueFreshness: ContractFormulaCachedValueFreshness;
recalcRequiredReasons: ContractRecalcRequiredReason[];
spillRole: "owner" | "follower" | "none";
spillOwnerKey: string | null;
navigationTargetKey: string;
}
interface ContractFormulaAuditCounts {
findings: number;
ignored: number;
watches: number;
}
interface ContractFormulaAuditFinding {
identity?: string;
revision?: number;
kind: ContractFormulaAuditFindingKind;
ignored: boolean;
nativeIgnoredFlag: string;
explanationCode: string;
relatedKeys: string[];
safeFix?: ContractFormulaAuditFix;
cell: ContractFormulaAuditCellProjection;
}
type ContractFormulaAuditFindingKind =
| "div0"
| "na"
| "value"
| "ref"
| "name"
| "num"
| "circular_reference"
| "inconsistent_formula"
| "omitted_adjacent_cell"
| "number_stored_as_text"
| "stale_dependency"
| "unsupported_formula_boundary";
interface ContractFormulaAuditFix {
kind: ContractFormulaAuditFixKind;
labelCode: string;
replacementPreview: string;
}
type ContractFormulaAuditFixKind = | "convert_number_stored_as_text" | "copy_consistent_formula" | "extend_adjacent_range";
type ContractFormulaAuditOutcome = "ready" | "mutated" | "stale" | "blocked" | "unavailable";
type ContractFormulaAuditWatchAction =
| "read"
| "ignore_error"
| "restore_ignored"
| "apply_fix"
| "reset_ignored"
| "add_watch"
| "remove_watch"
| "clear_watches";
interface ContractFormulaAuditWatchRow {
revision: number;
cell: ContractFormulaAuditCellProjection;
}
type ContractFormulaAuditingStatePersistence = "workbook_persistent" | "window_transient";
interface ContractFormulaBuilderArgument {
id: string;
localizedName: string;
description: string;
kind: ContractFormulaBuilderArgumentKind;
required: boolean;
repeating: boolean;
repeatGroupSize?: number;
}
type ContractFormulaBuilderArgumentKind = "scalar" | "range" | "multi-range" | "enum";
type ContractFormulaBuilderAvailability = "live" | "unsupported";
interface ContractFormulaBuilderCatalog {
schemaVersion: number;
locale: string;
semanticOwner: "rust";
functions: ContractFormulaBuilderFunction[];
}
interface ContractFormulaBuilderFunction {
identity: string;
canonicalName: string;
localizedName: string;
localizedDescription: string;
category: string;
availability: ContractFormulaBuilderAvailability;
arguments: ContractFormulaBuilderArgument[];
}
type ContractFormulaCachedValueFreshness =
| "live_calculated"
| "imported_cached"
| "dirty_recalc_needed"
| "stale_cache_recalc_required"
| "no_cached_value";
type ContractFormulaEvaluationAction = "start" | "evaluate" | "step_in" | "step_out" | "restart" | "close";
interface ContractFormulaEvaluationActions {
evaluate: boolean;
stepIn: boolean;
stepOut: boolean;
restart: boolean;
close: boolean;
}
interface ContractFormulaEvaluationDiagnostic {
kind:
| "typed_error"
| "circular"
| "manual"
| "unsupported"
| "stale"
| "cancelled"
| string;
code: string;
message: string;
cellKey?: string | null;
sourceSpan?: ContractFormulaEvaluationSourceSpan | null;
path: string[];
}
type ContractFormulaEvaluationOutcome = | "ready" | "complete" | "closed" | "stale" | "manual_pending" | "circular" | "unavailable";
interface ContractFormulaEvaluationSourceSpan {
utf8ByteStart: number;
utf8ByteEnd: number;
utf16Start: number;
utf16End: number;
sourceSlice: string;
}
interface ContractFormulaEvaluationStackFrame {
frameId: string;
parentFrameId?: string | null;
cellKey: string;
formulaSource: string;
callSiteSpan?: ContractFormulaEvaluationSourceSpan | null;
depth: number;
}
interface ContractFormulaEvaluationStep {
stepId: string;
ordinal: number;
parentStepId?: string | null;
depth: number;
sourceSpan: ContractFormulaEvaluationSourceSpan;
canonicalExpression: string;
substitutedExpression: string;
value: ContractFormulaEvaluationValue;
trust: ContractFormulaEvaluationTrust;
referenceTargetKey?: string | null;
}
interface ContractFormulaEvaluationTrust {
calculationState: ContractCalculationTrustState | string;
workbookCalculationMode: ContractWorkbookCalculationMode;
cachedValueFreshness: ContractFormulaCachedValueFreshness | string;
recalcRequiredReasons: string[];
volatileContextId?: string | null;
cyclePath: string[];
spillRole: "owner" | "follower" | "none";
spillOwnerKey?: string | null;
diagnosticOnly: boolean;
}
type ContractFormulaEvaluationValue =
| { kind: "blank"; displayText: string }
| { kind: "empty_string"; displayText: string }
| { kind: "number"; value: number; displayText: string }
| { kind: "boolean"; value: boolean; displayText: string }
| { kind: "text"; value: string; displayText: string }
| { kind: "computed_text"; value: string; displayText: string }
| { kind: "live_error"; code: string; displayText: string }
| { kind: "imported_error"; code: string; displayText: string }
| { kind: "array";
rowCount: number;
colCount: number;
values: ContractFormulaEvaluationValue[];
displayText: string;
}
| { kind: "unavailable"; reason: string; displayText: string };
type ContractFormulaTraceDirection = "precedent" | "dependent";
interface ContractFormulaTraceEdge {
edgeId: string;
direction: ContractFormulaTraceDirection;
depth: number;
sourceKey: string;
targetKey: string;
status: ContractFormulaTraceEdgeStatus;
crossSheet: boolean;
referenceText?: string | null;
}
type ContractFormulaTraceEdgeStatus = | "resolved" | "cycle" | "missing_or_deleted_reference" | "unsupported_boundary";
interface ContractFormulaTrustCell {
cellKey: string;
sheetKey: string;
row: number;
col: number;
rawFormula: string;
cachedValue?: string | null;
publishedResultType?:
"blank" | "emptyString" | "number" | "logical" | "text" | "error" | null;
supportedStatus: FormulaSubsetStatus;
unsupportedReason?: string | null;
spillObstructionKind?:
| "occupied_cell"
| "out_of_bounds"
| "merged_range"
| "table"
| "protected_cell"
| string
| null;
spillObstructionCellKey?: string | null;
spillObstructionDetail?: string | null;
referenceShapes: string[];
sharedFormula?: ContractSharedFormulaTrustMetadata | null;
calcChain?: ContractCalcChainTrustMetadata | null;
arrayFormula?: ContractArrayFormulaTrustMetadata | null;
arrayDynamicShapes: string[];
definedNames: ContractDefinedNameTrustMetadata[];
structuredReferences: ContractStructuredReferenceTrustMetadata[];
externalReferences: ContractExternalWorkbookReferenceTrustMetadata[];
directDependenciesWhenKnown: string[];
directDependenciesTruncated?: boolean;
calculationState: ContractCalculationTrustState;
workbookCalcMode: ContractWorkbookCalculationMode;
cachedValueFreshness: ContractFormulaCachedValueFreshness;
recalcRequiredReasons: ContractRecalcRequiredReason[];
}
interface ContractFormulaTrustSnapshot {
scope: string;
supportedSubset: string;
workbookCalcMode: ContractWorkbookCalculationMode;
workbookCalcOnSave?: boolean | null;
iterativeCalculationEnabled: boolean;
iterativeCalculationMaximumIterations: number;
iterativeCalculationMaximumChange: string;
iterativeCalculationOutcomes: ContractIterativeCalculationOutcome[];
parallelRecalc: ContractParallelRecalcInstrumentation;
calculationPolicy: ContractCalculationPolicySnapshot;
formulaCellsWindow?: ContractFormulaTrustCellsWindow | null;
formulaCellTotals?: ContractFormulaTrustTotals | null;
formulaCells: ContractFormulaTrustCell[];
}
interface ContractFormulaTrustTotals {
formulaCellCount: number;
supportedFormulaCellCount: number;
referenceValuedFormulaCellCount: number;
}
interface ContractIterativeCalculationOutcome {
cellKeys: string[];
status: ContractIterativeCalculationStatus;
iterations: number;
maximumIterations: number;
maximumChange: string;
lastMaximumChange: string;
errorCode?: string | null;
}
interface ContractIterativeCalculationSettings {
enabled: boolean;
maximumIterations: number;
maximumChange: number;
}
type ContractIterativeCalculationStatus = "converged" | "non_converged" | "iteration_disabled" | "unsupported";
interface ContractSharedFormulaTrustMetadata {
role: string;
sharedIndex: string;
anchorCellKey?: string | null;
refRange?: string | null;
expandedFromAnchor: boolean;
formulaTextAvailable: boolean;
}
type ContractTrustCenterAuditCategory =
| "source_trust"
| "macros"
| "external_links"
| "data_connections"
| "trusted_locations"
| "protected_files";
interface ContractTrustCenterAuditEntry {
schemaVersion: 1;
category: ContractTrustCenterAuditCategory;
action: ContractSourceTrustAction;
allowed: boolean;
reasonCode: ContractSourceTrustReason;
policyState: ContractTrustCenterPolicyState;
trustStoreRevision: number;
trustStoreHash: string;
}
interface ContractWhatIfScenarioInput {
cell: ContractWhatIfCellRef;
value: ContractWhatIfValue;
}
interface ContractWhatIfScenarioView {
stableId: string;
name: string;
comment?: string | null;
locked: boolean;
hidden: boolean;
permissions: {
readable: boolean;
showable: boolean;
editable: boolean;
deletable: boolean;
};
inputs: ContractWhatIfScenarioInput[];
}
interface ContractXlsxDefinedNameDeletePatch {
name: string;
scope?: ContractXlsxDefinedNameScope | null;
activeSheetPath?: string | null;
scopeSheetPath?: string | null;
localSheetId?: number | null;
}
interface ContractXlsxDefinedNamePatch {
name: string;
activeSheetPath: string;
ref?: string | null;
refersTo?: string | null;
scope?: ContractXlsxDefinedNameScope | null;
scopeSheetPath?: string | null;
scopeSheetName?: string | null;
localSheetId?: number | null;
valueKind?: ContractXlsxDefinedNameValueKind | null;
comment?: string | null;
}
type ContractXlsxDefinedNameScope = "workbook" | "sheet";
type ContractXlsxDefinedNameValueKind = "range" | "number" | "text" | "formula" | "logical" | "date" | "error";
type MWireTypeName =
| "any"
| "null"
| "logical"
| "number"
| "text"
| "date"
| "integer"
| "datetime"
| "datetimezone"
| "time"
| "duration"
| "binary"
| "list"
| "record"
| "table"
| "function"
| "type";

Documentation assistant

Answers are assembled from the documentation and may be inaccurate — check the sources.