svelte-adapter-uws 0.3.1 → 0.3.2

package/README.md

@@ -60,6 +60,7 @@ I've been loving Svelte and SvelteKit for a long time. I always wanted to expand
 
 **Help**
 - [Troubleshooting](#troubleshooting)
+- [Related projects](#related-projects)
 - [License](#license)
 
 ---
@@ -998,6 +999,7 @@ One-liner for real-time collections. Handles `created`, `updated`, and `deleted`
 Options:
 - `key` - property to match items by (default: `'id'`)
 - `prepend` - add new items to the beginning instead of end (default: `false`)
+- `maxAge` - auto-remove entries that haven't been created/updated within this many milliseconds (see [maxAge](#maxage---client-side-entry-expiry) below)
 
 ```js
 // Notifications, newest first
@@ -1044,6 +1046,29 @@ Like `crud()` but returns a `Record<string, T>` instead of an array. Better for
 {/if}
 ```
 
+Options:
+- `key` - property to match items by (default: `'id'`)
+- `maxAge` - auto-remove entries that haven't been created/updated within this many milliseconds (see [maxAge](#maxage---client-side-entry-expiry) below)
+
+### `maxAge` - client-side entry expiry
+
+Both `crud()` and `lookup()` accept a `maxAge` option (in milliseconds). When set, entries that haven't received a `created` or `updated` event within that window are automatically removed from the store. Explicit `deleted` events still remove entries immediately.
+
+This is useful for state backed by an external store with TTL (e.g. Redis). If the server fails to broadcast a removal event (mass disconnects, crashes, Redis TTL expiry without keyspace notifications), clients clean up on their own:
+
+```js
+// Presence entries expire after 90s without a refresh
+const users = lookup('__presence:board', data.users, { key: 'key', maxAge: 90_000 });
+
+// Sensor readings expire after 30s without an update
+const sensors = lookup('sensors', [], { key: 'id', maxAge: 30_000 });
+
+// Same option works on crud()
+const items = crud('items', data.items, { maxAge: 60_000 });
+```
+
+The sweep runs at `maxAge / 2` intervals (minimum 1 second). The timer is cleaned up automatically when the last subscriber unsubscribes.
+
 ### `latest(topic, max?, initial?)` - ring buffer
 
 Keeps the last N events. Perfect for chat, activity feeds, notifications:
@@ -1552,6 +1577,13 @@ 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:
+
+```js
+// Entries expire after 90s without a server refresh
+const users = presence('room', { maxAge: 90_000 });
+```
+
 #### 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.
@@ -1847,6 +1879,12 @@ export function close(ws, { platform }) {
 
 The client store is a `Readable<Map<string, { user, data }>>`. The Map updates when cursors move or disconnect.
 
+The `cursor()` function accepts an optional second argument with a `maxAge` option (in milliseconds). When set, cursor entries that haven't received an update within that window are automatically removed. This makes clients self-healing when the server fails to broadcast `remove` events under load:
+
+```js
+const positions = cursor('canvas', { maxAge: 30_000 });
+```
+
 #### Server API
 
 | Method | Description |
@@ -2520,6 +2558,11 @@ Or if you're using `on()` directly (which auto-connects), call `connect()` first
 
 ---
 
+## Related projects
+
+- [svelte-adapter-uws-extensions](https://github.com/lanteanio/svelte-adapter-uws-extensions) -- Redis-backed extensions for multi-server deployments: persistent presence, distributed pub/sub, session storage, and more.
+- [svelte-realtime](https://github.com/lanteanio/svelte-realtime) -- Opinionated full-stack starter built on this adapter. Auth, database, real-time CRUD, and deployment config out of the box.
+
 ## License
 
 [MIT](LICENSE)

package/client.d.ts

@@ -179,7 +179,7 @@ export const status: Readable<'connecting' | 'open' | 'closed'>;
 export function crud<T extends Record<string, any>>(
 	topic: string,
 	initial?: T[],
-	options?: { key?: keyof T & string; prepend?: boolean }
+	options?: { key?: keyof T & string; prepend?: boolean; maxAge?: number }
 ): Readable<T[]>;
 
 /**
@@ -207,7 +207,7 @@ export function crud<T extends Record<string, any>>(
 export function lookup<T extends Record<string, any>>(
 	topic: string,
 	initial?: T[],
-	options?: { key?: keyof T & string }
+	options?: { key?: keyof T & string; maxAge?: number }
 ): Readable<Record<string, T>>;
 
 /**

package/client.js

@@ -104,49 +104,225 @@ export function ready() {
  * Live CRUD list - one line for real-time collections.
  * Auto-connects, auto-subscribes, and auto-handles created/updated/deleted events.
  *
+ * When `maxAge` is set, entries that haven't been created or updated
+ * within that window are automatically removed from the list.
+ *
  * @template T
  * @param {string} topic - Topic to subscribe to
  * @param {T[]} [initial] - Starting data (e.g. from a load function)
- * @param {{ key?: string, prepend?: boolean }} [options] - Options
+ * @param {{ key?: string, prepend?: boolean, maxAge?: number }} [options] - Options
  * @returns {import('svelte/store').Readable<T[]>}
  */
 export function crud(topic, initial = [], options = {}) {
 	const key = options.key || 'id';
 	const prepend = options.prepend || false;
-	return on(topic).scan(/** @type {any[]} */ (initial), (list, { event, data }) => {
-		if (event === 'created') return prepend ? [data, ...list] : [...list, data];
-		if (event === 'updated') return list.map((item) => item[key] === data[key] ? data : item);
-		if (event === 'deleted') return list.filter((item) => item[key] !== data[key]);
-		return list;
-	});
+	const maxAge = options.maxAge;
+
+	if (maxAge == null || maxAge <= 0) {
+		return on(topic).scan(/** @type {any[]} */ (initial), (list, { event, data }) => {
+			if (event === 'created') return prepend ? [data, ...list] : [...list, data];
+			if (event === 'updated') return list.map((item) => item[key] === data[key] ? data : item);
+			if (event === 'deleted') return list.filter((item) => item[key] !== data[key]);
+			return list;
+		});
+	}
+
+	// maxAge mode: track timestamps per key, sweep on interval
+	const conn = ensureConnection();
+	const source = conn.on(topic);
+
+	/** @type {any[]} */
+	let list = [...initial];
+	/** @type {Map<string, number>} */
+	const timestamps = new Map();
+	const now = Date.now();
+	for (const item of initial) {
+		timestamps.set(String(item[key]), now);
+	}
+
+	const output = writable(list);
+	/** @type {(() => void) | null} */
+	let sourceUnsub = null;
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let sweepTimer = null;
+	let subCount = 0;
+
+	function sweep() {
+		const cutoff = Date.now() - /** @type {number} */ (maxAge);
+		let changed = false;
+		for (const [id, ts] of timestamps) {
+			if (ts < cutoff) {
+				timestamps.delete(id);
+				const before = list.length;
+				list = list.filter((item) => String(item[key]) !== id);
+				if (list.length !== before) changed = true;
+			}
+		}
+		if (changed) output.set(list);
+	}
+
+	function start() {
+		sourceUnsub = source.subscribe((event) => {
+			if (event === null) return;
+			const { event: evt, data } = event;
+			const id = String(data[key]);
+			if (evt === 'created') {
+				timestamps.set(id, Date.now());
+				list = prepend ? [data, ...list] : [...list, data];
+				output.set(list);
+			} else if (evt === 'updated') {
+				timestamps.set(id, Date.now());
+				list = list.map((item) => String(item[key]) === id ? data : item);
+				output.set(list);
+			} else if (evt === 'deleted') {
+				timestamps.delete(id);
+				list = list.filter((item) => String(item[key]) !== id);
+				output.set(list);
+			}
+		});
+		sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
+	}
+
+	function stop() {
+		if (sourceUnsub) { sourceUnsub(); sourceUnsub = null; }
+		if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+		list = [...initial];
+		const now = Date.now();
+		timestamps.clear();
+		for (const item of initial) {
+			timestamps.set(String(item[key]), now);
+		}
+		output.set(list);
+	}
+
+	return {
+		subscribe(fn) {
+			if (subCount++ === 0) start();
+			const unsub = output.subscribe(fn);
+			return () => {
+				unsub();
+				if (--subCount === 0) stop();
+			};
+		}
+	};
 }
 
 /**
  * Live keyed object - like `crud()` but returns a `Record` keyed by ID.
  * Better for dashboards and fast lookups.
  *
+ * When `maxAge` is set, entries that haven't been created or updated
+ * within that window are automatically removed. Useful for presence,
+ * cursors, or any state backed by an external store with TTL expiry.
+ *
  * @template T
  * @param {string} topic - Topic to subscribe to
  * @param {T[]} [initial] - Starting data (e.g. from a load function)
- * @param {{ key?: string }} [options] - Options
+ * @param {{ key?: string, maxAge?: number }} [options] - Options
  * @returns {import('svelte/store').Readable<Record<string, T>>}
  */
 export function lookup(topic, initial = [], options = {}) {
 	const key = options.key || 'id';
+	const maxAge = options.maxAge;
 	/** @type {Record<string, any>} */
 	const initialMap = {};
 	for (const item of initial) {
 		initialMap[/** @type {any} */ (item)[key]] = item;
 	}
-	return on(topic).scan(initialMap, (map, { event, data }) => {
-		const id = data[key];
-		if (event === 'created' || event === 'updated') return { ...map, [id]: data };
-		if (event === 'deleted') {
-			const { [id]: _, ...rest } = map;
-			return rest;
+
+	if (maxAge == null || maxAge <= 0) {
+		return on(topic).scan(initialMap, (map, { event, data }) => {
+			const id = data[key];
+			if (event === 'created' || event === 'updated') return { ...map, [id]: data };
+			if (event === 'deleted') {
+				const { [id]: _, ...rest } = map;
+				return rest;
+			}
+			return map;
+		});
+	}
+
+	// maxAge mode: track timestamps per key, sweep on interval
+	const conn = ensureConnection();
+	const source = conn.on(topic);
+
+	/** @type {Record<string, any>} */
+	let map = { ...initialMap };
+	/** @type {Map<string, number>} */
+	const timestamps = new Map();
+	const now = Date.now();
+	for (const id in initialMap) {
+		timestamps.set(id, now);
+	}
+
+	const output = writable(map);
+	/** @type {(() => void) | null} */
+	let sourceUnsub = null;
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let sweepTimer = null;
+	let subCount = 0;
+
+	function sweep() {
+		const cutoff = Date.now() - /** @type {number} */ (maxAge);
+		let changed = false;
+		for (const [id, ts] of timestamps) {
+			if (ts < cutoff) {
+				timestamps.delete(id);
+				if (id in map) {
+					const { [id]: _, ...rest } = map;
+					map = rest;
+					changed = true;
+				}
+			}
 		}
-		return map;
-	});
+		if (changed) output.set(map);
+	}
+
+	function start() {
+		sourceUnsub = source.subscribe((event) => {
+			if (event === null) return;
+			const { event: evt, data } = event;
+			const id = data[key];
+			if (evt === 'created' || evt === 'updated') {
+				timestamps.set(id, Date.now());
+				map = { ...map, [id]: data };
+				output.set(map);
+			} else if (evt === 'deleted') {
+				timestamps.delete(id);
+				if (id in map) {
+					const { [id]: _, ...rest } = map;
+					map = rest;
+					output.set(map);
+				}
+			}
+		});
+		// Sweep at half the maxAge interval for responsive cleanup
+		// without burning cycles on very short intervals
+		sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
+	}
+
+	function stop() {
+		if (sourceUnsub) { sourceUnsub(); sourceUnsub = null; }
+		if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+		map = { ...initialMap };
+		const now = Date.now();
+		timestamps.clear();
+		for (const id in initialMap) {
+			timestamps.set(id, now);
+		}
+		output.set(map);
+	}
+
+	return {
+		subscribe(fn) {
+			if (subCount++ === 0) start();
+			const unsub = output.subscribe(fn);
+			return () => {
+				unsub();
+				if (--subCount === 0) stop();
+			};
+		}
+	};
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/plugins/cursor/client.d.ts

@@ -29,5 +29,6 @@ export interface CursorPosition<UserInfo = unknown, Data = unknown> {
  * ```
  */
 export function cursor<UserInfo = unknown, Data = unknown>(
-	topic: string
+	topic: string,
+	options?: { maxAge?: number }
 ): Readable<Map<string, CursorPosition<UserInfo, Data>>>;

package/plugins/cursor/client.js

@@ -5,6 +5,11 @@
  * a live Map of cursor positions. The server handles throttling and
  * cleanup; this module keeps the client-side state in sync.
  *
+ * When `maxAge` is set, cursor entries that haven't received an update
+ * within that window are automatically removed. This makes clients
+ * self-healing when the server fails to broadcast a `remove` event
+ * (e.g. mass disconnects overwhelming Redis cleanup).
+ *
  * @module svelte-adapter-uws/plugins/cursor/client
  */
 
@@ -20,6 +25,7 @@ import { writable } from 'svelte/store';
  *
  * @template UserInfo, Data
  * @param {string} topic - Topic to track cursors on
+ * @param {{ maxAge?: number }} [options] - Options
  * @returns {import('svelte/store').Readable<Map<string, { user: UserInfo, data: Data }>>}
  *
  * @example
@@ -36,36 +42,68 @@ import { writable } from 'svelte/store';
  *   </div>
  * {/each}
  * ```
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   // Self-healing: cursors expire after 30s without movement
+ *   const cursors = cursor('canvas', { maxAge: 30_000 });
+ * </script>
+ * ```
  */
-export function cursor(topic) {
+export function cursor(topic, options) {
+	const maxAge = options?.maxAge;
 	const cursorTopic = '__cursor:' + topic;
-	const source = on(cursorTopic);
 
 	/** @type {Map<string, { user: any, data: any }>} */
 	let cursorMap = new Map();
+	/** @type {Map<string, number>} */
+	const timestamps = new Map();
 	const output = writable(/** @type {Map<string, any>} */ (new Map()));
 
 	let sourceUnsub = /** @type {(() => void) | null} */ (null);
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let sweepTimer = null;
 	let refCount = 0;
 
+	function sweep() {
+		if (!maxAge || maxAge <= 0) return;
+		const cutoff = Date.now() - maxAge;
+		let changed = false;
+		for (const [key, ts] of timestamps) {
+			if (ts < cutoff) {
+				timestamps.delete(key);
+				if (cursorMap.delete(key)) changed = true;
+			}
+		}
+		if (changed) output.set(new Map(cursorMap));
+	}
+
 	function startListening() {
+		const source = on(cursorTopic);
 		sourceUnsub = source.subscribe((event) => {
 			if (event === null) return;
 
 			if (event.event === 'update' && event.data != null) {
 				const { key, user, data } = event.data;
 				cursorMap.set(key, { user, data });
+				timestamps.set(key, Date.now());
 				output.set(new Map(cursorMap));
 				return;
 			}
 
 			if (event.event === 'remove' && event.data != null) {
 				const { key } = event.data;
+				timestamps.delete(key);
 				if (cursorMap.delete(key)) {
 					output.set(new Map(cursorMap));
 				}
 			}
 		});
+
+		if (maxAge > 0) {
+			sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
+		}
 	}
 
 	function stopListening() {
@@ -73,7 +111,12 @@ export function cursor(topic) {
 			sourceUnsub();
 			sourceUnsub = null;
 		}
+		if (sweepTimer) {
+			clearInterval(sweepTimer);
+			sweepTimer = null;
+		}
 		cursorMap = new Map();
+		timestamps.clear();
 	}
 
 	return {

package/plugins/presence/client.d.ts

@@ -30,5 +30,6 @@ import type { Readable } from 'svelte/store';
  * ```
  */
 export function presence<T extends Record<string, any> = Record<string, any>>(
-	topic: string
+	topic: string,
+	options?: { maxAge?: number }
 ): Readable<T[]>;

package/plugins/presence/client.js

@@ -5,6 +5,11 @@
  * 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).
+ *
  * @module svelte-adapter-uws/plugins/presence/client
  */
 
@@ -20,8 +25,9 @@ const presenceStores = new Map();
  * Returns a readable Svelte store containing an array of user data objects.
  * The array updates automatically when users join or leave.
  *
- * Memoized by topic: calling `presence('room')` multiple times (e.g. from
- * `$derived`) returns the same store instance, preventing flickering.
+ * Memoized by topic + maxAge: calling `presence('room', { maxAge: 90000 })`
+ * multiple times (e.g. from `$derived`) returns the same store instance,
+ * preventing flickering.
  *
  * You must also subscribe to the topic itself (via `on()`, `crud()`, etc.)
  * for the server's `subscribe` hook to fire and register your presence.
@@ -30,6 +36,7 @@ const presenceStores = new Map();
  *
  * @template T
  * @param {string} topic - Topic to track presence on
+ * @param {{ maxAge?: number }} [options] - Options
  * @returns {import('svelte/store').Readable<T[]>}
  *
  * @example
@@ -49,20 +56,52 @@ const presenceStores = new Map();
  *   {/each}
  * </aside>
  * ```
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   // Self-healing: entries expire after 90s without a refresh
+ *   const users = presence('room', { maxAge: 90_000 });
+ * </script>
+ * ```
  */
-export function presence(topic) {
-	const cached = presenceStores.get(topic);
+export function presence(topic, options) {
+	const maxAge = options?.maxAge;
+	const cacheKey = maxAge > 0 ? topic + '\0' + maxAge : topic;
+
+	const cached = presenceStores.get(cacheKey);
 	if (cached) return cached;
 
 	const presenceTopic = '__presence:' + topic;
 
 	/** @type {Map<string, any>} */
 	let userMap = new Map();
+	/** @type {Map<string, number>} */
+	const timestamps = new Map();
 	const output = writable(/** @type {any[]} */ ([]));
 
 	let sourceUnsub = /** @type {(() => void) | null} */ (null);
+	/** @type {ReturnType<typeof setInterval> | null} */
+	let sweepTimer = null;
 	let refCount = 0;
 
+	function flush() {
+		output.set([...userMap.values()]);
+	}
+
+	function sweep() {
+		if (!maxAge || maxAge <= 0) return;
+		const cutoff = Date.now() - maxAge;
+		let changed = false;
+		for (const [key, ts] of timestamps) {
+			if (ts < cutoff) {
+				timestamps.delete(key);
+				if (userMap.delete(key)) changed = true;
+			}
+		}
+		if (changed) flush();
+	}
+
 	function startListening() {
 		// Fresh on() call each time -- the underlying writable in client.js
 		// is cleaned up on full unsubscribe, so a stale reference would
@@ -73,29 +112,38 @@ export function presence(topic) {
 
 			if (event.event === 'list' && Array.isArray(event.data)) {
 				userMap = new Map();
+				timestamps.clear();
+				const now = Date.now();
 				for (const entry of event.data) {
 					userMap.set(entry.key, entry.data);
+					timestamps.set(entry.key, now);
 				}
-				output.set([...userMap.values()]);
+				flush();
 				return;
 			}
 
 			if (event.event === 'join' && event.data != null) {
 				const { key, data } = event.data;
+				timestamps.set(key, Date.now());
 				if (!userMap.has(key)) {
 					userMap.set(key, data);
-					output.set([...userMap.values()]);
+					flush();
 				}
 				return;
 			}
 
 			if (event.event === 'leave' && event.data != null) {
 				const { key } = event.data;
+				timestamps.delete(key);
 				if (userMap.delete(key)) {
-					output.set([...userMap.values()]);
+					flush();
 				}
 			}
 		});
+
+		if (maxAge > 0) {
+			sweepTimer = setInterval(sweep, Math.max(maxAge / 2, 1000));
+		}
 	}
 
 	function stopListening() {
@@ -103,7 +151,12 @@ export function presence(topic) {
 			sourceUnsub();
 			sourceUnsub = null;
 		}
+		if (sweepTimer) {
+			clearInterval(sweepTimer);
+			sweepTimer = null;
+		}
 		userMap = new Map();
+		timestamps.clear();
 		output.set([]);
 	}
 
@@ -118,6 +171,6 @@ export function presence(topic) {
 		}
 	};
 
-	presenceStores.set(topic, store);
+	presenceStores.set(cacheKey, store);
 	return store;
 }