@searsuite/sear-domain-ot

Operations and transforms

TransactionOTRegistry chooses the transform for concurrent operations. Use the built-in registry when a host must rebase local and remote changes.

enumOTTransformPriority

Tie-break direction used when two concurrent operations target the same position.

enum memberLEFT: "left"

enum memberRIGHT: "right"

classBaseOT

Base class for Operational Transformation implementations.

Concrete domains provide the actual apply, append, compose, and transform semantics while sharing validation and creation helpers here.

constructorBaseOT(name: string): BaseOT

Constructs an OT implementation descriptor.

name: Stable implementation name.

propertyreadonly name: string

Human-readable OT implementation name for diagnostics and debugging.

methodappend(destination: OTOperation[], current: OTOperation): voidstatic

Appends one operation into a composed destination list.

ThrowsSearError until implemented by a concrete OT class.

methodapply(snapshot: unknown, operations: OTOperation[]): voidstatic

Applies operations to a domain snapshot.

ThrowsSearError until implemented by a concrete OT class.

methodcheckValidOp(operations: OTOperation[]): voidstatic

Validates the structural contract common to all operations.

ThrowsSearError when an operation is missing its path.

operations: Operations that must each carry an array path.

methodcompose(operation1: OTOperation[], operation2: OTOperation[]): OTOperation[]static

Composes two sequential operation lists into one equivalent list.

ThrowsSearError until implemented by a concrete OT class.

methodcreate(data?: OTOperation[]): OTOperation[]static

Creates an operation list snapshot.

ReturnsA mutable operation list detached from the caller's array.

data: Optional operations to clone into the new list.

methodtransform(operation: OTOperation[], otherOperation: OTOperation[], type: OTTransformPriority): OTOperation[]static

Transforms an operation list against concurrent operations.

ThrowsSearError until implemented by a concrete OT class.

classTransactionOTError

class TransactionOTError extends SearError

Public error for invalid or unavailable transaction OT behavior.

constructorTransactionOTError(code: TransactionOTErrorCode, message: string, details?: SearErrorDetails): TransactionOTError

propertyreadonly code: TransactionOTErrorCode

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classTransactionOTRegistry

Local registry of versioned OT families and explicit pair transformations.

constructorTransactionOTRegistry(): TransactionOTRegistry

methoddecode(id: string, version: number, payload: unknown): OTOperation[]

Decodes a wire payload through its registered family definition.

methoddestroy(): void

Permanently clears the registry.

method

encode<OperationType>(definition: TransactionOTDefinition<OperationType>, operations: readonly OperationType[]): OTEncodedValue

Encodes and validates one operation family payload.

method

invert<OperationType>(definition: TransactionOTDefinition<OperationType>, operations: readonly OperationType[]): OperationType[]

Inverts operations through their family definition.

methodregisterIndependent(left: TransactionOTDefinition, right: TransactionOTDefinition): (): void

Registers two families as independent, so pair transformation is explicit identity.

methodregisterRelation<Left, Right>(relation: OTTransformRelation<Left, Right>): (): void

Registers one explicit relation. Reverse lookup uses the same implementation with swapped branches.

methodregisterType<OperationType>(definition: TransactionOTDefinition<OperationType>): (): void

Registers one operation family and returns an idempotent disposer.

methodrequireType(id: string, version: number): TransactionOTDefinition

Resolves a registered operation family.

method

transformPair<Left, Right>(leftDefinition: TransactionOTDefinition<Left>, leftOperations: readonly Left[], rightDefinition: TransactionOTDefinition<Right>, rightOperations: readonly Right[], priority: OTTransformPriority): OTTransformPair<Left, Right>

Rebases two concurrent operation lists through their registered relation.

interfaceOTOperation

Minimal operation contract shared by every domain OT implementation.

propertyp: OTOperationPath

Path locating the operation target inside the snapshot.

interfaceOTTransformPair

interface OTTransformPair<Left, Right>

Pair transformation result preserving both concurrent branches.

propertyreadonly left: Left[]

propertyreadonly right: Right[]

interfaceOTTransformRelation

interface OTTransformRelation<Left, Right>

Domain-specific transformation relation between two operation families.

propertyreadonly left: TransactionOTDefinition<Left>

propertyreadonly right: TransactionOTDefinition<Right>

method

transformPair(left: readonly Left[], right: readonly Right[], priority: OTTransformPriority): OTTransformPair<Left, Right>

interfaceTransactionOTDefinition

interface TransactionOTDefinition<OperationType>

Stable, versioned operation family shared by history and collaboration.

propertyreadonly id: string

propertyreadonly version: number

methoddecode(payload: unknown): OperationType[]

methodencode(operations: readonly OperationType[]): OTEncodedValue

methodinvert(operations: readonly OperationType[]): OperationType[]

methodisOperation(operation: OTOperation): operation

typeOperation

type Operation = MatrixOTOperation<unknown> | UpdateRectOTOperation | RichDocOTOperation

Built-in operation union. Third-party callers use OTOperation as their open base contract.

typeOTEncodedValue

type OTEncodedValue = null | boolean | number | string | readonly OTEncodedValue[] | { }

JSON-compatible values accepted by collaboration transports.

typeTransactionOTErrorCode

type TransactionOTErrorCode = typeof TransactionOTErrorCode[keyof typeof TransactionOTErrorCode]

TransactionOTErrorCode: { InvalidDefinition: "SEAR_TRANSACTION_OT_INVALID_DEFINITION"; InvalidPayload: "SEAR_TRANSACTION_OT_INVALID_PAYLOAD"; InvertUnsupported: "SEAR_TRANSACTION_OT_INVERT_UNSUPPORTED"; RegistryDestroyed: "SEAR_TRANSACTION_OT_REGISTRY_DESTROYED"; RelationConflict: "SEAR_TRANSACTION_OT_RELATION_CONFLICT"; RelationNotRegistered: "SEAR_TRANSACTION_OT_RELATION_NOT_REGISTERED"; TypeConflict: "SEAR_TRANSACTION_OT_TYPE_CONFLICT"; TypeNotRegistered: "SEAR_TRANSACTION_OT_TYPE_NOT_REGISTERED" }

Stable errors raised by transaction OT definitions and registries.

variableMatrixTransactionOT

MatrixTransactionOT: TransactionOTDefinition<MatrixOTOperation<unknown>>

Built-in MatrixOT family shared by matrix-backed transaction owners.

variableMatrixTransactionOTRelation

MatrixTransactionOTRelation: OTTransformRelation<MatrixOTOperation<unknown>, MatrixOTOperation<unknown>>

Matrix-to-matrix pair transformation used by every matrix-backed owner.

variableRichDocTransactionOT

RichDocTransactionOT: TransactionOTDefinition<RichDocOTOperation>

Built-in rich-document operation family.

variableRichDocTransactionOTRelation

RichDocTransactionOTRelation: OTTransformRelation<RichDocOTOperation, RichDocOTOperation>

Rich-document pair transformation.

functioncreateBuiltinTransactionOTRegistry

createBuiltinTransactionOTRegistry(): TransactionOTRegistry

Creates an isolated registry containing all built-in OT definitions and relations.

functiongetAllActionNames

getAllActionNames(): Set<string>

Returns a Set of all known OT action name strings. Used by the engine to identify which action types are present in an operation.

functionOTClone

OTClone<T>(object: T): T

Deep-clones JSON-compatible OT payloads before mutation or composition.

functiontransactionOTTypeKey

transactionOTTypeKey(definition: Pick<TransactionOTDefinition, "id" | "version">): string

Returns the wire identity of one versioned OT family.

Row and column operations

interfaceDeleteColOTOperation: interface DeleteColOTOperation<T> extends OTOperation

Deletes one column and carries the deleted column payload for inversion.

propertycd: T | null[]

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.
interfaceDeleteRowOTOperation: interface DeleteRowOTOperation<T> extends OTOperation

Deletes one row and carries the deleted row payload for inversion.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyrd: T | null[]
interfaceInsertColOTOperation: interface InsertColOTOperation<T> extends OTOperation

Inserts one column at the target column index.

propertyci: T | null[]

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.
interfaceInsertRowOTOperation: interface InsertRowOTOperation<T> extends OTOperation

Inserts one row at the target row index.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyri: T | null[]
interfaceMoveColOTOperation: interface MoveColOTOperation<T> extends OTOperation

Exchanges the column at the path index with the column index encoded by cm.

propertycm: MatrixOTOperationPath

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.
interfaceMoveRowOTOperation: interface MoveRowOTOperation<T> extends OTOperation

Exchanges the row at the path index with the row index encoded by rm.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyrm: MatrixOTOperationPath
interfaceResizeColOTOperation: interface ResizeColOTOperation extends OTOperation

Updates one column dimension in a dimension matrix.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyrc: { prev: number | null; value: number | null }
interfaceResizeRowOTOperation: interface ResizeRowOTOperation extends OTOperation

Updates one row dimension in a dimension matrix.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyrr: { prev: number | null; value: number | null }
typeMatrixStructureOTOperation: type MatrixStructureOTOperation = InsertRowOTOperation<T> | DeleteRowOTOperation<T> | MoveRowOTOperation<T> | InsertColOTOperation<T> | DeleteColOTOperation<T> | MoveColOTOperation<T>

Structural matrix operations that shift row or column coordinates.
functioncreateDeleteColOTOperation: createDeleteColOTOperation<T>(path: readonly number[], values: readonly T | null[]): DeleteColOTOperation<T>

Creates a semantic column-delete operation carrying the deleted values required for inversion.
functioncreateDeleteRowOTOperation: createDeleteRowOTOperation<T>(path: readonly number[], values: readonly T | null[]): DeleteRowOTOperation<T>

Creates a semantic row-delete operation carrying the deleted values required for inversion.
functioncreateInsertColOTOperation: createInsertColOTOperation<T>(path: readonly number[], values: readonly T | null[]): InsertColOTOperation<T>

Creates a semantic column-insert operation without changing the MatrixOT wire shape.
functioncreateInsertRowOTOperation: createInsertRowOTOperation<T>(path: readonly number[], values: readonly T | null[]): InsertRowOTOperation<T>

Creates a semantic row-insert operation without changing the MatrixOT wire shape.
functioncreateMoveColOTOperation: createMoveColOTOperation(path: readonly number[], destination: readonly number[]): MoveColOTOperation<unknown>

Creates a semantic column-move operation.
functioncreateMoveRowOTOperation: createMoveRowOTOperation(path: readonly number[], destination: readonly number[]): MoveRowOTOperation<unknown>

Creates a semantic row-move operation.
functioncreateResizeColOTOperation: createResizeColOTOperation(path: readonly number[], value: number | null, previousValue: number | null): ResizeColOTOperation

Creates a semantic column-resize operation.
functioncreateResizeRowOTOperation: createResizeRowOTOperation(path: readonly number[], value: number | null, previousValue: number | null): ResizeRowOTOperation

Creates a semantic row-resize operation.
functionisMatrixStructureOperation: isMatrixStructureOperation<T>(operation: OTOperation): operation

Narrows an OT operation to one of the row or column structure operations.
functionisResizeColOperation: isResizeColOperation(operation: OTOperation): operation

Narrows an OT operation to a column-resize operation with a present action payload.
functionisResizeRowOperation: isResizeRowOperation(operation: OTOperation): operation

Narrows an OT operation to a row-resize operation with a present action payload.

Cell and rectangle operations

enumMatrixOTActionName

Compact command keys persisted in matrix OT payloads.

enum memberColDelete: "cd"

enum memberColInsert: "ci"

enum memberColMove: "cm"

enum memberResizeCol: "rc"

enum memberResizeRow: "rr"

enum memberRowDelete: "rd"

enum memberRowInsert: "ri"

enum memberRowMove: "rm"

enum memberUpdateCell: "uc"

enumRectOTActionName

Compact command keys persisted in rectangle OT payloads.

enum memberUpdateRect: "ur"

classMatrixOT

class MatrixOT extends BaseOT

Operational Transformation implementation for CSRMatrix-backed sheet state.

MatrixOT owns cell updates, row/column structure edits, dimension resize operations, and the transform rules that keep concurrent matrix changes convergent.

constructorMatrixOT(): MatrixOT

Creates a MatrixOT descriptor for diagnostics and shared OT registries.

methodappend(destination: MatrixOTOperation[], current: MatrixOTOperation): voidstatic

Appends one component into a composed matrix operation list.

destination: Composition destination mutated in place.
current: Operation to append.

methodapply<U, S>(snapshot: S, operations: MatrixOTOperation[]): Sstatic

Applies operations to a CSR matrix snapshot.

ReturnsThe same snapshot instance after mutation.

snapshot: Mutable CSR-backed state.
operations: Matrix operations to apply.

methodcommonLengthForOps(operation1: MatrixOTOperation, operation2: MatrixOTOperation): numberstatic

Computes the common parent depth used by component transformation.

ReturnsThe depth of the shared parent segment.

operation1: First operation whose parent path is compared.
operation2: Second operation whose parent path is compared.

methodcompose(operation1: MatrixOTOperation[], operation2: MatrixOTOperation[]): MatrixOTOperation[]static

Composes two sequential matrix operation lists.

ReturnsEquivalent composed operation list.

operation1: Earlier operation list.
operation2: Later operation list.

methodinvert(operations: MatrixOTOperation[]): MatrixOTOperation[]static

Inverts an operation list in rollback order.

ReturnsOperations that undo the input when applied in order.

operations: Forward operations to invert.

methodinvertComponent(currentOperation: MatrixOTOperation): MatrixOTOperationstatic

Builds the inverse of one matrix component.

ReturnsA component that restores the previous matrix state.

currentOperation: Component to invert.

method

transform<U>(operation: MatrixOTOperation<U>[], otherOperation: MatrixOTOperation<U>[], type: OTTransformPriority): MatrixOTOperation<U>[]

static

Transforms concurrent Matrix OT operations into a convergent pair.

method

transformComponent<U>(destination: MatrixOTOperation<U>[], currentOperation: MatrixOTOperation<U>, otherOperation: MatrixOTOperation<U>, type: OTTransformPriority): MatrixOTOperation<U>[]

static

Transforms one matrix component over one concurrent component.

ReturnsThe destination list after appending any transformed component.

destination: Output list receiving the transformed component or no-op.
currentOperation: Operation being rebased.
otherOperation: Concurrent operation already applied on the target branch.
type: Tie-break side for equal-position edits.

method

transformComponentX<U>(left: MatrixOTOperation<U>, right: MatrixOTOperation<U>, destLeft: MatrixOTOperation<U>[], destRight: MatrixOTOperation<U>[]): void

static

Transforms one Matrix OT component against another concurrent component.

methodtransformX(leftOperation: MatrixOTOperation[], rightOperation: MatrixOTOperation[]): MatrixOTOperation[][]static

Transforms one Matrix OT operation against a concurrent operation.

Inherited members 3

Inherited from BaseOT.

classRectOT

class RectOT extends BaseOT

Operational Transformation implementation for sheet rectangle state.

RectOT applies direct rectangle updates and matrix structure operations that shift row/column coordinates inside the rectangle.

constructorRectOT(): RectOT

Creates a RectOT descriptor for diagnostics and shared OT registries.

methodapply(snapshot: Rect, operations: RectOTOperation[]): Rectstatic

Applies rectangle operations to a mutable Rect snapshot.

ReturnsThe same rectangle after mutation.

snapshot: Rectangle to mutate.
operations: Operations to apply in order.

methodinvert(operations: RectOTOperation[], beforeRect: Rect): RectOTOperation[]static

Inverts a rectangle operation list using the rectangle state before each component.

ReturnsOperations that undo the input when applied in order.

operations: Forward operations to invert.
beforeRect: Rectangle state before any forward operations are applied.

methodinvertComponent(currentOperation: RectOTOperation, beforeRect?: Rect): RectOTOperationstatic

Builds the inverse of one rectangle operation.

ReturnsAn operation that restores the previous rectangle state.

currentOperation: Operation to invert.
beforeRect: Rectangle state before the forward update operation.

Inherited members 6

Inherited from BaseOT.

interfaceUpdateCellOTOperation

interface UpdateCellOTOperation<T> extends OTOperation

Updates a single cell and carries both forward and previous values.

propertyp: MatrixOTOperationPath

Path locating the operation target inside the snapshot.

propertyuc: { intent?: "relocation"; prev: T | null; value: T | null }

interfaceUpdateRectOTOperation

interface UpdateRectOTOperation extends OTOperation

Replaces a rectangle's two corner points.

propertyp: MatrixOTOperationPath

Target rectangle path or matrix coordinate path.

propertyur: [Point, Point]

New rectangle range as [startPoint, endPoint].

typeMatrixCellUpdateIntent

type MatrixCellUpdateIntent = typeof MatrixCellUpdateIntent[keyof typeof MatrixCellUpdateIntent] MatrixCellUpdateIntent: { Relocation: "relocation" }

Distinguishes ordinary replacement from relocation that preserves independently owned cell state.

typeMatrixOTOperation

type MatrixOTOperation = InsertRowOTOperation<T> | DeleteRowOTOperation<T> | UpdateCellOTOperation<T> | MoveRowOTOperation<T> | InsertColOTOperation<T> | DeleteColOTOperation<T> | MoveColOTOperation<T> | ResizeRowOTOperation | ResizeColOTOperation

Every operation understood by MatrixOT and matrix-backed sheet state.

functioncreateUpdateCellOTOperation

createUpdateCellOTOperation<T>(path: readonly number[], value: T | null, previousValue: T | null, intent?: "relocation"): UpdateCellOTOperation<T>

Creates a semantic cell-update operation carrying both values required for inversion.

functioncreateUpdateRectOTOperation

createUpdateRectOTOperation(path: readonly number[], start: readonly [number, number], end: readonly [number, number]): UpdateRectOTOperation

Creates a semantic rectangle update without changing the RectOT wire shape.

functionisMatrixOperation

isMatrixOperation(operation: OTOperation): operation

Narrows an operation to any operation understood by MatrixOT.

functionisUpdateCellOperation

isUpdateCellOperation<T>(operation: OTOperation): operation

Narrows an OT operation to an update-cell operation with a present action payload.

Document operations

Rich-document operations target nodes, text, and attributes in the document tree.

enumRichDocOTActionName

Compact operation keys persisted in rich-document OT payloads.

enum memberNodeDelete: "nd"

enum memberNodeInsert: "ni"

enum memberNodeMove: "nm"

enum memberStringDelete: "sd"

enum memberStringInsert: "si"

enum memberUpdateAttrs: "ua"

classRichDocOT

class RichDocOT extends BaseOT

Operational Transformation implementation for the JSON rich-document model.

RichDocOT applies node, text, and attribute operations and rebases concurrent edits so document trees converge across collaboration clients.

constructorRichDocOT(): RichDocOT

Creates a RichDocOT descriptor for diagnostics and shared OT registries.

methodappend(destination: RichDocOTOperation[], current: RichDocOTOperation): voidstatic

Appends one rich-document operation into a composed destination list.

destination: Composition destination mutated in place.
current: Operation to append.

methodapply(snapshot: NodeSchema, operations: RichDocOTOperation[]): NodeSchemastatic

Applies rich-document operations to a mutable node snapshot.

ReturnsThe same snapshot instance after mutation.

snapshot: Root node to mutate.
operations: Operations to apply in order.

methodcompose(operation1: RichDocOTOperation[], operation2: RichDocOTOperation[]): RichDocOTOperation[]static

Composes two sequential rich-document operation lists.

ReturnsEquivalent composed operation list.

operation1: Earlier operation list.
operation2: Later operation list.

methodcreate(data?: RichDocOTOperation[]): RichDocOTOperation[]static

Creates a detached rich-document operation list.

ReturnsA mutable operation list owned by the caller.

data: Optional operation list to clone.

methodinvert(operations: RichDocOTOperation[]): RichDocOTOperation[]static

Creates the inverse operation list for a committed rich-document change.

method

transform(operation: RichDocOTOperation[], otherOperation: RichDocOTOperation[], type: OTTransformPriority): RichDocOTOperation[]

static

Transforms one rich-document operation list against concurrent operations.

ReturnsThe operation list rebased over otherOperation.

operation: Operation list being rebased.
otherOperation: Concurrent operation list already applied on the target branch.
type: Tie-break side for equal-position edits.

Inherited members 2

Inherited from BaseOT.

interfaceDeleteNodeOTOperation

interface DeleteNodeOTOperation extends OTOperation

Deletes a node and carries the removed payload for inversion.

propertynd: NodeSchema

Deleted node payload.

propertyp: OTOperationPath

Target node path.

interfaceDeleteStringOTOperation

interface DeleteStringOTOperation extends OTOperation

Deletes text from a leaf text node and carries the removed string.

propertyp: OTOperationPath

Path ending in the string offset.

propertysd: string

Deleted string payload.

interfaceInsertNodeOTOperation

interface InsertNodeOTOperation extends OTOperation

Inserts a node into a parent content array.

propertyni: NodeSchema

Node payload inserted at the target path.

propertyp: OTOperationPath

Target insertion path.

interfaceInsertStringOTOperation

interface InsertStringOTOperation extends OTOperation

Inserts text into a leaf text node.

propertyp: OTOperationPath

Path ending in the string offset.

propertysi: string

String inserted at the offset.

interfaceMoveNodeOTOperation

interface MoveNodeOTOperation extends OTOperation

Moves a node within its parent content array.

propertynm: [number]

Destination sibling index.

propertyp: OTOperationPath

Source node path.

interfaceReplaceNodeOTOperation

interface ReplaceNodeOTOperation extends OTOperation

Replaces one node in a content array while retaining both sides for OT inversion.

propertynd: NodeSchema

Node payload removed from the target path.

propertyni: NodeSchema

Node payload inserted at the target path.

propertyp: OTOperationPath

Target node path.

interfaceUpdateAttrsOTOperation

interface UpdateAttrsOTOperation extends OTOperation

Updates one node attribute and carries both previous and next values.

propertyp: OTOperationPath

Path ending in the attribute key.

propertyua: { prev: unknown; value: unknown }

New attribute value and previous attribute value.

typeRichDocOTOperation

type RichDocOTOperation = InsertNodeOTOperation | DeleteNodeOTOperation | ReplaceNodeOTOperation | MoveNodeOTOperation | InsertStringOTOperation | DeleteStringOTOperation | UpdateAttrsOTOperation

Every operation understood by RichDocOT.

typeRichDocOTOperationPath

type RichDocOTOperationPath = OTOperationPath

Path into a rich-document tree; numeric segments address content arrays and string segments address attrs.

interfaceNodeSchema

Persisted rich-document node schema shared by document runtime, commands, and OT.

propertyattrs?: Record<string, any>

Node attributes for styles, formatting, and feature-owned metadata.

propertycontent?: Schema[]

Child rich-document nodes.

propertyid?: string

Stable structural identity for layout, retained render nodes, and collaboration mapping.