@dabble/patches 0.1.1

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

@@ -0,0 +1,142 @@
+import type { Change, PatchSnapshot, PatchState, VersionMetadata } from '../../types';
+/**
+ * Represents the possible states of a network transport connection.
+ * - 'connecting': Connection is being established
+ * - 'connected': Connection is active and ready for communication
+ * - 'disconnected': Connection is not active
+ * - 'error': Connection encountered an error
+ */
+export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';
+/**
+ * Interface defining the core functionality of a transport layer.
+ * Transport implementations provide a communication channel between client and server,
+ * abstracting the underlying protocol details (WebSocket, WebRTC, etc.).
+ */
+export interface Transport {
+    /**
+     * Establishes the connection for this transport.
+     * @returns A promise that resolves when the connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Terminates the connection for this transport.
+     */
+    disconnect(): void;
+    /**
+     * Sends data through this transport.
+     * @param data - The string data to send
+     */
+    send(data: string): void;
+    /**
+     * Registers a handler for incoming messages.
+     * @param handler - Function that will be called when a message is received
+     */
+    onMessage(handler: (data: string) => void): void;
+    /**
+     * Registers a handler for connection state changes.
+     * @param handler - Function that will be called when the connection state changes
+     */
+    onStateChange(handler: (state: ConnectionState) => void): void;
+}
+/**
+ * Represents a JSON-RPC 2.0 request object.
+ */
+export interface Request {
+    /** JSON-RPC protocol version, always "2.0" */
+    jsonrpc: '2.0';
+    /** Request identifier, used to match responses to requests */
+    id?: number;
+    /** Name of the remote procedure to call */
+    method: string;
+    /** Parameters to pass to the remote procedure */
+    params?: any;
+}
+/**
+ * Represents a JSON-RPC 2.0 response object.
+ */
+export interface Response {
+    /** JSON-RPC protocol version, always "2.0" */
+    jsonrpc: '2.0';
+    /** Response identifier, matches the id of the corresponding request */
+    id: number;
+    /** Result of the successful procedure call */
+    result?: any;
+    /** Error information if the procedure call failed */
+    error?: {
+        /** Numeric error code */
+        code: number;
+        /** Short error description */
+        message: string;
+        /** Additional error details (optional) */
+        data?: any;
+    };
+}
+/**
+ * Represents a JSON-RPC 2.0 notification object.
+ * Notifications are one-way messages that don't expect a response.
+ */
+export interface Notification {
+    /** JSON-RPC protocol version, always "2.0" */
+    jsonrpc: '2.0';
+    /** Name of the notification method */
+    method: string;
+    /** Parameters associated with the notification */
+    params?: any;
+}
+/** Union type for all possible JSON-RPC message types */
+export type Message = Request | Response | Notification;
+export interface ListOptions {
+    startAt?: string;
+    startAfter?: string;
+    endAt?: string;
+    endBefore?: string;
+    prefix?: string;
+    limit?: number;
+    reverse?: boolean;
+}
+export interface PatchesAPI {
+    /**
+     * Subscribes the connected client to one or more documents.
+     * @param ids Document ID(s) to subscribe to.
+     * @returns A list of document IDs the client is now successfully subscribed to.
+     */
+    subscribe(ids: string | string[]): Promise<string[]>;
+    /**
+     * Unsubscribes the connected client from one or more documents.
+     * @param ids Document ID(s) to unsubscribe from.
+     */
+    unsubscribe(ids: string | string[]): Promise<void>;
+    /** Get the latest version of a document and changes since the last version. */
+    getDoc(docId: string, atRev?: number): Promise<PatchSnapshot>;
+    /** Get changes that occurred after a specific revision. */
+    getChangesSince(docId: string, rev: number): Promise<Change[]>;
+    /** Apply a set of changes from the client to a document. Returns the committed changes. */
+    commitChanges(docId: string, changes: Change[]): Promise<Change[]>;
+    /** Delete a document. */
+    deleteDoc(docId: string): Promise<void>;
+    /** Create a new named version snapshot of a document's current state. */
+    createVersion(docId: string, name: string): Promise<string>;
+    /** List metadata for saved versions of a document. */
+    listVersions(docId: string, options: ListOptions): Promise<VersionMetadata[]>;
+    /** Get the state snapshot for a specific version ID. */
+    getVersionState(docId: string, versionId: string): Promise<PatchState>;
+    /** Get the original Change objects associated with a specific version ID. */
+    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    /** Update the name of a specific version. */
+    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+}
+export interface PatchesNotificationParams {
+    docId: string;
+    changes: Change[];
+}
+export interface AwarenessUpdateNotificationParams {
+    docId: string;
+    /** The awareness state from a specific client (server should add sender info) */
+    state: any;
+    /** Server should add the client ID of the sender */
+    clientId?: string;
+}
+export interface SignalNotificationParams {
+    fromClientId: string;
+    data: any;
+}

package/dist/net/protocol/types.js

@@ -0,0 +1 @@
+export {};

package/dist/net/webrtc/WebRTCAwareness.d.ts

@@ -0,0 +1,81 @@
+import type { WebRTCTransport } from './WebRTCTransport.js';
+/**
+ * Base type for awareness states, representing arbitrary structured data
+ * that will be shared between peers.
+ */
+type AwarenessState = Record<string, any>;
+/**
+ * Implements the awareness protocol over WebRTC to synchronize peer states.
+ * Awareness allows peers to share real-time information about their current state,
+ * such as cursor position, selection, user info, or any other application-specific data.
+ *
+ * @template T - The type of awareness state to be shared between peers
+ */
+export declare class WebRTCAwareness<T extends AwarenessState = AwarenessState> {
+    private transport;
+    private _states;
+    private _localState;
+    /**
+     * Signal that emits when the awareness state is updated.
+     * Subscribers receive the complete new awareness state array.
+     */
+    readonly onUpdate: import("../../event-signal.js").Signal<(states: T[]) => void>;
+    /**
+     * The peer ID of this client, obtained from the WebRTC transport.
+     */
+    private myId;
+    /**
+     * Creates a new WebRTC awareness instance.
+     * @param transport - The WebRTC transport to use for awareness communication
+     */
+    constructor(transport: WebRTCTransport);
+    /**
+     * Connects to the WebRTC network to start synchronizing awareness states.
+     * @returns A promise that resolves when the connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from the WebRTC network and stops awareness synchronization.
+     */
+    disconnect(): void;
+    /**
+     * Gets the current combined awareness state of all peers.
+     * @returns An array of awareness states from all connected peers
+     */
+    get states(): T[];
+    /**
+     * Sets the combined awareness state and emits an update event.
+     * This method is protected and typically used internally.
+     * @param state - The new combined awareness state array
+     */
+    protected set states(state: T[]);
+    /**
+     * Gets this peer's local awareness state.
+     * @returns The current local awareness state
+     */
+    get localState(): T;
+    /**
+     * Sets this peer's local awareness state and broadcasts it to all connected peers.
+     * @param value - The new local awareness state to set and broadcast
+     */
+    set localState(value: T);
+    /**
+     * Handles a new peer connection by sending the local state to the new peer.
+     * @private
+     * @param peerId - ID of the newly connected peer
+     */
+    private _addPeer;
+    /**
+     * Handles a peer disconnection by removing their state from the awareness state.
+     * @private
+     * @param peerId - ID of the disconnected peer
+     */
+    private _removePeer;
+    /**
+     * Processes incoming awareness data from other peers.
+     * @private
+     * @param data - The serialized awareness state data received from a peer
+     */
+    private _receiveData;
+}
+export {};

package/dist/net/webrtc/WebRTCAwareness.js

@@ -0,0 +1,119 @@
+import { signal } from '../../event-signal.js';
+/**
+ * Implements the awareness protocol over WebRTC to synchronize peer states.
+ * Awareness allows peers to share real-time information about their current state,
+ * such as cursor position, selection, user info, or any other application-specific data.
+ *
+ * @template T - The type of awareness state to be shared between peers
+ */
+export class WebRTCAwareness {
+    /**
+     * Creates a new WebRTC awareness instance.
+     * @param transport - The WebRTC transport to use for awareness communication
+     */
+    constructor(transport) {
+        this.transport = transport;
+        this._states = [];
+        this._localState = {};
+        /**
+         * Signal that emits when the awareness state is updated.
+         * Subscribers receive the complete new awareness state array.
+         */
+        this.onUpdate = signal();
+        this.transport.onPeerConnect(this._addPeer.bind(this));
+        this.transport.onPeerDisconnect(this._removePeer.bind(this));
+        this.transport.onMessage(this._receiveData.bind(this));
+    }
+    /**
+     * Connects to the WebRTC network to start synchronizing awareness states.
+     * @returns A promise that resolves when the connection is established
+     */
+    async connect() {
+        await this.transport.connect();
+        // Get the peer ID from the transport after connection
+        this.myId = this.transport.id;
+    }
+    /**
+     * Disconnects from the WebRTC network and stops awareness synchronization.
+     */
+    disconnect() {
+        this.transport.disconnect();
+    }
+    /**
+     * Gets the current combined awareness state of all peers.
+     * @returns An array of awareness states from all connected peers
+     */
+    get states() {
+        return this._states;
+    }
+    /**
+     * Sets the combined awareness state and emits an update event.
+     * This method is protected and typically used internally.
+     * @param state - The new combined awareness state array
+     */
+    set states(state) {
+        this._states = state;
+        this.onUpdate.emit(this._states);
+    }
+    /**
+     * Gets this peer's local awareness state.
+     * @returns The current local awareness state
+     */
+    get localState() {
+        return this._localState;
+    }
+    /**
+     * Sets this peer's local awareness state and broadcasts it to all connected peers.
+     * @param value - The new local awareness state to set and broadcast
+     */
+    set localState(value) {
+        value.id = this.myId;
+        this._localState = value;
+        this.transport.send(JSON.stringify(value));
+    }
+    /**
+     * Handles a new peer connection by sending the local state to the new peer.
+     * @private
+     * @param peerId - ID of the newly connected peer
+     */
+    _addPeer(peerId) {
+        // If localState has been set (id will exist once set)
+        if (this._localState.id) {
+            this.transport.send(JSON.stringify(this._localState), peerId);
+        }
+    }
+    /**
+     * Handles a peer disconnection by removing their state from the awareness state.
+     * @private
+     * @param peerId - ID of the disconnected peer
+     */
+    _removePeer(peerId) {
+        this.states = this.states.filter(s => s.id !== peerId);
+    }
+    /**
+     * Processes incoming awareness data from other peers.
+     * @private
+     * @param data - The serialized awareness state data received from a peer
+     */
+    _receiveData(data) {
+        let peerState;
+        try {
+            peerState = JSON.parse(data);
+            if (!peerState?.id)
+                return;
+        }
+        catch (err) {
+            console.error('Invalid peer data:', err);
+            return;
+        }
+        const update = [...this.states];
+        const existingIndex = update.findIndex(s => s.id === peerState.id);
+        if (existingIndex !== -1) {
+            update.splice(existingIndex, 1, { ...update[existingIndex], ...peerState });
+        }
+        else {
+            update.push(peerState);
+        }
+        this.states = update;
+    }
+}

package/dist/net/webrtc/WebRTCTransport.d.ts

@@ -0,0 +1,80 @@
+import Peer from 'simple-peer';
+import { AbstractTransport } from '../AbstractTransport.js';
+import type { WebSocketTransport } from '../websocket/WebSocketTransport.js';
+/**
+ * WebRTC-based transport implementation that enables direct peer-to-peer communication.
+ * Uses a WebSocket transport as a signaling channel to establish WebRTC connections.
+ * Once connections are established, data flows directly between peers without going through a server.
+ */
+export declare class WebRTCTransport extends AbstractTransport {
+    private transport;
+    private rpc;
+    private peers;
+    private _id;
+    private subscriptions;
+    /**
+     * Signal that emits when a message is received from a peer.
+     * Provides the message data, peer ID, and peer instance.
+     */
+    readonly onMessage: import("../../event-signal.js").Signal<(data: string, peerId: string, peer: Peer.Instance) => void>;
+    /**
+     * Signal that emits when a new peer connection is established.
+     * Provides the peer ID and peer instance.
+     */
+    readonly onPeerConnect: import("../../event-signal.js").Signal<(peerId: string, peer: Peer.Instance) => void>;
+    /**
+     * Signal that emits when a peer disconnects.
+     * Provides the peer ID and peer instance.
+     */
+    readonly onPeerDisconnect: import("../../event-signal.js").Signal<(peerId: string, peer: Peer.Instance) => void>;
+    /**
+     * Signal that emits when the underlying signaling transport's state changes.
+     * This is delegated directly from the WebSocketTransport.
+     */
+    readonly onStateChange: import("../../event-signal.js").Signal<(state: import("../index.js").ConnectionState) => void>;
+    /**
+     * Creates a new WebRTC transport instance.
+     * @param transport - The WebSocket transport to use for signaling
+     */
+    constructor(transport: WebSocketTransport);
+    /**
+     * Gets the unique ID assigned to this peer by the signaling server.
+     * @returns The peer ID, or undefined if not yet connected
+     */
+    get id(): string | undefined;
+    /**
+     * Gets the current connection state of the underlying signaling transport.
+     * @returns The current connection state
+     */
+    get state(): import("../index.js").ConnectionState;
+    /**
+     * Establishes the connection by connecting to the signaling server.
+     * Peer connections will be established automatically after this.
+     * @returns A promise that resolves when connected to the signaling server
+     */
+    connect(): Promise<void>;
+    /**
+     * Terminates the connection for this transport.
+     * Must be implemented by concrete subclasses.
+     */
+    disconnect(): void;
+    /**
+     * Sends data to one or all connected peers.
+     * @param data - The string data to send
+     * @param peerId - Optional ID of specific peer to send to; if omitted, sends to all peers
+     */
+    send(data: string, peerId?: string): void;
+    /**
+     * Establishes a WebRTC connection to a peer.
+     * @private
+     * @param peerId - ID of the peer to connect to
+     * @param initiator - Whether this peer is initiating the connection
+     */
+    private _connectToPeer;
+    /**
+     * Removes a peer from the connection pool and cleans up resources.
+     * @private
+     * @param peerId - ID of the peer to remove
+     */
+    private _removePeer;
+}

package/dist/net/webrtc/WebRTCTransport.js

@@ -0,0 +1,157 @@
+import Peer from 'simple-peer';
+import { signal } from '../../event-signal.js';
+import { JSONRPCClient } from '../../net/protocol/JSONRPCClient.js';
+import { AbstractTransport } from '../AbstractTransport.js';
+/**
+ * WebRTC-based transport implementation that enables direct peer-to-peer communication.
+ * Uses a WebSocket transport as a signaling channel to establish WebRTC connections.
+ * Once connections are established, data flows directly between peers without going through a server.
+ */
+export class WebRTCTransport extends AbstractTransport {
+    /**
+     * Creates a new WebRTC transport instance.
+     * @param transport - The WebSocket transport to use for signaling
+     */
+    constructor(transport) {
+        super();
+        this.transport = transport;
+        this.peers = new Map();
+        /**
+         * Signal that emits when a message is received from a peer.
+         * Provides the message data, peer ID, and peer instance.
+         */
+        this.onMessage = signal();
+        /**
+         * Signal that emits when a new peer connection is established.
+         * Provides the peer ID and peer instance.
+         */
+        this.onPeerConnect = signal();
+        /**
+         * Signal that emits when a peer disconnects.
+         * Provides the peer ID and peer instance.
+         */
+        this.onPeerDisconnect = signal();
+        /**
+         * Signal that emits when the underlying signaling transport's state changes.
+         * This is delegated directly from the WebSocketTransport.
+         */
+        this.onStateChange = this.transport.onStateChange;
+        this.rpc = new JSONRPCClient(transport);
+        this.subscriptions = [
+            this.rpc.on('peer-welcome', ({ id, peers }) => {
+                this._id = id;
+                peers.forEach((peerId) => this._connectToPeer(peerId, true));
+            }),
+            this.rpc.on('peer-disconnected', ({ id }) => {
+                this._removePeer(id);
+            }),
+            this.rpc.on('peer-signal', ({ from, data }) => {
+                if (!this.peers.has(from)) {
+                    this._connectToPeer(from, false);
+                }
+                this.peers.get(from)?.peer.signal(data);
+            }),
+        ];
+    }
+    /**
+     * Gets the unique ID assigned to this peer by the signaling server.
+     * @returns The peer ID, or undefined if not yet connected
+     */
+    get id() {
+        return this._id;
+    }
+    /**
+     * Gets the current connection state of the underlying signaling transport.
+     * @returns The current connection state
+     */
+    get state() {
+        return this.transport.state;
+    }
+    /**
+     * Establishes the connection by connecting to the signaling server.
+     * Peer connections will be established automatically after this.
+     * @returns A promise that resolves when connected to the signaling server
+     */
+    async connect() {
+        await this.transport.connect();
+    }
+    /**
+     * Terminates the connection for this transport.
+     * Must be implemented by concrete subclasses.
+     */
+    disconnect() {
+        this.subscriptions.forEach(u => u());
+        this.subscriptions.length = 0;
+        // Call _removePeer for each peer, which handles destroy()
+        const peerIds = Array.from(this.peers.keys());
+        peerIds.forEach(peerId => this._removePeer(peerId));
+        // Ensure the map is clear after removal
+        this.peers.clear();
+        // Disconnect the underlying transport if needed (optional, depends on desired behavior)
+        // this.transport.disconnect();
+    }
+    /**
+     * Sends data to one or all connected peers.
+     * @param data - The string data to send
+     * @param peerId - Optional ID of specific peer to send to; if omitted, sends to all peers
+     */
+    send(data, peerId) {
+        for (const info of this.peers.values()) {
+            if (peerId && info.id !== peerId)
+                continue;
+            if (info.connected) {
+                try {
+                    info.peer.send(data);
+                }
+                catch (e) {
+                    console.warn('Failed to send to peer:', e);
+                }
+            }
+        }
+    }
+    /**
+     * Establishes a WebRTC connection to a peer.
+     * @private
+     * @param peerId - ID of the peer to connect to
+     * @param initiator - Whether this peer is initiating the connection
+     */
+    _connectToPeer(peerId, initiator) {
+        const peer = new Peer({ initiator, trickle: false });
+        peer.on('signal', data => {
+            this.rpc.request('peer-signal', { to: peerId, data });
+        });
+        peer.on('connect', () => {
+            this.peers.set(peerId, { id: peerId, peer, connected: true });
+            this.onPeerConnect.emit(peerId, peer);
+        });
+        peer.on('data', raw => {
+            try {
+                this.onMessage.emit(raw, peerId, peer);
+            }
+            catch (e) {
+                console.error('Invalid peer data:', e);
+            }
+        });
+        peer.on('close', () => {
+            this._removePeer(peerId);
+        });
+        peer.on('error', err => {
+            console.error('Peer error:', err);
+            this._removePeer(peerId);
+        });
+        this.peers.set(peerId, { id: peerId, peer, connected: false });
+    }
+    /**
+     * Removes a peer from the connection pool and cleans up resources.
+     * @private
+     * @param peerId - ID of the peer to remove
+     */
+    _removePeer(peerId) {
+        const info = this.peers.get(peerId);
+        if (info) {
+            this.peers.delete(peerId);
+            this.onPeerDisconnect.emit(peerId, info.peer);
+            info.peer.destroy();
+        }
+    }
+}

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

@@ -0,0 +1,107 @@
+import { type Signal } from '../../event-signal.js';
+import type { Change, PatchSnapshot, VersionMetadata } from '../../types.js';
+import type { ConnectionState, ListOptions, PatchesAPI, PatchesNotificationParams } from '../protocol/types.js';
+import { type WebSocketOptions } 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 declare class PatchesWebSocket implements PatchesAPI {
+    private rpc;
+    private transport;
+    /** Signal emitted when the underlying WebSocket connection state changes. */
+    readonly onStateChange: Signal<(state: ConnectionState) => void>;
+    /** Signal emitted when the server pushes document changes. */
+    readonly onChangesCommitted: Signal<(params: PatchesNotificationParams) => void>;
+    /**
+     * 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: string, wsOptions?: WebSocketOptions);
+    /**
+     * Establishes a connection to the Patches server.
+     * @returns A promise that resolves when the connection is established
+     */
+    connect(): Promise<void>;
+    /**
+     * Terminates the connection to the Patches server.
+     */
+    disconnect(): void;
+    /**
+     * 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.
+     */
+    subscribe(ids: string | string[]): Promise<string[]>;
+    /**
+     * 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.
+     */
+    unsubscribe(ids: string | string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    getDoc(docId: string): Promise<PatchSnapshot>;
+    /**
+     * 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.
+     */
+    getChangesSince(docId: string, rev: number): Promise<Change[]>;
+    /**
+     * 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).
+     */
+    commitChanges(docId: string, changes: Change[]): Promise<Change[]>;
+    /**
+     * Deletes a document on the server.
+     * @param docId - The ID of the document to delete.
+     * @returns A promise resolving when the deletion is confirmed.
+     */
+    deleteDoc(docId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    createVersion(docId: string, name: string): Promise<string>;
+    /**
+     * 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.
+     */
+    listVersions(docId: string, options?: ListOptions): Promise<VersionMetadata[]>;
+    /**
+     * 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.
+     */
+    getVersionState(docId: string, versionId: string): Promise<PatchSnapshot>;
+    /**
+     * 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.
+     */
+    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    /**
+     * 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.
+     */
+    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+}