ObjectStackObjectStack

Websocket

Websocket protocol schemas

WebSocket Event Protocol

Defines the schema for WebSocket-based real-time communication in ObjectStack.

Supports event subscriptions, filtering, presence tracking, and collaborative editing.

Industry alignment: Firebase Realtime Database, Socket.IO, Pusher

Source: packages/spec/src/api/websocket.zod.ts

TypeScript Usage

import { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api';
import type { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventFilter, EventFilterCondition, EventMessage, EventPattern, EventSubscription, FilterOperator, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api';

// Validate data
const result = AckMessage.parse(data);

AckMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
ackMessageIdstring✅ID of the message being acknowledged
successboolean✅Whether the operation was successful
errorstringoptionalError message if operation failed

CursorMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
cursorObject✅Cursor position

CursorPosition

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
sessionIdstring✅Session identifier
documentIdstring✅Document identifier being edited
positionObjectoptionalCursor position in document
selectionObjectoptionalSelection range (if text is selected)
colorstringoptionalCursor color for visual representation
userNamestringoptionalDisplay name of user
lastUpdatestring✅ISO 8601 datetime of last cursor update

DocumentState

Properties

PropertyTypeRequiredDescription
documentIdstring✅Document identifier
versioninteger✅Current document version
contentstring✅Current document content
lastModifiedstring✅ISO 8601 datetime of last modification
activeSessionsstring[]✅Active editing session IDs
checksumstringoptionalContent checksum for integrity verification

EditMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
operationObject✅Edit operation

EditOperation

Properties

PropertyTypeRequiredDescription
operationIdstring✅Unique operation identifier
documentIdstring✅Document identifier
userIdstring✅User who performed the edit
sessionIdstring✅Session identifier
typeEnum<'insert' | 'delete' | 'replace'>✅Type of edit operation
positionObject✅Starting position of the operation
endPositionObjectoptionalEnding position (for delete/replace operations)
contentstringoptionalContent to insert/replace
versioninteger✅Document version before this operation
timestampstring✅ISO 8601 datetime when operation was created
baseOperationIdstringoptionalPrevious operation ID this builds upon (for OT)

EditOperationType

Allowed Values

  • insert
  • delete
  • replace

ErrorMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
codestring✅Error code
messagestring✅Error message
detailsanyoptionalAdditional error details

EventFilter

Properties

PropertyTypeRequiredDescription
conditionsObject[]optionalArray of filter conditions
and[#](./#)[]optionalAND logical combination of filters
or[#](./#)[]optionalOR logical combination of filters
not[#](./#)optionalNOT logical negation of filter

EventFilterCondition

Properties

PropertyTypeRequiredDescription
fieldstring✅Field path to filter on (supports dot notation, e.g., "user.email")
operatorEnum<'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'exists' | 'regex'>✅Comparison operator
valueanyoptionalValue to compare against (not needed for "exists" operator)

EventMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
subscriptionIdstring✅Subscription ID this event belongs to
eventNamestring✅Event name
objectstringoptionalObject name the event relates to
payloadany✅Event payload data
userIdstringoptionalUser who triggered the event

EventSubscription

Properties

PropertyTypeRequiredDescription
subscriptionIdstring✅Unique subscription identifier
eventsstring[]✅Event patterns to subscribe to (supports wildcards, e.g., "record.*", "user.created")
objectsstring[]optionalObject names to filter events by (e.g., ["account", "contact"])
filters[__schema0](./__schema0)optionalAdvanced filter conditions for event payloads
channelsstring[]optionalChannel names for scoped subscriptions

FilterOperator

Allowed Values

  • eq
  • ne
  • gt
  • gte
  • lt
  • lte
  • in
  • nin
  • contains
  • startsWith
  • endsWith
  • exists
  • regex

PingMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent

PongMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
pingMessageIdstringoptionalID of ping message being responded to

PresenceMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
presenceObject✅Presence state

PresenceState

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
sessionIdstring✅Unique session identifier
statusEnum<'online' | 'away' | 'busy' | 'offline'>✅Current presence status
lastSeenstring✅ISO 8601 datetime of last activity
currentLocationstringoptionalCurrent page/route user is viewing
deviceEnum<'desktop' | 'mobile' | 'tablet' | 'other'>optionalDevice type
customStatusstringoptionalCustom user status message
metadataRecord<string, any>optionalAdditional custom presence data

PresenceUpdate

Properties

PropertyTypeRequiredDescription
statusEnum<'online' | 'away' | 'busy' | 'offline'>optionalUpdated presence status
currentLocationstringoptionalUpdated current location
customStatusstringoptionalUpdated custom status message
metadataRecord<string, any>optionalUpdated metadata

SimpleCursorPosition

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
recordIdstring✅Record identifier being edited
fieldNamestring✅Field name being edited
positionnumber✅Cursor position (character offset from start)
selectionObjectoptionalText selection range (if text is selected)

SimplePresenceState

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
userNamestring✅User display name
statusEnum<'online' | 'away' | 'offline'>✅User presence status
lastSeennumber✅Unix timestamp of last activity in milliseconds
metadataRecord<string, any>optionalAdditional presence metadata (e.g., current page, custom status)

SubscribeMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
subscriptionObject✅Subscription configuration

UnsubscribeMessage

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
requestObject✅Unsubscribe request

UnsubscribeRequest

Properties

PropertyTypeRequiredDescription
subscriptionIdstring✅Subscription ID to unsubscribe from

WebSocketConfig

Properties

PropertyTypeRequiredDescription
urlstring✅WebSocket server URL
protocolsstring[]optionalWebSocket sub-protocols
reconnectboolean✅Enable automatic reconnection
reconnectIntervalinteger✅Reconnection interval in milliseconds
maxReconnectAttemptsinteger✅Maximum reconnection attempts
pingIntervalinteger✅Ping interval in milliseconds
timeoutinteger✅Message timeout in milliseconds
headersRecord<string, string>optionalCustom headers for WebSocket handshake

WebSocketEvent

Properties

PropertyTypeRequiredDescription
typeEnum<'subscribe' | 'unsubscribe' | 'data-change' | 'presence-update' | 'cursor-update' | 'error'>✅Event type
channelstring✅Channel identifier (e.g., "record.account.123", "user.456")
payloadany✅Event payload data
timestampnumber✅Unix timestamp in milliseconds

WebSocketMessage

Union Options

This schema accepts one of the following structures:

Option 1

Type: subscribe

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
subscriptionObject✅Subscription configuration

Option 2

Type: unsubscribe

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
requestObject✅Unsubscribe request

Option 3

Type: event

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
subscriptionIdstring✅Subscription ID this event belongs to
eventNamestring✅Event name
objectstringoptionalObject name the event relates to
payloadany✅Event payload data
userIdstringoptionalUser who triggered the event

Option 4

Type: presence

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
presenceObject✅Presence state

Option 5

Type: cursor

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
cursorObject✅Cursor position

Option 6

Type: edit

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
operationObject✅Edit operation

Option 7

Type: ack

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
ackMessageIdstring✅ID of the message being acknowledged
successboolean✅Whether the operation was successful
errorstringoptionalError message if operation failed

Option 8

Type: error

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
codestring✅Error code
messagestring✅Error message
detailsanyoptionalAdditional error details

Option 9

Type: ping

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent

Option 10

Type: pong

Properties

PropertyTypeRequiredDescription
messageIdstring✅Unique message identifier
typestring✅
timestampstring✅ISO 8601 datetime when message was sent
pingMessageIdstringoptionalID of ping message being responded to

WebSocketMessageType

Allowed Values

  • subscribe
  • unsubscribe
  • event
  • ping
  • pong
  • ack
  • error
  • presence
  • cursor
  • edit

WebSocketPresenceStatus

Allowed Values

  • online
  • away
  • busy
  • offline

WebSocketServerConfig

Properties

PropertyTypeRequiredDescription
enabledboolean✅Enable WebSocket server
pathstring✅WebSocket endpoint path
heartbeatIntervalnumber✅Heartbeat interval in milliseconds
reconnectAttemptsnumber✅Maximum reconnection attempts for clients
presenceboolean✅Enable presence tracking
cursorSharingboolean✅Enable collaborative cursor sharing

On this page

TypeScript UsageAckMessagePropertiesCursorMessagePropertiesCursorPositionPropertiesDocumentStatePropertiesEditMessagePropertiesEditOperationPropertiesEditOperationTypeAllowed ValuesErrorMessagePropertiesEventFilterPropertiesEventFilterConditionPropertiesEventMessagePropertiesEventSubscriptionPropertiesFilterOperatorAllowed ValuesPingMessagePropertiesPongMessagePropertiesPresenceMessagePropertiesPresenceStatePropertiesPresenceUpdatePropertiesSimpleCursorPositionPropertiesSimplePresenceStatePropertiesSubscribeMessagePropertiesUnsubscribeMessagePropertiesUnsubscribeRequestPropertiesWebSocketConfigPropertiesWebSocketEventPropertiesWebSocketMessageUnion OptionsOption 1PropertiesOption 2PropertiesOption 3PropertiesOption 4PropertiesOption 5PropertiesOption 6PropertiesOption 7PropertiesOption 8PropertiesOption 9PropertiesOption 10PropertiesWebSocketMessageTypeAllowed ValuesWebSocketPresenceStatusAllowed ValuesWebSocketServerConfigProperties