SearSuite
← All packages

@searsuite/sear-assembly-commands

Command dispatch

A host or input handler requests a change by running a feature-owned command. The command definition identifies the operation; the registered handler builds the state owner's operations. The Sheet core stages those operations and commits them as one change. Rendering and observers then see the committed result rather than a partial step.

SheetCommandDispatcher and DocCommandBus are dispatch contracts, not alternate state stores. Use the typed command exported by the feature that owns the behavior. For selection, SelectRangeCommand changes the selected range and GetSelection reads it afterward.

Use when: changing editor state from application code or wiring a host event. Read-only questions belong to a query; ongoing notifications belong to observations. Neither should mutate committed state.

classDocCommandBus

The supported execution entry point for document user and program actions.

constructorDocCommandBus(platform?: Platform): DocCommandBus

Creates a command bus that reports boundary diagnostics through the host platform.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving the command bus bound to one document editor instance.

methodbind(context: DocCommandContext): void

Binds the command bus to the runtime services for one editor instance.

methoddestroy(): void

Clears editor binding, listeners, and command registrations during teardown.

methodenforceRegistrationBoundary(assertWrite: (): void): void

Closes setup-time command registration after the editor is assembled.

methodgetRegisteredCommandIds(): readonly string[]

Returns a stable snapshot of all document commands exposed by this editor instance.

methodgetRegisteredCommands(): readonly DocCommandDefinition<unknown, DocCommandResult>[]

Returns the typed definitions registered on this editor instance.

methodhas(definition: string | DocCommandDefinition<unknown, DocCommandResult>): boolean

Returns whether this editor instance currently exposes a document command id.

methodisExecuting(): boolean

Whether this editor's command bus is currently dispatching a command.

methodregister<Definition>(definition: Definition, factory: DocCommandFactory<Definition>): (): void

Registers one feature-owned command factory. The returned function must be called by lifecycle cleanup when a feature registers dynamically.

methodrun<Definition>(definition: Definition, input: DocCommandInput<Definition>): DocCommandDefinitionResult<Definition>

Executes a registered command through its feature-owned typed definition.

methodrunWithoutMutationAuthority<Value>(callback: (): Value): Value

Invokes external observers without inheriting this editor's command write authority.

methodsubscribe(listener: DocCommandListener): (): void

Subscribes to document command lifecycle events and returns an unsubscribe function.

classDocCommandDispatcher

Executes document command objects against one command context.

constructorDocCommandDispatcher(): DocCommandDispatcher
methodexecute<Result>(context: DocCommandContext, command: DocEditorCommand<Result>): Result

Runs a command, validates its result and applies its operation/effects.

classSheetCommandBus

The only supported execution entry point for sheet user and program actions. Hosts bind it to one editor instance after the Core has been created.

constructorSheetCommandBus(platform?: Platform): SheetCommandBus

Creates a command bus that reports boundary diagnostics through the host platform.

propertyreadonly symbol: typeof symbolstatic

DI token for resolving the command bus bound to one editor instance.

methodbind(context: SheetCommandContext): void

Binds the command bus to the runtime services for one editor instance.

methoddestroy(): void

Clears editor binding, listeners and command registrations during teardown.

methodenforceRegistrationBoundary(assertWrite: (): void): void

Closes setup-time command registration after the editor is assembled.

methodgetRegisteredCommandIds(): readonly string[]

Returns a stable snapshot of all commands exposed by this editor instance.

methodgetRegisteredCommands(): readonly SheetCommandDefinition<unknown, SheetCommandResult>[]

Returns the typed definitions registered on this editor instance.

methodhas(definition: string | SheetCommandDefinition<unknown, SheetCommandResult>): boolean

Returns whether this editor instance currently exposes a command id.

methodisExecuting(): boolean

Whether this editor's command bus is currently dispatching a command.

methodregister<Definition>(definition: Definition, factory: SheetCommandFactory<Definition>): (): void

Registers one feature-owned command factory. The returned function must be called by the feature's lifecycle cleanup when it registers dynamically.

methodrun<Definition>(definition: Definition, input: SheetCommandInput<Definition>): SheetCommandDefinitionResult<Definition>

Executes a registered command through its feature-owned typed definition.

methodrunWithoutMutationAuthority<Value>(callback: (): Value): Value

Invokes external observers without inheriting this editor's command write authority.

methodsubscribe(listener: SheetCommandListener): (): void

Subscribes to command lifecycle events and returns an unsubscribe function.

classSheetCommandDispatcher

Executes command objects against one command context.

constructorSheetCommandDispatcher(): SheetCommandDispatcher
methodexecute<Result>(context: SheetCommandContext, command: SheetCommand<Result>): Result

Runs a command, validates its result and applies its pipeline/effects.

interfaceDocCommandContext

Runtime services exposed to document commands while they execute.

methodapplyEffect(effect: DocCommandEffect): void

Applies a local UI/runtime effect after the operation has been committed.

methodexecutePipeline(pipeline: Pipeline): void

Executes command-owned work through the document core's shared pipeline boundary. Implementations commit document state before rendering.

interfaceDocCommandDefinition
interface DocCommandDefinition<Input, Result>

A stable document command identifier carrying its input and result contract.

propertyreadonly [docCommandInputType]: Input

Phantom field that preserves the command input type for callers.

propertyreadonly [docCommandResultType]: Result

Phantom field that preserves the command result type for callers.

propertyreadonly id: string

Globally stable command id owned by the document feature package that defines it.

interfaceDocCommandEvent

Lifecycle event emitted by the document command bus for diagnostics and host UI.

propertyreadonly error?: unknown

Original thrown value when the command failed.

propertyreadonly id: string

Stable command id being executed.

propertyreadonly phase: CommandExecutionPhase

Execution phase represented by this event.

propertyreadonly result?: DocCommandResult

Result returned by a completed command.

interfaceDocCommandResult

Standard command result that document Core can execute and observe.

propertyreadonly effects?: readonly DocCommandEffect[]

Optional local effects requested after operation execution.

propertyreadonly pipeline: Pipeline

Command-owned pipeline containing mutation, render and local-action steps.

interfaceDocEditorCommand
interface DocEditorCommand<Result>

Executable unit behind a typed document command definition.

propertyreadonly id: string

Stable, domain-owned command identifier for observability and automation.

methodexecute(context: DocCommandContext): Result

Runs command logic and returns a pipeline-backed result.

interfaceSheetCommand
interface SheetCommand<Result>

Executable unit behind a typed command definition.

propertyreadonly id: string

Stable, domain-owned command identifier for observability and automation.

methodexecute(context: SheetCommandContext): Result

Runs command logic and returns a pipeline-backed result.

interfaceSheetCommandContext

Runtime services exposed to commands while they execute.

methodapplyEffect(effect: SheetCommandEffect): void

Applies a local UI/runtime effect after pipeline execution.

methodexecutePipeline(pipeline: Pipeline): void

Applies the command-produced pipeline through the core transaction boundary.

interfaceSheetCommandDefinition
interface SheetCommandDefinition<Input, Result>

A stable command identifier carrying its input and result contract.

propertyreadonly [sheetCommandInputType]: Input

Phantom field that preserves the command input type for callers.

propertyreadonly [sheetCommandResultType]: Result

Phantom field that preserves the command result type for callers.

propertyreadonly id: string

Globally stable command id owned by the feature package that defines it.

interfaceSheetCommandEvent

Lifecycle event emitted by the command bus for diagnostics and host UI.

propertyreadonly error?: unknown

Original thrown value when the command failed.

propertyreadonly id: string

Stable command id being executed.

propertyreadonly phase: CommandExecutionPhase

Execution phase represented by this event.

propertyreadonly result?: SheetCommandResult

Successfully executed command result, present only for the completed phase.

interfaceSheetCommandResult

Standard command result that Core can execute and observe.

propertyreadonly completion?: Promise<unknown>

Optional asynchronous completion of a command-owned external effect.

propertyreadonly effects?: readonly SheetCommandEffect[]

Optional local effects requested after pipeline execution.

propertyreadonly historyGroup?: { id: string; phase: "end" | "begin" }

Optional identifier for combining two committed commands into one undo entry.

propertyreadonly pipeline: Pipeline

Pipeline containing transaction, render, interaction and local-action steps.

typeCommandExecutionPhase
type CommandExecutionPhase = typeof CommandExecutionPhase[keyof typeof CommandExecutionPhase] CommandExecutionPhase: { Completed: "completed"; Failed: "failed"; Started: "started" }

Public string union for command lifecycle event phases.

typeDocCommandDefinitionResult
type DocCommandDefinitionResult = conditional

Extracts the result contract from a typed document command definition.

typeDocCommandEffect
type DocCommandEffect = { type: "focus-document" } | { type: "reset-caret-blink" }

Local runtime effects that document commands can request outside document state.

typeDocCommandFactory
type DocCommandFactory = (input: DocCommandInput<Definition>): DocEditorCommand<DocCommandDefinitionResult<Definition>>

Factory installed by a document feature plugin to create a command from typed input.

typeDocCommandInput
type DocCommandInput = conditional

Extracts the input contract from a typed document command definition.

typeDocCommandListener
type DocCommandListener = (event: DocCommandEvent): void

Observer invoked when document command execution starts, completes, or fails.

typeSheetCommandDefinitionResult
type SheetCommandDefinitionResult = conditional

Extracts the result contract from a typed command definition.

typeSheetCommandFactory
type SheetCommandFactory = (input: SheetCommandInput<Definition>): SheetCommand<SheetCommandDefinitionResult<Definition>>

Factory installed by a feature plugin to create a command from typed input.

typeSheetCommandInput
type SheetCommandInput = conditional

Extracts the input contract from a typed command definition.

typeSheetCommandListener
type SheetCommandListener = (event: SheetCommandEvent): void

Observer invoked when command execution starts, completes or fails.

functiondefineDocCommand
defineDocCommand<Input, Result>(id: string): DocCommandDefinition<Input, Result>

Creates an immutable, feature-owned document command contract.

functiondefineSheetCommand
defineSheetCommand<Input, Result>(id: string): SheetCommandDefinition<Input, Result>

Creates an immutable, feature-owned command contract.

Transactions

A command can stage several owner-specific operations in one pipeline. If preparation or staging fails, the transaction does not publish a partial document. Successful commits advance history and collaboration through the owning feature's adapters; local interaction and render updates follow the commit boundary.

Command definitions, transaction factories, and handlers work together: definitions provide typed inputs and results, handlers decide which operations to make, and state owners define how those operations change their own data. This is why an optional plugin can add a command without expanding a central command switch.

classEffectCommand
class EffectCommand extends SheetCommand<SheetCommandResult>

Command that emits local effects without mutating OT state.

constructorEffectCommand(effects: readonly SheetCommandEffect[]): EffectCommand

Creates an effect-only command.

propertyreadonly id: "effect.apply"

Stable id for effect-only command execution.

methodexecute(_context: SheetCommandContext): SheetCommandResult

Returns an empty pipeline plus the local effects to apply.

classLocalActionCommand
class LocalActionCommand extends SheetCommand<SheetCommandResult>

Runs a local, command-owned action that does not produce an OT transaction.

constructorLocalActionCommand(id: string, run: (): void): LocalActionCommand

Creates a command that schedules one local action in a pipeline.

propertyreadonly id: string

Stable, domain-owned command identifier for observability and automation.

methodexecute(_context: SheetCommandContext): SheetCommandResult

Returns a pipeline containing only the local action step.

classPipelineExecutionCommand
class PipelineExecutionCommand extends SheetCommand<SheetCommandResult>

Executes a complete, named pipeline through the command bus.

constructorPipelineExecutionCommand(id: string, pipeline: Pipeline): PipelineExecutionCommand

Creates a command around an existing named pipeline.

propertyreadonly id: string

Stable, domain-owned command identifier for observability and automation.

methodexecute(_context: SheetCommandContext): SheetCommandResult

Returns the provided pipeline unchanged.

classTransactionPipelineCommand
class TransactionPipelineCommand extends SheetCommand<SheetCommandResult>

Executes an already-created transaction through the pipeline command boundary.

constructorTransactionPipelineCommand(id: string, transaction: Transaction): TransactionPipelineCommand

Creates a command around an existing transaction.

propertyreadonly id: string

Stable, domain-owned command identifier for observability and automation.

methodexecute(_context: SheetCommandContext): SheetCommandResult

Converts the provided transaction into a pipeline result.

functioncreateSheetTransaction
createSheetTransaction<OperationType>(target: PluginKey, operations: readonly OperationType[], meta?: Readonly<Record<string, unknown>>): Transaction

Creates a transaction for command factories that need to produce pipeline transactions internally.

Selection

interfaceExtendSelectionCommandInput

Input required to extend a sheet selection by keyboard navigation.

propertyreadonly cursor: SelectionPoint

Current moving edge before this navigation step.

propertyreadonly direction: SelectionMoveDirection

Direction requested by the user.

propertyreadonly findMerge: (point: SelectionPoint): { end: SelectionPoint; start: SelectionPoint } | undefined

Lookup for merged ranges that should be selected as a whole.

propertyreadonly jumpToEdge?: boolean

Whether navigation should jump to the sheet edge.

propertyreadonly lastCol: number

Last valid column index.

propertyreadonly lastRow: number

Last valid row index.

propertyreadonly origin: SelectionPoint

Fixed selection anchor where extension began.

typeSelectionMoveDirection
type SelectionMoveDirection = typeof SelectionMoveDirection[keyof typeof SelectionMoveDirection] SelectionMoveDirection: { Down: "down"; Left: "left"; Right: "right"; Up: "up" }
functionextendSelection
extendSelection(input: ExtendSelectionCommandInput): { anchor: [number, number]; cursor: [number, number]; focus: [number, number] }

Extends a selection by one keyboard navigation step.

ReturnsNormalized selection range and updated moving cursor.

input

Current selection extension state.

functionmoveSelection
moveSelection(input: MoveSelectionCommandInput): MoveSelectionCommandResult

Resolves navigation as a sheet interaction, including merged-range boundaries.

functionselectRange
selectRange(input: SelectRangeCommandInput): SelectRangeCommandResult

Normalizes pointer or test-provided ranges so intersected merged cells are selected whole.

Sheet structure

Insert, delete, and move commands create row or column operations that the editor can commit together.

classSheetAxisMoveBoundsError
class SheetAxisMoveBoundsError extends SearError

A requested block or insertion boundary falls outside its axis.

constructorSheetAxisMoveBoundsError(input: SheetMoveAxisInput, size: number): SheetAxisMoveBoundsError
propertyreadonly code: "SHEET_AXIS_MOVE_BOUNDS"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

interfaceSheetDeleteColumnsInput

Public input for deleting columns starting at index.

propertyreadonly count?: number
propertyreadonly index: number
interfaceSheetDeleteRowsInput

Public input for deleting rows starting at index.

propertyreadonly count?: number
propertyreadonly index: number
interfaceSheetInsertColumnsInput

Public input for inserting columns before index.

propertyreadonly count?: number
propertyreadonly index: number
interfaceSheetInsertRowsInput

Public input for inserting rows before index.

propertyreadonly count?: number
propertyreadonly index: number
interfaceSheetMoveAxisInput

Moves a contiguous block before a boundary in the original axis (0 through size).

propertyreadonly before: number
propertyreadonly count?: number
propertyreadonly index: number
interfaceSheetStructureCommandDataSource
interface SheetStructureCommandDataSource<Cell>

Sheet matrix access used by structure commands without depending on a concrete data package.

propertyreadonly target: PluginKey

Plugin key that owns the persisted sheet data matrix.

methodgetColumnCount(): number

Current column count.

methodgetRowCount(): number

Current row count.

methodreadColumn(index: number): Cell | null[]

Reads a dense column payload for invertible column deletion.

methodreadRow(index: number): Cell | null[]

Reads a dense row payload for invertible row deletion.

variableDeleteColumnCommand
DeleteColumnCommand: SheetCommandDefinition<SheetDeleteColumnsInput, SheetCommandResult>

Deletes one or more columns starting at the requested column index.

variableDeleteRowCommand
DeleteRowCommand: SheetCommandDefinition<SheetDeleteRowsInput, SheetCommandResult>

Deletes one or more rows starting at the requested row index.

variableInsertColumnCommand
InsertColumnCommand: SheetCommandDefinition<SheetInsertColumnsInput, SheetCommandResult>

Inserts one or more columns before the requested column index.

variableInsertRowCommand
InsertRowCommand: SheetCommandDefinition<SheetInsertRowsInput, SheetCommandResult>

Inserts one or more rows before the requested row index.

variableMoveColumnsCommand
MoveColumnsCommand: SheetCommandDefinition<SheetMoveAxisInput, SheetCommandResult>

Reorders complete columns without overwriting their neighbors.

variableMoveRowsCommand
MoveRowsCommand: SheetCommandDefinition<SheetMoveAxisInput, SheetCommandResult>

Reorders complete rows without overwriting their neighbors.

functioncreateDeleteColumnOperations
createDeleteColumnOperations(input: SheetDeleteColumnsInput, dataSource: Pick<SheetStructureCommandDataSource, "getColumnCount" | "readColumn">): DeleteColOTOperation<unknown>[]

Creates ColDelete operations from public command input, ordered from right to left.

functioncreateDeleteRowOperations
createDeleteRowOperations(input: SheetDeleteRowsInput, dataSource: Pick<SheetStructureCommandDataSource, "getRowCount" | "readRow">): DeleteRowOTOperation<unknown>[]

Creates RowDelete operations from public command input, ordered from bottom to top.

functioncreateInsertColumnOperations
createInsertColumnOperations(input: SheetInsertColumnsInput, dataSource: Pick<SheetStructureCommandDataSource, "getRowCount">): InsertColOTOperation<unknown>[]

Creates ColInsert operations from public command input.

functioncreateInsertRowOperations
createInsertRowOperations(input: SheetInsertRowsInput, dataSource: Pick<SheetStructureCommandDataSource, "getColumnCount">): InsertRowOTOperation<unknown>[]

Creates RowInsert operations from public command input.

functioncreateMoveColumnsOperations
createMoveColumnsOperations(input: SheetMoveAxisInput, size: number): MoveColOTOperation<unknown>[]

Creates column swaps implementing insertion at an original column boundary.

functioncreateMoveRowsOperations
createMoveRowsOperations(input: SheetMoveAxisInput, size: number): MoveRowOTOperation<unknown>[]

Creates row swaps implementing insertion at an original row boundary.

functionregisterSheetStructureCommands
registerSheetStructureCommands(commands: SheetCommandBus, dataSource: SheetStructureCommandDataSource, moves?: SheetStructureMoveRegistry): void

Registers the default sheet row/column structure commands.

Cell ranges

interfaceSheetClearRangeContentsCommandDataSource
interface SheetClearRangeContentsCommandDataSource<Cell>

Sheet cell data required to create clear-contents operations.

propertyreadonly target: PluginKey

Plugin key that owns the persisted sheet data matrix.

methodgetColumnCount(): number

Current column count.

methodgetRowCount(): number

Current row count.

methodreadCell(row: number, column: number): Cell | null

Reads the current cell value at row, column.

interfaceSheetClearRangeContentsInput
interface SheetClearRangeContentsInput extends SheetRangeInput

Public input for clearing persisted contents in a range.

Inherited members 2

Inherited from SheetRangeInput.

interfaceSheetRangeBounds

Normalized rectangular sheet range bounds expressed as inclusive cell coordinates.

propertyreadonly end: SheetCellPoint

Inclusive bottom-right cell coordinate.

propertyreadonly start: SheetCellPoint

Inclusive top-left cell coordinate.

interfaceSheetRangeInput

Common range input accepted by explicit range commands.

propertyreadonly anchor: SheetCellPoint

One corner of the target range.

propertyreadonly focus: SheetCellPoint

Opposite corner of the target range.

typeSheetCellPoint
type SheetCellPoint = readonly [number, number]

A zero-based sheet cell coordinate expressed as [row, column].

typeSheetRangeCommandDataSource
type SheetRangeCommandDataSource = SheetClearRangeContentsCommandDataSource<Cell>

Data source for the built-in clear-contents command.

variableClearRangeContentsCommand
ClearRangeContentsCommand: SheetCommandDefinition<SheetClearRangeContentsInput, SheetCommandResult>

Clears persisted cell contents in an explicit rectangular range.

functioncreateClearRangeContentsOperations
createClearRangeContentsOperations<Cell>(input: SheetClearRangeContentsInput, dataSource: SheetClearRangeContentsCommandDataSource<Cell>): UpdateCellOTOperation<Cell>[]

Creates UpdateCell operations that clear non-empty cells inside a range.

functionregisterSheetRangeCommands
registerSheetRangeCommands(commands: SheetCommandBus, dataSource: SheetRangeCommandDataSource): void

Registers the built-in range commands on one sheet command bus.

Queries

Queries read the current editor state through the command surface without committing a change.

interfaceSheetQueryDefinition
interface SheetQueryDefinition<Input, Result>

A stable query identifier carrying its input and result contract.

propertyreadonly __input?: Input
propertyreadonly __result?: Result
propertyreadonly id: string
propertyreadonly resultMode?: "reader"

Reader queries return a live, read-only projection instead of a data snapshot.

typeSheetQueryHandler
type SheetQueryHandler = (input: Input): Result
typeSheetQueryInput
type SheetQueryInput = conditional
typeSheetQueryResult
type SheetQueryResult = conditional
functiondefineSheetQuery
defineSheetQuery<Input, Result>(id: string): SheetQueryDefinition<Input, Result>

Creates an immutable, feature-owned query contract.

functiondefineSheetReaderQuery
defineSheetReaderQuery<Input, Result>(id: string): SheetQueryDefinition<Input, Result>

Defines a live reader whose methods own detached values at their read boundary.