@tldraw/sync-core 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b9999db71010

package/src/lib/diff.ts

@@ -1,17 +1,32 @@
 import { RecordsDiff, UnknownRecord } from '@tldraw/store'
 import { isEqual, objectMapEntries, objectMapValues } from '@tldraw/utils'
 
-/** @internal */
+/**
+ * Constants representing the types of operations that can be applied to records in network diffs.
+ * These operations describe how a record has been modified during synchronization.
+ *
+ * @internal
+ */
 export const RecordOpType = {
 	Put: 'put',
 	Patch: 'patch',
 	Remove: 'remove',
 } as const
 
-/** @internal */
+/**
+ * Union type of all possible record operation types.
+ *
+ * @internal
+ */
 export type RecordOpType = (typeof RecordOpType)[keyof typeof RecordOpType]
 
-/** @internal */
+/**
+ * Represents a single operation to be applied to a record during synchronization.
+ *
+ * @param R - The record type being operated on
+ *
+ * @internal
+ */
 export type RecordOp<R extends UnknownRecord> =
 	| [typeof RecordOpType.Put, R]
 	| [typeof RecordOpType.Patch, ObjectDiff]
@@ -32,8 +47,29 @@ export interface NetworkDiff<R extends UnknownRecord> {
 
 /**
  * Converts a (reversible, verbose) RecordsDiff into a (non-reversible, concise) NetworkDiff
+ * suitable for transmission over the network. This function optimizes the diff representation
+ * for minimal bandwidth usage while maintaining all necessary change information.
+ *
+ * @param diff - The RecordsDiff containing added, updated, and removed records
+ * @returns A compact NetworkDiff for network transmission, or null if no changes exist
+ *
+ * @example
+ * ```ts
+ * const recordsDiff = {
+ *   added: { 'shape:1': newShape },
+ *   updated: { 'shape:2': [oldShape, updatedShape] },
+ *   removed: { 'shape:3': removedShape }
+ * }
+ *
+ * const networkDiff = getNetworkDiff(recordsDiff)
+ * // Returns: {
+ * //   'shape:1': ['put', newShape],
+ * //   'shape:2': ['patch', { x: ['put', 100] }],
+ * //   'shape:3': ['remove']
+ * // }
+ * ```
  *
- *@internal
+ * @internal
  */
 export function getNetworkDiff<R extends UnknownRecord>(
 	diff: RecordsDiff<R>
@@ -61,34 +97,90 @@ export function getNetworkDiff<R extends UnknownRecord>(
 	return res
 }
 
-/** @internal */
+/**
+ * Constants representing the types of operations that can be applied to individual values
+ * within object diffs. These operations describe how object properties have changed.
+ *
+ * @internal
+ */
 export const ValueOpType = {
 	Put: 'put',
 	Delete: 'delete',
 	Append: 'append',
 	Patch: 'patch',
 } as const
-/** @internal */
+/**
+ * Union type of all possible value operation types.
+ *
+ * @internal
+ */
 export type ValueOpType = (typeof ValueOpType)[keyof typeof ValueOpType]
 
-/** @internal */
+/**
+ * Operation that replaces a value entirely with a new value.
+ *
+ * @internal
+ */
 export type PutOp = [type: typeof ValueOpType.Put, value: unknown]
-/** @internal */
+/**
+ * Operation that appends new values to the end of an array.
+ *
+ * @internal
+ */
 export type AppendOp = [type: typeof ValueOpType.Append, values: unknown[], offset: number]
-/** @internal */
+/**
+ * Operation that applies a nested diff to an object or array.
+ *
+ * @internal
+ */
 export type PatchOp = [type: typeof ValueOpType.Patch, diff: ObjectDiff]
-/** @internal */
+/**
+ * Operation that removes a property from an object.
+ *
+ * @internal
+ */
 export type DeleteOp = [type: typeof ValueOpType.Delete]
 
-/** @internal */
+/**
+ * Union type representing any value operation that can be applied during diffing.
+ *
+ * @internal
+ */
 export type ValueOp = PutOp | AppendOp | PatchOp | DeleteOp
 
-/** @internal */
+/**
+ * Represents the differences between two objects as a mapping of property names
+ * to the operations needed to transform one object into another.
+ *
+ * @internal
+ */
 export interface ObjectDiff {
 	[k: string]: ValueOp
 }
 
-/** @internal */
+/**
+ * Computes the difference between two record objects, generating an ObjectDiff
+ * that describes how to transform the previous record into the next record.
+ * This function is optimized for tldraw records and treats 'props' as a nested object.
+ *
+ * @param prev - The previous version of the record
+ * @param next - The next version of the record
+ * @returns An ObjectDiff describing the changes, or null if no changes exist
+ *
+ * @example
+ * ```ts
+ * const oldShape = { id: 'shape:1', x: 100, y: 200, props: { color: 'red' } }
+ * const newShape = { id: 'shape:1', x: 150, y: 200, props: { color: 'blue' } }
+ *
+ * const diff = diffRecord(oldShape, newShape)
+ * // Returns: {
+ * //   x: ['put', 150],
+ * //   props: ['patch', { color: ['put', 'blue'] }]
+ * // }
+ * ```
+ *
+ * @internal
+ */
 export function diffRecord(prev: object, next: object): ObjectDiff | null {
 	return diffObject(prev, next, new Set(['props']))
 }
@@ -197,7 +289,29 @@ function diffArray(prevArray: unknown[], nextArray: unknown[]): PutOp | AppendOp
 	return [ValueOpType.Append, nextArray.slice(prevArray.length), prevArray.length]
 }
 
-/** @internal */
+/**
+ * Applies an ObjectDiff to an object, returning a new object with the changes applied.
+ * This function handles all value operation types and creates a shallow copy when modifications
+ * are needed. If no changes are required, the original object is returned.
+ *
+ * @param object - The object to apply the diff to
+ * @param objectDiff - The ObjectDiff containing the operations to apply
+ * @returns A new object with the diff applied, or the original object if no changes were needed
+ *
+ * @example
+ * ```ts
+ * const original = { x: 100, y: 200, props: { color: 'red' } }
+ * const diff = {
+ *   x: ['put', 150],
+ *   props: ['patch', { color: ['put', 'blue'] }]
+ * }
+ *
+ * const updated = applyObjectDiff(original, diff)
+ * // Returns: { x: 150, y: 200, props: { color: 'blue' } }
+ * ```
+ *
+ * @internal
+ */
 export function applyObjectDiff<T extends object>(object: T, objectDiff: ObjectDiff): T {
 	// don't patch nulls
 	if (!object || typeof object !== 'object') return object

package/src/lib/findMin.ts

@@ -3,6 +3,12 @@
  *
  * @param values - An iterable of numbers to find the minimum from
  * @returns The minimum value, or null if the iterable is empty
+ * @example
+ * ```ts
+ * findMin([3, 1, 4, 1, 5]) // returns 1
+ * findMin(new Set([10, 5, 8])) // returns 5
+ * findMin([]) // returns null
+ * ```
  */
 export function findMin(values: Iterable<number>): number | null {
 	let min: number | null = null

package/src/lib/interval.ts

@@ -1,3 +1,43 @@
+/**
+ * Creates a repeating timer that executes a callback at regular intervals and returns a cleanup function.
+ *
+ * This utility function wraps the standard `setInterval`/`clearInterval` pattern into a more convenient
+ * interface that returns a dispose function for cleanup. It's commonly used in the sync system for
+ * periodic tasks like health checks, ping operations, and session pruning.
+ *
+ * @param cb - The callback function to execute at each interval
+ * @param timeout - The time interval in milliseconds between callback executions
+ * @returns A cleanup function that stops the interval when called
+ *
+ * @example
+ * ```ts
+ * // Create a periodic health check
+ * const stopHealthCheck = interval(() => {
+ *   console.log('Checking server health...')
+ *   checkServerConnection()
+ * }, 5000)
+ *
+ * // Later, stop the health check
+ * stopHealthCheck()
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use in a disposables array for cleanup management
+ * class MyClass {
+ *   private disposables = [
+ *     interval(() => this.sendPing(), 30000),
+ *     interval(() => this.pruneSessions(), 2000)
+ *   ]
+ *
+ *   dispose() {
+ *     this.disposables.forEach(dispose => dispose())
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export function interval(cb: () => void, timeout: number) {
 	const i = setInterval(cb, timeout)
 	return () => clearInterval(i)

package/src/lib/protocol.ts

@@ -3,12 +3,41 @@ import { NetworkDiff, ObjectDiff, RecordOpType } from './diff'
 
 const TLSYNC_PROTOCOL_VERSION = 7
 
-/** @internal */
+/**
+ * Gets the current tldraw sync protocol version number.
+ *
+ * This version number is used during WebSocket connection handshake to ensure
+ * client and server compatibility. When versions don't match, the connection
+ * will be rejected with an incompatibility error.
+ *
+ * @returns The current protocol version number
+ *
+ * @example
+ * ```ts
+ * const version = getTlsyncProtocolVersion()
+ * console.log(`Using protocol version: ${version}`)
+ * ```
+ *
+ * @internal
+ */
 export function getTlsyncProtocolVersion() {
 	return TLSYNC_PROTOCOL_VERSION
 }
 
 /**
+ * Constants defining the different types of protocol incompatibility reasons.
+ *
+ * These values indicate why a client-server connection was rejected due to
+ * version or compatibility issues. Each reason helps diagnose specific problems
+ * during the connection handshake.
+ *
+ * @example
+ * ```ts
+ * if (error.reason === TLIncompatibilityReason.ClientTooOld) {
+ *   showUpgradeMessage('Please update your client')
+ * }
+ * ```
+ *
  * @internal
  * @deprecated Replaced by websocket .close status/reason
  */
@@ -20,13 +49,53 @@ export const TLIncompatibilityReason = {
 } as const
 
 /**
+ * Union type representing all possible incompatibility reason values.
+ *
+ * This type represents the different reasons why a client-server connection
+ * might fail due to protocol or version mismatches.
+ *
+ * @example
+ * ```ts
+ * function handleIncompatibility(reason: TLIncompatibilityReason) {
+ *   switch (reason) {
+ *     case 'clientTooOld':
+ *       return 'Client needs to be updated'
+ *     case 'serverTooOld':
+ *       return 'Server needs to be updated'
+ *   }
+ * }
+ * ```
+ *
  * @internal
  * @deprecated replaced by websocket .close status/reason
  */
 export type TLIncompatibilityReason =
 	(typeof TLIncompatibilityReason)[keyof typeof TLIncompatibilityReason]
 
-/** @internal */
+/**
+ * Union type representing all possible message types that can be sent from server to client.
+ *
+ * This encompasses the complete set of server-originated WebSocket messages in the tldraw
+ * sync protocol, including connection establishment, data synchronization, and error handling.
+ *
+ * @param R - The record type being synchronized (extends UnknownRecord)
+ *
+ * @example
+ * ```ts
+ * syncClient.onReceiveMessage((message: TLSocketServerSentEvent<MyRecord>) => {
+ *   switch (message.type) {
+ *     case 'connect':
+ *       console.log('Connected to room with clock:', message.serverClock)
+ *       break
+ *     case 'data':
+ *       console.log('Received data updates:', message.data)
+ *       break
+ *   }
+ * })
+ * ```
+ *
+ * @internal
+ */
 export type TLSocketServerSentEvent<R extends UnknownRecord> =
 	| {
 			type: 'connect'
@@ -50,7 +119,31 @@ export type TLSocketServerSentEvent<R extends UnknownRecord> =
 	| { type: 'custom'; data: any }
 	| TLSocketServerSentDataEvent<R>
 
-/** @internal */
+/**
+ * Union type representing data-related messages sent from server to client.
+ *
+ * These messages handle the core synchronization operations: applying patches from
+ * other clients and confirming the results of client push operations.
+ *
+ * @param R - The record type being synchronized (extends UnknownRecord)
+ *
+ * @example
+ * ```ts
+ * function handleDataEvent(event: TLSocketServerSentDataEvent<MyRecord>) {
+ *   if (event.type === 'patch') {
+ *     // Apply changes from other clients
+ *     applyNetworkDiff(event.diff)
+ *   } else if (event.type === 'push_result') {
+ *     // Handle result of our push request
+ *     if (event.action === 'commit') {
+ *       console.log('Changes accepted by server')
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type TLSocketServerSentDataEvent<R extends UnknownRecord> =
 	| {
 			type: 'patch'
@@ -64,7 +157,30 @@ export type TLSocketServerSentDataEvent<R extends UnknownRecord> =
 			action: 'discard' | 'commit' | { rebaseWithDiff: NetworkDiff<R> }
 	  }
 
-/** @internal */
+/**
+ * Interface defining a client-to-server push request message.
+ *
+ * Push requests are sent when the client wants to synchronize local changes
+ * with the server. They contain document changes and optionally presence updates
+ * (like cursor position or user selection).
+ *
+ * @param R - The record type being synchronized (extends UnknownRecord)
+ *
+ * @example
+ * ```ts
+ * const pushRequest: TLPushRequest<MyRecord> = {
+ *   type: 'push',
+ *   clientClock: 15,
+ *   diff: {
+ *     'shape:abc123': [RecordOpType.Patch, { x: [ValueOpType.Put, 100] }]
+ *   },
+ *   presence: [RecordOpType.Put, { cursor: { x: 150, y: 200 } }]
+ * }
+ * socket.sendMessage(pushRequest)
+ * ```
+ *
+ * @internal
+ */
 export interface TLPushRequest<R extends UnknownRecord> {
 	type: 'push'
 	clientClock: number
@@ -72,7 +188,27 @@ export interface TLPushRequest<R extends UnknownRecord> {
 	presence?: [typeof RecordOpType.Patch, ObjectDiff] | [typeof RecordOpType.Put, R]
 }
 
-/** @internal */
+/**
+ * Interface defining a client-to-server connection request message.
+ *
+ * This message initiates a WebSocket connection to a sync room. It includes
+ * the client's schema, protocol version, and last known server clock for
+ * proper synchronization state management.
+ *
+ * @example
+ * ```ts
+ * const connectRequest: TLConnectRequest = {
+ *   type: 'connect',
+ *   connectRequestId: 'conn-123',
+ *   lastServerClock: 42,
+ *   protocolVersion: getTlsyncProtocolVersion(),
+ *   schema: mySchema.serialize()
+ * }
+ * socket.sendMessage(connectRequest)
+ * ```
+ *
+ * @internal
+ */
 export interface TLConnectRequest {
 	type: 'connect'
 	connectRequestId: string
@@ -81,12 +217,54 @@ export interface TLConnectRequest {
 	schema: SerializedSchema
 }
 
-/** @internal */
+/**
+ * Interface defining a client-to-server ping request message.
+ *
+ * Ping requests are used to measure network latency and ensure the connection
+ * is still active. The server responds with a 'pong' message.
+ *
+ * @example
+ * ```ts
+ * const pingRequest: TLPingRequest = { type: 'ping' }
+ * socket.sendMessage(pingRequest)
+ *
+ * // Server will respond with { type: 'pong' }
+ * ```
+ *
+ * @internal
+ */
 export interface TLPingRequest {
 	type: 'ping'
 }
 
-/** @internal */
+/**
+ * Union type representing all possible message types that can be sent from client to server.
+ *
+ * This encompasses the complete set of client-originated WebSocket messages in the tldraw
+ * sync protocol, covering connection establishment, data synchronization, and connectivity checks.
+ *
+ * @param R - The record type being synchronized (extends UnknownRecord)
+ *
+ * @example
+ * ```ts
+ * function sendMessage(message: TLSocketClientSentEvent<MyRecord>) {
+ *   switch (message.type) {
+ *     case 'connect':
+ *       console.log('Establishing connection...')
+ *       break
+ *     case 'push':
+ *       console.log('Pushing changes:', message.diff)
+ *       break
+ *     case 'ping':
+ *       console.log('Checking connection latency')
+ *       break
+ *   }
+ *   socket.send(JSON.stringify(message))
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type TLSocketClientSentEvent<R extends UnknownRecord> =
 	| TLPushRequest<R>
 	| TLConnectRequest

package/src/lib/server-types.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { PersistedRoomSnapshotForSupabase } from './server-types'
+import { RoomSnapshot } from './TLSyncRoom'
+
+describe('PersistedRoomSnapshotForSupabase', () => {
+	describe('JSON serialization compatibility', () => {
+		it('should properly serialize and deserialize for database storage', () => {
+			// This tests actual business logic: compatibility with database storage
+			const roomSnapshot: RoomSnapshot = {
+				clock: 42,
+				documentClock: 38,
+				documents: [
+					{
+						state: {
+							id: 'shape:test' as any,
+							typeName: 'shape',
+							type: 'geo',
+							x: 100,
+							y: 200,
+						} as any,
+						lastChangedClock: 35,
+					},
+				],
+				tombstones: { 'shape:deleted': 20 },
+				tombstoneHistoryStartsAtClock: 15,
+			}
+
+			const persistedData: PersistedRoomSnapshotForSupabase = {
+				id: 'test-room-id',
+				slug: 'test-room-slug',
+				drawing: roomSnapshot,
+			}
+
+			// Test actual serialization behavior that matters for database storage
+			const serialized = JSON.stringify(persistedData)
+			const deserialized = JSON.parse(serialized) as PersistedRoomSnapshotForSupabase
+
+			// Verify critical data survives serialization roundtrip
+			expect(deserialized.drawing.clock).toBe(42)
+			expect(deserialized.drawing.documents[0].state.id).toBe('shape:test')
+			expect(deserialized.drawing.tombstones!['shape:deleted']).toBe(20)
+		})
+	})
+})

package/src/lib/server-types.ts

@@ -1,6 +1,50 @@
 import { RoomSnapshot } from './TLSyncRoom'
 
-/** @internal */
+/**
+ * Database schema interface for persisting tldraw room snapshots in Supabase.
+ *
+ * This interface defines the structure used to store collaborative drawing rooms
+ * in a Supabase database, containing both metadata and the complete room state.
+ * The room snapshot includes all documents, tombstones, and synchronization clocks
+ * needed to restore a collaborative session.
+ *
+ * @param id - Unique identifier for the persisted room record in the database
+ * @param slug - Human-readable URL slug or identifier for the room (e.g., "my-drawing-123")
+ * @param drawing - Complete room snapshot containing all synchronized state and metadata
+ *
+ * @example
+ * ```ts
+ * // Saving a room snapshot to Supabase
+ * const roomSnapshot = syncRoom.getSnapshot()
+ * const persistedData: PersistedRoomSnapshotForSupabase = {
+ *   id: crypto.randomUUID(),
+ *   slug: 'collaborative-whiteboard-session',
+ *   drawing: roomSnapshot
+ * }
+ *
+ * await supabase
+ *   .from('rooms')
+ *   .insert(persistedData)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Loading a room snapshot from Supabase
+ * const { data } = await supabase
+ *   .from('rooms')
+ *   .select('*')
+ *   .eq('slug', roomSlug)
+ *   .single()
+ *
+ * const roomData = data as PersistedRoomSnapshotForSupabase
+ * const room = new TLSyncRoom({
+ *   schema: mySchema,
+ *   snapshot: roomData.drawing
+ * })
+ * ```
+ *
+ * @internal
+ */
 export interface PersistedRoomSnapshotForSupabase {
 	id: string
 	slug: string