svelte-realtime 0.4.19 → 0.4.21

package/README.md

@@ -147,8 +147,6 @@ export const messages = live.stream('messages', async (ctx) => {
 
 {#if $messages === undefined}
   <p>Loading...</p>
-{:else if $messages?.error}
-  <p>Failed to load: {$messages.error.message}</p>
 {:else}
   {#each $messages as msg (msg.id)}
     <p><b>{msg.userId}:</b> {msg.text}</p>
@@ -378,21 +376,19 @@ When the WebSocket reconnects, streams automatically refetch initial data and re
 
 ## Error handling
 
-Stream stores have three states:
+The data store value never changes shape. It is always your data type or `undefined` while loading. Errors and connection status live on separate reactive stores so a network failure can never crash your UI:
 
-| Value | Meaning |
-|---|---|
-| `undefined` | Loading (initial fetch in progress) |
-| `Array` / `any` | Data loaded and receiving live updates |
-| `{ error: RpcError }` | Initial fetch failed |
+| Property | Type | Description |
+|---|---|---|
+| `$store` | `T \| undefined` | Your data. Never replaced by an error object. On failure, the last loaded value is preserved. |
+| `store.error` | `Readable<RpcError \| null>` | Current error, or `null` when healthy. |
+| `store.status` | `Readable<'loading' \| 'connected' \| 'reconnecting' \| 'error'>` | Connection status. |
 
-Handle all three in your template:
+Handle loading in your template:
 
 ```svelte
 {#if $messages === undefined}
   <p>Loading...</p>
-{:else if $messages?.error}
-  <p>Failed: {$messages.error.message}</p>
 {:else}
   {#each $messages as msg (msg.id)}
     <p>{msg.text}</p>
@@ -400,6 +396,27 @@ Handle all three in your template:
 {/if}
 ```
 
+To show errors, subscribe to the `.error` store:
+
+```svelte
+<script>
+  import { messages } from '$live/chat';
+
+  const err = messages.error;
+  const status = messages.status;
+</script>
+
+{#if $err}
+  <p>Error: {$err.message} ({$err.code})</p>
+{/if}
+
+{#if $status === 'reconnecting'}
+  <p>Reconnecting...</p>
+{/if}
+```
+
+Defensive patterns like `($store ?? []).filter(...)` work correctly because `$store` is always an array or `undefined`.
+
 For RPC calls, errors are thrown as `RpcError` with a `code` field:
 
 ```js
@@ -421,22 +438,23 @@ try {
 When the adapter's `ready()` promise rejects (terminal close codes 1008, 4401, 4403, exhausted retries, or explicit `close()`), svelte-realtime:
 
 - Rejects all pending RPCs immediately with `RpcError('CONNECTION_CLOSED', ...)`
-- Sets an `{ error }` state on all active stream stores
+- Sets `.error` on all active stream stores (the data value is preserved)
 - Drains the offline queue with errors
 
 RPCs called after a terminal close reject immediately without sending.
 
 ### Reusable error boundary component
 
-For Svelte 5, you can build a reusable boundary that handles all three stream states:
+For Svelte 5, you can build a reusable boundary that handles loading and error states:
 
 ```svelte
 <!-- src/lib/StreamView.svelte -->
 <script>
-  /** @type {{ store: import('svelte/store').Readable, children: import('svelte').Snippet, loading?: import('svelte').Snippet, error?: import('svelte').Snippet<[any]> }} */
+  /** @type {{ store: any, children: import('svelte').Snippet, loading?: import('svelte').Snippet, error?: import('svelte').Snippet<[any]> }} */
   let { store, children, loading, error } = $props();
 
   let value = $derived($store);
+  const err = store.error;
 </script>
 
 {#if value === undefined}
@@ -445,11 +463,11 @@ For Svelte 5, you can build a reusable boundary that handles all three stream st
   {:else}
     <p>Loading...</p>
   {/if}
-{:else if value?.error}
+{:else if $err}
   {#if error}
-    {@render error(value.error)}
+    {@render error($err)}
   {:else}
-    <p>Error: {value.error.message}</p>
+    <p>Error: {$err.message}</p>
   {/if}
 {:else}
   {@render children()}
@@ -492,7 +510,7 @@ With default slots, the minimal version is just:
 </StreamView>
 ```
 
-This removes the `{#if}/{:else if}/{:else}` boilerplate from every page that uses a stream.
+This removes the `{#if}/{:else}` boilerplate from every page that uses a stream.
 
 ---
 
@@ -673,6 +691,32 @@ export async function load({ platform, locals }) {
 
 The hydrated store still subscribes for live updates on first render. It keeps the SSR data visible instead of showing `undefined` during the initial fetch. Guards still run during `.load()` calls. Pass `{ user }` as the second argument if your guard or init function needs user data.
 
+For dynamic streams (streams with a topic function), call the stream first to get the store, then hydrate:
+
+```js
+// src/routes/team/[id]/+page.server.js
+export async function load({ platform, locals, params }) {
+  const { invitations } = await import('$live/invitation');
+  const data = await invitations.load(platform, { args: [params.id], user: locals.user });
+  return { invitations: data };
+}
+```
+
+```svelte
+<!-- src/routes/team/[id]/+page.svelte -->
+<script>
+  import { invitations } from '$live/invitation';
+  import { page } from '$app/state';
+  let { data } = $props();
+
+  const invites = invitations(page.params.id).hydrate(data.invitations);
+</script>
+
+{#each $invites as invite (invite.id)}
+  <p>{invite.email}</p>
+{/each}
+```
+
 ---
 
 ## Batching
@@ -1281,6 +1325,10 @@ export function open(ws, { platform }) {
 }
 ```
 
+Without this call, derived streams will still serve their initial SSR data but will never receive live updates. In dev mode, a console warning is emitted when a client subscribes to a derived stream and `_activateDerived` has not been called.
+
+Dynamic derived compute functions receive `ctx.user` from the subscribing client, so auth checks like `if (orgId !== ctx.user.organization_id) throw new LiveError("FORBIDDEN")` work the same as they do in regular stream handlers.
+
 | Option | Default | Description |
 |---|---|---|
 | `merge` | `'set'` | Merge strategy for the derived topic |
@@ -2009,6 +2057,8 @@ Import from `svelte-realtime/client`.
 
 | Method/Property | Description |
 |---|---|
+| `error` | `Readable<RpcError \| null>` -- current error, or `null` when healthy |
+| `status` | `Readable<'loading' \| 'connected' \| 'reconnecting' \| 'error'>` -- connection status |
 | `optimistic(event, data)` | Apply instant UI update, returns rollback function |
 | `hydrate(initialData)` | Pre-populate with SSR data |
 | `loadMore(...extraArgs)` | Load next page (cursor-based) |

package/client.d.ts

@@ -45,7 +45,9 @@ export function __rpc(path: string): ((...args: any[]) => Promise<any>) & {
  * - `undefined` while loading
  * - The initial data once loaded
  * - Automatically updated with live pub/sub events
- * - `{ error: RpcError }` if the initial fetch fails
+ *
+ * Errors never replace the store value. On failure, the last known data
+ * is preserved and the error is available via the `.error` store.
  *
  * @param path - Stream path (e.g. `'chat/messages'`)
  * @param options - Merge strategy and options
@@ -57,6 +59,10 @@ export function __rpc(path: string): ((...args: any[]) => Promise<any>) & {
  * SSR hydration, and cursor-based pagination.
  */
 export interface StreamStore<T = any> extends Readable<T> {
+	/** Reactive store holding the current error, or null when healthy. Errors never replace the data store value. */
+	readonly error: Readable<RpcError | null>;
+	/** Reactive store holding the connection status: 'loading', 'connected', 'reconnecting', or 'error'. */
+	readonly status: Readable<'loading' | 'connected' | 'reconnecting' | 'error'>;
 	/** Apply an instant UI update. Returns a rollback function. */
 	optimistic(event: string, data: any): () => void;
 	/** Pre-populate with SSR data to avoid loading spinners. */

package/client.js

@@ -508,6 +508,28 @@ function _createStream(path, options, dynamicArgs) {
 	let currentValue;
 	const store = writable(undefined);
 
+	/** @type {RpcError | null} */
+	let _error = null;
+	const _errorStore = writable(null);
+
+	/** @type {'loading' | 'connected' | 'reconnecting' | 'error'} */
+	let _status = 'loading';
+	const _statusStore = writable(/** @type {'loading' | 'connected' | 'reconnecting' | 'error'} */ ('loading'));
+
+	function _setError(/** @type {RpcError} */ err) {
+		_error = err;
+		_errorStore.set(err);
+		_status = 'error';
+		_statusStore.set('error');
+	}
+
+	function _clearError() {
+		if (_error !== null) {
+			_error = null;
+			_errorStore.set(null);
+		}
+	}
+
 	/** @type {string | null} */
 	let topic = null;
 
@@ -841,7 +863,7 @@ function _createStream(path, options, dynamicArgs) {
 	function fetchAndSubscribe() {
 		if (fetching) return;
 		if (_terminated) {
-			store.set({ error: new RpcError('CONNECTION_CLOSED', 'Connection permanently closed') });
+			_setError(new RpcError('CONNECTION_CLOSED', 'Connection permanently closed'));
 			return;
 		}
 		fetching = true;
@@ -871,13 +893,13 @@ function _createStream(path, options, dynamicArgs) {
 				pending.delete(id);
 				pendingId = null;
 				fetching = false;
-				store.set({ error: new RpcError('DISCONNECTED', 'Connection interrupted (device sleep)') });
+				_setError(new RpcError('DISCONNECTED', 'Connection interrupted (device sleep)'));
 				return;
 			}
 			pending.delete(id);
 			pendingId = null;
 			fetching = false;
-			store.set({ error: new RpcError('TIMEOUT', `Stream '${path}' timed out after 30s`) });
+			_setError(new RpcError('TIMEOUT', `Stream '${path}' timed out after 30s`));
 		}, _getTimeout());
 
 		pending.set(id, {
@@ -886,6 +908,9 @@ function _createStream(path, options, dynamicArgs) {
 				fetching = false;
 				pendingId = null;
 				_reconnectAttempts = 0;
+				_clearError();
+				_status = 'connected';
+				_statusStore.set('connected');
 				topic = response.topic || null;
 
 				// Track sequence number for replay
@@ -985,7 +1010,7 @@ function _createStream(path, options, dynamicArgs) {
 			reject(err) {
 				fetching = false;
 				pendingId = null;
-				store.set({ error: err instanceof RpcError ? err : new RpcError('STREAM_ERROR', err?.message || 'Stream failed') });
+				_setError(err instanceof RpcError ? err : new RpcError('STREAM_ERROR', err?.message || 'Stream failed'));
 			},
 			timer
 		});
@@ -1035,6 +1060,10 @@ function _createStream(path, options, dynamicArgs) {
 		buffer = [];
 		currentValue = undefined;
 		store.set(undefined);
+		_error = null;
+		_errorStore.set(null);
+		_status = 'loading';
+		_statusStore.set('loading');
 		_index.clear();
 		_history = [];
 		_historyIndex = -1;
@@ -1046,6 +1075,8 @@ function _createStream(path, options, dynamicArgs) {
 	let _pendingCleanup = false;
 
 	return {
+		error: { subscribe: _errorStore.subscribe },
+		status: { subscribe: _statusStore.subscribe },
 		subscribe(fn) {
 			if (subCount++ === 0) {
 				if (_pendingCleanup) {
@@ -1064,6 +1095,8 @@ function _createStream(path, options, dynamicArgs) {
 						return;
 					}
 					if (s === 'open' && subCount > 0) {
+						_status = 'reconnecting';
+						_statusStore.set('reconnecting');
 						if (_reconnectTimer) clearTimeout(_reconnectTimer);
 						let delay;
 						if (_reconnectAttempts < 2) {
@@ -1093,7 +1126,7 @@ function _createStream(path, options, dynamicArgs) {
 					if (conn && typeof conn.ready === 'function') {
 						conn.ready().catch((/** @type {any} */ err) => {
 							if (subCount > 0) {
-								store.set({ error: new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed') });
+								_setError(new RpcError(err?.code || 'CONNECTION_CLOSED', err?.message || 'Connection permanently closed'));
 							}
 						});
 					}

package/package.json

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

package/server.js

@@ -778,7 +778,7 @@ live.derived = function derived(sources, fn, options) {
 		/** @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');
+			const t = baseTopic + '~' + args.map(a => String(a).replace(/~/g, '')).join('~');
 			topicArgs.set(t, args);
 			if (topicArgs.size > 10000) {
 				const iter = topicArgs.keys();
@@ -791,7 +791,7 @@ live.derived = function derived(sources, fn, options) {
 		/** @type {any} */ (fn).__derivedTopicArgs = topicArgs;
 
 		/** @type {any} */ (fn).__onSubscribe = function (_ctx, resolvedTopic) {
-			_activateDynamicDerived(fn, resolvedTopic);
+			_activateDynamicDerived(fn, resolvedTopic, _ctx && _ctx.user);
 		};
 		/** @type {any} */ (fn).__onUnsubscribe = function (_ctx, resolvedTopic) {
 			_deactivateDynamicDerived(fn, resolvedTopic);
@@ -815,6 +815,12 @@ const _dynamicDerivedByFn = new Map();
 /** @type {import('svelte-adapter-uws').Platform | null} Captured platform for dynamic derived recomputation */
 let _derivedPlatform = null;
 
+/** @type {boolean} Whether _activateDerived has been called at least once */
+let _activateDerivedCalled = false;
+
+/** @type {boolean} Whether the missing _activateDerived warning has already fired */
+let _warnedActivateDerived = false;
+
 /** @type {Map<string, { sources: string[], fn: Function, debounce: number, timer: ReturnType<typeof setTimeout> | null }>} */
 const effectRegistry = new Map();
 
@@ -1387,6 +1393,7 @@ live.breaker = function breaker(options, fn) {
 export function __registerDerived(path, fn) {
 	if (/** @type {any} */ (fn).__lazy) {
 		_lazyQueue.push({ type: 'derived', path, loader: fn });
+		_hasDynamicDerived = true;
 		return;
 	}
 
@@ -1397,7 +1404,7 @@ export function __registerDerived(path, fn) {
 		/** @type {Map<string, any[]>} */
 		const topicArgs = new Map();
 		const topicFn = (...args) => {
-			const t = path + '\x00' + args.map(a => String(a).replace(/\x00/g, '')).join('\x00');
+			const t = path + '~' + args.map(a => String(a).replace(/~/g, '')).join('~');
 			topicArgs.set(t, args);
 			if (topicArgs.size > 10000) {
 				const iter = topicArgs.keys();
@@ -1443,6 +1450,7 @@ const _activatedPlatforms = new WeakSet();
 
 export function _activateDerived(platform) {
 	_derivedPlatform = platform;
+	_activateDerivedCalled = true;
 	if (_activatedPlatforms.has(platform)) return;
 
 	// Only wrap platform.publish if there are actual reactive registrations
@@ -1543,7 +1551,7 @@ async function _recomputeDerived(entry, platform) {
 		let result;
 		if (entry.args) {
 			const _h = _getCtxHelpers(platform);
-			const ctx = _buildCtx(null, null, platform, _h, null);
+			const ctx = _buildCtx(entry.user || null, null, platform, _h, null);
 			result = await entry.fn(ctx, ...entry.args);
 		} else {
 			result = await entry.fn();
@@ -1563,8 +1571,9 @@ async function _recomputeDerived(entry, platform) {
  * 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')
+ * @param {any} [user] - The subscribing client's user data, used for ctx during recomputation
  */
-function _activateDynamicDerived(fn, resolvedTopic) {
+function _activateDynamicDerived(fn, resolvedTopic, user) {
 	const entry = _dynamicDerivedByFn.get(fn);
 	if (!entry) return;
 
@@ -1600,7 +1609,8 @@ function _activateDynamicDerived(fn, resolvedTopic) {
 		resolvedSources,
 		debounce: entry.debounce,
 		timer: null,
-		refCount: 1
+		refCount: 1,
+		user: user || null
 	};
 
 	entry.instances.set(resolvedTopic, instance);
@@ -1852,6 +1862,8 @@ export function _prepareHmr() {
 	_streamsWithUnsubscribe.clear();
 	_hasDynamicDerived = false;
 	_dynamicDerivedByFn.clear();
+	_activateDerivedCalled = false;
+	_warnedActivateDerived = false;
 
 	return snap;
 }
@@ -2334,6 +2346,13 @@ async function _executeSingleRpc(ws, msg, platform, options) {
 				try { await /** @type {any} */ (fn).__onSubscribe(ctx, topic); } catch {}
 			}
 
+			if (/** @type {any} */ (fn).__isDerived && !_activateDerivedCalled && !_warnedActivateDerived) {
+				if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
+					_warnedActivateDerived = true;
+					console.warn('[svelte-realtime] live.derived() subscribed but _activateDerived(platform) was never called. Derived streams will not receive live updates.\n  Call _activateDerived(platform) in your WebSocket open hook.\n  See: https://svti.me/derived');
+				}
+			}
+
 			// Channel fast-path
 			if (/** @type {any} */ (fn).__isChannel) {
 				const emptyValue = streamOpts.merge === 'set' ? null : [];