svelte-adapter-uws 0.5.6 → 0.5.8

package/MIGRATION.md

@@ -145,9 +145,9 @@ These change observable runtime behavior. Most apps are unaffected; a few will n
 
 ### Presence plugin wire format switched to a compact diff protocol
 
-**What changed.** The five-event format (`list` / `join` / `updated` / `leave` / `heartbeat`) collapses to two diff-shaped events plus the existing heartbeat: `presence_state` (full snapshot) and `presence_diff` (joins/leaves). Diffs are microtask-batched. Server and client ship in one bundle, so a single-package upgrade is seamless.
+**What changed.** The five-event format (`list` / `join` / `updated` / `leave` / `heartbeat`) collapses to two diff-shaped events plus the existing heartbeat: `state` (full snapshot) and `diff` (joins/leaves). Diffs are microtask-batched. Server and client ship in one bundle, so a single-package upgrade is seamless.
 
-**How to migrate.** No action needed for users of the bundled `presence()` Svelte store on the client. Hand-rolled clients that consume the wire directly need to switch decoders to handle `presence_state` and `presence_diff` events. Stale browser tabs from a previous deploy will see a blank presence list until refresh.
+**How to migrate.** No action needed for users of the bundled `presence()` Svelte store on the client. Hand-rolled clients that consume the wire directly need to switch decoders to handle `state` and `diff` events. Stale browser tabs from a previous deploy will see a blank presence list until refresh.
 
 ### Wire single-subscribe frames consult `subscribeBatch` when only `subscribeBatch` is exported
 

package/README.md

@@ -2476,7 +2476,7 @@ presence.leave(ws, platform)         // remove from all topics (call from close
 presence.sync(ws, topic, platform)   // send snapshot without joining (for observers)
 presence.list(topic)                 // current user data array
 presence.count(topic)                // unique user count
-presence.flushDiffs()                // drain buffered presence_diff publishes synchronously
+presence.flushDiffs()                // drain buffered diff publishes synchronously
 presence.clear()                     // reset everything (stops heartbeat timer)
 ```
 
@@ -2484,9 +2484,9 @@ presence.clear()                     // reset everything (stops heartbeat timer)
 
 The plugin emits three frame types on the `__presence:{topic}` channel:
 
-- `{event: 'presence_state', data: {[key]: meta}}` - full snapshot, sent to a single connection on join or sync.
-- `{event: 'presence_diff', data: {joins: {[key]: meta}, leaves: {[key]: meta}}}` - changes, broadcast to all subscribers of the topic.
-- `{event: 'heartbeat', data: {[key]: meta}}` - periodic full-roster refresh, broadcast every `heartbeat` ms (30 s default). Carries a `{userKey: data}` map so a client whose entry aged out of its local `maxAge` sweep can re-add it from the heartbeat alone, without waiting for the next `presence_diff`.
+- `{event: 'state', data: {[key]: meta}}` - full snapshot, sent to a single connection on join or sync.
+- `{event: 'diff', data: {joins: {[key]: meta}, leaves: {[key]: meta}}}` - changes, broadcast to all subscribers of the topic.
+- `{event: 'heartbeat', data: {[key]: meta}}` - periodic full-roster refresh, broadcast every `heartbeat` ms (30 s default). Carries a `{userKey: data}` map so a client whose entry aged out of its local `maxAge` sweep can re-add it from the heartbeat alone, without waiting for the next `diff`.
 
 Diffs are buffered in a microtask queue: multiple joins / leaves in the same tick collapse into one diff frame. Within a diff, `leaves` are applied first then `joins`, so an update (same key in both) ends with the user present using the new data. If a key cycles join then leave in the same tick, the diff carries only the latest op (`leave` wins).
 
@@ -2501,7 +2501,7 @@ const users = presence('room');
 // $users = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]
 ```
 
-The client store defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed by a heartbeat or `presence_diff` / `presence_state` inside the window are removed from the local map. With the server's 30 s default heartbeat, still-present users are refreshed three times per window and never flicker; ghost entries left over by silent server-side cleanup (cluster mass-disconnect, ungraceful client close) clear within one sweep window.
+The client store defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed by a heartbeat or `diff` / `state` inside the window are removed from the local map. With the server's 30 s default heartbeat, still-present users are refreshed three times per window and never flicker; ghost entries left over by silent server-side cleanup (cluster mass-disconnect, ungraceful client close) clear within one sweep window.
 
 For admin / audit views that want unbounded retention ("show every user who ever touched this topic"), opt out with `maxAge: 0`:
 

package/files/handler.js

@@ -366,12 +366,24 @@ const app = is_tls
 	: uWS.App();
 
 // - Cross-worker pub/sub relay (batched) ------------------------------------
-// Batch postMessage calls within a single microtask. A SvelteKit action that
-// publishes N events sends one structured-clone across the thread boundary
-// instead of N. No-op in single-process mode (parentPort is null).
+// Batch postMessage calls within a single event-loop iteration. A SvelteKit
+// action that publishes N events sends one structured-clone across the thread
+// boundary instead of N. No-op in single-process mode (parentPort is null).
+//
+// Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS message
+// as its own JS task, and N-API drains microtasks at the C++/JS boundary
+// between tasks. A microtask-deferred flush fires BEFORE the next socket's
+// handler runs, so cross-socket coalescing is impossible at the microtask
+// level - N publishes from N socket handlers in the same iteration produce N
+// postMessage structured-clones instead of one batched. `setTimeout(0)` lands
+// in libuv's timers phase, which fires only after the poll phase has
+// dispatched every ready socket message in the current iteration. Same
+// structural choice the 0.5.6 cursor always-tick rewrite locked in.
 
 /** @type {Array<{topic: string, envelope: string}> | null} */
 let relayBatch = null;
+/** @type {ReturnType<typeof setTimeout> | null} */
+let relayTimer = null;
 
 /**
  * @param {string} topic
@@ -380,12 +392,14 @@ let relayBatch = null;
 function batchRelay(topic, envelope) {
 	if (!relayBatch) {
 		relayBatch = [];
-		queueMicrotask(() => {
+		relayTimer = setTimeout(() => {
+			relayTimer = null;
 			if (relayBatch) {
 				parentPort.postMessage({ type: 'publish-batch', messages: relayBatch });
 			}
 			relayBatch = null;
-		});
+		}, 0);
+		if (relayTimer.unref) relayTimer.unref();
 	}
 	relayBatch.push({ topic, envelope });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "publishConfig": {
     "tag": "latest"
   },

package/plugins/presence/client.d.ts

@@ -7,7 +7,7 @@ import type { Readable } from 'svelte/store';
  * The array updates automatically when users join or leave.
  *
  * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
- * by a heartbeat or presence_diff/state inside the window are removed
+ * by a heartbeat or diff/state inside the window are removed
  * from the local map. The server emits `{userKey: data}` heartbeats
  * every 30 s by default, so still-present users re-appear on the next
  * heartbeat (no flicker). Pass `maxAge: 0` to opt out of the sweep for

package/plugins/presence/client.js

@@ -6,7 +6,7 @@
  * this module just keeps the client-side state in sync.
  *
  * Defaults to a 90 s `maxAge` sweep: entries that haven't been refreshed
- * by a heartbeat or presence_diff/state inside the window are removed
+ * by a heartbeat or diff/state inside the window are removed
  * from the local map. The in-memory server (and the Redis-backed variant
  * in svelte-adapter-uws-extensions) emits `{userKey: data}` heartbeats
  * every 30 s by default, so a still-present user re-appears on the very
@@ -127,7 +127,7 @@ export function presence(topic, options) {
 		sourceUnsub = source.subscribe((event) => {
 			if (event === null) return;
 
-			if (event.event === 'presence_state' && event.data && typeof event.data === 'object') {
+			if (event.event === 'state' && event.data && typeof event.data === 'object') {
 				userMap = new Map();
 				timestamps.clear();
 				const now = Date.now();
@@ -139,7 +139,7 @@ export function presence(topic, options) {
 				return;
 			}
 
-			if (event.event === 'presence_diff' && event.data && typeof event.data === 'object') {
+			if (event.event === 'diff' && event.data && typeof event.data === 'object') {
 				const { joins, leaves } = event.data;
 				const now = Date.now();
 				let changed = false;
@@ -175,7 +175,7 @@ export function presence(topic, options) {
 					// recover entries the local sweep had already removed -
 					// once an entry aged out, the next heartbeat couldn't
 					// bring it back and the user stayed missing until a
-					// presence_diff or presence_state arrived.
+					// diff or state arrived.
 					for (const [key, data] of Object.entries(event.data)) {
 						timestamps.set(key, now);
 						const prev = userMap.get(key);
@@ -187,7 +187,7 @@ export function presence(topic, options) {
 				} else if (Array.isArray(event.data)) {
 					// Back-compat: keys-only heartbeat (older server). Refresh
 					// existing entries; cannot recover aged-out ones from this
-					// shape. The presence_diff / presence_state reconciliation
+					// shape. The diff / state reconciliation
 					// path still corrects missing entries on the next event.
 					for (const key of event.data) {
 						if (timestamps.has(key)) {
@@ -206,7 +206,7 @@ export function presence(topic, options) {
 
 		// Request a presence snapshot every time the socket opens (initial
 		// connect AND reconnects). Without this, a reconnecting client
-		// missed any presence_diff frames that fired during the disconnect
+		// missed any diff frames that fired during the disconnect
 		// window and its in-memory map stayed at whatever it last knew.
 		// Symmetric to the cursor plugin's `cursor-snapshot` send.
 		statusUnsub = status.subscribe((s) => {

package/plugins/presence/server.d.ts

@@ -51,7 +51,7 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	 * topics carrying a `{userKey: data}` map of every active user. This
 	 * refreshes each entry's `maxAge` timer on the client AND re-adds any
 	 * entry the client swept while the user was still present, so live
-	 * users do not flicker out when a `presence_diff` is missed (transient
+	 * users do not flicker out when a `diff` is missed (transient
 	 * network blip, JS thread saturation).
 	 *
 	 * Set this to a value shorter than the client's `maxAge`. The 30 s
@@ -69,7 +69,7 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	 *
 	 * @example
 	 * ```js
-	 * // Disable heartbeats; client must rely on presence_diff alone
+	 * // Disable heartbeats; client must rely on diff alone
 	 * const presence = createPresence({ heartbeat: 0 });
 	 * ```
 	 */
@@ -105,9 +105,9 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	 *
 	 * What happens:
 	 * 1. Adds the user to the topic's presence map
-	 * 2. Buffers a `join` entry into the next presence_diff broadcast (microtask-flushed)
+	 * 2. Buffers a `join` entry into the next diff broadcast (microtask-flushed)
 	 * 3. Subscribes this ws to the presence channel
-	 * 4. Sends the full current snapshot (`presence_state`) to this ws
+	 * 4. Sends the full current snapshot (`state`) to this ws
 	 *
 	 * @example
 	 * ```js
@@ -123,7 +123,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	 *
 	 * Call this from your `close` hook. Handles multi-tab correctly:
 	 * if the user has other connections still open, they stay present.
-	 * Only buffers a `leave` entry into the next presence_diff when the
+	 * Only buffers a `leave` entry into the next diff when the
 	 * last connection closes.
 	 *
 	 * @example
@@ -136,7 +136,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	leave(ws: WebSocket<any>, platform: Platform): void;
 
 	/**
-	 * Send the current presence snapshot (`presence_state`) to a connection without joining.
+	 * Send the current presence snapshot (`state`) to a connection without joining.
 	 *
 	 * Use this for observers (admin dashboards, spectators) who want to
 	 * see who's present without being counted as present themselves.
@@ -187,7 +187,7 @@ export interface PresenceTracker<Selected extends Record<string, any> = Record<s
 	clear(): void;
 
 	/**
-	 * Drain any buffered `presence_diff` publishes synchronously.
+	 * Drain any buffered `diff` publishes synchronously.
 	 *
 	 * Diffs are normally microtask-batched: multiple joins / leaves in the
 	 * same tick collapse into one broadcast frame. Tests use this to

package/plugins/presence/server.js

@@ -56,7 +56,7 @@ const TOPIC_PREFIX = '__presence:';
  *   The server periodically publishes a `heartbeat` event to all presence topics carrying a
  *   `{userKey: data}` map of every active user. This refreshes each entry's `maxAge` timer on
  *   the client AND re-adds any entry the client swept while the user was still present, so
- *   live users do not flicker out when a `presence_diff` is missed (e.g. transient network
+ *   live users do not flicker out when a `diff` is missed (e.g. transient network
  *   blip, JS thread saturation). Set this to a value shorter than the client's `maxAge`
  *   (default client `maxAge` is 90 s, so 30 s gives a 3x safety margin). Pass `0` to disable
  *   heartbeats entirely (apps that do not use the `maxAge` self-healing path).
@@ -302,12 +302,28 @@ export function createPresence(options = {}) {
 
 	/**
 	 * Per-topic pending diff buffer: latest op per key wins. Joins and leaves
-	 * happening on the same key in a tick collapse so the wire only sees the
-	 * net change. Flushed once per microtask via `scheduleDiffFlush`.
+	 * happening on the same key in one event-loop iteration collapse so the
+	 * wire only sees the net change. Flushed once per iteration via
+	 * `setTimeout(() => flushDiffs(platform), 0)` armed when the first dirty
+	 * entry lands.
+	 *
+	 * Why `setTimeout(0)` and not `queueMicrotask`: uWS dispatches each WS
+	 * message as its own JS task, and N-API drains microtasks at the C++/JS
+	 * boundary between tasks. A microtask-deferred flush fires BEFORE the
+	 * next socket's handler runs, so cross-socket coalescing is impossible
+	 * at the microtask level - a mass-join into a populated topic produces
+	 * O(N) one-entry diffs instead of one batched diff. `setTimeout(0)`
+	 * lands in libuv's timers phase, which fires only after the poll phase
+	 * has dispatched every ready socket message in the current iteration -
+	 * so all joins arriving together end up in one flush regardless of how
+	 * many task boundaries separate them. Same structural choice the
+	 * 0.5.6 cursor always-tick rewrite locked in.
+	 *
 	 * @type {Map<string, Map<string, { op: 'join' | 'leave', data: Record<string, any> }>>}
 	 */
 	const pendingDiffs = new Map();
-	let diffFlushScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let diffFlushTimer = null;
 
 	/**
 	 * @param {string} topic
@@ -323,15 +339,18 @@ export function createPresence(options = {}) {
 			pendingDiffs.set(topic, entries);
 		}
 		entries.set(key, { op, data });
-		if (!diffFlushScheduled) {
-			diffFlushScheduled = true;
-			queueMicrotask(() => flushDiffs(platform));
+		if (diffFlushTimer === null) {
+			diffFlushTimer = setTimeout(() => flushDiffs(platform), 0);
+			if (diffFlushTimer.unref) diffFlushTimer.unref();
 		}
 	}
 
 	/** @param {import('../../index.js').Platform} platform */
 	function flushDiffs(platform) {
-		diffFlushScheduled = false;
+		if (diffFlushTimer !== null) {
+			clearTimeout(diffFlushTimer);
+			diffFlushTimer = null;
+		}
 		for (const [topic, entries] of pendingDiffs) {
 			/** @type {Record<string, Record<string, any>>} */
 			const joins = {};
@@ -341,13 +360,13 @@ export function createPresence(options = {}) {
 				if (op === 'join') joins[key] = data;
 				else leaves[key] = data;
 			}
-			platform.publish(TOPIC_PREFIX + topic, 'presence_diff', { joins, leaves });
+			platform.publish(TOPIC_PREFIX + topic, 'diff', { joins, leaves });
 		}
 		pendingDiffs.clear();
 	}
 
 	/**
-	 * Build a presence_state snapshot for a topic: {[key]: data}.
+	 * Build a state snapshot for a topic: {[key]: data}.
 	 * @param {Map<string, { data: Record<string, any>, count: number }> | undefined} users
 	 * @returns {Record<string, Record<string, any>>}
 	 */
@@ -387,8 +406,8 @@ export function createPresence(options = {}) {
 					// Publish a `{userKey: data}` map (rather than a keys-only
 					// array) so a client whose entry aged out of its local
 					// `maxAge` sweep between heartbeats can re-add it from the
-					// heartbeat alone, without waiting for a presence_diff /
-					// presence_state to reconcile. Matches the Redis-backed
+					// heartbeat alone, without waiting for a diff /
+					// state to reconcile. Matches the Redis-backed
 					// variant in svelte-adapter-uws-extensions.
 					/** @type {Record<string, any>} */
 					const dataMap = {};
@@ -484,7 +503,7 @@ export function createPresence(options = {}) {
 			if (existing) {
 				// Same user, additional connection (another tab) - bump count.
 				// A data change (e.g. avatar updated in another session) becomes
-				// a `join` entry in the next presence_diff: client overwrites
+				// a `join` entry in the next diff: client overwrites
 				// the existing key with the new data.
 				existing.count++;
 				if (!deepEqual(existing.data, data)) {
@@ -507,7 +526,7 @@ export function createPresence(options = {}) {
 			// user sees the complete state (including themselves) immediately;
 			// any pending diff fan-out reaches them too but is idempotent on
 			// the client (joins[key] = data is a no-op if already set).
-			platform.send(ws, presenceTopic, 'presence_state', snapshotState(users));
+			platform.send(ws, presenceTopic, 'state', snapshotState(users));
 		},
 
 		leave(ws, platform) {
@@ -527,7 +546,7 @@ export function createPresence(options = {}) {
 			const users = topicPresence.get(topic);
 			const presenceTopic = TOPIC_PREFIX + topic;
 			try { ws.subscribe(presenceTopic); } catch { return; }
-			platform.send(ws, presenceTopic, 'presence_state', snapshotState(users));
+			platform.send(ws, presenceTopic, 'state', snapshotState(users));
 		},
 
 		list(topic) {
@@ -554,21 +573,24 @@ export function createPresence(options = {}) {
 			wsTopics.clear();
 			topicPresence.clear();
 			pendingDiffs.clear();
-			diffFlushScheduled = false;
+			if (diffFlushTimer !== null) {
+				clearTimeout(diffFlushTimer);
+				diffFlushTimer = null;
+			}
 			connCounter = 0;
 		},
 
 		/**
 		 * Drain any buffered diff publishes synchronously. Tests use this
-		 * to assert on the wire output without awaiting the microtask
-		 * queue. Production code generally does not need to call it - the
-		 * microtask flush happens automatically. Useful when a caller
+		 * to assert on the wire output without awaiting the next-tick
+		 * setTimeout flush. Production code generally does not need to call
+		 * it - the tick flush happens automatically. Useful when a caller
 		 * needs presence state visible to other workers before its own
 		 * synchronous block returns (e.g. before responding to an HTTP
 		 * request that just triggered a leave).
 		 */
 		flushDiffs() {
-			if (!diffFlushScheduled || !_platform) return;
+			if (diffFlushTimer === null || !_platform) return;
 			flushDiffs(_platform);
 		},