svelte-adapter-uws 0.3.2 → 0.3.3

package/README.md

@@ -1488,7 +1488,8 @@ import { createPresence } from 'svelte-adapter-uws/plugins/presence';
 
 export const presence = createPresence({
   key: 'id',
-  select: (userData) => ({ id: userData.id, name: userData.name })
+  select: (userData) => ({ id: userData.id, name: userData.name }),
+  heartbeat: 60_000  // optional: needed if clients use maxAge
 });
 ```
 
@@ -1556,7 +1557,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)
+  select: (userData) => userData,  // extract public fields (default: full userData)
+  heartbeat: 60_000      // broadcast active keys every 60s (default: disabled)
 });
 
 presence.hooks                       // ready-made { subscribe, close } hooks
@@ -1565,7 +1567,7 @@ presence.leave(ws, platform)         // remove from all topics (call from close
 presence.sync(ws, topic, platform)   // send list without joining (for observers)
 presence.list(topic)                 // current user data array
 presence.count(topic)                // unique user count
-presence.clear()                     // reset everything
+presence.clear()                     // reset everything (stops heartbeat timer)
 ```
 
 #### Client API
@@ -1577,13 +1579,20 @@ 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 (via `list` or `join` events) within that window are automatically removed from the store. This makes clients self-healing when the server fails to broadcast `leave` events under load:
+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 `leave` events under load.
+
+**Important:** `maxAge` requires the server-side `heartbeat` option. Without heartbeat, no events arrive between the initial `list` 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.
 
 ```js
-// Entries expire after 90s without a server refresh
-const users = presence('room', { maxAge: 90_000 });
+// 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 });
 ```
 
+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.3.2",
+  "version": "0.3.3",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/plugins/presence/client.js

@@ -138,6 +138,19 @@ export function presence(topic, options) {
 				if (userMap.delete(key)) {
 					flush();
 				}
+				return;
+			}
+
+			if (event.event === 'heartbeat' && Array.isArray(event.data)) {
+				// Server confirms these keys are still active -- refresh their
+				// timestamps so maxAge doesn't expire them. Keys not in the
+				// heartbeat are left alone (maxAge will handle them).
+				const now = Date.now();
+				for (const key of event.data) {
+					if (timestamps.has(key)) {
+						timestamps.set(key, now);
+					}
+				}
 			}
 		});
 

package/plugins/presence/server.d.ts

@@ -27,6 +27,25 @@ export interface PresenceOptions<UserData = unknown, Selected extends Record<str
 	 * ```
 	 */
 	select?: (userData: UserData) => Selected;
+
+	/**
+	 * 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.
+	 *
+	 * Set this to a value shorter than the client's `maxAge`.
+	 *
+	 * @default 0 (disabled)
+	 *
+	 * @example
+	 * ```js
+	 * // Server heartbeat every 60s, client maxAge 120s
+	 * const presence = createPresence({ heartbeat: 60_000 });
+	 * ```
+	 */
+	heartbeat?: number;
 }
 
 export interface PresenceTracker<Selected extends Record<string, any> = Record<string, any>> {

package/plugins/presence/server.js

@@ -20,6 +20,11 @@
  *   presence data from the connection's userData (whatever your `upgrade` handler returned).
  *   Only the selected fields are broadcast to other clients. Defaults to the full userData.
  *   Use this to avoid leaking private fields like session tokens.
+ * @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).
  */
 
 /**
@@ -96,10 +101,21 @@
 export function createPresence(options = {}) {
 	const keyField = options.key || 'id';
 	const select = options.select || ((userData) => userData);
+	const heartbeatMs = options.heartbeat || 0;
 
 	// Auto-generated ID counter for connections without a key field
 	let connCounter = 0;
 
+	/**
+	 * Platform reference, captured on first use of join/leave/sync.
+	 * Needed by the heartbeat timer to publish without a hook context.
+	 * @type {import('../../index.js').Platform | null}
+	 */
+	let _platform = null;
+
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let heartbeatTimer = null;
+
 	/**
 	 * Per-connection state: which topics they've joined and their key on each.
 	 * @type {Map<any, Map<string, { key: string, data: Record<string, any> }>>}
@@ -126,9 +142,33 @@ export function createPresence(options = {}) {
 		return '__conn:' + (++connCounter);
 	}
 
+	/**
+	 * Capture the platform reference and start the heartbeat if configured.
+	 * Called lazily on first join/leave/sync -- the platform object isn't
+	 * available at createPresence() time.
+	 * @param {import('../../index.js').Platform} platform
+	 */
+	function capturePlatform(platform) {
+		if (_platform) return;
+		_platform = platform;
+		if (heartbeatMs > 0) {
+			heartbeatTimer = setInterval(() => {
+				for (const [topic, users] of topicPresence) {
+					_platform.publish(
+						'__presence:' + topic,
+						'heartbeat',
+						[...users.keys()]
+					);
+				}
+			}, heartbeatMs);
+		}
+	}
+
 	/** @type {PresenceTracker} */
 	const tracker = {
 		join(ws, topic, platform) {
+			capturePlatform(platform);
+
 			// Skip internal topics to prevent recursion when the subscribe
 			// hook fires for __presence:* subscriptions
 			if (topic.startsWith('__')) return;
@@ -181,6 +221,7 @@ export function createPresence(options = {}) {
 		},
 
 		leave(ws, platform) {
+			capturePlatform(platform);
 			const connTopics = wsTopics.get(ws);
 			if (!connTopics) return;
 
@@ -207,6 +248,7 @@ export function createPresence(options = {}) {
 		},
 
 		sync(ws, topic, platform) {
+			capturePlatform(platform);
 			const users = topicPresence.get(topic);
 			const presenceTopic = '__presence:' + topic;
 			const list = [];
@@ -235,6 +277,11 @@ export function createPresence(options = {}) {
 		},
 
 		clear() {
+			if (heartbeatTimer) {
+				clearInterval(heartbeatTimer);
+				heartbeatTimer = null;
+			}
+			_platform = null;
 			wsTopics.clear();
 			topicPresence.clear();
 			connCounter = 0;