@dabble/patches 0.1.1

package/dist/net/websocket/PatchesWebSocket.js

@@ -0,0 +1,144 @@
+import { signal } from '../../event-signal.js';
+import { JSONRPCClient } from '../protocol/JSONRPCClient.js';
+import { WebSocketTransport } from './WebSocketTransport.js';
+/**
+ * High-level client for the Patches real-time collaboration service.
+ * This class provides document subscription, patch notification handling,
+ * versioning, and other OT-specific functionality
+ * over a WebSocket connection.
+ */
+export class PatchesWebSocket {
+    /**
+     * Creates a new Patches WebSocket client instance.
+     * @param url - The WebSocket server URL to connect to
+     * @param wsOptions - Optional configuration for the underlying WebSocket connection
+     */
+    constructor(url, wsOptions) {
+        /** Signal emitted when the server pushes document changes. */
+        this.onChangesCommitted = signal();
+        this.transport = new WebSocketTransport(url, wsOptions);
+        this.rpc = new JSONRPCClient(this.transport);
+        this.onStateChange = this.transport.onStateChange;
+        // Register handlers for server-sent notifications
+        // Note: Type assertions might be needed if rpc.on doesn't infer strongly enough
+        this.rpc.on('changesCommitted', (params /*: PatchesNotificationParams */) => {
+            this.onChangesCommitted.emit(params);
+        });
+    }
+    // --- Connection Management ---
+    /**
+     * Establishes a connection to the Patches server.
+     * @returns A promise that resolves when the connection is established
+     */
+    async connect() {
+        await this.transport.connect();
+    }
+    /**
+     * Terminates the connection to the Patches server.
+     */
+    disconnect() {
+        // Unsubscribe rpc listeners? JSONRPCClient should handle this if transport disconnects.
+        this.transport.disconnect();
+        // Consider clearing signal listeners here if needed, though they are instance-based.
+    }
+    // --- Patches API Methods ---
+    // === Subscription Operations ===
+    /**
+     * Subscribes the client to one or more documents to receive real-time updates.
+     * @param ids - Document ID or IDs to subscribe to.
+     * @returns A promise resolving with the list of successfully subscribed document IDs.
+     */
+    async subscribe(ids) {
+        return this.rpc.request('subscribe', { ids });
+    }
+    /**
+     * Unsubscribes the client from one or more documents.
+     * @param ids - Document ID or IDs to unsubscribe from.
+     * @returns A promise resolving when the unsubscription is confirmed.
+     */
+    async unsubscribe(ids) {
+        return this.rpc.request('unsubscribe', { ids });
+    }
+    // === Document Operations ===
+    /**
+     * Gets the latest state (content and revision) of a document.
+     * @param docId - The ID of the document.
+     * @returns A promise resolving with the document snapshot.
+     */
+    async getDoc(docId) {
+        return this.rpc.request('getDoc', { docId });
+    }
+    /**
+     * Gets changes that occurred for a document after a specific revision number.
+     * @param docId - The ID of the document.
+     * @param rev - The revision number after which to fetch changes.
+     * @returns A promise resolving with an array of changes.
+     */
+    async getChangesSince(docId, rev) {
+        return this.rpc.request('getChangesSince', { docId, rev });
+    }
+    /**
+     * Applies a set of client-generated changes to a document on the server.
+     * @param docId - The ID of the document.
+     * @param changes - An array of changes to apply.
+     * @returns A promise resolving with the changes as committed by the server (potentially transformed).
+     */
+    async commitChanges(docId, changes) {
+        return this.rpc.request('commitChanges', { docId, changes });
+    }
+    /**
+     * Deletes a document on the server.
+     * @param docId - The ID of the document to delete.
+     * @returns A promise resolving when the deletion is confirmed.
+     */
+    async deleteDoc(docId) {
+        return this.rpc.request('deleteDoc', { docId });
+    }
+    // === Version Operations ===
+    /**
+     * Creates a named version snapshot of a document's current state on the server.
+     * @param docId - The ID of the document.
+     * @param name - A descriptive name for the version.
+     * @returns A promise resolving with the unique ID of the newly created version.
+     */
+    async createVersion(docId, name) {
+        return this.rpc.request('createVersion', { docId, name });
+    }
+    /**
+     * Lists metadata for saved versions of a document.
+     * @param docId - The ID of the document.
+     * @param options - Options for filtering or pagination (e.g., limit, offset).
+     * @returns A promise resolving with an array of version metadata objects.
+     */
+    async listVersions(docId, options = {}) {
+        return this.rpc.request('listVersions', { docId, options });
+    }
+    /**
+     * Gets the document state snapshot corresponding to a specific version ID.
+     * @param docId - The ID of the document.
+     * @param versionId - The ID of the version to retrieve.
+     * @returns A promise resolving with the document snapshot for that version.
+     */
+    async getVersionState(docId, versionId) {
+        return this.rpc.request('getVersionState', { docId, versionId });
+    }
+    /**
+     * Gets the original changes associated with a specific version ID.
+     * @param docId - The ID of the document.
+     * @param versionId - The ID of the version.
+     * @returns A promise resolving with an array of changes that constitute that version.
+     */
+    async getVersionChanges(docId, versionId) {
+        return this.rpc.request('getVersionChanges', { docId, versionId });
+    }
+    /**
+     * Updates the name of a specific version.
+     * @param docId - The ID of the document.
+     * @param versionId - The ID of the version to update.
+     * @param name - The new name for the version.
+     * @returns A promise resolving when the update is confirmed.
+     */
+    async updateVersion(docId, versionId, name) {
+        return this.rpc.request('updateVersion', { docId, versionId, name });
+    }
+}

package/dist/net/websocket/SignalingService.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Represents a JSON-RPC 2.0 request object.
+ */
+export interface JsonRpcRequest {
+    /** JSON-RPC protocol version, always "2.0" */
+    jsonrpc: '2.0';
+    /** Name of the remote procedure to call */
+    method: string;
+    /** Parameters to pass to the remote procedure */
+    params?: any;
+    /** Request identifier, used to match responses to requests */
+    id?: number | string;
+}
+/**
+ * Represents a JSON-RPC 2.0 response object.
+ */
+export interface JsonRpcResponse {
+    /** JSON-RPC protocol version, always "2.0" */
+    jsonrpc: '2.0';
+    /** Result of the successful procedure call */
+    result?: any;
+    /** Error information if the procedure call failed */
+    error?: {
+        code: number;
+        message: string;
+    };
+    /** Response identifier, matches the id of the corresponding request */
+    id: number | string;
+}
+/** Union type for all possible JSON-RPC message types */
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse;
+/** Function type for sending JSON-RPC messages */
+export type SendFn = (message: JsonRpcMessage) => void;
+/**
+ * Service that facilitates WebRTC connection establishment by relaying signaling messages.
+ * Acts as a central hub for WebRTC peers to exchange connection information.
+ */
+export declare class SignalingService {
+    private clients;
+    /**
+     * Registers a new client connection with the signaling service.
+     * Assigns a unique ID to the client and informs them of other connected peers.
+     *
+     * @param send - Function to send messages to this client
+     * @param id - Optional client ID (generated if not provided)
+     * @returns The client's assigned ID
+     */
+    onClientConnected(send: SendFn, id?: string): string;
+    /**
+     * Handles a client disconnection by removing them from the registry
+     * and notifying all other connected clients.
+     *
+     * @param id - ID of the disconnected client
+     */
+    onClientDisconnected(id: string): void;
+    /**
+     * Handles a signaling message from a client, relaying WebRTC session data
+     * between peers to facilitate connection establishment.
+     *
+     * @param fromId - ID of the client sending the message
+     * @param message - The JSON-RPC message or its string representation
+     * @returns True if the message was a valid signaling message and was handled, false otherwise
+     */
+    handleClientMessage(fromId: string, message: string | JsonRpcRequest): boolean;
+    /**
+     * Sends a successful JSON-RPC response to a client.
+     *
+     * @private
+     * @param toId - ID of the client to send the response to
+     * @param id - Request ID to match in the response
+     * @param result - Result data to include in the response
+     */
+    private respond;
+    /**
+     * Sends an error JSON-RPC response to a client.
+     *
+     * @private
+     * @param toId - ID of the client to send the error response to
+     * @param id - Request ID to match in the response, or undefined for notifications
+     * @param message - Error message to include
+     */
+    private respondError;
+    /**
+     * Broadcasts a message to all connected clients, optionally excluding one.
+     *
+     * @private
+     * @param message - The message to broadcast
+     * @param excludeId - Optional ID of a client to exclude from the broadcast
+     */
+    private broadcast;
+}

package/dist/net/websocket/SignalingService.js

@@ -0,0 +1,140 @@
+import { createId } from 'crypto-id';
+/**
+ * Service that facilitates WebRTC connection establishment by relaying signaling messages.
+ * Acts as a central hub for WebRTC peers to exchange connection information.
+ */
+export class SignalingService {
+    constructor() {
+        this.clients = new Map();
+    }
+    /**
+     * Registers a new client connection with the signaling service.
+     * Assigns a unique ID to the client and informs them of other connected peers.
+     *
+     * @param send - Function to send messages to this client
+     * @param id - Optional client ID (generated if not provided)
+     * @returns The client's assigned ID
+     */
+    onClientConnected(send, id = createId(14)) {
+        this.clients.set(id, { send });
+        const welcome = {
+            jsonrpc: '2.0',
+            method: 'peer-welcome',
+            params: {
+                id,
+                peers: Array.from(this.clients.keys()).filter(pid => pid !== id),
+            },
+        };
+        send(welcome);
+        return id;
+    }
+    /**
+     * Handles a client disconnection by removing them from the registry
+     * and notifying all other connected clients.
+     *
+     * @param id - ID of the disconnected client
+     */
+    onClientDisconnected(id) {
+        this.clients.delete(id);
+        // Broadcast to all others
+        this.broadcast({
+            jsonrpc: '2.0',
+            method: 'peer-disconnected',
+            params: { id },
+        });
+    }
+    /**
+     * Handles a signaling message from a client, relaying WebRTC session data
+     * between peers to facilitate connection establishment.
+     *
+     * @param fromId - ID of the client sending the message
+     * @param message - The JSON-RPC message or its string representation
+     * @returns True if the message was a valid signaling message and was handled, false otherwise
+     */
+    handleClientMessage(fromId, message) {
+        let parsed;
+        try {
+            parsed = typeof message === 'string' ? JSON.parse(message) : message;
+        }
+        catch (err) {
+            return false;
+        }
+        if (parsed.jsonrpc !== '2.0' || parsed.method !== 'peer-signal' || !parsed.params?.to)
+            return false;
+        const { params, id } = parsed;
+        const { to, data } = params;
+        const target = this.clients.get(to);
+        if (!target) {
+            this.respondError(fromId, id, 'Target not connected');
+            // Was a signaling message, even if the target is not connected
+            return true;
+        }
+        const outbound = {
+            jsonrpc: '2.0',
+            method: 'signal',
+            params: {
+                from: fromId,
+                data,
+            },
+        };
+        target.send(outbound);
+        if (id !== undefined) {
+            this.respond(fromId, id, 'ok');
+        }
+        return true;
+    }
+    /**
+     * Sends a successful JSON-RPC response to a client.
+     *
+     * @private
+     * @param toId - ID of the client to send the response to
+     * @param id - Request ID to match in the response
+     * @param result - Result data to include in the response
+     */
+    respond(toId, id, result) {
+        const client = this.clients.get(toId);
+        if (!client)
+            return;
+        const response = {
+            jsonrpc: '2.0',
+            result,
+            id,
+        };
+        client.send(response);
+    }
+    /**
+     * Sends an error JSON-RPC response to a client.
+     *
+     * @private
+     * @param toId - ID of the client to send the error response to
+     * @param id - Request ID to match in the response, or undefined for notifications
+     * @param message - Error message to include
+     */
+    respondError(toId, id, message) {
+        if (id === undefined)
+            return;
+        const client = this.clients.get(toId);
+        if (!client)
+            return;
+        const response = {
+            jsonrpc: '2.0',
+            error: { code: -32000, message },
+            id,
+        };
+        client.send(response);
+    }
+    /**
+     * Broadcasts a message to all connected clients, optionally excluding one.
+     *
+     * @private
+     * @param message - The message to broadcast
+     * @param excludeId - Optional ID of a client to exclude from the broadcast
+     */
+    broadcast(message, excludeId) {
+        for (const [id, client] of this.clients.entries()) {
+            if (id !== excludeId) {
+                client.send(message);
+            }
+        }
+    }
+}

package/dist/net/websocket/WebSocketTransport.d.ts

@@ -0,0 +1,47 @@
+import { AbstractTransport } from '../AbstractTransport.js';
+/** WebSocket constructor options (subset) */
+export interface WebSocketOptions {
+    protocol?: string | string[];
+}
+/**
+ * WebSocket-based transport implementation that provides communication over the WebSocket protocol.
+ * Includes automatic reconnection with exponential backoff.
+ */
+export declare class WebSocketTransport extends AbstractTransport {
+    private url;
+    private wsOptions?;
+    private ws;
+    private reconnectTimer;
+    private backoff;
+    private connecting;
+    private connectionPromise;
+    /**
+     * Creates a new WebSocket transport instance.
+     * @param url - The WebSocket server URL to connect to
+     * @param wsOptions - Optional configuration for the WebSocket connection
+     */
+    constructor(url: string, wsOptions?: WebSocketOptions | undefined);
+    /**
+     * Establishes a connection to the WebSocket server.
+     * If a connection is already open or in progress, this method returns immediately.
+     * On connection failure, an automatic reconnection attempt will be scheduled.
+     * @returns A promise that resolves when the connection is established or rejects on error
+     */
+    connect(): Promise<void>;
+    /**
+     * Terminates the WebSocket connection and cancels any pending reconnection attempts.
+     */
+    disconnect(): void;
+    /**
+     * Sends data through the WebSocket connection.
+     * @param data - The string data to send
+     * @throws {Error} If the WebSocket is not connected
+     */
+    send(data: string): void;
+    /**
+     * Schedules a reconnection attempt using exponential backoff.
+     * The backoff time increases with each failed attempt, up to a maximum of 30 seconds.
+     * @private
+     */
+    private scheduleReconnect;
+}

package/dist/net/websocket/WebSocketTransport.js

@@ -0,0 +1,138 @@
+import { AbstractTransport } from '../AbstractTransport.js';
+/**
+ * WebSocket-based transport implementation that provides communication over the WebSocket protocol.
+ * Includes automatic reconnection with exponential backoff.
+ */
+export class WebSocketTransport extends AbstractTransport {
+    /**
+     * Creates a new WebSocket transport instance.
+     * @param url - The WebSocket server URL to connect to
+     * @param wsOptions - Optional configuration for the WebSocket connection
+     */
+    constructor(url, wsOptions) {
+        super();
+        this.url = url;
+        this.wsOptions = wsOptions;
+        this.ws = null;
+        this.reconnectTimer = null;
+        this.backoff = 1000;
+        this.connecting = false;
+        this.connectionPromise = null;
+    }
+    /**
+     * Establishes a connection to the WebSocket server.
+     * If a connection is already open or in progress, this method returns immediately.
+     * On connection failure, an automatic reconnection attempt will be scheduled.
+     * @returns A promise that resolves when the connection is established or rejects on error
+     */
+    async connect() {
+        // Return existing connection if already connected
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            return Promise.resolve();
+        }
+        // Return pending connection promise if already connecting
+        if (this.connecting && this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        this.connecting = true;
+        this.state = 'connecting';
+        // Create a new connection promise
+        this.connectionPromise = new Promise((resolve, reject) => {
+            try {
+                // Pass protocol option if available (standard 2nd arg)
+                // Other options like headers are not standard and require specific server/client handling
+                // or a different WebSocket client library.
+                this.ws = new WebSocket(this.url, this.wsOptions?.protocol);
+                this.ws.onopen = () => {
+                    this.backoff = 1000; // Reset backoff on successful connection
+                    this.state = 'connected';
+                    this.connecting = false;
+                    resolve();
+                };
+                this.ws.onclose = () => {
+                    this.state = 'disconnected';
+                    // If we were in the process of connecting, reject the promise
+                    if (this.connecting) {
+                        reject(new Error('Connection closed'));
+                        this.connecting = false;
+                    }
+                    // Schedule reconnect regardless of whether it was a clean close
+                    // as WebSockets don't always emit error events before closing
+                    this.scheduleReconnect();
+                };
+                this.ws.onerror = error => {
+                    this.state = 'error';
+                    // If we're in the connection phase, reject the promise
+                    if (this.connecting) {
+                        this.connecting = false;
+                        reject(error);
+                    }
+                    else {
+                        // If error happens after established connection,
+                        // schedule a reconnect. The socket will likely close
+                        // right after this, but we schedule it anyway to be sure.
+                        this.scheduleReconnect();
+                    }
+                    // Log the error for debugging
+                    console.error('WebSocket error:', error);
+                };
+                this.ws.onmessage = event => {
+                    this.onMessage.emit(event.data);
+                };
+            }
+            catch (error) {
+                this.state = 'error';
+                this.connecting = false;
+                reject(error);
+                this.scheduleReconnect();
+            }
+        });
+        return this.connectionPromise;
+    }
+    /**
+     * Terminates the WebSocket connection and cancels any pending reconnection attempts.
+     */
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.connecting = false;
+        if (this.ws) {
+            // Only attempt to close if not already closed
+            if (this.ws.readyState !== WebSocket.CLOSED && this.ws.readyState !== WebSocket.CLOSING) {
+                this.ws.close();
+            }
+            this.ws = null;
+        }
+        this.state = 'disconnected';
+    }
+    /**
+     * Sends data through the WebSocket connection.
+     * @param data - The string data to send
+     * @throws {Error} If the WebSocket is not connected
+     */
+    send(data) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('WebSocket is not connected');
+        }
+        this.ws.send(data);
+    }
+    /**
+     * Schedules a reconnection attempt using exponential backoff.
+     * The backoff time increases with each failed attempt, up to a maximum of 30 seconds.
+     * @private
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            return;
+        }
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect().catch(err => {
+                console.error('WebSocket reconnect failed:', err);
+            });
+        }, this.backoff);
+        this.backoff = Math.min(this.backoff * 1.5, 30000);
+    }
+}

package/dist/persist/IndexedDBStore.d.ts

@@ -0,0 +1,72 @@
+import type { Change, PatchSnapshot } from '../types.js';
+/**
+ * Creates a new IndexedDB database with stores:
+ * - snapshots<{ docId: string; rev: number; state: any }> (primary key: docId)
+ * - committedChanges<Change & { docId: string; }> (primary key: [docId, rev])
+ * - pendingChanges<Change & { docId: string; }> (primary key: [docId, rev])
+ * - deleted<{ docId: string; }> (primary key: docId)
+ *
+ * Under the hood, this class will store snapshots of the document only for committed state. It will not update the
+ * committed state on *every* received committed change as this can cause issues with IndexedDB with many large updates.
+ * After every 200 committed changes, the class will save the current state to the snapshot store and delete the committed changes that went into it.
+ * A snapshot will not be created if there are pending changes based on revisions older than the 200th committed change until those pending changes are committed.
+ */
+export declare class IndexedDBStore {
+    private db;
+    private dbName;
+    private dbPromise;
+    /** Subscribe to be notified after local state changes are saved to the database. */
+    readonly onPendingChanges: import("../event-signal.js").Signal<(docId: string, changes: Change[]) => void>;
+    constructor(dbName: string);
+    private initDB;
+    private getDB;
+    /**
+     * Closes the database connection. After calling this method, the store
+     * will no longer be usable. A new instance must be created to reopen
+     * the database.
+     */
+    close(): Promise<void>;
+    private transaction;
+    /**
+     * Rebuilds a document snapshot + pending queue *without* loading
+     * the full PatchDoc into memory.
+     *
+     * 1. load the last snapshot (state + rev)
+     * 2. load committedChanges[rev > snapshot.rev]
+     * 3. load pendingChanges
+     * 4. apply committed changes, rebase pending
+     * 5. return { state, rev, changes: pending }
+     */
+    getDoc(docId: string): Promise<PatchSnapshot | undefined>;
+    /**
+     * Completely remove all data for this docId and mark it
+     * as deleted (tombstone).  Provider will call `patchAPI.deleteDoc`
+     * on reconnect.
+     */
+    deleteDoc(docId: string): Promise<void>;
+    /**
+     * Append an array of local changes to the pending queue.
+     * Called *before* you attempt to send them to the server.
+     */
+    savePendingChanges(docId: string, changes: Change[]): Promise<void>;
+    /** Read back all pending changes for this docId (in order). */
+    getPendingChanges(docId: string): Promise<Change[]>;
+    /**
+     * Store server‐confirmed changes.  Will:
+     * - persist them in the committedChanges store
+     * - remove any pending changes whose rev falls within `sentPendingRange`
+     * - optionally compact a new snapshot after N changes (hidden internally)
+     * @param docId - The ID of the document to save the changes for
+     * @param changes - The changes to save
+     * @param sentPendingRange - The range of pending changes to remove, *must* be provided after receiving the changes
+     * from the server in response to a patchDoc request.
+     */
+    saveCommittedChanges(docId: string, changes: Change[], sentPendingRange?: [number, number]): Promise<void>;
+    /**
+     * Tell me the last committed revision you have *and* the highest
+     * rev of any change.  Use these to drive:
+     *   - fetch changes:   api.getChangesSince(docId, committedRev)
+     *   - build new patch: newChange.rev = pendingRev; baseRev = committedRev
+     */
+    getLastRevs(docId: string): Promise<[number, number]>;
+}