svelte-adapter-uws-extensions 0.5.7 → 0.5.8

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.8",
   "publishConfig": {
     "tag": "latest"
   },
@@ -154,7 +154,7 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "svelte-adapter-uws": "^0.5.6"
+    "svelte-adapter-uws": "^0.5.7"
   },
   "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,9 +6,9 @@
  * 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, microtask-batched)
  *       payload: `{joins: {[key]: data}, leaves: {[key]: data}}`
  *       Same-tick joins+leaves on the same key collapse: latest op wins.
  *   - `heartbeat` (broadcast to topic subscribers, per heartbeat interval)
@@ -148,7 +148,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 +256,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;
@@ -363,7 +363,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 +533,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 +590,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 +599,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 +1223,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 +1270,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)) {
@@ -1396,13 +1396,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