svelte-adapter-uws-extensions 0.5.7 → 0.5.9

package/MIGRATION.md

@@ -36,7 +36,7 @@ Both hashes have per-field TTLs via `HPEXPIRE`. The pre-fix whole-key EXPIRE is
 
 3. **`metrics().staleCleanedTotal` is now always 0.** Per-field staleness is enforced atomically by Redis HPEXPIRE rather than by an application-side cleanup script, so there is nothing to count. The field stays in the return shape for backward-compatibility. The corresponding Prometheus counter `presence_stale_cleaned_total` is no longer registered.
 
-4. **`keyspaceNotifications: true` scope is narrower.** Pre-fix, the option subscribed to whole-key `__keyevent@*__:expired` for `presence:{topic}` keys and emitted an empty `presence_state` when one fired. Same shape in 0.5 (the per-topic hash whole-key expiry only fires when every field has expired, i.e. no live instances). Per-field expiry (a single crashed instance) does NOT trigger this notification; users disappear from `list()` / `count()` results lazily. If you need explicit per-field-expiry events, subscribe to `__keyevent@*__:hexpired` separately (separate Redis CONFIG flag).
+4. **`keyspaceNotifications: true` scope is narrower.** Pre-fix, the option subscribed to whole-key `__keyevent@*__:expired` for `presence:{topic}` keys and emitted an empty `state` when one fired. Same shape in 0.5 (the per-topic hash whole-key expiry only fires when every field has expired, i.e. no live instances). Per-field expiry (a single crashed instance) does NOT trigger this notification; users disappear from `list()` / `count()` results lazily. If you need explicit per-field-expiry events, subscribe to `__keyevent@*__:hexpired` separately (separate Redis CONFIG flag).
 
 5. **Falling back to single-instance.** If you can't upgrade Redis, switch to the in-memory `createPresence` plugin from `svelte-adapter-uws/plugins/presence`. Public API is the same; you lose cross-instance presence which is the whole point of the Redis variant, but for single-instance deployments it's a clean drop-in.
 
@@ -219,19 +219,19 @@ export function leaveBoard(ws, { topic, platform }) {
 
 No `close`-hook change required: uWS releases all per-`ws` subscriptions on disconnect, so `cursors.remove(ws, platform)` in your `close` hook still handles cleanup. The legacy `cursors.hooks.subscribe` slot is now a no-op (the adapter's wire gate prevents it from ever firing); it stays exported for source-compat but new code should not rely on it.
 
-### Presence wire shape on `__presence:{topic}` migrated to `presence_state` / `presence_diff`
+### Presence wire shape on `__presence:{topic}` migrated to `state` / `diff`
 
 **Only impacts apps with hand-rolled WebSocket clients consuming the wire directly.**
 
 **What changed.** The `redis/presence` channel previously emitted `list` / `join` / `leave` / `updated` / `heartbeat` events. It now emits:
 
-- `presence_state` (sent once on subscribe to a single connection): payload is `{[userKey]: data}` - a flat snapshot.
-- `presence_diff` (broadcast to topic subscribers, microtask-batched): payload is `{joins: {[key]: data}, leaves: {[key]: data}}`. Same-tick joins+leaves on the same key collapse to the latest op; updates appear as a `joins` entry with the new data.
+- `state` (sent once on subscribe to a single connection): payload is `{[userKey]: data}` - a flat snapshot.
+- `diff` (broadcast to topic subscribers, microtask-batched): payload is `{joins: {[key]: data}, leaves: {[key]: data}}`. Same-tick joins+leaves on the same key collapse to the latest op; updates appear as a `joins` entry with the new data.
 - `heartbeat` is unchanged.
 
-The public JS API on `createPresence` is unchanged (`join`, `leave`, `sync`, `list`, `count`, `metrics`, `clear`, `destroy`, `hooks` keep their signatures). The cross-instance Redis pub/sub envelope on `presence:events:{topic}` is also unchanged. The `keyspaceNotifications: true` mode now emits an empty `presence_state` event (was an empty `list` event) on hash expiry.
+The public JS API on `createPresence` is unchanged (`join`, `leave`, `sync`, `list`, `count`, `metrics`, `clear`, `destroy`, `hooks` keep their signatures). The cross-instance Redis pub/sub envelope on `presence:events:{topic}` is also unchanged. The `keyspaceNotifications: true` mode now emits an empty `state` event (was an empty `list` event) on hash expiry.
 
-**How to migrate.** Apps with a custom WebSocket client decoding presence frames must swap their decoder from the four legacy event names to `presence_state` / `presence_diff`:
+**How to migrate.** Apps with a custom WebSocket client decoding presence frames must swap their decoder from the four legacy event names to `state` / `diff`:
 
 ```js
 // before
@@ -241,11 +241,11 @@ case 'leave':   remove(payload.key); break;
 case 'updated': set(payload.key, payload.data); break;
 
 // after
-case 'presence_state':
+case 'state':
   state.clear();
   for (const k of Object.keys(payload)) state.set(k, payload[k]);
   break;
-case 'presence_diff':
+case 'diff':
   for (const k of Object.keys(payload.joins)) state.set(k, payload.joins[k]);
   for (const k of Object.keys(payload.leaves)) state.delete(k);
   break;

package/README.md

@@ -608,13 +608,13 @@ Clients see three event types on `__presence:{topic}`. Mirrors the adapter's bun
 
 | Event | When | Payload | Direction |
 |---|---|---|---|
-| `presence_state` | Once on subscribe | `{[userKey]: data}` - flat snapshot of current presence | Server -> single connection |
-| `presence_diff` | Microtask-batched after joins / leaves / updates | `{joins: {[key]: data}, leaves: {[key]: data}}` | Server -> topic subscribers |
+| `state` | Once on subscribe | `{[userKey]: data}` - flat snapshot of current presence | Server -> single connection |
+| `diff` | Microtask-batched after joins / leaves / updates | `{joins: {[key]: data}, leaves: {[key]: data}}` | Server -> topic subscribers |
 | `heartbeat` | Per heartbeat interval | `string[]` - array of currently-known user keys | Server -> topic subscribers |
 
-`presence_diff` collapses by key per-tick: if the same user joins and leaves in the same microtask, only the latest op survives on the wire. An update (same user re-joins with different data) appears as a `joins` entry carrying the new data, since clients overwrite their `Map.set` on the same key.
+`diff` collapses by key per-tick: if the same user joins and leaves in the same microtask, only the latest op survives on the wire. An update (same user re-joins with different data) appears as a `joins` entry carrying the new data, since clients overwrite their `Map.set` on the same key.
 
-Cross-instance traffic on the dedicated `presence:events:{topic}` Redis pub/sub channel is `{instanceId, topic, event, payload}` with `event` in `'join' | 'leave' | 'updated'`. Receivers route inbound events into their local diff buffer for client fan-out, so clients only ever see the unified `presence_state` / `presence_diff` shape regardless of which instance the change originated on.
+Cross-instance traffic on the dedicated `presence:events:{topic}` Redis pub/sub channel is `{instanceId, topic, event, payload}` with `event` in `'join' | 'leave' | 'updated'`. Receivers route inbound events into their local diff buffer for client fan-out, so clients only ever see the unified `state` / `diff` shape regardless of which instance the change originated on.
 
 Joins are staged with full rollback on failure: local state is set up first, then the Redis hashes are written, then the WebSocket is subscribed. If any step fails (circuit breaker trips, Redis is down, WebSocket closed during an async gap), all prior steps are undone - local maps, the Redis state, and any buffered diff entry are reversed. Compensating join+leave ops on the same key in the same tick collapse to nothing on the wire.
 
@@ -662,7 +662,7 @@ export async function close(ws, { platform }) {
 | `select` | strips `__`-prefixed keys | Extract public fields from userData |
 | `heartbeat` | `30000` | TTL refresh interval in ms |
 | `ttl` | `90` | Per-entry expiry in seconds. Entries from crashed instances expire individually after this period, even if other instances are still active on the same topic. |
-| `keyspaceNotifications` | `false` | Subscribe to Redis `__keyevent@*__:expired`. When a presence hash key expires (instance-died scenario), this instance's local subscribers receive an empty `presence_state` event. See [Keyspace cleanup mode](#keyspace-cleanup-mode). |
+| `keyspaceNotifications` | `false` | Subscribe to Redis `__keyevent@*__:expired`. When a presence hash key expires (instance-died scenario), this instance's local subscribers receive an empty `state` event. See [Keyspace cleanup mode](#keyspace-cleanup-mode). |
 
 #### API
 
@@ -674,7 +674,7 @@ export async function close(ws, { platform }) {
 | `list(topic)` | Get current users |
 | `count(topic)` | Count unique users |
 | `metrics()` | Synchronous snapshot: `{ totalOnline, heartbeatLatencyMs, staleCleanedTotal }`. See [Metrics snapshot](#metrics-snapshot). |
-| `flushDiffs()` | Drain the pending `presence_diff` buffer synchronously. Use in graceful-shutdown paths or tests that need the diff to land before the await chain continues. |
+| `flushDiffs()` | Drain the pending `diff` buffer synchronously. Use in graceful-shutdown paths or tests that need the diff to land before the await chain continues. |
 | `clear()` | Reset all presence state |
 | `destroy()` | Stop heartbeat and subscriber |
 | `hooks` | `{ subscribe, close }` - ready-made WebSocket hooks. Destructure for one-line `hooks.ws.js` setup. |
@@ -695,14 +695,14 @@ Two additional counters track the diff-protocol behavior:
 
 | Metric | Description |
 |---|---|
-| `presence_diff_frames_total{topic="..."}` | `presence_diff` frames published to topic subscribers. Compared against `presence_joins_total` + `presence_leaves_total` it tells you how much per-tick coalescing the buffer is doing - the bigger the gap, the more bandwidth saved versus per-event broadcast. |
+| `presence_diff_frames_total{topic="..."}` | `diff` frames published to topic subscribers. Compared against `presence_joins_total` + `presence_leaves_total` it tells you how much per-tick coalescing the buffer is doing - the bigger the gap, the more bandwidth saved versus per-event broadcast. |
 | `presence_diff_coalesced_total{topic="..."}` | Buffered diff entries overwritten by a later op in the same tick. A non-zero rate confirms the same-key collapse is working (e.g. a user reconnecting fast enough to leave-then-join in one tick). Zero is also a valid state under steady traffic. |
 
 #### Keyspace cleanup mode
 
-By default a sync-only observer (a connection that called `presence.sync()` to watch a room without joining it) only learns about leaves when the tracking instance broadcasts a `presence_diff` with the user in `leaves`. If the tracking instance crashes, the broadcast never fires and the observer's UI shows stale data until the page is reloaded.
+By default a sync-only observer (a connection that called `presence.sync()` to watch a room without joining it) only learns about leaves when the tracking instance broadcasts a `diff` with the user in `leaves`. If the tracking instance crashes, the broadcast never fires and the observer's UI shows stale data until the page is reloaded.
 
-`keyspaceNotifications: true` closes that gap by `psubscribe`-ing to `__keyevent@*__:expired`. When the presence hash key for a topic expires (which happens once no instance is heartbeating the topic anymore - typically because the only tracker crashed), this instance emits an empty `presence_state` event on `__presence:<topic>` so local subscribers can replace their entire local map with "no one here."
+`keyspaceNotifications: true` closes that gap by `psubscribe`-ing to `__keyevent@*__:expired`. When the presence hash key for a topic expires (which happens once no instance is heartbeating the topic anymore - typically because the only tracker crashed), this instance emits an empty `state` event on `__presence:<topic>` so local subscribers can replace their entire local map with "no one here."
 
 ```js
 const presence = createPresence(redis, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "publishConfig": {
     "tag": "latest"
   },
@@ -154,7 +154,7 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "svelte-adapter-uws": "^0.5.6"
+    "svelte-adapter-uws": "^0.5.8"
   },
   "dependencies": {
     "ioredis": "^5.0.0"

package/redis/presence.d.ts

@@ -38,8 +38,8 @@ export interface RedisPresenceOptions {
  * both single-instance and cluster deployments.
  */
 export type PresenceWireEvent =
-	| { event: 'presence_state'; data: Record<string, Record<string, any>> }
-	| { event: 'presence_diff'; data: { joins: Record<string, Record<string, any>>; leaves: Record<string, Record<string, any>> } }
+	| { event: 'state'; data: Record<string, Record<string, any>> }
+	| { event: 'diff'; data: { joins: Record<string, Record<string, any>>; leaves: Record<string, Record<string, any>> } }
 	| { event: 'heartbeat'; data: string[] };
 
 export interface PresenceMetricsSnapshot {
@@ -101,7 +101,7 @@ export interface RedisPresenceTracker {
 	 * Drain the pending diff buffer synchronously. The diff buffer
 	 * normally flushes on the next microtask after a join / leave /
 	 * update; call this when a test or graceful-shutdown path needs
-	 * the `presence_diff` to land before the await chain continues.
+	 * the `diff` to land before the await chain continues.
 	 */
 	flushDiffs(): void;
 

package/redis/presence.js

@@ -6,11 +6,12 @@
  * for cross-instance join/leave notifications.
  *
  * Wire shape clients see on `__presence:{topic}`:
- *   - `presence_state` (sent once on subscribe to a single connection)
+ *   - `state` (sent once on subscribe to a single connection)
  *       payload: `{[userKey]: data}` flat snapshot of current presence
- *   - `presence_diff` (broadcast to topic subscribers, microtask-batched)
+ *   - `diff` (broadcast to topic subscribers, tick-batched)
  *       payload: `{joins: {[key]: data}, leaves: {[key]: data}}`
- *       Same-tick joins+leaves on the same key collapse: latest op wins.
+ *       Joins+leaves on the same key in one event-loop iteration
+ *       collapse: latest op wins.
  *   - `heartbeat` (broadcast to topic subscribers, per heartbeat interval)
  *       payload: array of currently-known user keys
  *
@@ -148,7 +149,7 @@ return 0
 
 /**
  * Internal cross-instance Redis pub/sub envelope event names. NOT the
- * client wire shape - clients see `presence_state` / `presence_diff` /
+ * client wire shape - clients see `state` / `diff` /
  * `heartbeat`. These names live on the `presence:events:{topic}` channel
  * between instances and are routed into the local diff buffer on receive.
  */
@@ -256,7 +257,7 @@ export function createPresence(client, options = {}) {
 	const mTotalOnline = m?.gauge('presence_total_online', 'Unique users present per topic on this instance', ['topic']);
 	const mHeartbeatLatency = m?.gauge('presence_heartbeat_latency_ms', 'Duration of the most recent heartbeat tick in milliseconds');
 	const mKeyspaceCleanups = m?.counter('presence_keyspace_cleanups_total', 'Topics whose hash expiry triggered a local empty-list emit');
-	const mDiffFrames = m?.counter('presence_diff_frames_total', 'presence_diff frames published to topic subscribers', ['topic']);
+	const mDiffFrames = m?.counter('presence_diff_frames_total', 'diff frames published to topic subscribers', ['topic']);
 	const mDiffCoalesced = m?.counter('presence_diff_coalesced_total', 'Buffered diff entries overwritten by a later op in the same tick', ['topic']);
 
 	let lastHeartbeatLatency = 0;
@@ -317,14 +318,29 @@ export function createPresence(client, options = {}) {
 
 	/**
 	 * Per-topic pending diff buffer: latest op per key wins. Joins and
-	 * leaves on the same key in the same microtask collapse so the wire
-	 * only sees the net change. Flushed once per microtask via
-	 * `scheduleFlush`. Mirrors the buffer model the adapter's bundled
-	 * presence plugin uses, so a single client decoder handles both.
+	 * leaves on the same key in one event-loop iteration collapse so the
+	 * wire only sees the net change. Flushed once per iteration via
+	 * `setTimeout(flushPendingDiffs, 0)` armed when the first dirty entry
+	 * lands. Mirrors the buffer model the adapter's bundled presence
+	 * plugin uses, so a single client decoder handles both.
+	 *
+	 * 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 publishes 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.7 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;
 	/** @type {import('svelte-adapter-uws').Platform | null} */
 	let diffFlushPlatform = null;
 
@@ -339,14 +355,17 @@ export function createPresence(client, options = {}) {
 		}
 		entries.set(key, { op, data });
 		diffFlushPlatform = platform;
-		if (!diffFlushScheduled) {
-			diffFlushScheduled = true;
-			queueMicrotask(flushPendingDiffs);
+		if (diffFlushTimer === null) {
+			diffFlushTimer = setTimeout(flushPendingDiffs, 0);
+			if (diffFlushTimer.unref) diffFlushTimer.unref();
 		}
 	}
 
 	function flushPendingDiffs() {
-		diffFlushScheduled = false;
+		if (diffFlushTimer !== null) {
+			clearTimeout(diffFlushTimer);
+			diffFlushTimer = null;
+		}
 		const platform = diffFlushPlatform;
 		diffFlushPlatform = null;
 		if (!platform) {
@@ -363,7 +382,7 @@ export function createPresence(client, options = {}) {
 				else leaves[key] = data;
 			}
 			try {
-				platform.publish('__presence:' + topic, 'presence_diff', { joins, leaves }, { relay: false });
+				platform.publish('__presence:' + topic, 'diff', { joins, leaves }, { relay: false });
 				mDiffFrames?.inc({ topic: mt(topic) });
 			} catch { /* platform unavailable mid-flight */ }
 		}
@@ -533,11 +552,11 @@ export function createPresence(client, options = {}) {
 					// handler could only refresh `existing` entries; an
 					// entry the client swept (cross-replica relay latency,
 					// brief backpressure, JS thread saturation) could never
-					// be recovered without a presence_diff for that user.
+					// be recovered without a diff for that user.
 					// Older clients fall back gracefully: they see an
 					// object instead of an array and skip the legacy
-					// "refresh-existing" branch, but the next presence_diff
-					// or presence_state still reconciles them.
+					// "refresh-existing" branch, but the next diff
+					// or state still reconciles them.
 					/** @type {Record<string, any>} */
 					const dataMap = {};
 					for (const [userKey, entry] of data) dataMap[userKey] = entry.data;
@@ -590,7 +609,7 @@ export function createPresence(client, options = {}) {
 				// The per-topic hash key expires only when every field has
 				// expired (no live instances presenting any user on this
 				// topic). That is the "whole topic empty" signal we forward
-				// as an empty presence_state to local subscribers. Per-user
+				// as an empty state to local subscribers. Per-user
 				// hash keys (presence:user:{topic}:{userKey}) and the events
 				// channel are filtered out.
 				const topicPrefix = client.key('presence:topic:');
@@ -599,7 +618,7 @@ export function createPresence(client, options = {}) {
 					if (!expiredKey.startsWith(topicPrefix)) return;
 					const topic = expiredKey.slice(topicPrefix.length);
 					if (activePlatform) {
-						activePlatform.publish('__presence:' + topic, 'presence_state', {}, { relay: false });
+						activePlatform.publish('__presence:' + topic, 'state', {}, { relay: false });
 						mKeyspaceCleanups?.inc();
 					}
 				});
@@ -1223,7 +1242,7 @@ export function createPresence(client, options = {}) {
 				state[userKey] = entry.data;
 			}
 			try {
-				platform.send(ws, '__presence:' + topic, 'presence_state', state);
+				platform.send(ws, '__presence:' + topic, 'state', state);
 			} catch {
 				// WebSocket closed before send
 			}
@@ -1270,7 +1289,7 @@ export function createPresence(client, options = {}) {
 
 			try {
 				ws.subscribe(presenceTopic);
-				platform.send(ws, presenceTopic, 'presence_state', state);
+				platform.send(ws, presenceTopic, 'state', state);
 			} catch {
 				const topics = syncObservers.get(ws);
 				if (topics && topics.has(topic)) {
@@ -1359,7 +1378,10 @@ export function createPresence(client, options = {}) {
 			syncObservers.clear();
 			syncCounts.clear();
 			pendingDiffs.clear();
-			diffFlushScheduled = false;
+			if (diffFlushTimer !== null) {
+				clearTimeout(diffFlushTimer);
+				diffFlushTimer = null;
+			}
 			diffFlushPlatform = null;
 			connCounter = 0;
 		},
@@ -1379,7 +1401,10 @@ export function createPresence(client, options = {}) {
 			keyspaceSubscribed = false;
 			activePlatform = null;
 			pendingDiffs.clear();
-			diffFlushScheduled = false;
+			if (diffFlushTimer !== null) {
+				clearTimeout(diffFlushTimer);
+				diffFlushTimer = null;
+			}
 			diffFlushPlatform = null;
 		},
 
@@ -1396,13 +1421,13 @@ export function createPresence(client, options = {}) {
 				// Client-initiated reconnect-snapshot. The presence plugin
 				// client sends `{type:'presence-snapshot', topic}` on every
 				// status==='open' (initial connect + reconnect). Re-emits
-				// `presence_state` to the requesting ws via `tracker.sync`,
+				// `state` to the requesting ws via `tracker.sync`,
 				// which is the same path that fires on a fresh subscribe.
 				// Symmetric to cursor's `cursor-snapshot` text frame.
 				//
 				// Without this, board-scoped presence stayed stale across
 				// reconnects: a tab that had joined via an RPC saw no
-				// presence_diff during the disconnect window, and on
+				// diff during the disconnect window, and on
 				// reconnect its in-memory map was whatever it last knew.
 				// Global presence accidentally self-healed because most
 				// apps call `presence.join('global')` from the `open` hook

package/redis/pubsub.js

@@ -120,13 +120,25 @@ export function createPubSubBus(client, options = {}) {
 	/** @type {(() => void) | null} */
 	let unsubscribeBreaker = null;
 
-	// Microtask relay batching: coalesce Redis publishes within a single
-	// event-loop tick into one pipelined round trip. Each envelope tracks
-	// its underlying message count so the relayed-messages counter stays
-	// accurate when batch envelopes carry many messages each.
+	// Tick relay batching: coalesce Redis publishes within a single
+	// event-loop iteration into one pipelined round trip. Each envelope
+	// tracks its underlying message count so the relayed-messages counter
+	// stays accurate when batch envelopes carry many messages each.
+	//
+	// 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 Redis round-trips instead of one pipelined
+	// call. `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.7 cursor always-tick
+	// rewrite locked in.
 	/** @type {Array<{msg: string, count: number}>} */
 	let relayBatch = [];
-	let relayScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let relayTimer = null;
 	let relayBatchWarnFired = false;
 
 	function scheduleRelay(msg, count) {
@@ -135,23 +147,26 @@ export function createPubSubBus(client, options = {}) {
 		if (relayBatch.length >= MAX_PUBSUB_RELAY_BATCH_PER_TICK && !relayBatchWarnFired) {
 			relayBatchWarnFired = true;
 			console.warn(
-				'[pubsub] microtask relay batch reached ' + relayBatch.length +
-				' entries in one tick. The batch is drained every microtask, so a ' +
+				'[pubsub] tick relay batch reached ' + relayBatch.length +
+				' entries in one iteration. The batch is drained every tick, so a ' +
 				'caller emitted a million publishes in one synchronous burst - likely ' +
 				'a publish-in-loop without yielding.\n' +
 				'  See: https://svti.me/pubsub-burst'
 			);
 		}
-		if (!relayScheduled) {
-			relayScheduled = true;
-			queueMicrotask(flushRelay);
+		if (relayTimer === null) {
+			relayTimer = setTimeout(flushRelay, 0);
+			if (relayTimer.unref) relayTimer.unref();
 		}
 	}
 
 	function flushRelay() {
 		const batch = relayBatch;
 		relayBatch = [];
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		if (b) {
 			try { b.guard(); } catch { return; }
 		}
@@ -380,6 +395,11 @@ export function createPubSubBus(client, options = {}) {
 				unsubscribeBreaker();
 				unsubscribeBreaker = null;
 			}
+			if (relayTimer !== null) {
+				clearTimeout(relayTimer);
+				relayTimer = null;
+			}
+			relayBatch = [];
 			if (!active || !subscriber) return;
 			active = false;
 			activePlatform = null;

package/redis/sharded-pubsub.js

@@ -107,16 +107,26 @@ export function createShardedBus(client, options = {}) {
 	/** @type {WeakMap<any, Set<string>>} ws -> set of followed topics */
 	const wsFollows = new WeakMap();
 
-	// One-shot warn flag for the per-tick microtask batch cap.
+	// One-shot warn flag for the per-tick batch cap.
 	let batchChannelsWarnFired = false;
 
-	// Per-channel microtask batch: coalesce SPUBLISHes for the same
-	// channel within one tick into a single pipelined call. Each entry
-	// tracks the underlying topic list so the relayed-messages counter
-	// stays accurate when batch envelopes carry many messages.
+	// Per-channel tick batch: coalesce SPUBLISHes for the same channel
+	// within one event-loop iteration into a single pipelined call. Each
+	// entry tracks the underlying topic list so the relayed-messages
+	// counter stays accurate when batch envelopes carry many messages.
+	//
+	// 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. `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.7 cursor always-tick rewrite locked in.
 	/** @type {Map<string, Array<{msg: string, topics: string[]}>>} */
 	let channelBatches = new Map();
-	let relayScheduled = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let relayTimer = null;
 
 	function scheduleRelay(channel, msg, topics) {
 		let arr = channelBatches.get(channel);
@@ -128,23 +138,26 @@ export function createShardedBus(client, options = {}) {
 		if (channelBatches.size >= MAX_SHARDED_BUS_BATCH_CHANNELS_PER_TICK && !batchChannelsWarnFired) {
 			batchChannelsWarnFired = true;
 			console.warn(
-				'[sharded-bus] microtask batch reached ' + channelBatches.size +
-				' distinct channels in one tick. The batch is drained every microtask, ' +
+				'[sharded-bus] tick batch reached ' + channelBatches.size +
+				' distinct channels in one iteration. The batch is drained every tick, ' +
 				'so reaching this size means a publisher emitted a million distinct ' +
 				'channels in one synchronous burst - likely a topic-cardinality leak.\n' +
 				'  See: https://svti.me/sharded-bus-burst'
 			);
 		}
-		if (!relayScheduled) {
-			relayScheduled = true;
-			queueMicrotask(flushRelay);
+		if (relayTimer === null) {
+			relayTimer = setTimeout(flushRelay, 0);
+			if (relayTimer.unref) relayTimer.unref();
 		}
 	}
 
 	function flushRelay() {
 		const batches = channelBatches;
 		channelBatches = new Map();
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		if (b) {
 			try { b.guard(); } catch { return; }
 		}
@@ -268,7 +281,10 @@ export function createShardedBus(client, options = {}) {
 			subscriber = null;
 		}
 		channelBatches = new Map();
-		relayScheduled = false;
+		if (relayTimer !== null) {
+			clearTimeout(relayTimer);
+			relayTimer = null;
+		}
 		followCounts.clear();
 		channelRefcounts.clear();
 	}