@hocuspocus/provider 4.3.0 → 4.5.0

package/src/HocuspocusProvider.ts

@@ -1,4 +1,8 @@
-import { awarenessStatesToArray, makeRoutingKey, parseRoutingKey } from "@hocuspocus/common";
+import {
+	awarenessStatesToArray,
+	makeRoutingKey,
+	parseRoutingKey,
+} from "@hocuspocus/common";
 import { Awareness, removeAwarenessStates } from "y-protocols/awareness";
 import * as Y from "yjs";
 import EventEmitter from "./EventEmitter.ts";
@@ -82,7 +86,7 @@ export interface CompleteHocuspocusProviderConfiguration {
 	 * sessionId in the documentName field of every message, allowing multiple
 	 * providers with the same document name on a single WebSocket connection.
 	 *
-	 * Only set this to `true` when connecting to a v4 server that does 
+	 * Only set this to `true` when connecting to a v4 server that does
 	 * support session awareness.
 	 *
 	 * Default: false
@@ -94,6 +98,22 @@ export interface CompleteHocuspocusProviderConfiguration {
 	 */
 	forceSyncInterval: false | number;
 
+	/**
+	 * Batch outgoing document and awareness updates over a short window (in
+	 * milliseconds) instead of sending one message per change. During heavy
+	 * editing this drastically reduces the number of websocket messages: Yjs
+	 * updates collected in the window are merged with `Y.mergeUpdates` into a
+	 * single message, and awareness collapses to the latest state of each
+	 * changed client.
+	 *
+	 * The window is a fixed batch, not a resetting debounce, so the added
+	 * latency is capped at `flushDelay` even while the user keeps typing. Keep
+	 * it small (e.g. 500) to avoid delaying what other clients see.
+	 *
+	 * Set to `false` (the default) to send every change immediately.
+	 */
+	flushDelay: false | number;
+
 	onAuthenticated: (data: onAuthenticatedParameters) => void;
 	onAuthenticationFailed: (data: onAuthenticationFailedParameters) => void;
 	onOpen: (data: onOpenParameters) => void;
@@ -125,6 +145,7 @@ export class HocuspocusProvider extends EventEmitter {
 		token: null,
 		sessionAwareness: false,
 		forceSyncInterval: false,
+		flushDelay: false,
 		onAuthenticated: () => null,
 		onAuthenticationFailed: () => null,
 		onOpen: () => null,
@@ -155,6 +176,18 @@ export class HocuspocusProvider extends EventEmitter {
 
 	private _isAttached = false;
 
+	/**
+	 * Outgoing document updates buffered for the current `flushDelay` window.
+	 */
+	private pendingUpdates: Uint8Array[] = [];
+
+	/**
+	 * Awareness client ids whose latest state should be sent on the next flush.
+	 */
+	private pendingAwarenessClients = new Set<number>();
+
+	private flushTimeout: ReturnType<typeof setTimeout> | null = null;
+
 	/**
 	 * Unique session identifier for this provider instance.
 	 * Used for multiplexing multiple providers with the same document name on a single WebSocket.
@@ -355,23 +388,103 @@ export class HocuspocusProvider extends EventEmitter {
 		});
 	}
 
+	private get batchingEnabled(): boolean {
+		return (
+			!!this.configuration.flushDelay &&
+			typeof this.configuration.flushDelay === "number"
+		);
+	}
+
 	documentUpdateHandler(update: Uint8Array, origin: any) {
 		if (origin === this) {
 			return;
 		}
 
-		this.incrementUnsyncedChanges();
-		this.send(UpdateMessage, { update, documentName: this.effectiveName });
+		if (!this.batchingEnabled) {
+			this.incrementUnsyncedChanges();
+			this.send(UpdateMessage, { update, documentName: this.effectiveName });
+			return;
+		}
+
+		// Count one outstanding change per batch: the server acks once per
+		// merged message, so incrementing per buffered update would never balance.
+		if (this.pendingUpdates.length === 0) {
+			this.incrementUnsyncedChanges();
+		}
+
+		this.pendingUpdates.push(update);
+		this.scheduleFlush();
 	}
 
 	awarenessUpdateHandler({ added, updated, removed }: any, origin: any) {
+		if (origin === this) {
+			return;
+		}
+
 		const changedClients = added.concat(updated).concat(removed);
 
-		this.send(AwarenessMessage, {
-			awareness: this.awareness,
-			clients: changedClients,
-			documentName: this.effectiveName,
-		});
+		if (!this.batchingEnabled) {
+			this.send(AwarenessMessage, {
+				awareness: this.awareness,
+				clients: changedClients,
+				documentName: this.effectiveName,
+			});
+			return;
+		}
+
+		for (const client of changedClients) {
+			this.pendingAwarenessClients.add(client);
+		}
+
+		this.scheduleFlush();
+	}
+
+	private scheduleFlush() {
+		// Fixed-window batching: the first pending change starts the timer and
+		// everything until it fires is flushed together, so latency stays capped
+		// at `flushDelay` instead of growing while the user keeps typing.
+		if (this.flushTimeout !== null) {
+			return;
+		}
+
+		this.flushTimeout = setTimeout(() => {
+			this.flushTimeout = null;
+			this.flushPendingUpdates();
+		}, this.configuration.flushDelay as number);
+	}
+
+	/**
+	 * Send everything buffered for the current `flushDelay` window right away.
+	 * Buffered document updates are merged into a single message and awareness
+	 * collapses to the latest state of each changed client. Safe to call when
+	 * nothing is pending.
+	 */
+	flushPendingUpdates() {
+		if (this.flushTimeout !== null) {
+			clearTimeout(this.flushTimeout);
+			this.flushTimeout = null;
+		}
+
+		if (this.pendingUpdates.length > 0) {
+			const update =
+				this.pendingUpdates.length === 1
+					? this.pendingUpdates[0]
+					: Y.mergeUpdates(this.pendingUpdates);
+
+			this.pendingUpdates = [];
+			this.send(UpdateMessage, { update, documentName: this.effectiveName });
+		}
+
+		if (this.pendingAwarenessClients.size > 0) {
+			const clients = Array.from(this.pendingAwarenessClients);
+
+			this.pendingAwarenessClients.clear();
+			this.send(AwarenessMessage, {
+				awareness: this.awareness,
+				clients,
+				documentName: this.effectiveName,
+			});
+		}
 	}
 
 	/**
@@ -482,6 +595,15 @@ export class HocuspocusProvider extends EventEmitter {
 		this.isAuthenticated = false;
 		this.synced = false;
 
+		// Drop anything buffered for batching; the reconnect sync handshake will
+		// reconcile these changes from the document via state vectors.
+		if (this.flushTimeout !== null) {
+			clearTimeout(this.flushTimeout);
+			this.flushTimeout = null;
+		}
+		this.pendingUpdates = [];
+		this.pendingAwarenessClients.clear();
+
 		// update awareness (all users except local left)
 		if (this.awareness) {
 			removeAwarenessStates(
@@ -511,6 +633,10 @@ export class HocuspocusProvider extends EventEmitter {
 			this.awareness.destroy();
 		}
 
+		// Send any buffered updates before the socket is torn down. The websocket
+		// safely queues the message if it is no longer open.
+		this.flushPendingUpdates();
+
 		this.document.off("update", this.boundDocumentUpdateHandler);
 
 		this.removeAllListeners();

package/src/OutgoingMessage.ts

@@ -11,6 +11,8 @@ export class OutgoingMessage implements OutgoingMessageInterface {
 
 	type?: MessageType;
 
+	description?: string;
+
 	constructor() {
 		this.encoder = createEncoder();
 	}

package/src/types.ts

@@ -34,6 +34,7 @@ export type AuthorizedScope = "read-write" | "readonly";
 export interface OutgoingMessageInterface {
 	encoder: Encoder;
 	type?: MessageType;
+	description?: string;
 }
 
 export interface OutgoingMessageArguments {