@dabble/patches 0.1.1

package/dist/net/AbstractTransport.js

@@ -0,0 +1,37 @@
+import { signal } from '../event-signal.js';
+/**
+ * Abstract base class that implements common functionality for various transport implementations.
+ * Provides state management and event signaling for connection state changes and message reception.
+ * Concrete transport implementations must extend this class and implement the abstract methods.
+ */
+export class AbstractTransport {
+    constructor() {
+        this._state = 'disconnected';
+        /**
+         * Signal that emits when the connection state changes.
+         * Subscribers will receive the new connection state as an argument.
+         */
+        this.onStateChange = signal();
+        /**
+         * Signal that emits when a message is received from the transport.
+         * Subscribers will receive the message data as a string.
+         */
+        this.onMessage = signal();
+    }
+    /**
+     * Gets the current connection state of the transport.
+     * @returns The current connection state ('connecting', 'connected', 'disconnected', or 'error')
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Sets the connection state and emits a state change event.
+     * This method is protected and should only be called by subclasses.
+     * @param state - The new connection state
+     */
+    set state(state) {
+        this._state = state;
+        this.onStateChange.emit(state);
+    }
+}

package/dist/net/PatchesOfflineFirst.d.ts

@@ -0,0 +1,3 @@
+import { PatchesRealtime } from '../client/PatchesRealtime';
+export declare class PatchesOfflineFirst extends PatchesRealtime {
+}

package/dist/net/PatchesOfflineFirst.js

@@ -0,0 +1,3 @@
+import { PatchesRealtime } from '../client/PatchesRealtime';
+export class PatchesOfflineFirst extends PatchesRealtime {
+}

package/dist/net/PatchesRealtime.d.ts

@@ -0,0 +1,90 @@
+import { PatchDoc } from '../client/PatchDoc.js';
+import { type Signal } from '../event-signal.js';
+import type { ConnectionState } from './protocol/types.js';
+import type { WebSocketOptions } from './websocket/WebSocketTransport.js';
+export interface PatchesRealtimeOptions {
+    /** Initial metadata to attach to changes from this client */
+    metadata?: Record<string, any>;
+    /** Custom WebSocket configuration (e.g. headers, protocols) */
+    wsOptions?: WebSocketOptions;
+}
+/**
+ * High-level client for real-time collaborative editing.
+ * Manages WebSocket connection and document synchronization.
+ */
+export declare class PatchesRealtime {
+    private ws;
+    private docs;
+    private options;
+    private wsChangesUnsubscriber;
+    private connectionState;
+    /** Emitted when the WebSocket connection state changes. */
+    readonly onStateChange: Signal<(state: ConnectionState) => void>;
+    /** Emitted when an error occurs during synchronization or connection. */
+    readonly onError: Signal<(details: {
+        type: "sendFailed" | "applyFailed" | "syncError" | "connectionError";
+        docId?: string;
+        error: Error;
+        recoveryAttempted?: boolean;
+        recoveryError?: Error;
+    }) => void>;
+    /**
+     * Creates an instance of PatchesRealtime.
+     * @param url The WebSocket URL of the Patches server.
+     * @param opts Configuration options.
+     */
+    constructor(url: string, opts?: PatchesRealtimeOptions);
+    /**
+     * Establishes the WebSocket connection to the server.
+     * Automatically called by `openDoc` if not already connected.
+     */
+    connect(): Promise<void>;
+    /**
+     * Opens a document by its ID, fetches its initial state, and sets up
+     * real-time synchronization. If the document is already open, returns
+     * the existing instance.
+     * @param docId The unique identifier for the document.
+     * @param opts Options, including optional metadata specific to this client's interaction with the document.
+     * @returns A Promise resolving to the synchronized PatchDoc instance.
+     * @throws If the connection fails, subscription fails, or fetching the initial document state fails.
+     */
+    openDoc<T extends object>(docId: string, opts?: {
+        metadata?: Record<string, any>;
+    }): Promise<PatchDoc<T>>;
+    /**
+     * Closes a specific document locally, stops listening for its changes,
+     * and unsubscribes from server updates for that document.
+     * @param docId The ID of the document to close.
+     */
+    closeDoc(docId: string): Promise<void>;
+    /**
+     * Closes all open documents, unsubscribes from all server updates,
+     * cleans up all local listeners, and disconnects the WebSocket.
+     */
+    close(): void;
+    /**
+     * Sets up the synchronization logic for a single document. Listens for local
+     * changes on the `PatchDoc` and triggers sending them to the server.
+     * @param docId The document ID.
+     * @param doc The `PatchDoc` instance.
+     * @returns An unsubscriber function to remove the listener.
+     * @internal
+     */
+    private _setupDocSync;
+    /**
+     * Checks if a document has pending local changes that haven't been sent
+     * to the server and attempts to send them if the document is not already
+     * in the process of sending. Handles server confirmation and potential
+     * new changes that occurred during the send operation.
+     * @param docId The document ID.
+     * @param doc The `PatchDoc` instance.
+     * @internal
+     */
+    private _sendPendingIfNecessary;
+    /**
+     * Attempts to resynchronize a document by fetching its latest state from the server.
+     * @param docId The ID of the document to resynchronize.
+     * @internal
+     */
+    private _resyncDoc;
+}

package/dist/net/PatchesRealtime.js

@@ -0,0 +1,257 @@
+import { PatchDoc } from '../client/PatchDoc.js';
+import { signal } from '../event-signal.js';
+import { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
+/**
+ * High-level client for real-time collaborative editing.
+ * Manages WebSocket connection and document synchronization.
+ */
+export class PatchesRealtime {
+    /**
+     * Creates an instance of PatchesRealtime.
+     * @param url The WebSocket URL of the Patches server.
+     * @param opts Configuration options.
+     */
+    constructor(url, opts = {}) {
+        this.docs = new Map();
+        this.wsChangesUnsubscriber = null;
+        this.connectionState = 'disconnected'; // Track internal state
+        /** Emitted when an error occurs during synchronization or connection. */
+        this.onError = signal();
+        this.ws = new PatchesWebSocket(url, opts.wsOptions);
+        this.options = opts;
+        // Re-emit the state change signal and track internally
+        this.onStateChange = signal(); // Explicit type
+        this.ws.onStateChange((state) => {
+            // Call signal directly to subscribe
+            this.connectionState = state;
+            this.onStateChange.emit(state); // Pass through the signal
+        });
+        // Register a single listener for all incoming changes from the WebSocket.
+        this.wsChangesUnsubscriber = this.ws.onChangesCommitted(({ docId, changes }) => {
+            const managedDoc = this.docs.get(docId);
+            if (managedDoc) {
+                try {
+                    // Apply changes received from the server to the local document copy.
+                    managedDoc.doc.applyExternalServerUpdate(changes);
+                    // After applying, immediately check if there are new local changes to send.
+                    this._sendPendingIfNecessary(docId, managedDoc.doc);
+                }
+                catch (error) {
+                    console.error(`Error applying external server update for doc ${docId}:`, error);
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    // Emit error and attempt recovery by resyncing
+                    this.onError.emit({ type: 'applyFailed', docId, error: err, recoveryAttempted: true });
+                    // Use void to explicitly ignore the promise returned by _resyncDoc
+                    void this._resyncDoc(docId);
+                }
+            }
+            // If the document isn't open locally (e.g., already closed), ignore the incoming change.
+        });
+    }
+    /**
+     * Establishes the WebSocket connection to the server.
+     * Automatically called by `openDoc` if not already connected.
+     */
+    async connect() {
+        // The underlying PatchesWebSocket handles connection state and idempotency.
+        await this.ws.connect();
+    }
+    /**
+     * Opens a document by its ID, fetches its initial state, and sets up
+     * real-time synchronization. If the document is already open, returns
+     * the existing instance.
+     * @param docId The unique identifier for the document.
+     * @param opts Options, including optional metadata specific to this client's interaction with the document.
+     * @returns A Promise resolving to the synchronized PatchDoc instance.
+     * @throws If the connection fails, subscription fails, or fetching the initial document state fails.
+     */
+    async openDoc(docId, opts = {}) {
+        // Ensure connection is established before proceeding.
+        await this.connect();
+        // Return existing instance if already managed.
+        const existingManagedDoc = this.docs.get(docId);
+        if (existingManagedDoc) {
+            return existingManagedDoc.doc;
+        }
+        // Subscribe to server updates for this document ID *before* fetching state
+        // to avoid missing updates that might occur between getDoc and subscription completion.
+        await this.ws.subscribe(docId);
+        let snapshot;
+        try {
+            // Fetch the initial state (snapshot) of the document from the server.
+            snapshot = await this.ws.getDoc(docId);
+        }
+        catch (err) {
+            // If fetching the document fails, attempt to clean up by unsubscribing.
+            console.error(`Failed to get initial state for doc ${docId}, attempting to unsubscribe:`, err);
+            this.ws.unsubscribe(docId).catch(unsubErr => {
+                // Log secondary error if unsubscribe also fails, but prioritize original error.
+                console.warn(`Failed to unsubscribe ${docId} after getDoc error:`, unsubErr);
+            });
+            // Re-throw the original error to signal failure to the caller.
+            throw err;
+        }
+        // Create the local PatchDoc instance with the fetched state and merged metadata.
+        const doc = new PatchDoc(snapshot.state, { ...this.options.metadata, ...opts.metadata });
+        // Import the snapshot details (like revision number) into the PatchDoc.
+        doc.import(snapshot);
+        // Set up the listener to send local changes to the server.
+        const onChangeUnsubscriber = this._setupDocSync(docId, doc);
+        // Store the document instance and its change listener unsubscriber.
+        this.docs.set(docId, { doc, onChangeUnsubscriber });
+        return doc;
+    }
+    /**
+     * Closes a specific document locally, stops listening for its changes,
+     * and unsubscribes from server updates for that document.
+     * @param docId The ID of the document to close.
+     */
+    async closeDoc(docId) {
+        const managedDoc = this.docs.get(docId);
+        if (managedDoc) {
+            // Stop listening to local changes for this document.
+            managedDoc.onChangeUnsubscriber();
+            // Remove the document from local management.
+            this.docs.delete(docId);
+            // Unsubscribe from server updates for this document.
+            try {
+                await this.ws.unsubscribe(docId);
+            }
+            catch (err) {
+                // Log error but continue, as the primary goal (local cleanup) is done.
+                console.warn(`Error unsubscribing from doc ${docId} during closeDoc:`, err);
+            }
+        }
+        else {
+            // Log if closeDoc is called for a document not currently managed.
+            // This might indicate a logic error elsewhere or harmless redundant calls.
+            console.warn(`closeDoc called for non-existent or already closed doc: ${docId}`);
+            // No need to attempt unsubscribe if we don't think we were subscribed.
+        }
+    }
+    /**
+     * Closes all open documents, unsubscribes from all server updates,
+     * cleans up all local listeners, and disconnects the WebSocket.
+     */
+    close() {
+        // Attempt to unsubscribe from all currently managed documents on the server.
+        const docIds = Array.from(this.docs.keys());
+        if (docIds.length > 0) {
+            this.ws.unsubscribe(docIds).catch(err => {
+                console.warn('Error unsubscribing from documents during close:', err);
+            });
+        }
+        // Clean up local change listeners for all managed documents.
+        this.docs.forEach(managedDoc => managedDoc.onChangeUnsubscriber());
+        this.docs.clear(); // Remove all documents from local management.
+        // Clean up the global listener for incoming changes from the WebSocket.
+        if (this.wsChangesUnsubscriber) {
+            this.wsChangesUnsubscriber();
+            this.wsChangesUnsubscriber = null;
+        }
+        // Disconnect the WebSocket connection.
+        this.ws.disconnect();
+    }
+    /**
+     * Sets up the synchronization logic for a single document. Listens for local
+     * changes on the `PatchDoc` and triggers sending them to the server.
+     * @param docId The document ID.
+     * @param doc The `PatchDoc` instance.
+     * @returns An unsubscriber function to remove the listener.
+     * @internal
+     */
+    _setupDocSync(docId, doc) {
+        // Listen for local changes and attempt to send them.
+        return doc.onChange(async () => {
+            await this._sendPendingIfNecessary(docId, doc);
+        });
+    }
+    /**
+     * Checks if a document has pending local changes that haven't been sent
+     * to the server and attempts to send them if the document is not already
+     * in the process of sending. Handles server confirmation and potential
+     * new changes that occurred during the send operation.
+     * @param docId The document ID.
+     * @param doc The `PatchDoc` instance.
+     * @internal
+     */
+    async _sendPendingIfNecessary(docId, doc) {
+        // Only proceed if there are pending changes and we are not already sending.
+        if (!doc.isSending && doc.hasPending) {
+            let changes;
+            try {
+                // Get the changes formatted for the server.
+                changes = doc.getUpdatesForServer();
+                // Basic sanity check - should not happen if hasPending is true.
+                if (changes.length === 0) {
+                    console.warn(`_sendPendingIfNecessary called for ${docId} with hasPending=true but getUpdatesForServer returned empty.`);
+                    return;
+                }
+                // Send the changes to the server via WebSocket.
+                const serverCommit = await this.ws.commitChanges(docId, changes);
+                // Apply the server's confirmation (e.g., updated revision number) to the local doc.
+                doc.applyServerConfirmation(serverCommit);
+                // IMPORTANT: After successful confirmation, immediately check again.
+                // New local changes might have occurred while the commit request was in flight.
+                // This recursive call ensures those are sent promptly.
+                await this._sendPendingIfNecessary(docId, doc);
+            }
+            catch (error) {
+                console.error(`Error sending changes to server for doc ${docId}:`, error);
+                const err = error instanceof Error ? error : new Error(String(error));
+                // Notify PatchDoc to move sending changes back to pending
+                doc.handleSendFailure();
+                // Emit error and attempt recovery if online
+                this.onError.emit({ type: 'sendFailed', docId, error: err, recoveryAttempted: true });
+                // Use the internally tracked state
+                if (this.connectionState === 'connected' || this.connectionState === 'connecting') {
+                    console.warn(`Attempting recovery via resync for doc ${docId} after send failure.`);
+                    // Use void to explicitly ignore the promise returned by _resyncDoc
+                    void this._resyncDoc(docId);
+                }
+                else {
+                    console.warn(`Send failure for doc ${docId} while offline. Recovery deferred until reconnection.`);
+                    // No immediate recovery action needed, handleSendFailure already reset state.
+                    // The standard reconnection logic should trigger a send attempt later.
+                }
+            }
+        }
+    }
+    /**
+     * Attempts to resynchronize a document by fetching its latest state from the server.
+     * @param docId The ID of the document to resynchronize.
+     * @internal
+     */
+    async _resyncDoc(docId) {
+        const managedDoc = this.docs.get(docId);
+        if (!managedDoc) {
+            console.warn(`_resyncDoc called for non-managed doc: ${docId}`);
+            return;
+        }
+        console.log(`Attempting resync for doc ${docId}...`);
+        try {
+            const snapshot = await this.ws.getDoc(docId);
+            // Import will trigger recalculateLocalState and onUpdate
+            managedDoc.doc.import(snapshot);
+            console.log(`Successfully resynced doc ${docId} to revision ${snapshot.rev}.`);
+            // After successful resync, try sending any pending changes immediately
+            await this._sendPendingIfNecessary(docId, managedDoc.doc);
+        }
+        catch (recoveryError) {
+            console.error(`Failed to resync doc ${docId}:`, recoveryError);
+            const recErr = recoveryError instanceof Error ? recoveryError : new Error(String(recoveryError));
+            // Emit a specific syncError to indicate recovery failure
+            this.onError.emit({
+                type: 'syncError',
+                docId,
+                // TODO: Should we include the original error that triggered the resync attempt?
+                // For now, just include the recovery error itself.
+                error: recErr, // Error during the recovery attempt
+                recoveryAttempted: true,
+                recoveryError: recErr,
+            });
+            // If resync fails, the document might be in an inconsistent state.
+            // Further actions might be needed (e.g., closing the doc, user notification).
+        }
+    }
+}

package/dist/net/index.d.ts

@@ -0,0 +1,9 @@
+export { PatchesOfflineFirst } from './PatchesOfflineFirst';
+export { PatchesRealtime } from './PatchesRealtime';
+export { JSONRPCClient } from './protocol/JSONRPCClient';
+export { PatchesWebSocket } from './websocket/PatchesWebSocket';
+export { WebSocketTransport } from './websocket/WebSocketTransport';
+export type { ConnectionState, ListOptions, PatchesAPI, PatchesNotificationParams, SignalNotificationParams, } from './protocol/types';
+export * from './protocol/types.js';
+export * from './webrtc/WebRTCAwareness.js';
+export * from './webrtc/WebRTCTransport.js';

package/dist/net/index.js

@@ -0,0 +1,8 @@
+export { PatchesOfflineFirst } from './PatchesOfflineFirst';
+export { PatchesRealtime } from './PatchesRealtime';
+export { JSONRPCClient } from './protocol/JSONRPCClient';
+export { PatchesWebSocket } from './websocket/PatchesWebSocket';
+export { WebSocketTransport } from './websocket/WebSocketTransport';
+export * from './protocol/types.js';
+export * from './webrtc/WebRTCAwareness.js';
+export * from './webrtc/WebRTCTransport.js';

package/dist/net/protocol/JSONRPCClient.d.ts

@@ -0,0 +1,55 @@
+import { type SignalSubscriber, type Unsubscriber } from '../../event-signal.js';
+import type { Transport } from './types.js';
+/**
+ * Implementation of a JSON-RPC 2.0 client that communicates over a provided transport layer.
+ * This client handles sending requests, notifications, and processing responses from a server.
+ * It also supports subscription to server-sent notifications.
+ */
+export declare class JSONRPCClient {
+    private transport;
+    private nextId;
+    private pending;
+    private notificationSignals;
+    /**
+     * Creates a new JSON-RPC client instance.
+     *
+     * @param transport - The transport layer implementation that will be used for sending/receiving messages
+     */
+    constructor(transport: Transport);
+    /**
+     * Sends a JSON-RPC request to the server and returns a promise for the response.
+     *
+     * @param method - The name of the remote procedure to call
+     * @param params - The parameters to pass to the remote procedure (optional)
+     * @returns A promise that resolves with the result of the procedure call or rejects with an error
+     * @template T - The expected return type of the remote procedure
+     */
+    request<T = any>(method: string, params?: any): Promise<T>;
+    /**
+     * Sends a JSON-RPC notification to the server (no response expected).
+     *
+     * @param method - The name of the remote procedure to call
+     * @param params - The parameters to pass to the remote procedure (optional)
+     */
+    notify(method: string, params?: any): void;
+    /**
+     * Subscribes to server-sent notifications for a specific method.
+     *
+     * @param method - The notification method name to subscribe to
+     * @param handler - The callback function that will be invoked when notifications are received
+     * @returns A function that can be called to unsubscribe from the notifications
+     * @template T - The type of the handler function
+     */
+    on<T extends SignalSubscriber = SignalSubscriber>(method: string, handler: T): Unsubscriber;
+    /**
+     * Processes incoming messages from the transport layer.
+     * Handles three types of messages:
+     * - Notifications: Emitted to registered subscribers
+     * - Responses: Resolved/rejected to the corresponding pending promise
+     * - Invalid messages: Logged as warnings
+     *
+     * @private
+     * @param data - The raw message data received from the transport
+     */
+    private handleMessage;
+}

package/dist/net/protocol/JSONRPCClient.js

@@ -0,0 +1,106 @@
+import { signal } from '../../event-signal.js';
+/**
+ * Implementation of a JSON-RPC 2.0 client that communicates over a provided transport layer.
+ * This client handles sending requests, notifications, and processing responses from a server.
+ * It also supports subscription to server-sent notifications.
+ */
+export class JSONRPCClient {
+    /**
+     * Creates a new JSON-RPC client instance.
+     *
+     * @param transport - The transport layer implementation that will be used for sending/receiving messages
+     */
+    constructor(transport) {
+        this.transport = transport;
+        this.nextId = 1;
+        this.pending = new Map();
+        this.notificationSignals = new Map();
+        transport.onMessage(this.handleMessage.bind(this));
+    }
+    /**
+     * Sends a JSON-RPC request to the server and returns a promise for the response.
+     *
+     * @param method - The name of the remote procedure to call
+     * @param params - The parameters to pass to the remote procedure (optional)
+     * @returns A promise that resolves with the result of the procedure call or rejects with an error
+     * @template T - The expected return type of the remote procedure
+     */
+    async request(method, params) {
+        const id = this.nextId++;
+        const message = { jsonrpc: '2.0', id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.transport.send(JSON.stringify(message));
+        });
+    }
+    /**
+     * Sends a JSON-RPC notification to the server (no response expected).
+     *
+     * @param method - The name of the remote procedure to call
+     * @param params - The parameters to pass to the remote procedure (optional)
+     */
+    notify(method, params) {
+        const message = { jsonrpc: '2.0', method, params };
+        this.transport.send(JSON.stringify(message));
+    }
+    /**
+     * Subscribes to server-sent notifications for a specific method.
+     *
+     * @param method - The notification method name to subscribe to
+     * @param handler - The callback function that will be invoked when notifications are received
+     * @returns A function that can be called to unsubscribe from the notifications
+     * @template T - The type of the handler function
+     */
+    on(method, handler) {
+        let thisSignal = this.notificationSignals.get(method);
+        if (!thisSignal) {
+            thisSignal = signal();
+            this.notificationSignals.set(method, thisSignal);
+        }
+        return thisSignal(handler);
+    }
+    /**
+     * Processes incoming messages from the transport layer.
+     * Handles three types of messages:
+     * - Notifications: Emitted to registered subscribers
+     * - Responses: Resolved/rejected to the corresponding pending promise
+     * - Invalid messages: Logged as warnings
+     *
+     * @private
+     * @param data - The raw message data received from the transport
+     */
+    handleMessage(data) {
+        try {
+            const message = JSON.parse(data);
+            // Check if it's a notification (has method but no id)
+            if (typeof message === 'object' && message !== null && 'method' in message && !('id' in message)) {
+                const thisSignal = this.notificationSignals.get(message.method);
+                if (thisSignal)
+                    thisSignal.emit(message.params);
+                return;
+            }
+            // Must be a response (has id)
+            if (typeof message === 'object' && message !== null && 'id' in message) {
+                const response = message;
+                const pending = this.pending.get(response.id);
+                if (pending) {
+                    this.pending.delete(response.id);
+                    if ('error' in response) {
+                        pending.reject(response.error);
+                    }
+                    else {
+                        pending.resolve(response.result);
+                    }
+                }
+                else {
+                    console.warn(`Received response for unknown id: ${response.id}`);
+                }
+                return;
+            }
+            console.warn('Received unexpected message format:', message);
+        }
+        catch (error) {
+            console.error('Failed to parse incoming message:', data, error);
+        }
+    }
+}