svelte-realtime 0.1.5 → 0.1.7

package/README.md

@@ -647,7 +647,7 @@ const [board, column] = await batch(() => [
 ], { sequential: true });
 ```
 
-Each call resolves or rejects independently -- one failure does not cancel the others. Batches are limited to 50 calls per frame.
+Each call resolves or rejects independently -- one failure does not cancel the others. Batches are limited to 50 calls -- enforced both client-side (rejects before sending) and server-side.
 
 ---
 
@@ -1511,7 +1511,7 @@ The adapter's `sendQueued()` drops the oldest item if the queue exceeds 1000. Un
 
 ### Batch size (max 50 calls)
 
-A single `batch()` call is limited to 50 RPC calls. If exceeded, the server rejects the entire batch. Split into multiple `batch()` calls if you need more.
+A single `batch()` call is limited to 50 RPC calls. The client rejects before sending if the limit is exceeded, and the server enforces the same limit as a safety net. Split into multiple `batch()` calls if you need more.
 
 ### ws.subscribe() vs the subscribe hook
 
@@ -1773,6 +1773,14 @@ What gets measured:
 
 Merge strategies use an internal `Map<key, index>` for O(1) lookups instead of linear scans. Updates and upserts on keyed strategies (crud, presence, cursor) are constant-time regardless of array size. Deletes and prepends require an index rebuild (linear), which matches the cost of the delete itself.
 
+### Event batching (browser)
+
+In the browser, incoming pub/sub events are queued and flushed once per `requestAnimationFrame` instead of triggering a Svelte store update per event. This is automatic -- no configuration needed.
+
+With high-frequency streams (e.g. 1000 cursors at 20 updates/sec), this reduces reactive store updates from ~20,000/sec to ~60/sec (one per frame). All merge operations still run, but Svelte only diffs and re-renders once per frame.
+
+In Node/SSR (tests, `__directCall`, etc.), events apply synchronously -- no batching overhead.
+
 These benchmarks run in-process with mock objects (no real network). They isolate the framework overhead from network latency. See [bench/rpc.js](bench/rpc.js) for the full source.
 
 ---

package/client.js

@@ -4,6 +4,14 @@ import { writable } from 'svelte/store';
 
 const _textEncoder = new TextEncoder();
 
+/**
+ * RAF-based event batching for high-frequency streams (cursors, presence).
+ * In the browser, incoming pub/sub events are queued and flushed once per
+ * animation frame, reducing Svelte reactive updates from N-per-event to
+ * 1-per-frame. In Node/SSR, events apply synchronously (no DOM to protect).
+ */
+const _useRAF = typeof window !== 'undefined' && typeof requestAnimationFrame === 'function';
+
 /**
  * Typed error for RPC failures.
  */
@@ -535,18 +543,49 @@ function _createStream(path, options, dynamicArgs) {
 		return false;
 	}
 
+	/** @type {Array<{ event: string, data: any }>} Queued events waiting for next animation frame */
+	let _eventQueue = [];
+
+	/** @type {number | null} */
+	let _rafId = null;
+
 	/**
-	 * Apply a single pub/sub event to the current value using the merge strategy.
-	 * Creates a new array reference for Svelte reactivity only when needed.
-	 * @param {{ event: string, data: any }} envelope
+	 * Flush all queued events in a single batch, then update the store once.
+	 * Reduces reactive updates from N-per-event to 1-per-frame.
 	 */
-	function applyEvent(envelope) {
-		const replaced = _applyMerge(envelope);
-		if (!replaced && Array.isArray(currentValue)) currentValue = currentValue.slice();
+	function _flushEvents() {
+		_rafId = null;
+		if (_eventQueue.length === 0) return;
+		const queue = _eventQueue;
+		_eventQueue = [];
+		for (let i = 0; i < queue.length; i++) {
+			_applyMerge(queue[i]);
+		}
+		if (Array.isArray(currentValue)) currentValue = currentValue.slice();
 		store.set(currentValue);
 		_recordHistory();
 	}
 
+	/**
+	 * Apply a pub/sub event to the store. In the browser, events are queued
+	 * and flushed once per animation frame to reduce reactive updates from
+	 * N-per-event to 1-per-frame. In Node/SSR, events apply immediately.
+	 * @param {{ event: string, data: any }} envelope
+	 */
+	function applyEvent(envelope) {
+		if (_useRAF) {
+			_eventQueue.push(envelope);
+			if (_rafId === null) {
+				_rafId = requestAnimationFrame(_flushEvents);
+			}
+		} else {
+			const replaced = _applyMerge(envelope);
+			if (!replaced && Array.isArray(currentValue)) currentValue = currentValue.slice();
+			store.set(currentValue);
+			_recordHistory();
+		}
+	}
+
 	/**
 	 * Fetch initial data and subscribe to live updates.
 	 */
@@ -716,6 +755,11 @@ function _createStream(path, options, dynamicArgs) {
 			clearTimeout(_reconnectTimer);
 			_reconnectTimer = null;
 		}
+		if (_rafId !== null) {
+			cancelAnimationFrame(_rafId);
+			_rafId = null;
+		}
+		_eventQueue = [];
 		topic = null;
 		initialLoaded = false;
 		fetching = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",