@tldraw/sync-core 4.0.2 → 4.1.0-canary.0259516ffb8c

package/dist-cjs/index.d.ts

@@ -34,7 +34,19 @@ import { UnknownRecord } from '@tldraw/store';
 
 /* Excluded from this release type: ObjectDiff */
 
-/** @public */
+/**
+ * Utility type that removes properties with void values from an object type.
+ * This is used internally to conditionally require session metadata based on
+ * whether SessionMeta extends void.
+ *
+ * @example
+ * ```ts
+ * type Example = { a: string, b: void, c: number }
+ * type Result = OmitVoid<Example> // { a: string, c: number }
+ * ```
+ *
+ * @public
+ */
 export declare type OmitVoid<T, KS extends keyof T = keyof T> = {
     [K in KS extends any ? (void extends T[KS] ? never : KS) : never]: T[K];
 };
@@ -55,26 +67,84 @@ export declare type OmitVoid<T, KS extends keyof T = keyof T> = {
 
 /* Excluded from this release type: RoomSessionState */
 
-/** @public */
+/**
+ * Snapshot of a room's complete state that can be persisted and restored.
+ * Contains all documents, tombstones, and metadata needed to reconstruct the room.
+ *
+ * @public
+ */
 export declare interface RoomSnapshot {
+    /**
+     * The current logical clock value for the room
+     */
     clock: number;
+    /**
+     * Clock value when document data was last changed (optional for backwards compatibility)
+     */
     documentClock?: number;
+    /**
+     * Array of all document records with their last modification clocks
+     */
     documents: Array<{
         lastChangedClock: number;
         state: UnknownRecord;
     }>;
+    /**
+     * Map of deleted record IDs to their deletion clock values (optional)
+     */
     tombstones?: Record<string, number>;
+    /**
+     * Clock value where tombstone history begins - older deletions are not tracked (optional)
+     */
     tombstoneHistoryStartsAtClock?: number;
+    /**
+     * Serialized schema used when creating this snapshot (optional)
+     */
     schema?: SerializedSchema;
 }
 
 /**
+ * Interface for making transactional changes to room store data. Used within
+ * updateStore transactions to modify documents atomically.
+ *
+ * @example
+ * ```ts
+ * await room.updateStore((store) => {
+ *   const shape = store.get('shape:123')
+ *   if (shape) {
+ *     store.put({ ...shape, x: shape.x + 10 })
+ *   }
+ *   store.delete('shape:456')
+ * })
+ * ```
+ *
  * @public
  */
 export declare interface RoomStoreMethods<R extends UnknownRecord = UnknownRecord> {
+    /**
+     * Add or update a record in the store.
+     *
+     * @param record - The record to store
+     */
     put(record: R): void;
+    /**
+     * Delete a record from the store.
+     *
+     * @param recordOrId - The record or record ID to delete
+     */
     delete(recordOrId: R | string): void;
+    /**
+     * Get a record by its ID.
+     *
+     * @param id - The record ID
+     * @returns The record or null if not found
+     */
     get(id: string): null | R;
+    /**
+     * Get all records in the store.
+     *
+     * @returns Array of all records
+     */
     getAll(): R[];
 }
 
@@ -83,7 +153,27 @@ export declare interface RoomStoreMethods<R extends UnknownRecord = UnknownRecor
 /* Excluded from this release type: TLConnectRequest */
 
 /**
- * Event handler for userland socket messages
+ * Handler function for custom application messages sent through the sync protocol.
+ * These are user-defined messages that can be sent between clients via the sync server,
+ * separate from the standard document synchronization messages.
+ *
+ * @param data - Custom message payload (application-defined structure)
+ *
+ * @example
+ * ```ts
+ * const customMessageHandler: TLCustomMessageHandler = (data) => {
+ *   if (data.type === 'user_joined') {
+ *     console.log(`${data.username} joined the session`)
+ *     showToast(`${data.username} is now collaborating`)
+ *   }
+ * }
+ *
+ * const syncClient = new TLSyncClient({
+ *   // ... other config
+ *   onCustomMessageReceived: customMessageHandler
+ * })
+ * ```
+ *
  * @public
  */
 export declare type TLCustomMessageHandler = (this: null, data: any) => void;
@@ -100,10 +190,58 @@ export declare type TLCustomMessageHandler = (this: null, data: any) => void;
 
 /* Excluded from this release type: TLPushRequest */
 
-/** @public */
+/**
+ * Specialized error class for synchronization-related failures in tldraw collaboration.
+ *
+ * This error is thrown when the sync client encounters fatal errors that prevent
+ * successful synchronization with the server. It captures both the error message
+ * and the specific reason code that triggered the failure.
+ *
+ * Common scenarios include schema version mismatches, authentication failures,
+ * network connectivity issues, and server-side validation errors.
+ *
+ * @example
+ * ```ts
+ * import { TLRemoteSyncError, TLSyncErrorCloseEventReason } from '@tldraw/sync-core'
+ *
+ * // Handle sync errors in your application
+ * syncClient.onSyncError((error) => {
+ *   if (error instanceof TLRemoteSyncError) {
+ *     switch (error.reason) {
+ *       case TLSyncErrorCloseEventReason.NOT_AUTHENTICATED:
+ *         // Redirect user to login
+ *         break
+ *       case TLSyncErrorCloseEventReason.CLIENT_TOO_OLD:
+ *         // Show update required message
+ *         break
+ *       default:
+ *         console.error('Sync error:', error.message)
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Server-side: throwing a sync error
+ * if (!hasPermission(userId, roomId)) {
+ *   throw new TLRemoteSyncError(TLSyncErrorCloseEventReason.FORBIDDEN)
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare class TLRemoteSyncError extends Error {
     readonly reason: string | TLSyncErrorCloseEventReason;
     name: string;
+    /**
+     * Creates a new TLRemoteSyncError with the specified reason.
+     *
+     * reason - The specific reason code or custom string describing why the sync failed.
+     *                 When using predefined reasons from TLSyncErrorCloseEventReason, the client
+     *                 can handle specific error types appropriately. Custom strings allow for
+     *                 application-specific error details.
+     */
     constructor(reason: string | TLSyncErrorCloseEventReason);
 }
 
@@ -111,7 +249,66 @@ export declare class TLRemoteSyncError extends Error {
 
 /* Excluded from this release type: TLSocketClientSentEvent */
 
-/** @public */
+/**
+ * A server-side room that manages WebSocket connections and synchronizes tldraw document state
+ * between multiple clients in real-time. Each room represents a collaborative document space
+ * where users can work together on drawings with automatic conflict resolution.
+ *
+ * TLSocketRoom handles:
+ * - WebSocket connection lifecycle management
+ * - Real-time synchronization of document changes
+ * - Session management and presence tracking
+ * - Message chunking for large payloads
+ * - Automatic client timeout and cleanup
+ *
+ * @example
+ * ```ts
+ * // Basic room setup
+ * const room = new TLSocketRoom({
+ *   onSessionRemoved: (room, { sessionId, numSessionsRemaining }) => {
+ *     console.log(`Client ${sessionId} disconnected, ${numSessionsRemaining} remaining`)
+ *     if (numSessionsRemaining === 0) {
+ *       room.close()
+ *     }
+ *   },
+ *   onDataChange: () => {
+ *     console.log('Document data changed, consider persisting')
+ *   }
+ * })
+ *
+ * // Handle new client connections
+ * room.handleSocketConnect({
+ *   sessionId: 'user-session-123',
+ *   socket: webSocket,
+ *   isReadonly: false
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Room with initial snapshot and schema
+ * const room = new TLSocketRoom({
+ *   initialSnapshot: existingSnapshot,
+ *   schema: myCustomSchema,
+ *   clientTimeout: 30000,
+ *   log: {
+ *     warn: (...args) => logger.warn('SYNC:', ...args),
+ *     error: (...args) => logger.error('SYNC:', ...args)
+ *   }
+ * })
+ *
+ * // Update document programmatically
+ * await room.updateStore(store => {
+ *   const shape = store.get('shape:abc123')
+ *   if (shape) {
+ *     shape.x = 100
+ *     store.put(shape)
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
 export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta = void> {
     readonly opts: {
         /* Excluded from this release type: onPresenceChange */
@@ -142,6 +339,20 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
     private readonly sessions;
     readonly log?: TLSyncLog;
     private readonly syncCallbacks;
+    /**
+     * Creates a new TLSocketRoom instance for managing collaborative document synchronization.
+     *
+     * opts - Configuration options for the room
+     *   - initialSnapshot - Optional initial document state to load
+     *   - schema - Store schema defining record types and validation
+     *   - clientTimeout - Milliseconds to wait before disconnecting inactive clients
+     *   - log - Optional logger for warnings and errors
+     *   - onSessionRemoved - Called when a client session is removed
+     *   - onBeforeSendMessage - Called before sending messages to clients
+     *   - onAfterReceiveMessage - Called after receiving messages from clients
+     *   - onDataChange - Called when document data changes
+     *   - onPresenceChange - Called when presence data changes
+     */
     constructor(opts: {
         /* Excluded from this release type: onPresenceChange */
         clientTimeout?: number;
@@ -176,14 +387,35 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      */
     getNumActiveSessions(): number;
     /**
-     * Call this when a client establishes a new socket connection.
+     * Handles a new client WebSocket connection, creating a session within the room.
+     * This should be called whenever a client establishes a WebSocket connection to join
+     * the collaborative document.
      *
-     * - `sessionId` is a unique ID for a browser tab. This is passed as a query param by the useSync hook.
-     * - `socket` is a WebSocket-like object that the server uses to communicate with the client.
-     * - `isReadonly` is an optional boolean that can be set to true if the client should not be able to make changes to the document. They will still be able to send presence updates.
-     * - `meta` is an optional object that can be used to store additional information about the session.
+     * @param opts - Connection options
+     *   - sessionId - Unique identifier for the client session (typically from browser tab)
+     *   - socket - WebSocket-like object for client communication
+     *   - isReadonly - Whether the client can modify the document (defaults to false)
+     *   - meta - Additional session metadata (required if SessionMeta is not void)
+     *
+     * @example
+     * ```ts
+     * // Handle new WebSocket connection
+     * room.handleSocketConnect({
+     *   sessionId: 'user-session-abc123',
+     *   socket: webSocketConnection,
+     *   isReadonly: !userHasEditPermission
+     * })
+     * ```
      *
-     * @param opts - The options object
+     * @example
+     * ```ts
+     * // With session metadata
+     * room.handleSocketConnect({
+     *   sessionId: 'session-xyz',
+     *   socket: ws,
+     *   meta: { userId: 'user-123', name: 'Alice' }
+     * })
+     * ```
      */
     handleSocketConnect(opts: {
         isReadonly?: boolean;
@@ -193,42 +425,119 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
         meta: SessionMeta;
     })): void;
     /**
-     * If executing in a server environment where sockets do not have instance-level listeners
-     * (e.g. Bun.serve, Cloudflare Worker with WebSocket hibernation), you should call this
-     * method when messages are received. See our self-hosting example for Bun.serve for an example.
+     * Processes a message received from a client WebSocket. Use this method in server
+     * environments where WebSocket event listeners cannot be attached directly to socket
+     * instances (e.g., Bun.serve, Cloudflare Workers with WebSocket hibernation).
      *
-     * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
-     * @param message - The message received from the client.
+     * The method handles message chunking/reassembly and forwards complete messages
+     * to the underlying sync room for processing.
+     *
+     * @param sessionId - Session identifier matching the one used in handleSocketConnect
+     * @param message - Raw message data from the client (string or binary)
+     *
+     * @example
+     * ```ts
+     * // In a Bun.serve handler
+     * server.upgrade(req, {
+     *   data: { sessionId, room },
+     *   upgrade(res, req) {
+     *     // Connection established
+     *   },
+     *   message(ws, message) {
+     *     const { sessionId, room } = ws.data
+     *     room.handleSocketMessage(sessionId, message)
+     *   }
+     * })
+     * ```
      */
     handleSocketMessage(sessionId: string, message: AllowSharedBufferSource | string): void;
     /**
-     * If executing in a server environment where sockets do not have instance-level listeners,
-     * call this when a socket error occurs.
-     * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
+     * Handles a WebSocket error for the specified session. Use this in server environments
+     * where socket event listeners cannot be attached directly. This will initiate cleanup
+     * and session removal for the affected client.
+     *
+     * @param sessionId - Session identifier matching the one used in handleSocketConnect
+     *
+     * @example
+     * ```ts
+     * // In a custom WebSocket handler
+     * socket.addEventListener('error', () => {
+     *   room.handleSocketError(sessionId)
+     * })
+     * ```
      */
     handleSocketError(sessionId: string): void;
     /**
-     * If executing in a server environment where sockets do not have instance-level listeners,
-     * call this when a socket is closed.
-     * @param sessionId - The id of the session. (should match the one used when calling handleSocketConnect)
+     * Handles a WebSocket close event for the specified session. Use this in server
+     * environments where socket event listeners cannot be attached directly. This will
+     * initiate cleanup and session removal for the disconnected client.
+     *
+     * @param sessionId - Session identifier matching the one used in handleSocketConnect
+     *
+     * @example
+     * ```ts
+     * // In a custom WebSocket handler
+     * socket.addEventListener('close', () => {
+     *   room.handleSocketClose(sessionId)
+     * })
+     * ```
      */
     handleSocketClose(sessionId: string): void;
     /**
-     * Returns the current 'clock' of the document.
-     * The clock is an integer that increments every time the document changes.
-     * The clock is stored as part of the snapshot of the document for consistency purposes.
+     * Returns the current document clock value. The clock is a monotonically increasing
+     * integer that increments with each document change, providing a consistent ordering
+     * of changes across the distributed system.
      *
-     * @returns The clock
+     * @returns The current document clock value
+     *
+     * @example
+     * ```ts
+     * const clock = room.getCurrentDocumentClock()
+     * console.log(`Document is at version ${clock}`)
+     * ```
      */
     getCurrentDocumentClock(): number;
     /**
-     * Returns a deeply cloned record from the store, if available.
-     * @param id - The id of the record
-     * @returns the cloned record
+     * Retrieves a deeply cloned copy of a record from the document store.
+     * Returns undefined if the record doesn't exist. The returned record is
+     * safe to mutate without affecting the original store data.
+     *
+     * @param id - Unique identifier of the record to retrieve
+     * @returns Deep clone of the record, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * const shape = room.getRecord('shape:abc123')
+     * if (shape) {
+     *   console.log('Shape position:', shape.x, shape.y)
+     *   // Safe to modify without affecting store
+     *   shape.x = 100
+     * }
+     * ```
      */
     getRecord(id: string): R | undefined;
     /**
-     * Returns a list of the sessions in the room.
+     * Returns information about all active sessions in the room. Each session
+     * represents a connected client with their current connection status and metadata.
+     *
+     * @returns Array of session information objects containing:
+     *   - sessionId - Unique session identifier
+     *   - isConnected - Whether the session has an active WebSocket connection
+     *   - isReadonly - Whether the session can modify the document
+     *   - meta - Custom session metadata
+     *
+     * @example
+     * ```ts
+     * const sessions = room.getSessions()
+     * console.log(`Room has ${sessions.length} active sessions`)
+     *
+     * for (const session of sessions) {
+     *   console.log(`${session.sessionId}: ${session.isConnected ? 'online' : 'offline'}`)
+     *   if (session.isReadonly) {
+     *     console.log('  (read-only access)')
+     *   }
+     * }
+     * ```
      */
     getSessions(): Array<{
         isConnected: boolean;
@@ -237,66 +546,172 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
         sessionId: string;
     }>;
     /**
-     * Return a snapshot of the document state, including clock-related bookkeeping.
-     * You can store this and load it later on when initializing a TLSocketRoom.
-     * You can also pass a snapshot to {@link TLSocketRoom#loadSnapshot} if you need to revert to a previous state.
-     * @returns The snapshot
+     * Creates a complete snapshot of the current document state, including all records
+     * and synchronization metadata. This snapshot can be persisted to storage and used
+     * to restore the room state later or revert to a previous version.
+     *
+     * @returns Complete room snapshot including documents, clock values, and tombstones
+     *
+     * @example
+     * ```ts
+     * // Capture current state for persistence
+     * const snapshot = room.getCurrentSnapshot()
+     * await saveToDatabase(roomId, JSON.stringify(snapshot))
+     *
+     * // Later, restore from snapshot
+     * const savedSnapshot = JSON.parse(await loadFromDatabase(roomId))
+     * const newRoom = new TLSocketRoom({ initialSnapshot: savedSnapshot })
+     * ```
      */
     getCurrentSnapshot(): RoomSnapshot;
     /* Excluded from this release type: getPresenceRecords */
     /* Excluded from this release type: getCurrentSerializedSnapshot */
     /**
-     * Load a snapshot of the document state, overwriting the current state.
-     * @param snapshot - The snapshot to load
+     * Loads a document snapshot, completely replacing the current room state.
+     * This will disconnect all current clients and update the document to match
+     * the provided snapshot. Use this for restoring from backups or implementing
+     * document versioning.
+     *
+     * @param snapshot - Room or store snapshot to load
+     *
+     * @example
+     * ```ts
+     * // Restore from a saved snapshot
+     * const backup = JSON.parse(await loadBackup(roomId))
+     * room.loadSnapshot(backup)
+     *
+     * // All clients will be disconnected and need to reconnect
+     * // to see the restored document state
+     * ```
      */
     loadSnapshot(snapshot: RoomSnapshot | TLStoreSnapshot): void;
     /**
-     * Allow applying changes to the store inside of a transaction.
+     * Executes a transaction to modify the document store. Changes made within the
+     * transaction are atomic and will be synchronized to all connected clients.
+     * The transaction provides isolation from concurrent changes until it commits.
      *
-     * You can get values from the store by id with `store.get(id)`.
-     * These values are safe to mutate, but to commit the changes you must call `store.put(...)` with the updated value.
-     * You can get all values in the store with `store.getAll()`.
-     * You can also delete values with `store.delete(id)`.
+     * @param updater - Function that receives store methods to make changes
+     *   - store.get(id) - Retrieve a record (safe to mutate, but must call put() to commit)
+     *   - store.put(record) - Save a modified record
+     *   - store.getAll() - Get all records in the store
+     *   - store.delete(id) - Remove a record from the store
+     * @returns Promise that resolves when the transaction completes
      *
      * @example
      * ```ts
-     * room.updateStore(store => {
-     *   const shape = store.get('shape:abc123')
-     *   shape.meta.approved = true
-     *   store.put(shape)
+     * // Update multiple shapes in a single transaction
+     * await room.updateStore(store => {
+     *   const shape1 = store.get('shape:abc123')
+     *   const shape2 = store.get('shape:def456')
+     *
+     *   if (shape1) {
+     *     shape1.x = 100
+     *     store.put(shape1)
+     *   }
+     *
+     *   if (shape2) {
+     *     shape2.meta.approved = true
+     *     store.put(shape2)
+     *   }
      * })
      * ```
      *
-     * Changes to the store inside the callback are isolated from changes made by other clients until the transaction commits.
-     *
-     * @param updater - A function that will be called with a store object that can be used to make changes.
-     * @returns A promise that resolves when the transaction is complete.
+     * @example
+     * ```ts
+     * // Async transaction with external API call
+     * await room.updateStore(async store => {
+     *   const doc = store.get('document:main')
+     *   if (doc) {
+     *     doc.lastModified = await getCurrentTimestamp()
+     *     store.put(doc)
+     *   }
+     * })
+     * ```
      */
     updateStore(updater: (store: RoomStoreMethods<R>) => Promise<void> | void): Promise<void>;
     /**
-     * Send a custom message to a connected client.
+     * Sends a custom message to a specific client session. This allows sending
+     * application-specific data that doesn't modify the document state, such as
+     * notifications, chat messages, or custom commands.
+     *
+     * @param sessionId - Target session identifier
+     * @param data - Custom payload to send (will be JSON serialized)
+     *
+     * @example
+     * ```ts
+     * // Send a notification to a specific user
+     * room.sendCustomMessage('session-123', {
+     *   type: 'notification',
+     *   message: 'Your changes have been saved'
+     * })
      *
-     * @param sessionId - The id of the session to send the message to.
-     * @param data - The payload to send.
+     * // Send a chat message
+     * room.sendCustomMessage('session-456', {
+     *   type: 'chat',
+     *   from: 'Alice',
+     *   text: 'Great work on this design!'
+     * })
+     * ```
      */
     sendCustomMessage(sessionId: string, data: any): void;
     /**
-     * Immediately remove a session from the room, and close its socket if not already closed.
+     * Immediately removes a session from the room and closes its WebSocket connection.
+     * The client will attempt to reconnect automatically unless a fatal reason is provided.
      *
-     * The client will attempt to reconnect unless you provide a `fatalReason` parameter.
+     * @param sessionId - Session identifier to remove
+     * @param fatalReason - Optional fatal error reason that prevents reconnection
      *
-     * The `fatalReason` parameter will be available in the return value of the `useSync` hook as `useSync().error.reason`.
+     * @example
+     * ```ts
+     * // Kick a user (they can reconnect)
+     * room.closeSession('session-troublemaker')
      *
-     * @param sessionId - The id of the session to remove
-     * @param fatalReason - The reason message to use when calling .close on the underlying websocket
+     * // Permanently ban a user
+     * room.closeSession('session-banned', 'PERMISSION_DENIED')
+     *
+     * // Close session due to inactivity
+     * room.closeSession('session-idle', 'TIMEOUT')
+     * ```
      */
     closeSession(sessionId: string, fatalReason?: string | TLSyncErrorCloseEventReason): void;
     /**
-     * Close the room and disconnect all clients. Call this before discarding the room instance or shutting down the server.
+     * Closes the room and disconnects all connected clients. This should be called
+     * when shutting down the room permanently, such as during server shutdown or
+     * when the room is no longer needed. Once closed, the room cannot be reopened.
+     *
+     * @example
+     * ```ts
+     * // Clean shutdown when no users remain
+     * if (room.getNumActiveSessions() === 0) {
+     *   await persistSnapshot(room.getCurrentSnapshot())
+     *   room.close()
+     * }
+     *
+     * // Server shutdown
+     * process.on('SIGTERM', () => {
+     *   for (const room of activeRooms.values()) {
+     *     room.close()
+     *   }
+     * })
+     * ```
      */
     close(): void;
     /**
-     * @returns true if the room is closed
+     * Checks whether the room has been permanently closed. Closed rooms cannot
+     * accept new connections or process further changes.
+     *
+     * @returns True if the room is closed, false if still active
+     *
+     * @example
+     * ```ts
+     * if (room.isClosed()) {
+     *   console.log('Room has been shut down')
+     *   // Create a new room or redirect users
+     * } else {
+     *   // Room is still accepting connections
+     *   room.handleSocketConnect({ sessionId, socket })
+     * }
+     * ```
      */
     isClosed(): boolean;
 }
@@ -312,47 +727,115 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
 /* Excluded from this release type: TLSyncClient */
 
 /**
- * This the close code that we use on the server to signal to a socket that
- * the connection is being closed because of a non-recoverable error.
- *
- * You should use this if you need to close a connection.
+ * WebSocket close code used by the server to signal a non-recoverable sync error.
+ * This close code indicates that the connection is being terminated due to an error
+ * that cannot be automatically recovered from, such as authentication failures,
+ * incompatible client versions, or invalid data.
  *
  * @example
  * ```ts
+ * // Server-side: Close connection with specific error reason
  * socket.close(TLSyncErrorCloseEventCode, TLSyncErrorCloseEventReason.NOT_FOUND)
- * ```
  *
- * The `reason` parameter that you pass to `socket.close()` will be made available at `useSync().error.reason`
+ * // Client-side: Handle the error in your sync error handler
+ * const syncClient = new TLSyncClient({
+ *   // ... other config
+ *   onSyncError: (reason) => {
+ *     console.error('Sync failed:', reason) // Will receive 'NOT_FOUND'
+ *   }
+ * })
+ * ```
  *
  * @public
  */
 export declare const TLSyncErrorCloseEventCode: 4099;
 
 /**
- * The set of reasons that a connection can be closed by the server
+ * Predefined reasons for server-initiated connection closures.
+ * These constants represent different error conditions that can cause
+ * the sync server to terminate a WebSocket connection.
+ *
+ * @example
+ * ```ts
+ * // Server usage
+ * if (!user.hasPermission(roomId)) {
+ *   socket.close(TLSyncErrorCloseEventCode, TLSyncErrorCloseEventReason.FORBIDDEN)
+ * }
+ *
+ * // Client error handling
+ * syncClient.onSyncError((reason) => {
+ *   switch (reason) {
+ *     case TLSyncErrorCloseEventReason.NOT_FOUND:
+ *       showError('Room does not exist')
+ *       break
+ *     case TLSyncErrorCloseEventReason.FORBIDDEN:
+ *       showError('Access denied')
+ *       break
+ *     case TLSyncErrorCloseEventReason.CLIENT_TOO_OLD:
+ *       showError('Please update your app')
+ *       break
+ *   }
+ * })
+ * ```
+ *
  * @public
  */
 export declare const TLSyncErrorCloseEventReason: {
+    /** Client exceeded rate limits */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Client protocol version too old */
     readonly CLIENT_TOO_OLD: "CLIENT_TOO_OLD";
-    readonly FORBIDDEN: "FORBIDDEN";
+    /** Client sent invalid or corrupted record data */
     readonly INVALID_RECORD: "INVALID_RECORD";
-    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Room has reached maximum capacity */
     readonly ROOM_FULL: "ROOM_FULL";
+    /** Room or resource not found */
+    readonly NOT_FOUND: "NOT_FOUND";
+    /** Server protocol version too old */
     readonly SERVER_TOO_OLD: "SERVER_TOO_OLD";
+    /** Unexpected server error occurred */
     readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    /** User authentication required or invalid */
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    /** User lacks permission to access the room */
+    readonly FORBIDDEN: "FORBIDDEN";
 };
 
 /**
- * The set of reasons that a connection can be closed by the server
+ * Union type of all possible server connection close reasons.
+ * Represents the string values that can be passed when a server closes
+ * a sync connection due to an error condition.
+ *
  * @public
  */
 export declare type TLSyncErrorCloseEventReason = (typeof TLSyncErrorCloseEventReason)[keyof typeof TLSyncErrorCloseEventReason];
 
-/** @public */
+/**
+ * Logging interface for TLSocketRoom operations. Provides optional methods
+ * for warning and error logging during synchronization operations.
+ *
+ * @example
+ * ```ts
+ * const logger: TLSyncLog = {
+ *   warn: (...args) => console.warn('[SYNC]', ...args),
+ *   error: (...args) => console.error('[SYNC]', ...args)
+ * }
+ *
+ * const room = new TLSocketRoom({ log: logger })
+ * ```
+ *
+ * @public
+ */
 export declare interface TLSyncLog {
+    /**
+     * Optional warning logger for non-fatal sync issues
+     * @param args - Arguments to log
+     */
     warn?(...args: any[]): void;
+    /**
+     * Optional error logger for sync errors and failures
+     * @param args - Arguments to log
+     */
     error?(...args: any[]): void;
 }
 
@@ -363,19 +846,66 @@ export declare interface TLSyncLog {
 /* Excluded from this release type: ValueOpType */
 
 /**
- * Minimal server-side WebSocket interface that is compatible with
+ * Minimal server-side WebSocket interface that is compatible with various WebSocket implementations.
+ * This interface abstracts over different WebSocket libraries and platforms to provide a consistent
+ * API for the ServerSocketAdapter.
  *
- * - The standard WebSocket interface (cloudflare, deno, some node setups)
- * - The 'ws' WebSocket interface (some node setups)
+ * Supports:
+ * - The standard WebSocket interface (Cloudflare, Deno, some Node.js setups)
+ * - The 'ws' WebSocket interface (Node.js ws library)
  * - The Bun.serve socket implementation
  *
  * @public
+ * @example
+ * ```ts
+ * // Standard WebSocket
+ * const standardWs: WebSocketMinimal = new WebSocket('ws://localhost:8080')
+ *
+ * // Node.js 'ws' library WebSocket
+ * import WebSocket from 'ws'
+ * const nodeWs: WebSocketMinimal = new WebSocket('ws://localhost:8080')
+ *
+ * // Bun WebSocket (in server context)
+ * // const bunWs: WebSocketMinimal = server.upgrade(request)
+ * ```
  */
 export declare interface WebSocketMinimal {
+    /**
+     * Optional method to add event listeners for WebSocket events.
+     * Not all WebSocket implementations provide this method.
+     *
+     * @param type - The event type to listen for
+     * @param listener - The event handler function
+     */
     addEventListener?: (type: 'close' | 'error' | 'message', listener: (event: any) => void) => void;
+    /**
+     * Optional method to remove event listeners for WebSocket events.
+     * Not all WebSocket implementations provide this method.
+     *
+     * @param type - The event type to stop listening for
+     * @param listener - The event handler function to remove
+     */
     removeEventListener?: (type: 'close' | 'error' | 'message', listener: (event: any) => void) => void;
+    /**
+     * Sends a string message through the WebSocket connection.
+     *
+     * @param data - The string data to send
+     */
     send: (data: string) => void;
+    /**
+     * Closes the WebSocket connection.
+     *
+     * @param code - Optional close code (default: 1000 for normal closure)
+     * @param reason - Optional human-readable close reason
+     */
     close: (code?: number, reason?: string) => void;
+    /**
+     * The current state of the WebSocket connection.
+     * - 0: CONNECTING
+     * - 1: OPEN
+     * - 2: CLOSING
+     * - 3: CLOSED
+     */
     readyState: number;
 }