svelte-realtime 0.4.15 → 0.4.16

package/README.md

@@ -1222,6 +1222,40 @@ On the client, derived streams work like regular streams:
 <p>Orders: {$dashboardStats?.totalOrders}</p>
 ```
 
+### Dynamic derived streams
+
+When source topics depend on runtime arguments (e.g., an org ID, a room ID), pass a source factory function instead of a static array. The factory receives the same args the client passes at subscribe time:
+
+```js
+export const orgStats = live.derived(
+  (orgId) => [`memberships:${orgId}`, `emails:${orgId}`, `audit:${orgId}`],
+  async (ctx, orgId) => {
+    const [members, emails, auditCount] = await Promise.all([
+      db.query('SELECT count(*) FROM memberships WHERE org_id = $1', [orgId]),
+      db.query('SELECT count(*) FROM emails WHERE org_id = $1', [orgId]),
+      db.query('SELECT count(*) FROM audit_log WHERE org_id = $1', [orgId])
+    ]);
+    return { members, emails, auditCount };
+  },
+  { debounce: 100 }
+);
+```
+
+On the client, dynamic derived streams are called like functions:
+
+```svelte
+<script>
+  import { orgStats } from '$live/dashboard';
+  let { orgId } = $props();
+</script>
+
+<p>Members: {$orgStats(orgId)?.members}</p>
+```
+
+Each unique set of args creates an independent instance with its own source subscriptions. Instances are created when the first subscriber connects and cleaned up when the last subscriber disconnects.
+
+### Activation
+
 Call `_activateDerived(platform)` in your `open` hook to enable derived stream listeners:
 
 ```js
@@ -1916,7 +1950,7 @@ Import from `svelte-realtime/server`.
 | `live.binary(fn, options?)` | Mark a function as a binary RPC handler (`maxSize` limits payload, default 10MB) |
 | `live.validated(schema, fn)` | RPC with Zod/Valibot input validation |
 | `live.cron(schedule, topic, fn)` | Server-side scheduled function |
-| `live.derived(sources, fn, options?)` | Server-side computed stream |
+| `live.derived(sources, fn, options?)` | Server-side computed stream (static or dynamic sources) |
 | `live.effect(sources, fn, options?)` | Server-side reactive side effect |
 | `live.aggregate(source, reducers, options)` | Real-time incremental aggregation |
 | `live.room(config)` | Collaborative room (data + presence + cursors + actions) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/server.d.ts

@@ -477,17 +477,35 @@ export namespace live {
 	/**
 	 * Create a server-side computed stream that recomputes when any source topic publishes.
 	 *
-	 * @param sources - Topic names to watch for changes
+	 * Static form: pass an array of topic names to watch.
+	 * Dynamic form: pass a function that receives runtime args and returns topic names.
+	 *
+	 * @param sources - Topic names to watch, or a factory function that receives runtime args
 	 * @param fn - Async function that computes the derived value
 	 * @param options - Merge mode and debounce settings
 	 *
 	 * @example
 	 * ```js
+	 * // Static sources
 	 * export const summary = live.derived(['orders', 'inventory'], async () => {
 	 *   return { totalOrders: await db.orders.count(), totalItems: await db.inventory.count() };
 	 * });
+	 *
+	 * // Dynamic sources (parameterized)
+	 * export const stats = live.derived(
+	 *   (orgId) => [`memberships:${orgId}`, `emails:${orgId}`],
+	 *   async (ctx, orgId) => {
+	 *     return { members: await countMembers(orgId), emails: await countEmails(orgId) };
+	 *   },
+	 *   { debounce: 100 }
+	 * );
 	 * ```
 	 */
+	function derived<T extends (...args: any[]) => any>(
+		sources: (...args: any[]) => string[],
+		fn: T,
+		options?: { merge?: string; debounce?: number }
+	): T;
 	function derived<T extends () => any>(
 		sources: string[],
 		fn: T,

package/server.js

@@ -108,6 +108,14 @@ function _copyStreamMeta(target, source) {
 	if (source.__streamVersion !== undefined) target.__streamVersion = source.__streamVersion;
 	if (source.__streamMigrate) target.__streamMigrate = source.__streamMigrate;
 	if (source.__isChannel) target.__isChannel = source.__isChannel;
+	if (source.__isDerived) target.__isDerived = source.__isDerived;
+	if (source.__derivedDynamic) {
+		target.__derivedDynamic = source.__derivedDynamic;
+		target.__derivedSourceFactory = source.__derivedSourceFactory;
+		target.__derivedTopicArgs = source.__derivedTopicArgs;
+		target.__derivedDebounce = source.__derivedDebounce;
+	}
+	if (source.__derivedSources) target.__derivedSources = source.__derivedSources;
 	if (source.__isGated) {
 		target.__isGated = true;
 		target.__gatePredicate = source.__gatePredicate;
@@ -720,28 +728,69 @@ const derivedRegistry = new Map();
 /**
  * Create a server-side computed stream that recomputes when any source topic publishes.
  *
- * @param {string[]} sources - Topic names to watch
+ * Static form: sources is a string[] of topic names.
+ * Dynamic form: sources is a function (...args) => string[] that resolves topics at subscribe time.
+ *
+ * @param {string[] | Function} sources - Topic names to watch, or a factory that receives runtime args
  * @param {Function} fn - Async function that computes the derived value
  * @param {{ merge?: string, debounce?: number }} [options]
  * @returns {Function}
  */
 live.derived = function derived(sources, fn, options) {
-	const topic = /** @type {any} */ (fn).__derivedTopic || ('__derived:' + (_derivedIdCounter++));
+	const baseTopic = /** @type {any} */ (fn).__derivedTopic || ('__derived:' + (_derivedIdCounter++));
 	const merge = options?.merge || 'set';
 	const debounce = options?.debounce || 0;
+	const dynamic = typeof sources === 'function';
 
 	/** @type {any} */ (fn).__isDerived = true;
 	/** @type {any} */ (fn).__isStream = true;
 	/** @type {any} */ (fn).__isLive = true;
-	/** @type {any} */ (fn).__streamTopic = topic;
 	/** @type {any} */ (fn).__streamOptions = { merge, key: 'id' };
-	/** @type {any} */ (fn).__derivedSources = sources;
 	/** @type {any} */ (fn).__derivedDebounce = debounce;
+
+	if (dynamic) {
+		/** @type {any} */ (fn).__derivedDynamic = true;
+		/** @type {any} */ (fn).__derivedSourceFactory = sources;
+		/** @type {Map<string, any[]>} */
+		const topicArgs = new Map();
+		const topicFn = (...args) => {
+			const t = baseTopic + '\x00' + args.map(a => String(a).replace(/\x00/g, '')).join('\x00');
+			topicArgs.set(t, args);
+			if (topicArgs.size > 10000) {
+				const iter = topicArgs.keys();
+				topicArgs.delete(iter.next().value);
+			}
+			return t;
+		};
+		/** @type {any} */ (topicFn).__topicUsesCtx = false;
+		/** @type {any} */ (fn).__streamTopic = topicFn;
+		/** @type {any} */ (fn).__derivedTopicArgs = topicArgs;
+
+		/** @type {any} */ (fn).__onSubscribe = function (_ctx, resolvedTopic) {
+			_activateDynamicDerived(fn, resolvedTopic);
+		};
+		/** @type {any} */ (fn).__onUnsubscribe = function (_ctx, resolvedTopic) {
+			_deactivateDynamicDerived(fn, resolvedTopic);
+		};
+	} else {
+		/** @type {any} */ (fn).__streamTopic = baseTopic;
+		/** @type {any} */ (fn).__derivedSources = sources;
+	}
+
 	return fn;
 };
 
 let _derivedIdCounter = 0;
 
+/** @type {boolean} Whether any dynamic derived streams have been registered */
+let _hasDynamicDerived = false;
+
+/** @type {Map<Function, object>} O(1) lookup from fn reference to dynamic derived registry entry */
+const _dynamicDerivedByFn = new Map();
+
+/** @type {import('svelte-adapter-uws').Platform | null} Captured platform for dynamic derived recomputation */
+let _derivedPlatform = null;
+
 /** @type {Map<string, { sources: string[], fn: Function, debounce: number, timer: ReturnType<typeof setTimeout> | null }>} */
 const effectRegistry = new Map();
 
@@ -1316,6 +1365,20 @@ export function __registerDerived(path, fn) {
 		_lazyQueue.push({ type: 'derived', path, loader: fn });
 		return;
 	}
+
+	if (/** @type {any} */ (fn).__derivedDynamic) {
+		const sourceFactory = /** @type {any} */ (fn).__derivedSourceFactory;
+		const debounce = /** @type {any} */ (fn).__derivedDebounce || 0;
+		const entry = {
+			sources: null, sourceFactory, fn, topic: /** @type {any} */ (fn).__streamTopic,
+			debounce, timer: null, dynamic: true, instances: new Map()
+		};
+		derivedRegistry.set(path, entry);
+		_dynamicDerivedByFn.set(fn, entry);
+		_hasDynamicDerived = true;
+		return;
+	}
+
 	const sources = /** @type {any} */ (fn).__derivedSources;
 	const topic = /** @type {any} */ (fn).__streamTopic;
 	const debounce = /** @type {any} */ (fn).__derivedDebounce || 0;
@@ -1339,14 +1402,19 @@ export function __registerDerived(path, fn) {
 const _activatedPlatforms = new WeakSet();
 
 export function _activateDerived(platform) {
+	_derivedPlatform = platform;
 	if (_activatedPlatforms.has(platform)) return;
 
 	// Only wrap platform.publish if there are actual reactive registrations
-	if (_derivedBySource.size === 0 && _effectBySource.size === 0 && _aggregateBySource.size === 0) {
+	if (_derivedBySource.size === 0 && _effectBySource.size === 0 && _aggregateBySource.size === 0 && !_hasDynamicDerived) {
 		return;
 	}
 
 	_activatedPlatforms.add(platform);
+	_wrapPlatformPublish(platform);
+}
+
+function _wrapPlatformPublish(platform) {
 
 	const originalPublish = platform.publish.bind(platform);
 
@@ -1426,20 +1494,121 @@ export function _activateDerived(platform) {
 
 /**
  * Recompute a derived stream and publish the result.
- * @param {{ fn: Function, topic: string }} entry
+ * For dynamic instances, entry.args holds the runtime args and a ctx is built from the platform.
+ * @param {{ fn: Function, topic: string, args?: any[] }} entry
  * @param {import('svelte-adapter-uws').Platform} platform
  */
 async function _recomputeDerived(entry, platform) {
 	try {
-		const result = await entry.fn();
+		let result;
+		if (entry.args) {
+			const _h = _getCtxHelpers(platform);
+			const ctx = _buildCtx(null, null, platform, _h, null);
+			result = await entry.fn(ctx, ...entry.args);
+		} else {
+			result = await entry.fn();
+		}
 		platform.publish(entry.topic, 'set', result);
 	} catch (err) {
-		if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
+		if (_serverErrorHandler) {
+			try { _serverErrorHandler('derived', err); } catch {}
+		} else if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
 			console.error(`[svelte-realtime] Derived stream '${entry.topic}' error:`, err);
 		}
 	}
 }
 
+/**
+ * Activate a dynamic derived instance for a resolved topic.
+ * Wires the instance's resolved sources into _derivedBySource so publishes trigger recomputation.
+ * @param {Function} fn - The derived compute function
+ * @param {string} resolvedTopic - The resolved output topic (e.g. '__derived:5:org_123')
+ */
+function _activateDynamicDerived(fn, resolvedTopic) {
+	const entry = _dynamicDerivedByFn.get(fn);
+	if (!entry) return;
+
+	const existing = entry.instances.get(resolvedTopic);
+	if (existing) {
+		existing.refCount++;
+		return;
+	}
+
+	// Late activation: if _activateDerived returned early before dynamic entries existed,
+	// wrap platform.publish now that we have something to watch.
+	if (_derivedPlatform && !_activatedPlatforms.has(_derivedPlatform)) {
+		_activatedPlatforms.add(_derivedPlatform);
+		_wrapPlatformPublish(_derivedPlatform);
+	}
+
+	const topicArgs = /** @type {any} */ (fn).__derivedTopicArgs;
+	const args = topicArgs && topicArgs.get(resolvedTopic);
+	if (!args) return;
+
+	const resolvedSources = entry.sourceFactory(...args);
+	if (!Array.isArray(resolvedSources) || resolvedSources.length === 0) {
+		if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
+			console.warn(`[svelte-realtime] Dynamic derived sourceFactory returned empty sources for topic '${resolvedTopic}'`);
+		}
+		return;
+	}
+
+	const instance = {
+		fn: entry.fn,
+		args,
+		topic: resolvedTopic,
+		resolvedSources,
+		debounce: entry.debounce,
+		timer: null,
+		refCount: 1
+	};
+
+	entry.instances.set(resolvedTopic, instance);
+
+	for (const src of resolvedSources) {
+		let set = _derivedBySource.get(src);
+		if (!set) { set = new Set(); _derivedBySource.set(src, set); }
+		set.add(instance);
+		_watchedTopics.add(src);
+	}
+}
+
+/**
+ * Deactivate a dynamic derived instance when the last subscriber disconnects.
+ * Removes the instance from _derivedBySource and cleans up.
+ * @param {Function} fn - The derived compute function
+ * @param {string} resolvedTopic - The resolved output topic
+ */
+function _deactivateDynamicDerived(fn, resolvedTopic) {
+	const entry = _dynamicDerivedByFn.get(fn);
+	if (!entry) return;
+
+	const instance = entry.instances.get(resolvedTopic);
+	if (!instance) return;
+
+	instance.refCount--;
+	if (instance.refCount > 0) return;
+
+	if (instance.timer) clearTimeout(instance.timer);
+
+	for (const src of instance.resolvedSources) {
+		const set = _derivedBySource.get(src);
+		if (set) {
+			set.delete(instance);
+			if (set.size === 0) {
+				_derivedBySource.delete(src);
+				if (!_effectBySource.has(src) && !_aggregateBySource.has(src)) {
+					_watchedTopics.delete(src);
+				}
+			}
+		}
+	}
+
+	entry.instances.delete(resolvedTopic);
+	const topicArgs = /** @type {any} */ (fn).__derivedTopicArgs;
+	if (topicArgs) topicArgs.delete(resolvedTopic);
+}
+
 /**
  * Fire an effect handler. Errors are caught and routed to the error handler.
  * @param {{ fn: Function }} entry
@@ -1606,7 +1775,12 @@ export function _prepareHmr() {
 	};
 
 	// Clear debounce timers
-	for (const e of derivedRegistry.values()) { if (e.timer) clearTimeout(e.timer); }
+	for (const e of derivedRegistry.values()) {
+		if (e.timer) clearTimeout(e.timer);
+		if (e.instances) {
+			for (const inst of e.instances.values()) { if (inst.timer) clearTimeout(inst.timer); }
+		}
+	}
 	for (const e of effectRegistry.values()) { if (e.timer) clearTimeout(e.timer); }
 	for (const e of aggregateRegistry.values()) { if (e.timer) clearTimeout(e.timer); }
 
@@ -1636,6 +1810,8 @@ export function _prepareHmr() {
 	_aggregateByTopic.clear();
 	_watchedTopics.clear();
 	_streamsWithUnsubscribe.clear();
+	_hasDynamicDerived = false;
+	_dynamicDerivedByFn.clear();
 
 	return snap;
 }
@@ -1662,11 +1838,27 @@ export function _restoreHmr(snap) {
 	for (const [k, v] of snap.derived) {
 		v.timer = null;
 		derivedRegistry.set(k, v);
-		for (const src of v.sources) {
-			let set = _derivedBySource.get(src);
-			if (!set) { set = new Set(); _derivedBySource.set(src, set); }
-			set.add(v);
-			_watchedTopics.add(src);
+		if (v.dynamic) {
+			_hasDynamicDerived = true;
+			_dynamicDerivedByFn.set(v.fn, v);
+			if (v.instances) {
+				for (const inst of v.instances.values()) {
+					inst.timer = null;
+					for (const src of inst.resolvedSources) {
+						let set = _derivedBySource.get(src);
+						if (!set) { set = new Set(); _derivedBySource.set(src, set); }
+						set.add(inst);
+						_watchedTopics.add(src);
+					}
+				}
+			}
+		} else {
+			for (const src of v.sources) {
+				let set = _derivedBySource.get(src);
+				if (!set) { set = new Set(); _derivedBySource.set(src, set); }
+				set.add(v);
+				_watchedTopics.add(src);
+			}
 		}
 	}
 

package/vite.js

@@ -12,6 +12,7 @@ const DYNAMIC_STREAM_RE = /export\s+const\s+(\w+)\s*=\s*live\.stream\s*\(\s*(?:\
 const CRON_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.cron\s*\(/g;
 const BINARY_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.binary\s*\(/g;
 const DERIVED_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.derived\s*\(/g;
+const DYNAMIC_DERIVED_RE = /export\s+const\s+(\w+)\s*=\s*live\.derived\s*\(\s*(?:\([^)]*\)|[a-zA-Z_$][\w$]*)\s*=>/g;
 const ROOM_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.room\s*\(/g;
 const WEBHOOK_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.webhook\s*\(/g;
 const CHANNEL_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.channel\s*\(/g;
@@ -518,8 +519,8 @@ function _generateSsrStubs(filePath, modulePath) {
 	const dynamicNames = new Set();
 	let match;
 
-	// Detect dynamic (function-returning) streams and channels
-	for (const re of [DYNAMIC_STREAM_RE, DYNAMIC_CHANNEL_RE]) {
+	// Detect dynamic (function-returning) streams, channels, and derived
+	for (const re of [DYNAMIC_STREAM_RE, DYNAMIC_CHANNEL_RE, DYNAMIC_DERIVED_RE]) {
 		re.lastIndex = 0;
 		while ((match = re.exec(source)) !== null) {
 			dynamicNames.add(match[1]);
@@ -683,8 +684,12 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		if (!exportedNames.has(name)) {
 			exportedNames.add(name);
 			imports.add('__stream');
-			// Derived streams use 'set' merge by default
-			lines.push(`export const ${name} = __stream('${modulePath}/${name}', ${JSON.stringify({ merge: 'set', key: 'id' })});`);
+			const isDynamic = _isDynamicExport(source, name, 'live\\.derived');
+			if (isDynamic) {
+				lines.push(`export const ${name} = __stream('${modulePath}/${name}', ${JSON.stringify({ merge: 'set', key: 'id' })}, true);`);
+			} else {
+				lines.push(`export const ${name} = __stream('${modulePath}/${name}', ${JSON.stringify({ merge: 'set', key: 'id' })});`);
+			}
 		}
 	}
 
@@ -1645,14 +1650,25 @@ function _generateTypeDeclarations(liveDir, dir) {
 			}
 		}
 
-		// Detect live.derived() exports (read-only stream)
+		// Detect live.derived() exports (read-only stream, static or dynamic)
 		DERIVED_EXPORT_RE.lastIndex = 0;
 		while ((match = DERIVED_EXPORT_RE.exec(source)) !== null) {
 			const name = match[1];
 			handledNames.add(name);
 			if (!exports.some(e => e.includes(`export const ${name}:`))) {
 				needsStreamStore = true;
-				exports.push(`  export const ${name}: StreamStore<any> & { load(platform: any, options?: { args?: any[]; user?: any }): Promise<any> };`);
+				const isDynamic = _isDynamicExport(source, name, 'live\\.derived');
+				const loadSig = `{ load(platform: any, options?: { args?: any[]; user?: any }): Promise<any> }`;
+				if (isDynamic) {
+					if (isTS) {
+						const factoryParams = _extractDynamicFactoryParams(source, name, 'live\\.derived');
+						exports.push(`  export const ${name}: (${factoryParams} => StreamStore<any>) & ${loadSig};`);
+					} else {
+						exports.push(`  export const ${name}: ((...args: any[]) => StreamStore<any>) & ${loadSig};`);
+					}
+				} else {
+					exports.push(`  export const ${name}: StreamStore<any> & ${loadSig};`);
+				}
 			}
 		}