svelte-realtime 0.4.20 → 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
@@ -2013,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.20",
+  "version": "0.4.21",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",