@dabble/patches 0.1.1 → 0.2.0

package/dist/server/{PatchServer.js → PatchesServer.js}

@@ -7,7 +7,7 @@ import { applyChanges } from '../utils.js';
  * coordinating batches of changes, managing versioning based on sessions (including offline),
  * and persisting data using a backend store.
  */
-export class PatchServer {
+export class PatchesServer {
     constructor(store, options = {}) {
         this.store = store;
         this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1000;

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { BranchManager } from './BranchManager';
-export { HistoryManager } from './HistoryManager';
-export { PatchServer } from './PatchServer';
-export type { Change, PatchSnapshot, PatchState, VersionMetadata } from '../types';
+export { PatchesBranchManager } from './PatchesBranchManager';
+export { PatchesHistoryManager } from './PatchesHistoryManager';
+export { PatchesServer } from './PatchesServer';
+export type { Change, PatchesSnapshot as PatchSnapshot, PatchesState as PatchState, VersionMetadata } from '../types';

package/dist/server/index.js

@@ -1,3 +1,3 @@
-export { BranchManager } from './BranchManager';
-export { HistoryManager } from './HistoryManager';
-export { PatchServer } from './PatchServer';
+export { PatchesBranchManager } from './PatchesBranchManager';
+export { PatchesHistoryManager } from './PatchesHistoryManager';
+export { PatchesServer } from './PatchesServer';

package/dist/types.d.ts

@@ -20,7 +20,7 @@ export interface Change {
  * @property state - The state of the document.
  * @property rev - The revision number of the state.
  */
-export interface PatchState<T = any> {
+export interface PatchesState<T = any> {
     state: T;
     rev: number;
 }
@@ -30,7 +30,7 @@ export interface PatchState<T = any> {
  * @property rev - The revision number of the state.
  * @property changes - Any unapplied changes since `rev` that may be applied to the `state` to get the latest state.
  */
-export interface PatchSnapshot<T = any> extends PatchState<T> {
+export interface PatchesSnapshot<T = any> extends PatchesState<T> {
     changes: Change[];
 }
 /** Status options for a branch */
@@ -111,9 +111,9 @@ export interface ListVersionsOptions {
 }
 /**
  * Interface for a backend storage system for patch synchronization.
- * Defines methods needed by PatchServer, HistoryManager, etc.
+ * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
  */
-export interface PatchStoreBackend {
+export interface PatchesStoreBackend {
     /** Adds a subscription for a client to one or more documents. */
     addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
     /** Removes a subscription for a client from one or more documents. */
@@ -139,9 +139,9 @@ export interface PatchStoreBackend {
     deleteDoc(docId: string): Promise<void>;
 }
 /**
- * Extends PatchStoreBackend with methods specifically for managing branches.
+ * Extends PatchesStoreBackend with methods specifically for managing branches.
  */
-export interface BranchingStoreBackend extends PatchStoreBackend {
+export interface BranchingStoreBackend extends PatchesStoreBackend {
     /** Lists metadata records for branches originating from a document. */
     listBranches(docId: string): Promise<Branch[]>;
     /** Loads the metadata record for a specific branch ID. */
@@ -156,3 +156,8 @@ export interface BranchingStoreBackend extends PatchStoreBackend {
      */
     closeBranch(branchId: string): Promise<void>;
 }
+export interface Deferred<T = void> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+}

package/dist/utils/batching.d.ts

@@ -0,0 +1,5 @@
+import type { Change } from '../types.js';
+/** Estimate JSON string byte size. */
+export declare function getJSONByteSize(data: any): number;
+/** Break changes into batches based on maxBatchSize. */
+export declare function breakIntoBatches(changes: Change[], maxSize?: number): Change[][];

package/dist/utils/batching.js

@@ -0,0 +1,38 @@
+import { createId } from 'crypto-id';
+/** Estimate JSON string byte size. */
+export function getJSONByteSize(data) {
+    // Basic estimation, might not be perfectly accurate due to encoding nuances
+    return new TextEncoder().encode(JSON.stringify(data)).length;
+}
+/** Break changes into batches based on maxBatchSize. */
+export function breakIntoBatches(changes, maxSize) {
+    if (!maxSize || getJSONByteSize(changes) < maxSize) {
+        return [changes];
+    }
+    const batchId = createId(12);
+    const batches = [];
+    let currentBatch = [];
+    let currentSize = 2; // Account for [] wrapper
+    for (const change of changes) {
+        // Add batchId if breaking up
+        const changeWithBatchId = { ...change, batchId };
+        const changeSize = getJSONByteSize(changeWithBatchId) + (currentBatch.length > 0 ? 1 : 0); // Add 1 for comma
+        // If a single change is too big, we have an issue (should be rare)
+        if (changeSize > maxSize && currentBatch.length === 0) {
+            console.error(`Single change ${change.id} (size ${changeSize}) exceeds maxBatchSize (${maxSize}). Sending as its own batch.`);
+            batches.push([changeWithBatchId]); // Send it anyway
+            continue;
+        }
+        if (currentSize + changeSize > maxSize) {
+            batches.push(currentBatch);
+            currentBatch = [];
+            currentSize = 2;
+        }
+        currentBatch.push(changeWithBatchId);
+        currentSize += changeSize;
+    }
+    if (currentBatch.length > 0) {
+        batches.push(currentBatch);
+    }
+    return batches;
+}

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { Change, DeletedChange } from './types.js';
+import type { Change, Deferred } from './types.js';
 /**
  * Splits an array of changes into two arrays based on the presence of a baseRev.
  * The first array contains changes before the first change with a baseRev,
@@ -33,4 +33,4 @@ export declare function applyChanges<T>(state: T, changes: Change[]): T;
  * @returns Array of rebased local changes with updated revision numbers
  */
 export declare function rebaseChanges(serverChanges: Change[], localChanges: Change[]): Change[];
-export declare function isChange(change: Change | DeletedChange): change is Change;
+export declare function deferred<T = void>(): Deferred<T>;

package/dist/utils.js

@@ -78,6 +78,12 @@ export function rebaseChanges(serverChanges, localChanges) {
     })
         .filter(Boolean);
 }
-export function isChange(change) {
-    return 'rev' in change;
+export function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((_resolve, _reject) => {
+        resolve = _resolve;
+        reject = _reject;
+    });
+    return { promise, resolve, reject };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {

package/dist/net/PatchesOfflineFirst.d.ts

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

package/dist/net/PatchesOfflineFirst.js

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

package/dist/net/PatchesRealtime.d.ts

@@ -1,90 +0,0 @@
-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

@@ -1,257 +0,0 @@
-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).
-        }
-    }
-}