API reference

@searsuite/sear-domain-workbook

Stable workbook and Sheet identities, structure, and document-state contracts.

Search exports in this package

56 exportsderived from source

Concept 1

Separate Workbook structure from the active Sheet session

WorkbookDocumentState holds stable Sheet identities, order, names, visibility, and each Sheet's document state. WorkbookSessionState holds local values needed to remount the active Sheet. Internal references use stable sheetId values so renaming a Sheet changes its label without changing its identity.

The Workbook assembly mounts one active Sheet editor. Before switching, it captures that Sheet's document and local session, tears down the editor, and mounts the next Sheet. Switching back restores the captured session; viewport state does not become durable Workbook content.

Concept 2

Change Workbook structure through staged operations

addWorkbookSheet(), moveWorkbookSheet(), and related operations describe structural changes. The Workbook assembly stages add, remove, move, rename, hide, and unhide commands as Workbook transactions, with history separate from edits inside a mounted Sheet.

Use when: managing several Sheets or resolving references across them. Keep structural reads and identity in the Workbook domain; use the active Sheet editor and its feature commands for cell content or appearance. Formula references and collaboration channels use stable Sheet identities rather than mutable display names.

classWorkbookError source ↗

class WorkbookError extends SearError

Error thrown when workbook state or workbook references violate their domain contract.

constructorconstructor

WorkbookError(code: WorkbookErrorCode, message: string, details?: SearErrorDetails): WorkbookError

Creates a WorkbookError instance.

code: WorkbookErrorCode
message: string
details: SearErrorDetails

propertycode

readonly code: WorkbookErrorCode

Stable machine-readable error code.

Inherited members 9

Inherited from SearError.

interfaceAddWorkbookSheetInput source ↗

interface AddWorkbookSheetInput<SheetState>

Input accepted by addWorkbookSheet.

propertyindex

readonly index?: number

Optional insertion index; defaults to appending after the current last sheet.

propertysheet

readonly sheet: WorkbookSheetDescriptor

Descriptor for the sheet being inserted.

propertysheetState

readonly sheetState: SheetState

Initial state payload for the inserted sheet.

interfaceCreateWorkbookDocumentStateInput source ↗

interface CreateWorkbookDocumentStateInput<SheetState>

Input accepted by createWorkbookDocumentState.

propertyid

readonly id: string

Stable workbook id used by persistence and collaboration rooms.

propertymetadata

readonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata copied onto the workbook state.

propertysheets

readonly sheets: readonly WorkbookSheetDescriptor[]

Ordered sheet descriptors.

propertysheetStates

readonly sheetStates: WorkbookSheetStateMap<SheetState>

Per-sheet state payloads keyed by sheet id.

interfaceMoveWorkbookSheetInput source ↗

interface MoveWorkbookSheetInput

Input accepted by moveWorkbookSheet.

propertysheetId

readonly sheetId: string

Sheet id to move.

propertytoIndex

readonly toIndex: number

Destination index in WorkbookDocumentState.sheets.

interfaceParsedWorkbookFormulaReference source ↗

interface ParsedWorkbookFormulaReference

Parsed workbook formula reference bound to a stable sheet id.

propertyrange

readonly range: WorkbookRangeReference

Normalized workbook range. Single-cell references use the same start and end coordinate.

propertysheetId

readonly sheetId: string

Stable sheet id resolved from the user-facing formula sheet name.

interfaceRemoveWorkbookSheetInput source ↗

interface RemoveWorkbookSheetInput

Input accepted by removeWorkbookSheet.

propertysheetId

readonly sheetId: string

Sheet id to remove.

interfaceRenameWorkbookSheetInput source ↗

interface RenameWorkbookSheetInput

Input accepted by renameWorkbookSheet.

propertyname

readonly name: string

New user-facing sheet name.

propertysheetId

readonly sheetId: string

Sheet id to rename.

interfaceSetWorkbookSheetHiddenInput source ↗

interface SetWorkbookSheetHiddenInput

Input accepted by setWorkbookSheetHidden.

propertyhidden

readonly hidden: boolean

Whether the sheet should be hidden.

propertysheetId

readonly sheetId: string

Sheet id whose hidden flag should change.

interfaceUpdateWorkbookSheetStateInput source ↗

interface UpdateWorkbookSheetStateInput<SheetState>

Input accepted by updateWorkbookSheetState.

propertysheetId

readonly sheetId: string

Sheet id whose state payload should be replaced.

propertysheetState

readonly sheetState: SheetState

Replacement sheet state payload.

interfaceWorkbookCellReference source ↗

interface WorkbookCellReference

Qualified cell reference used by workbook-level formulas and dependency graphs.

propertycol

readonly col: number

Zero-based column index.

propertyrow

readonly row: number

Zero-based row index.

propertysheetId

readonly sheetId: string

Stable sheet id containing the referenced cell.

interfaceWorkbookColumnRangeReference source ↗

interface WorkbookColumnRangeReference

Qualified whole-column range reference used by workbook-level formulas.

propertyendCol

readonly endCol: number

Zero-based end column index.

propertysheetId

readonly sheetId: string

Stable sheet id containing the referenced columns.

propertystartCol

readonly startCol: number

Zero-based start column index.

interfaceWorkbookDocumentState source ↗

interface WorkbookDocumentState<SheetState>

Workbook state containing sheet metadata plus per-sheet state payloads.

SheetState is generic so this package stays independent from sheet, render, formula, and assembly packages.

propertyid

readonly id: string

Stable workbook id used by persistence and collaboration rooms.

propertymetadata

readonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata that does not affect core workbook semantics.

propertysheets

readonly sheets: readonly WorkbookSheetDescriptor[]

Ordered sheet descriptors; array order is the persisted tab order.

propertysheetStates

readonly sheetStates: WorkbookSheetStateMap<SheetState>

Per-sheet state payloads keyed by stable sheet id.

interfaceWorkbookRangeReference source ↗

interface WorkbookRangeReference

Qualified rectangular range reference used by workbook-level formulas.

propertyend

readonly end: readonly [number, number]

Zero-based bottom-right coordinate.

propertysheetId

readonly sheetId: string

Stable sheet id containing the referenced range.

propertystart

readonly start: readonly [number, number]

Zero-based top-left coordinate.

interfaceWorkbookRowRangeReference source ↗

interface WorkbookRowRangeReference

Qualified whole-row range reference used by workbook-level formulas.

propertyendRow

readonly endRow: number

Zero-based end row index.

propertysheetId

readonly sheetId: string

Stable sheet id containing the referenced rows.

propertystartRow

readonly startRow: number

Zero-based start row index.

interfaceWorkbookSheetDescriptor source ↗

interface WorkbookSheetDescriptor

Workbook-level sheet metadata.

The containing WorkbookDocumentState.sheets array is the only source of sheet order; descriptors intentionally do not carry a separate order field.

propertycolor

readonly color?: string

Optional UI tab color owned by the workbook host.

propertyhidden

readonly hidden?: boolean

Whether the sheet is hidden from normal tab navigation.

propertyid

readonly id: string

Stable sheet id used by workbook state, collaboration envelopes, and formula dependencies.

propertymetadata

readonly metadata?: Readonly<Record<string, unknown>>

Extension-owned serializable metadata that does not affect core workbook semantics.

propertyname

readonly name: string

Unique user-facing sheet name used when displaying formula references.

typeWorkbookCellKey source ↗

type WorkbookCellKey = string

Serialized key for a workbook-qualified formula cell.

typeWorkbookCoordinateAxis source ↗

type WorkbookCoordinateAxis = typeof WorkbookCoordinateAxis[keyof typeof WorkbookCoordinateAxis]

Stable workbook coordinate axis-name type.

typeWorkbookErrorCode source ↗

type WorkbookErrorCode = typeof WorkbookErrorCode[keyof typeof WorkbookErrorCode]

Machine-readable workbook error code type.

typeWorkbookFormulaReference source ↗

type WorkbookFormulaReference = WorkbookCellReference | WorkbookRangeReference | WorkbookColumnRangeReference | WorkbookRowRangeReference

Any workbook-qualified formula reference supported by the workbook protocol.

typeWorkbookId source ↗

type WorkbookId = string

Stable workbook identifier used by host-level workbook registries.

typeWorkbookReferenceDiagnosticField source ↗

type WorkbookReferenceDiagnosticField = WorkbookReferenceField | templateLiteral | templateLiteral

Diagnostic field path emitted by workbook reference validation errors.

typeWorkbookReferenceField source ↗

type WorkbookReferenceField = typeof WorkbookReferenceField[keyof typeof WorkbookReferenceField]

Stable workbook reference property-name type.

typeWorkbookSheetId source ↗

type WorkbookSheetId = string

Stable sheet identifier used inside workbook metadata and cross-sheet references.

typeWorkbookSheetStateMap source ↗

type WorkbookSheetStateMap = Readonly<Record<WorkbookSheetId, SheetState>>

Map from workbook sheet id to the host-selected sheet state payload.

variableWorkbookCoordinateAxis source ↗

WorkbookCoordinateAxis: { col: "col"; row: "row" }

Stable coordinate axis names used by tuple-backed workbook range references.

variableWorkbookCoordinateIndex source ↗

WorkbookCoordinateIndex: { col: 1; row: 0 }

Tuple positions for workbook range coordinates.

variableWorkbookErrorCode source ↗

WorkbookErrorCode: { cannotHideAllSheets: "SEAR_WORKBOOK_CANNOT_HIDE_ALL_SHEETS"; cannotRemoveLastSheet: "SEAR_WORKBOOK_CANNOT_REMOVE_LAST_SHEET"; duplicateSheetId: "SEAR_WORKBOOK_DUPLICATE_SHEET_ID"; duplicateSheetName: "SEAR_WORKBOOK_DUPLICATE_SHEET_NAME"; invalidCellKey: "SEAR_WORKBOOK_INVALID_CELL_KEY"; invalidReference: "SEAR_WORKBOOK_INVALID_REFERENCE"; invalidSheetIndex: "SEAR_WORKBOOK_INVALID_SHEET_INDEX"; invalidSheetName: "SEAR_WORKBOOK_INVALID_SHEET_NAME"; … }

Stable machine-readable error codes owned by the workbook domain package.

variableWorkbookReferenceField source ↗

WorkbookReferenceField: { col: "col"; end: "end"; endCol: "endCol"; endRow: "endRow"; row: "row"; sheetId: "sheetId"; start: "start"; startCol: "startCol"; … }

Stable property names used by workbook-qualified formula references.

functionaddWorkbookSheet source ↗

addWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: AddWorkbookSheetInput<SheetState>): WorkbookDocumentState<SheetState>

Adds a sheet descriptor and its initial state payload without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: AddWorkbookSheetInput<SheetState>

functioncreateWorkbookCellKey source ↗

createWorkbookCellKey(reference: WorkbookCellReference): string

Creates a stable string key for a workbook-qualified cell reference.

reference: WorkbookCellReference

functioncreateWorkbookDocumentState source ↗

createWorkbookDocumentState<SheetState>(input: CreateWorkbookDocumentStateInput<SheetState>): WorkbookDocumentState<SheetState>

Creates a validated workbook state using array order as the sheet tab order.

input: CreateWorkbookDocumentStateInput<SheetState>

functionformatParsedWorkbookFormulaReference source ↗

formatParsedWorkbookFormulaReference(reference: ParsedWorkbookFormulaReference, sheets: readonly WorkbookSheetDescriptor[]): string

Formats a parsed workbook formula reference with the current user-facing sheet name.

reference: ParsedWorkbookFormulaReference
sheets: readonly WorkbookSheetDescriptor[]

functionformatWorkbookCellReference source ↗

formatWorkbookCellReference(reference: WorkbookCellReference, sheetName: string): string

Formats a workbook-qualified cell reference using a caller-provided sheet name.

reference: WorkbookCellReference
sheetName: string

functionformatWorkbookRangeReference source ↗

formatWorkbookRangeReference(reference: WorkbookRangeReference, sheetName: string): string

Formats a workbook-qualified rectangular range reference using a caller-provided sheet name.

reference: WorkbookRangeReference
sheetName: string

functiongetWorkbookSheetDescriptor source ↗

getWorkbookSheetDescriptor<SheetState>(state: WorkbookDocumentState<SheetState>, sheetId: string): WorkbookSheetDescriptor | null

Returns the descriptor for a sheet id, or null when the sheet is absent.

state: WorkbookDocumentState<SheetState>
sheetId: string

functiongetWorkbookSheetState source ↗

getWorkbookSheetState<SheetState>(state: WorkbookDocumentState<SheetState>, sheetId: string): SheetState | null

Returns one sheet state payload, or null when the sheet is absent.

state: WorkbookDocumentState<SheetState>
sheetId: string

functionisValidWorkbookReference source ↗

isValidWorkbookReference(reference: unknown): reference

Reports whether an unknown value is any valid workbook-qualified formula reference.

reference: unknown

functionisWorkbookCellReference source ↗

isWorkbookCellReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified cell reference.

reference: unknown

functionisWorkbookColumnRangeReference source ↗

isWorkbookColumnRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified whole-column range reference.

reference: unknown

functionisWorkbookRangeReference source ↗

isWorkbookRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified rectangular range reference.

reference: unknown

functionisWorkbookRowRangeReference source ↗

isWorkbookRowRangeReference(reference: unknown): reference

Reports whether an unknown value is a valid workbook-qualified whole-row range reference.

reference: unknown

functionmoveWorkbookSheet source ↗

moveWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: MoveWorkbookSheetInput): WorkbookDocumentState<SheetState>

Moves a sheet descriptor to a new tab index without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: MoveWorkbookSheetInput

functionnormalizeWorkbookColumnRangeReference source ↗

normalizeWorkbookColumnRangeReference(reference: WorkbookColumnRangeReference): WorkbookColumnRangeReference

Normalizes a whole-column reference so the start column is before the end column.

reference: WorkbookColumnRangeReference

functionnormalizeWorkbookRangeReference source ↗

normalizeWorkbookRangeReference(reference: WorkbookRangeReference): WorkbookRangeReference

Normalizes a range reference so start is top-left and end is bottom-right.

reference: WorkbookRangeReference

functionnormalizeWorkbookRowRangeReference source ↗

normalizeWorkbookRowRangeReference(reference: WorkbookRowRangeReference): WorkbookRowRangeReference

Normalizes a whole-row reference so the start row is before the end row.

reference: WorkbookRowRangeReference

functionparseWorkbookCellKey source ↗

parseWorkbookCellKey(key: string): WorkbookCellReference

Parses a string produced by createWorkbookCellKey back into a cell reference.

key: string

functionparseWorkbookFormulaReference source ↗

parseWorkbookFormulaReference(reference: string, sheets: readonly WorkbookSheetDescriptor[]): ParsedWorkbookFormulaReference

Parses a displayed workbook reference such as Sheet2!A1 or Sheet2!A1:B5 into a stable sheet-id range.

reference: string
sheets: readonly WorkbookSheetDescriptor[]

functionquoteWorkbookSheetName source ↗

quoteWorkbookSheetName(name: string): string

Returns a formula-safe display name for a workbook sheet.

name: string

functionremoveWorkbookSheet source ↗

removeWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: RemoveWorkbookSheetInput): WorkbookDocumentState<SheetState>

Removes a sheet descriptor and its state payload without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: RemoveWorkbookSheetInput

functionrenameWorkbookSheet source ↗

renameWorkbookSheet<SheetState>(state: WorkbookDocumentState<SheetState>, input: RenameWorkbookSheetInput): WorkbookDocumentState<SheetState>

Renames a workbook sheet without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: RenameWorkbookSheetInput

functionsetWorkbookSheetHidden source ↗

setWorkbookSheetHidden<SheetState>(state: WorkbookDocumentState<SheetState>, input: SetWorkbookSheetHiddenInput): WorkbookDocumentState<SheetState>

Sets the hidden flag for a sheet without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: SetWorkbookSheetHiddenInput

functionupdateWorkbookSheetState source ↗

updateWorkbookSheetState<SheetState>(state: WorkbookDocumentState<SheetState>, input: UpdateWorkbookSheetStateInput<SheetState>): WorkbookDocumentState<SheetState>

Replaces one sheet state payload without mutating the source workbook.

state: WorkbookDocumentState<SheetState>
input: UpdateWorkbookSheetStateInput<SheetState>

functionvalidateWorkbookDocumentState source ↗

validateWorkbookDocumentState<SheetState>(state: WorkbookDocumentState<SheetState>): void

Validates the workbook structural invariants shared by commands and persistence.

state: WorkbookDocumentState<SheetState>

variableWorkbookCoordinateAxisValue source ↗

WorkbookCoordinateAxisValue: { col: "col"; row: "row" }

Stable coordinate axis names used by tuple-backed workbook range references.

variableWorkbookErrorCodeValue source ↗

WorkbookErrorCodeValue: { cannotHideAllSheets: "SEAR_WORKBOOK_CANNOT_HIDE_ALL_SHEETS"; cannotRemoveLastSheet: "SEAR_WORKBOOK_CANNOT_REMOVE_LAST_SHEET"; duplicateSheetId: "SEAR_WORKBOOK_DUPLICATE_SHEET_ID"; duplicateSheetName: "SEAR_WORKBOOK_DUPLICATE_SHEET_NAME"; invalidCellKey: "SEAR_WORKBOOK_INVALID_CELL_KEY"; invalidReference: "SEAR_WORKBOOK_INVALID_REFERENCE"; invalidSheetIndex: "SEAR_WORKBOOK_INVALID_SHEET_INDEX"; invalidSheetName: "SEAR_WORKBOOK_INVALID_SHEET_NAME"; … }

Stable machine-readable error codes owned by the workbook domain package.

variableWorkbookReferenceFieldValue source ↗

WorkbookReferenceFieldValue: { col: "col"; end: "end"; endCol: "endCol"; endRow: "endRow"; row: "row"; sheetId: "sheetId"; start: "start"; startCol: "startCol"; … }

Stable property names used by workbook-qualified formula references.