svelte-adapter-uws 0.5.3 → 0.5.4

package/README.md

@@ -2377,8 +2377,8 @@ import { createPresence } from 'svelte-adapter-uws/plugins/presence';
 
 export const presence = createPresence({
   key: 'id',
-  select: (userData) => ({ id: userData.id, name: userData.name }),
-  heartbeat: 60_000  // optional: needed if clients use maxAge
+  select: (userData) => ({ id: userData.id, name: userData.name })
+  // heartbeat:      30_000 (default) - broadcast every 30s; clients refresh maxAge / re-add aged-out entries
   // maxConnections: 1_000_000 (default) - hard cap on tracked connections
   // maxTopics:      1_000_000 (default) - hard cap on active topic registry
 });
@@ -2450,8 +2450,8 @@ import { createPresence } from 'svelte-adapter-uws/plugins/presence';
 
 const presence = createPresence({
   key: 'id',             // field for multi-tab dedup (default: 'id')
-  select: (userData) => userData,  // extract public fields (default: full userData)
-  heartbeat: 60_000      // broadcast active keys every 60s (default: disabled)
+  select: (userData) => userData,  // extract public fields (default: recursive denylist)
+  heartbeat: 30_000      // broadcast every 30s (default: 30000; pass 0 to disable)
 });
 
 presence.hooks                       // ready-made { subscribe, unsubscribe, close } hooks
@@ -2466,14 +2466,15 @@ presence.clear()                     // reset everything (stops heartbeat timer)
 
 #### Wire format
 
-The plugin emits two frame types on the `__presence:{topic}` channel:
+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`.
 
 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).
 
-`heartbeat` events (when configured) are unchanged: they carry an array of currently-active keys.
+The Redis-backed variant in the [extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) package emits the same three frame shapes, so the same client bundle works against either backend.
 
 #### Client API
 
@@ -2484,20 +2485,24 @@ const users = presence('room');
 // $users = [{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]
 ```
 
-The `presence()` function accepts an optional second argument with a `maxAge` option (in milliseconds). When set, entries that haven't been refreshed within that window are automatically removed from the store. This makes clients self-healing when the server fails to broadcast a leaving entry in a `presence_diff` frame under load.
+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.
 
-**Important:** `maxAge` requires the server-side `heartbeat` option. Without heartbeat, no events arrive between the initial `presence_state` snapshot and eventual leave, so maxAge would expire every user - including ones who are still connected. The heartbeat periodically tells clients which keys are still active, resetting their maxAge timers.
+For admin / audit views that want unbounded retention ("show every user who ever touched this topic"), opt out with `maxAge: 0`:
+
+```js
+const everyoneEver = presence('room', { maxAge: 0 });
+```
+
+To customize the window, set `maxAge` and the matching server `heartbeat` together (rule of thumb: heartbeat is one-third of `maxAge` or less, so a still-present user gets at least two refreshes per sweep window):
 
 ```js
 // Server: heartbeat every 60s
 const presence = createPresence({ key: 'id', heartbeat: 60_000 });
 
-// Client: entries expire after 120s without a heartbeat refresh
-const users = presence('room', { maxAge: 120_000 });
+// Client: entries expire after 180s without a heartbeat refresh
+const users = presence('room', { maxAge: 180_000 });
 ```
 
-Rule of thumb: set `heartbeat` to half (or less) of the client's `maxAge`.
-
 #### How multi-tab dedup works
 
 If user "Alice" (key `id: '1'`) has three browser tabs open, `presence.join()` is called three times with the same key. The plugin ref-counts connections per key: Alice appears once in the list. When she closes two tabs, she stays present. Only when the last tab closes does the plugin broadcast a `leave` event.

package/package.json

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

package/plugins/cursor/server.js

@@ -99,6 +99,13 @@ const EVENTS = Object.freeze({
  *   subscribe so late joiners see existing cursors immediately.
  * @property {() => void} clear -
  *   Clear all cursor tracking state and pending timers.
+ * @property {() => { flushes: number, driftMeanMs: number, driftMaxMs: number, dirtyTopicsCurrent: number, activeTopicsTotal: number }} stats -
+ *   Snapshot of scheduler health. `flushes` is the total tick-driven
+ *   flushes; `driftMeanMs` / `driftMaxMs` measure the gap between the
+ *   target deadline and the actual fire time (`> topicThrottle` indicates
+ *   sustained event-loop saturation); `dirtyTopicsCurrent` is topics with
+ *   pending coalesced entries (should hover near zero); `activeTopicsTotal`
+ *   is topics with at least one local cursor.
  */
 
 /**
@@ -193,14 +200,48 @@ export function createCursor(options = {}) {
 	const topics = new Map();
 
 	/**
-	 * Per-topic aggregate throttle state for `topicThrottle` coalescing.
-	 * Dirty entries are keyed by connection key; latest-wins. When the
-	 * coalesce window elapses, `dirty.size === 1` sends a single `update`
-	 * and any other count sends one `bulk` array.
-	 * @type {Map<string, { lastFlush: number, timer: any, dirty: Map<string, { data: any, platform: any }> }>}
+	 * Per-topic aggregate flush state.
+	 *
+	 * - `dirty`: cursors awaiting coalesced flush. Keyed by connection key;
+	 *   latest-wins. When the coalesce window elapses, `dirty.size === 1`
+	 *   sends a single `update`; any other count sends one `bulk` array.
+	 * - `lastFlush`: target-anchored timestamp of the most recent flush.
+	 *   Advanced by `topicThrottleMs` per cycle (not to actual fire time)
+	 *   so a single late tick does not compound drift on subsequent cycles.
+	 *
+	 * @type {Map<string, { dirty: Map<string, { data: any, platform: any }>, lastFlush: number }>}
 	 */
 	const topicFlush = new Map();
 
+	/**
+	 * Topics with at least one pending dirty entry. Bounded by mover count,
+	 * not active-topic count, so the scheduler walks only dirty topics on
+	 * each tick instead of every active one.
+	 * @type {Set<string>}
+	 */
+	const dirtyTopics = new Set();
+
+	/**
+	 * Single tracker-wide timer. Always points at the next earliest topic
+	 * deadline (or null when idle). Replaces the previous per-topic
+	 * setTimeout pattern: N pending timers -> 1 pending timer regardless
+	 * of topic count. Scheduling cost is O(dirty topics), not O(active
+	 * topics).
+	 * @type {ReturnType<typeof setTimeout> | null}
+	 */
+	let tickTimer = null;
+
+	/**
+	 * Drift accounting for `stats()` observability. Mean (target - actual)
+	 * and max over tick-driven flushes. Leading-edge synchronous flushes
+	 * are NOT counted (they fire on the caller's thread, not via the
+	 * scheduler; their drift is structurally zero).
+	 */
+	let driftSum = 0;
+	let driftCount = 0;
+	let driftMax = 0;
+	let flushCount = 0;
+
 	/**
 	 * Get or create ws state and return the connection key + user data.
 	 * @param {any} ws
@@ -224,14 +265,15 @@ export function createCursor(options = {}) {
 	}
 
 	/**
-	 * Drop the topic's coalesce state (clears any pending timer first).
+	 * Drop the topic's coalesce state. The single tracker-wide tickTimer is
+	 * left alone (it self-cancels on the next tick when `dirtyTopics` is
+	 * empty); we just remove this topic from both the flush map and the
+	 * dirty set so the next tick skips it.
 	 * @param {string} topic
 	 */
 	function clearTopicFlush(topic) {
-		const flushState = topicFlush.get(topic);
-		if (!flushState) return;
-		if (flushState.timer) clearTimeout(flushState.timer);
 		topicFlush.delete(topic);
+		dirtyTopics.delete(topic);
 	}
 
 	/**
@@ -262,6 +304,7 @@ export function createCursor(options = {}) {
 	 */
 	function flushDirty(topic, dirty) {
 		if (dirty.size === 0) return;
+		flushCount++;
 		if (dirty.size === 1) {
 			const [k, v] = dirty.entries().next().value;
 			doBroadcast(topic, k, v.data, v.platform);
@@ -278,9 +321,65 @@ export function createCursor(options = {}) {
 		}
 	}
 
+	/**
+	 * Scheduler tick. Walks `dirtyTopics`, flushes any topic whose deadline
+	 * (`lastFlush + topicThrottleMs`) has passed, and re-arms `tickTimer`
+	 * for the next earliest pending deadline. Topics whose deadline has
+	 * not yet passed stay in `dirtyTopics` for the next tick.
+	 *
+	 * Target-anchored advance: on flush, `lastFlush` is set to the deadline
+	 * (not the actual fire time) so a single late tick does not compound
+	 * drift on subsequent cycles. If we fell behind by more than one cycle
+	 * (event loop saturation > `topicThrottleMs`), `lastFlush` resets to
+	 * `now` to avoid queueing phantom catch-up fires.
+	 */
+	function tick() {
+		tickTimer = null;
+		const now = Date.now();
+		let nextDeadline = Infinity;
+
+		for (const topic of dirtyTopics) {
+			const state = topicFlush.get(topic);
+			if (!state) { dirtyTopics.delete(topic); continue; }
+			if (state.dirty.size === 0) {
+				dirtyTopics.delete(topic);
+				continue;
+			}
+			const deadline = state.lastFlush + topicThrottleMs;
+			if (deadline <= now) {
+				const drift = now - deadline;
+				driftSum += drift;
+				driftCount++;
+				if (drift > driftMax) driftMax = drift;
+
+				flushDirty(topic, state.dirty);  // increments flushCount internally
+				state.dirty.clear();
+				dirtyTopics.delete(topic);
+
+				state.lastFlush = drift < topicThrottleMs ? deadline : now;
+			} else if (deadline < nextDeadline) {
+				nextDeadline = deadline;
+			}
+		}
+
+		if (nextDeadline !== Infinity) {
+			tickTimer = setTimeout(tick, Math.max(0, nextDeadline - Date.now()));
+		}
+		// else: scheduler idle until next `broadcast()` call.
+	}
+
+	function armTick(delay) {
+		if (tickTimer !== null) return;
+		tickTimer = setTimeout(tick, delay);
+	}
+
 	/**
 	 * Route a broadcast through the per-topic coalesce window when
 	 * `topicThrottle` is enabled, or directly publish when disabled.
+	 *
+	 * Leading-edge synchronous flush preserves the contract that the first
+	 * call on an idle topic publishes immediately (no setTimeout(0) detour).
+	 * Trailing-edge fires via the single tracker-wide `tickTimer`.
 	 */
 	function broadcast(topic, key, data, platform) {
 		if (topicThrottleMs <= 0) {
@@ -290,34 +389,22 @@ export function createCursor(options = {}) {
 
 		let state = topicFlush.get(topic);
 		if (!state) {
-			state = { lastFlush: 0, timer: null, dirty: new Map() };
+			state = { dirty: new Map(), lastFlush: 0 };
 			topicFlush.set(topic, state);
 		}
-
 		state.dirty.set(key, { data, platform });
 
 		const now = Date.now();
 		if (now - state.lastFlush >= topicThrottleMs) {
-			if (state.timer) {
-				clearTimeout(state.timer);
-				state.timer = null;
-			}
 			state.lastFlush = now;
 			flushDirty(topic, state.dirty);
 			state.dirty.clear();
+			dirtyTopics.delete(topic);
 			return;
 		}
 
-		if (!state.timer) {
-			state.timer = setTimeout(() => {
-				const s = topicFlush.get(topic);
-				if (!s) return;
-				s.timer = null;
-				s.lastFlush = Date.now();
-				flushDirty(topic, s.dirty);
-				s.dirty.clear();
-			}, topicThrottleMs - (now - state.lastFlush));
-		}
+		dirtyTopics.add(topic);
+		armTick(Math.max(0, topicThrottleMs - (now - state.lastFlush)));
 	}
 
 	/** @type {CursorTracker} */
@@ -460,15 +547,42 @@ export function createCursor(options = {}) {
 					if (entry.timer) clearTimeout(entry.timer);
 				}
 			}
-			for (const [, state] of topicFlush) {
-				if (state.timer) clearTimeout(state.timer);
-			}
+			if (tickTimer !== null) { clearTimeout(tickTimer); tickTimer = null; }
+			dirtyTopics.clear();
 			topics.clear();
 			topicFlush.clear();
 			wsState.clear();
 			connCounter = 0;
 		},
 
+		/**
+		 * Snapshot of scheduler health. Always available, near-zero cost.
+		 *
+		 * - `flushes`: total tick-driven flushes since tracker creation.
+		 * - `driftMeanMs`: mean (target_deadline - actual_fire_time) across
+		 *   all tick-driven flushes. 0 means perfect cadence; values >
+		 *   `topicThrottle` indicate sustained event-loop saturation or
+		 *   CPU contention.
+		 * - `driftMaxMs`: largest single observed late fire. Useful for
+		 *   spotting one-off GC pauses vs. sustained drift.
+		 * - `dirtyTopicsCurrent`: topics with pending coalesced entries
+		 *   right now. Should hover near zero in healthy operation.
+		 * - `activeTopicsTotal`: topics with at least one local cursor.
+		 *
+		 * Leading-edge synchronous flushes (first call on an idle topic)
+		 * are not counted in drift stats - they fire on the call thread,
+		 * not via the scheduler.
+		 */
+		stats() {
+			return {
+				flushes: flushCount,
+				driftMeanMs: driftCount > 0 ? driftSum / driftCount : 0,
+				driftMaxMs: driftMax,
+				dirtyTopicsCurrent: dirtyTopics.size,
+				activeTopicsTotal: topics.size
+			};
+		},
+
 		hooks: {
 			message(ws, { data, platform }) {
 				let parsed;

package/plugins/presence/client.d.ts

@@ -6,10 +6,19 @@ import type { Readable } from 'svelte/store';
  * Returns a readable Svelte store containing an array of user data objects.
  * 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
+ * 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
+ * admin / audit views that want unbounded retention.
+ *
  * You must also subscribe to the topic itself (via `on()`, `crud()`, etc.)
  * for the server's `subscribe` hook to fire and register your presence.
  *
  * @param topic - Topic to track presence on
+ * @param options - `maxAge` defaults to 90000 (ms). Pass `0` to disable
+ *   the sweep.
  *
  * @example
  * ```svelte

package/plugins/presence/client.js

@@ -5,10 +5,17 @@
  * a live list of who's connected. The server handles join/leave tracking;
  * this module just keeps the client-side state in sync.
  *
- * When `maxAge` is set, entries that haven't been refreshed (via `list`
- * or `join` events) within that window are automatically removed. This
- * makes clients self-healing when the server fails to broadcast a `leave`
- * event (e.g. mass disconnects overwhelming Redis cleanup).
+ * 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
+ * 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
+ * next heartbeat - no flicker for live users, and ghost entries from
+ * silent server-side TTL expiry (cluster mass-disconnect, ungraceful
+ * client close) clear within one sweep window.
+ *
+ * Apps that want unbounded retention ("show every user who ever touched
+ * this topic" - admin / audit views) opt out with `maxAge: 0`.
  *
  * @module svelte-adapter-uws/plugins/presence/client
  */
@@ -62,14 +69,19 @@ const presenceStores = new Map();
  * @example
  * ```svelte
  * <script>
- *   // Self-healing: entries expire after 90s without a refresh
- *   const users = presence('room', { maxAge: 90_000 });
+ *   // Opt out of the default 90 s sweep for an admin / audit view.
+ *   const users = presence('room', { maxAge: 0 });
  * </script>
  * ```
  */
 export function presence(topic, options) {
-	const maxAge = options?.maxAge;
-	const cacheKey = maxAge > 0 ? topic + '\0' + maxAge : topic;
+	// Default 90 s sweep matches the extensions Redis presence's default
+	// `ttl: 90` (server-side per-field TTL) and gives the in-memory
+	// server's 30 s default heartbeat a 3x safety margin. Apps that want
+	// "show every user who ever touched this topic" (admin/audit views)
+	// opt out with `maxAge: 0`.
+	const maxAge = options?.maxAge ?? 90000;
+	const cacheKey = topic + '\0' + maxAge;
 
 	const cached = presenceStores.get(cacheKey);
 	if (cached) return cached;

package/plugins/presence/server.d.ts

@@ -47,19 +47,31 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	/**
 	 * Interval in milliseconds between heartbeat broadcasts.
 	 *
-	 * When set, the server periodically publishes a `heartbeat` event to all
-	 * presence topics containing the list of active user keys. This resets
-	 * the `maxAge` timer on clients, preventing live users from being expired.
+	 * 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 (transient
+	 * network blip, JS thread saturation).
 	 *
-	 * Set this to a value shorter than the client's `maxAge`.
+	 * Set this to a value shorter than the client's `maxAge`. The 30 s
+	 * default fits the 90 s default client `maxAge` with a 3x safety
+	 * margin. Pass `0` to disable heartbeats entirely (apps that do not
+	 * use the `maxAge` self-healing path).
 	 *
-	 * @default 0 (disabled)
+	 * @default 30000
 	 *
 	 * @example
 	 * ```js
-	 * // Server heartbeat every 60s, client maxAge 120s
+	 * // Slower heartbeat (less wire traffic, larger window for ghost entries)
 	 * const presence = createPresence({ heartbeat: 60_000 });
 	 * ```
+	 *
+	 * @example
+	 * ```js
+	 * // Disable heartbeats; client must rely on presence_diff alone
+	 * const presence = createPresence({ heartbeat: 0 });
+	 * ```
 	 */
 	heartbeat?: number;
 

package/plugins/presence/server.js

@@ -52,11 +52,14 @@ const TOPIC_PREFIX = '__presence:';
  *
  *   Should return JSON-serializable data (plain objects, arrays, strings, numbers,
  *   booleans, null) since the result is sent over WebSocket.
- * @property {number} [heartbeat=0] - Interval in milliseconds between heartbeat broadcasts.
- *   When set, the server periodically publishes a `heartbeat` event to all presence topics
- *   containing the list of active keys. This resets the `maxAge` timer on clients, preventing
- *   live users from being expired. Set this to a value shorter than the client's `maxAge`.
- *   Disabled by default (0 or omitted).
+ * @property {number} [heartbeat=30000] - Interval in milliseconds between heartbeat broadcasts.
+ *   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
+ *   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).
  */
 
 /**
@@ -252,7 +255,15 @@ function defaultPresenceSelect(obj, ancestors) {
 export function createPresence(options = {}) {
 	const keyField = options.key || 'id';
 	const select = options.select || defaultPresenceSelect;
-	const heartbeatMs = options.heartbeat || 0;
+	// Default 30 s heartbeat keeps the client's `maxAge` sweep self-healing:
+	// a still-present user re-appears on the next heartbeat after their
+	// entry ages out of the local map. Apps that want zero heartbeat
+	// traffic (no `maxAge` consumers, or out-of-band liveness) pass
+	// `heartbeat: 0` explicitly to opt out.
+	const heartbeatMs = options.heartbeat ?? 30000;
+	if (typeof heartbeatMs !== 'number' || !Number.isFinite(heartbeatMs) || heartbeatMs < 0) {
+		throw new Error('presence: heartbeat must be a non-negative number');
+	}
 	const maxConnections = options.maxConnections ?? 1_000_000;
 	const maxTopics = options.maxTopics ?? 1_000_000;
 
@@ -373,11 +384,16 @@ export function createPresence(options = {}) {
 		if (heartbeatMs > 0) {
 			heartbeatTimer = setInterval(() => {
 				for (const [topic, users] of topicPresence) {
-					_platform.publish(
-						TOPIC_PREFIX + topic,
-						'heartbeat',
-						[...users.keys()]
-					);
+					// 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
+					// variant in svelte-adapter-uws-extensions.
+					/** @type {Record<string, any>} */
+					const dataMap = {};
+					for (const [userKey, entry] of users) dataMap[userKey] = entry.data;
+					_platform.publish(TOPIC_PREFIX + topic, 'heartbeat', dataMap);
 				}
 			}, heartbeatMs);
 		}