@dabble/patches 0.2.10 → 0.2.12

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,58 @@
+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 connectionDeferred;
+    private onlineUnsubscriber;
+    /** Flag representing the *intent* to be connected. It is set by `connect()` and cleared by `disconnect()`. */
+    private shouldBeConnected;
+    /**
+     * 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;
+    /**
+     * Internal helper that adds (once) listeners for the browser's online/offline
+     * events so we can automatically attempt to connect when the network comes
+     * back and forcibly close when it goes away.
+     */
+    private _ensureOnlineOfflineListeners;
+    /** Removes previously registered online/offline listeners (if any) */
+    private _removeOnlineOfflineListeners;
+}

package/dist/net/websocket/WebSocketTransport.js

@@ -0,0 +1,190 @@
+import { deferred } from '../../utils.js';
+import { AbstractTransport } from '../AbstractTransport.js';
+import { onlineState } from './onlineState.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.connectionDeferred = null;
+        this.onlineUnsubscriber = null;
+        /** Flag representing the *intent* to be connected. It is set by `connect()` and cleared by `disconnect()`. */
+        this.shouldBeConnected = false;
+    }
+    /**
+     * 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() {
+        // Record the caller's intent.
+        this.shouldBeConnected = true;
+        // Make sure we react to browser connectivity changes
+        this._ensureOnlineOfflineListeners();
+        // If the browser is known to be offline, defer the actual connection until
+        // it comes back online.  We still return a promise that resolves once the
+        // connection is eventually established, so callers can `await` safely.
+        if (onlineState.isOffline) {
+            if (!this.connectionDeferred) {
+                this.connectionDeferred = deferred();
+            }
+            return this.connectionDeferred.promise;
+        }
+        // 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.connectionDeferred) {
+            return this.connectionDeferred.promise;
+        }
+        this.connecting = true;
+        this.state = 'connecting';
+        // Create a new connection promise
+        this.connectionDeferred = deferred();
+        const { resolve, reject } = this.connectionDeferred;
+        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.connectionDeferred.promise;
+    }
+    /**
+     * Terminates the WebSocket connection and cancels any pending reconnection attempts.
+     */
+    disconnect() {
+        // Clearing the intent stops automatic reconnection attempts.
+        this.shouldBeConnected = false;
+        // Remove listener now that we no longer intend to stay connected.
+        this._removeOnlineOfflineListeners();
+        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() {
+        // Only schedule a reconnect if the caller still wants to be connected.
+        if (!this.shouldBeConnected || onlineState.isOffline) {
+            return;
+        }
+        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);
+    }
+    /**
+     * Internal helper that adds (once) listeners for the browser's online/offline
+     * events so we can automatically attempt to connect when the network comes
+     * back and forcibly close when it goes away.
+     */
+    _ensureOnlineOfflineListeners() {
+        if (!this.onlineUnsubscriber) {
+            this.onlineUnsubscriber = onlineState.onOnlineChange(isOnline => {
+                if (isOnline && this.shouldBeConnected && !this.connecting && this.state !== 'connected') {
+                    const { resolve, reject } = this.connectionDeferred;
+                    this.connectionDeferred = null;
+                    this.connect().then(resolve, reject);
+                }
+                else if (!isOnline && this.ws) {
+                    this.ws.close();
+                }
+            });
+        }
+    }
+    /** Removes previously registered online/offline listeners (if any) */
+    _removeOnlineOfflineListeners() {
+        if (this.onlineUnsubscriber) {
+            this.onlineUnsubscriber();
+            this.onlineUnsubscriber = null;
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+declare class OnlineState {
+    onOnlineChange: import("../../event-signal").Signal<(isOnline: boolean) => void>;
+    _isOnline: boolean;
+    constructor();
+    get isOnline(): boolean;
+    get isOffline(): boolean;
+}
+export declare const onlineState: OnlineState;
+export {};

package/dist/net/websocket/onlineState.js

@@ -0,0 +1,18 @@
+import { signal } from '../../event-signal';
+class OnlineState {
+    constructor() {
+        this.onOnlineChange = signal();
+        this._isOnline = typeof navigator !== 'undefined' && navigator.onLine;
+        if (typeof addEventListener === 'function') {
+            addEventListener('online', () => (this._isOnline = true) && this.onOnlineChange.emit(true));
+            addEventListener('offline', () => (this._isOnline = false) || this.onOnlineChange.emit(false));
+        }
+    }
+    get isOnline() {
+        return this._isOnline;
+    }
+    get isOffline() {
+        return !this._isOnline;
+    }
+}
+export const onlineState = new OnlineState();

package/dist/persist/InMemoryStore.d.ts

@@ -0,0 +1,23 @@
+import type { Change, PatchesSnapshot } from '../types.js';
+import type { PatchesStore, TrackedDoc } from './PatchesStore.js';
+/**
+ * A trivial in‑memory implementation of OfflineStore (soon PatchesStore).
+ * All data lives in JS objects – nothing survives a page reload.
+ * Useful for unit tests or when you want the old 'stateless realtime' behaviour.
+ */
+export declare class InMemoryStore implements PatchesStore {
+    private docs;
+    /** Signal emitted when pending changes are added (mirrors IndexedDBStore API) */
+    readonly onPendingChanges: import("../event-signal.js").Signal<(docId: string, changes: Change[]) => void>;
+    getDoc(docId: string): Promise<PatchesSnapshot | undefined>;
+    getPendingChanges(docId: string): Promise<Change[]>;
+    getLastRevs(docId: string): Promise<[number, number]>;
+    listDocs(includeDeleted?: boolean): Promise<TrackedDoc[]>;
+    savePendingChanges(docId: string, changes: Change[]): Promise<void>;
+    saveCommittedChanges(docId: string, changes: Change[], sentPendingRange?: [number, number]): Promise<void>;
+    trackDocs(docIds: string[]): Promise<void>;
+    untrackDocs(docIds: string[]): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    confirmDeleteDoc(docId: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/persist/InMemoryStore.js

@@ -0,0 +1,103 @@
+import { signal } from '../event-signal.js';
+import { transformPatch } from '../json-patch/transformPatch.js';
+import { applyChanges } from '../utils.js';
+/**
+ * A trivial in‑memory implementation of OfflineStore (soon PatchesStore).
+ * All data lives in JS objects – nothing survives a page reload.
+ * Useful for unit tests or when you want the old 'stateless realtime' behaviour.
+ */
+export class InMemoryStore {
+    constructor() {
+        this.docs = new Map();
+        /** Signal emitted when pending changes are added (mirrors IndexedDBStore API) */
+        this.onPendingChanges = signal();
+    }
+    // ─── Reconstruction ────────────────────────────────────────────────────
+    async getDoc(docId) {
+        const buf = this.docs.get(docId);
+        if (!buf || buf.deleted)
+            return undefined;
+        const state = applyChanges(buf.snapshot?.state ?? null, buf.committed);
+        const committedRev = buf.committed.at(-1)?.rev ?? buf.snapshot?.rev ?? 0;
+        // Rebase pending if they are stale w.r.t committed
+        if (buf.pending.length && buf.pending[0].baseRev < committedRev) {
+            const patch = buf.committed.filter(c => c.rev > buf.pending[0].baseRev).flatMap(c => c.ops);
+            const offset = committedRev - buf.pending[0].baseRev;
+            buf.pending.forEach(ch => {
+                ch.rev += offset;
+                ch.ops = transformPatch(state, patch, ch.ops);
+            });
+        }
+        return {
+            state,
+            rev: committedRev,
+            changes: [...buf.pending],
+        };
+    }
+    async getPendingChanges(docId) {
+        return this.docs.get(docId)?.pending.slice() ?? [];
+    }
+    async getLastRevs(docId) {
+        const buf = this.docs.get(docId);
+        if (!buf)
+            return [0, 0];
+        const committedRev = buf.committed.at(-1)?.rev ?? buf.snapshot?.rev ?? 0;
+        const pendingRev = buf.pending.at(-1)?.rev ?? committedRev;
+        return [committedRev, pendingRev];
+    }
+    async listDocs(includeDeleted = false) {
+        return Array.from(this.docs.entries())
+            .filter(([, b]) => includeDeleted || !b.deleted)
+            .map(([docId, buf]) => ({
+            docId,
+            committedRev: buf.snapshot?.rev ?? buf.committed.at(-1)?.rev ?? 0,
+            deleted: buf.deleted,
+        }));
+    }
+    // ─── Writes ────────────────────────────────────────────────────────────
+    async savePendingChanges(docId, changes) {
+        const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
+        if (!this.docs.has(docId))
+            this.docs.set(docId, buf);
+        buf.pending.push(...changes);
+        this.onPendingChanges.emit(docId, changes);
+    }
+    async saveCommittedChanges(docId, changes, sentPendingRange) {
+        const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
+        if (!this.docs.has(docId))
+            this.docs.set(docId, buf);
+        buf.committed.push(...changes);
+        if (sentPendingRange) {
+            const [min, max] = sentPendingRange;
+            buf.pending = buf.pending.filter(p => p.rev < min || p.rev > max);
+        }
+    }
+    // ─── Metadata / Tracking ───────────────────────────────────────────
+    async trackDocs(docIds) {
+        for (const docId of docIds) {
+            const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
+            buf.deleted = undefined; // Ensure not marked as deleted
+            if (!this.docs.has(docId)) {
+                this.docs.set(docId, buf);
+            }
+        }
+    }
+    async untrackDocs(docIds) {
+        docIds.forEach(this.docs.delete, this.docs);
+    }
+    // ─── Misc / Lifecycle ────────────────────────────────────────────────
+    async deleteDoc(docId) {
+        const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
+        buf.deleted = true;
+        buf.committed = [];
+        buf.pending = [];
+        buf.snapshot = undefined;
+        this.docs.set(docId, buf);
+    }
+    async confirmDeleteDoc(docId) {
+        this.docs.delete(docId);
+    }
+    async close() {
+        this.docs.clear();
+    }
+}