svelte-realtime 0.4.5 → 0.4.7

package/README.md

@@ -1,6 +1,20 @@
-# svelte-realtime
+<p align="center">
+  <a href="https://svelte-realtime.dev">
+    <img src="https://svelte-realtime.dev/svelte_orange.png" alt="svelte-realtime" width="240" />
+  </a>
+</p>
 
-Realtime RPC and reactive subscriptions for SvelteKit, built on [svelte-adapter-uws](https://github.com/lanteanio/svelte-adapter-uws).
+<h1 align="center">svelte-realtime</h1>
+
+<p align="center">
+  Realtime RPC and reactive subscriptions for SvelteKit, built on <a href="https://github.com/lanteanio/svelte-adapter-uws">svelte-adapter-uws</a>.
+</p>
+
+<p align="center">
+  <a href="https://svelte-realtime.dev">Documentation</a> · <a href="https://svelte-realtime.dev/tutorial">Tutorial</a> · <a href="https://svelte-realtime-demo.lantean.io">Live Demo</a>
+</p>
+
+---
 
 Write server functions. Import them in components. Call them over WebSocket. No boilerplate, no manual pub/sub wiring, no protocol design.
 
@@ -1648,18 +1662,20 @@ export const message = createMessage({
 });
 ```
 
-### onCronError hook
+### Standalone onError
 
-For cron jobs, use the standalone `onCronError` function:
+For errors in cron jobs, effects, and derived streams, use the standalone `onError` function:
 
 ```js
-import { onCronError } from 'svelte-realtime/server';
+import { onError } from 'svelte-realtime/server';
 
-onCronError((path, error) => {
-  sentry.captureException(error, { tags: { cron: path } });
+onError((path, error) => {
+  sentry.captureException(error, { tags: { live: path } });
 });
 ```
 
+> `onCronError` still works but is deprecated -- use `onError` instead.
+
 ---
 
 ## Custom message handling
@@ -1814,7 +1830,8 @@ Import from `svelte-realtime/server`.
 | `close` | Ready-made close hook (fires onUnsubscribe for remaining topics) |
 | `unsubscribe` | Ready-made unsubscribe hook (fires onUnsubscribe in real time) |
 | `setCronPlatform(platform)` | Capture platform for cron jobs |
-| `onCronError(handler)` | Global cron error handler |
+| `onError(handler)` | Global error handler for cron, effects, and derived |
+| `onCronError(handler)` | Deprecated alias for `onError` |
 | `enableSignals(ws)` | Enable point-to-point signal delivery |
 | `_activateDerived(platform)` | Enable derived stream listeners |
 | `live.metrics(registry)` | Opt-in Prometheus metrics |

package/client.d.ts

@@ -1,4 +1,5 @@
 import type { Readable } from 'svelte/store';
+import type { WSEvent } from 'svelte-adapter-uws/client';
 
 /**
  * Typed error for RPC failures.
@@ -237,3 +238,23 @@ export const __devtools: {
 	streams: Map<string, { path: string; topic: string | null; subCount: number }>;
 	pending: Map<string, { path: string; args: any[]; startTime: number }>;
 } | null;
+
+/**
+ * Reactive derived topic subscription that auto-switches when a source store changes.
+ * Re-exported from `svelte-adapter-uws/client`.
+ *
+ * @param topicFn - Function that computes the topic from the store value
+ * @param store - Readable store whose value drives the topic
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { onDerived } from 'svelte-realtime/client';
+ *   const messages = onDerived((id) => `room:${id}`, roomId);
+ * </script>
+ * ```
+ */
+export function onDerived<T = unknown>(
+	topicFn: (value: T) => string,
+	store: Readable<T>
+): Readable<WSEvent | null>;

package/client.js

@@ -1503,7 +1503,7 @@ function _checkArgs(path, args) {
 		const t = typeof arg;
 		if (t === 'function' || t === 'symbol' || t === 'bigint' || t === 'undefined') {
 			console.warn(
-				`[svelte-realtime] RPC '${path}' called with non-JSON-serializable argument at index ${i} (${t}) -- this will be lost during transmission`
+				`[svelte-realtime] RPC '${path}' called with non-JSON-serializable argument at index ${i} (${t}) -- this will be lost during transmission\n  See: https://svti.me/rpc`
 			);
 		}
 	}
@@ -1644,10 +1644,10 @@ export function combine(...args) {
 	const sources = args;
 
 	if (typeof fn !== 'function') {
-		throw new Error('combine() requires a combining function as the last argument');
+		throw new Error('combine() requires a combining function as the last argument\n  See: https://svti.me/client');
 	}
 	if (sources.length < 2) {
-		throw new Error('combine() requires at least 2 source stores');
+		throw new Error('combine() requires at least 2 source stores\n  See: https://svti.me/client');
 	}
 
 	const values = new Array(sources.length);

package/package.json

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

package/server.d.ts

@@ -529,6 +529,43 @@ export namespace live {
 	 */
 	function webhook(topic: string, config: WebhookConfig): WebhookHandler;
 
+	/**
+	 * Opt-in Prometheus metrics integration.
+	 * Accepts a MetricsRegistry from `svelte-adapter-uws-extensions/prometheus`
+	 * and instruments RPC calls, stream subscriptions, and cron executions.
+	 *
+	 * Zero overhead if never called.
+	 *
+	 * @param registry - A MetricsRegistry instance with counter(), histogram(), gauge()
+	 *
+	 * @example
+	 * ```js
+	 * import { createRegistry } from 'svelte-adapter-uws-extensions/prometheus';
+	 * live.metrics(createRegistry());
+	 * ```
+	 */
+	function metrics(registry: any): void;
+
+	/**
+	 * Wrap a stream initFn call with a circuit breaker.
+	 * When the breaker is open, returns the fallback value or throws SERVICE_UNAVAILABLE.
+	 *
+	 * @param options - Circuit breaker instance and optional fallback
+	 * @param fn - The stream initFn to wrap
+	 *
+	 * @example
+	 * ```js
+	 * export const messages = live.breaker(
+	 *   { breaker: cb, fallback: [] },
+	 *   live.stream('messages', async (ctx) => db.messages.latest(50))
+	 * );
+	 * ```
+	 */
+	function breaker<T extends Function>(
+		options: { breaker: any; fallback?: any },
+		fn: T
+	): T;
+
 	/**
 	 * Declarative access control helpers for subscribe-time gating.
 	 * For per-event filtering, use `pipe.filter()`.
@@ -812,29 +849,23 @@ export function _clearCron(): void;
 export function _tickCron(): Promise<void>;
 
 /**
- * Set a global error handler for cron job failures.
- * Without this, cron errors are logged in dev and silently swallowed in production.
+ * Set a global error handler for server-side errors (cron, effects, derived).
+ * Without this, errors are logged in dev and silently swallowed in production.
  *
- * @param handler - Receives the cron path and the thrown error
+ * @param handler - Receives the path and the thrown error
  *
  * @example
  * ```js
- * onCronError((path, error) => {
- *   sentry.captureException(error, { tags: { cron: path } });
+ * onError((path, error) => {
+ *   sentry.captureException(error, { tags: { live: path } });
  * });
  * ```
  */
+export function onError(handler: (path: string, error: unknown) => void): void;
+
+/** @deprecated Use `onError()` instead. */
 export function onCronError(handler: (path: string, error: unknown) => void): void;
 
-/**
- * Handle a WebSocket close event. Fires `onUnsubscribe` lifecycle hooks
- * for stream functions that define them.
- *
- * Re-export from your `hooks.ws.js`:
- * ```js
- * export { close } from 'svelte-realtime/server';
- * ```
- */
 /**
  * Subscribe a WebSocket to its user's signal topic.
  * Call in your `open` hook to enable signal delivery.
@@ -847,6 +878,30 @@ export function onCronError(handler: (path: string, error: unknown) => void): vo
  */
 export function enableSignals(ws: WebSocket<any>, options?: { idField?: string }): void;
 
+/**
+ * Handle a real-time topic unsubscribe event. Fires onUnsubscribe lifecycle
+ * hooks for the stream function that owns the topic.
+ *
+ * Re-export from your `hooks.ws.js`:
+ * ```js
+ * export { unsubscribe } from 'svelte-realtime/server';
+ * ```
+ */
+export function unsubscribe(
+	ws: WebSocket<any>,
+	topic: string,
+	ctx: { platform: Platform }
+): void;
+
+/**
+ * Handle a WebSocket close event. Fires `onUnsubscribe` lifecycle hooks
+ * for stream functions that define them.
+ *
+ * Re-export from your `hooks.ws.js`:
+ * ```js
+ * export { close } from 'svelte-realtime/server';
+ * ```
+ */
 export function close(
 	ws: WebSocket<any>,
 	ctx: { platform: Platform }

package/server.js

@@ -354,11 +354,11 @@ export function live(fn) {
  */
 live.stream = function stream(topic, initFn, options) {
 	if (typeof topic === 'string' && topic.startsWith('__')) {
-		throw new Error(`[svelte-realtime] live.stream topic '${topic}' uses reserved prefix '__'`);
+		throw new Error(`[svelte-realtime] live.stream topic '${topic}' uses reserved prefix '__'\n  See: https://svti.me/streams`);
 	}
 	if (typeof topic === 'function') {
 		if (topic.constructor?.name === 'AsyncFunction') {
-			throw new Error(`[svelte-realtime] live.stream topic function must not be async -- topic resolution is synchronous`);
+			throw new Error(`[svelte-realtime] live.stream topic function must not be async -- topic resolution is synchronous\n  See: https://svti.me/streams`);
 		}
 		_tagTopicFn(topic);
 	}
@@ -391,11 +391,11 @@ live.stream = function stream(topic, initFn, options) {
  */
 live.channel = function channel(topic, options) {
 	if (typeof topic === 'string' && topic.startsWith('__')) {
-		throw new Error(`[svelte-realtime] live.channel topic '${topic}' uses reserved prefix '__'`);
+		throw new Error(`[svelte-realtime] live.channel topic '${topic}' uses reserved prefix '__'\n  See: https://svti.me/streams`);
 	}
 	if (typeof topic === 'function') {
 		if (topic.constructor?.name === 'AsyncFunction') {
-			throw new Error(`[svelte-realtime] live.channel topic function must not be async -- topic resolution is synchronous`);
+			throw new Error(`[svelte-realtime] live.channel topic function must not be async -- topic resolution is synchronous\n  See: https://svti.me/streams`);
 		}
 		_tagTopicFn(topic);
 	}
@@ -1082,13 +1082,13 @@ live.room = function room(config) {
 	let _roomArgCount = Math.max(0, topicFn.length - 1);
 	if (config.topicArgs !== undefined) {
 		if (!Number.isInteger(config.topicArgs) || config.topicArgs < 0) {
-			throw new Error(`[svelte-realtime] live.room() topicArgs must be a non-negative integer, got ${config.topicArgs}`);
+			throw new Error(`[svelte-realtime] live.room() topicArgs must be a non-negative integer, got ${config.topicArgs}\n  See: https://svti.me/rooms`);
 		}
 		_roomArgCount = config.topicArgs;
 	} else if (actions) {
 		throw new Error(
 			`[svelte-realtime] live.room() with actions requires 'topicArgs'. ` +
-			`Set topicArgs to the number of room-identifying args (excluding ctx).`
+			`Set topicArgs to the number of room-identifying args (excluding ctx).\n  See: https://svti.me/rooms`
 		);
 	}
 
@@ -1216,7 +1216,7 @@ live.room = function room(config) {
 		for (const [name, fn] of Object.entries(actions)) {
 			if (!_validSegmentRe.test(name)) {
 				if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn(`[svelte-realtime] Room action '${name}' contains invalid characters (only a-z, A-Z, 0-9, _ allowed) -- skipped`);
+					console.warn(`[svelte-realtime] Room action '${name}' contains invalid characters (only a-z, A-Z, 0-9, _ allowed) -- skipped\n  See: https://svti.me/rooms`);
 				}
 				continue;
 			}
@@ -1713,7 +1713,7 @@ export async function _tickCron() {
 			try {
 				if (!_cronPlatform) {
 					if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-						console.warn(`[svelte-realtime] Cron '${path}' fired but no platform captured. Call setCronPlatform(platform) in your open hook.`);
+						console.warn(`[svelte-realtime] Cron '${path}' fired but no platform captured. Call setCronPlatform(platform) in your open hook.\n  See: https://svti.me/cron`);
 					}
 					return;
 				}
@@ -1748,7 +1748,7 @@ export async function _tickCron() {
 function _parseCron(expr) {
 	const parts = expr.trim().split(/\s+/);
 	if (parts.length !== 5) {
-		throw new Error(`[svelte-realtime] Invalid cron expression '${expr}' -- expected 5 fields (minute hour day month weekday)`);
+		throw new Error(`[svelte-realtime] Invalid cron expression '${expr}' -- expected 5 fields (minute hour day month weekday)\n  See: https://svti.me/cron`);
 	}
 	return parts.map((field, idx) => _parseCronField(field, idx));
 }
@@ -1772,7 +1772,7 @@ function _parseCronField(field, idx) {
 	if (field.startsWith('*/')) {
 		const step = parseInt(field.slice(2), 10);
 		if (!Number.isFinite(step) || step < 1) {
-			throw new Error(`[svelte-realtime] Invalid cron step '${field}' -- step must be a positive integer`);
+			throw new Error(`[svelte-realtime] Invalid cron step '${field}' -- step must be a positive integer\n  See: https://svti.me/cron`);
 		}
 		return { step };
 	}
@@ -1782,7 +1782,7 @@ function _parseCronField(field, idx) {
 		const a = parseInt(parts[0], 10);
 		const b = parseInt(parts[1], 10);
 		if (!Number.isFinite(a) || !Number.isFinite(b) || a < min || b > max || a > b) {
-			throw new Error(`[svelte-realtime] Invalid cron range '${field}' -- values must be ${min}-${max}`);
+			throw new Error(`[svelte-realtime] Invalid cron range '${field}' -- values must be ${min}-${max}\n  See: https://svti.me/cron`);
 		}
 		const vals = new Set();
 		for (let i = a; i <= b; i++) vals.add(i);
@@ -1793,7 +1793,7 @@ function _parseCronField(field, idx) {
 		const nums = field.split(',').map(s => {
 			const n = parseInt(s, 10);
 			if (!Number.isFinite(n) || n < min || n > max) {
-				throw new Error(`[svelte-realtime] Invalid cron value '${s}' in '${field}' -- must be ${min}-${max}`);
+				throw new Error(`[svelte-realtime] Invalid cron value '${s}' in '${field}' -- must be ${min}-${max}\n  See: https://svti.me/cron`);
 			}
 			return n;
 		});
@@ -1802,7 +1802,7 @@ function _parseCronField(field, idx) {
 
 	const n = parseInt(field, 10);
 	if (!Number.isFinite(n) || n < min || n > max) {
-		throw new Error(`[svelte-realtime] Invalid cron value '${field}' -- must be ${min}-${max}`);
+		throw new Error(`[svelte-realtime] Invalid cron value '${field}' -- must be ${min}-${max}\n  See: https://svti.me/cron`);
 	}
 	return new Set([n]);
 }
@@ -1928,7 +1928,7 @@ export function handleRpc(ws, data, platform, options) {
 				}
 			} catch (err) {
 				if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn('[svelte-realtime] Failed to parse binary RPC header:', err);
+					console.warn('[svelte-realtime] Failed to parse binary RPC header:', err, '\n  See: https://svti.me/binary');
 				}
 			}
 		}
@@ -2050,7 +2050,7 @@ async function _executeSingleRpc(ws, msg, platform, options) {
 	const fn = await _resolveRegistryEntry(path);
 	if (!fn) {
 		if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-			console.warn(`[svelte-realtime] RPC call to '${path}' -- no such live function registered`);
+			console.warn(`[svelte-realtime] RPC call to '${path}' -- no such live function registered\n  See: https://svti.me/rpc`);
 		}
 		_recordRpcMetrics(path, 'NOT_FOUND', _metricsStart);
 		return { id, ok: false, code: 'NOT_FOUND', error: 'Not found' };
@@ -2188,7 +2188,7 @@ async function _executeSingleRpc(ws, msg, platform, options) {
 			console.warn(
 				`[svelte-realtime] '${path}' threw a non-LiveError:`,
 				err,
-				'\nUse throw new LiveError(code, message) for client-visible errors. Raw errors are hidden from clients.'
+				'\nUse throw new LiveError(code, message) for client-visible errors. Raw errors are hidden from clients.\n  See: https://svti.me/errors'
 			);
 			console.error(`[svelte-realtime] Error in '${path}':`, err);
 		}
@@ -2415,7 +2415,7 @@ function _migrateItem(item, fromVersion, toVersion, migrateFns) {
 		if (fn) {
 			result = fn(result);
 		} else if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-			console.warn(`[svelte-realtime] Missing migration function for version ${v} -> ${v + 1}`);
+			console.warn(`[svelte-realtime] Missing migration function for version ${v} -> ${v + 1}\n  See: https://svti.me/schema`);
 		}
 	}
 	return result;
@@ -2428,7 +2428,7 @@ function _respond(ws, platform, correlationId, payload) {
 		if ((Array.isArray(data) && data.length > 100) || (typeof data === 'string' && data.length > 12000)) {
 			console.warn(
 				`[svelte-realtime] RPC response for '${correlationId}' contains ${data.length} items -- ` +
-				'large responses may exceed maxPayloadLength (16KB). Increase maxPayloadLength in adapter config if needed.'
+				'large responses may exceed maxPayloadLength (16KB). Increase maxPayloadLength in adapter config if needed.\n  See: https://svti.me/adapter-config'
 			);
 		}
 	}

package/vite.js

@@ -37,7 +37,7 @@ function _isValidExportName(name, filePath) {
 	if (!_warnedExports.has(warnKey)) {
 		_warnedExports.add(warnKey);
 		console.warn(
-			`[svelte-realtime] ${filePath}: export '${name}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped`
+			`[svelte-realtime] ${filePath}: export '${name}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped\n  See: https://svti.me/rpc`
 		);
 	}
 	return false;
@@ -131,7 +131,7 @@ function _readStringLiteral(s, start) {
 		if (q === '`' && ch === '$' && s[j + 1] === '{') {
 			const snippet = s.slice(start, Math.min(start + 40, s.length)).replace(/\n/g, '\\n');
 			throw new Error(
-				`[svelte-realtime] Template literal with interpolation cannot be statically analyzed: ${snippet}... -- use a plain string ('...' or "...") instead`
+				`[svelte-realtime] Template literal with interpolation cannot be statically analyzed: ${snippet}... -- use a plain string ('...' or "...") instead\n  See: https://svti.me/vite`
 			);
 		}
 		result += ch;
@@ -265,7 +265,7 @@ export default function svelteRealtime(options) {
 				_warnedExports.clear();
 			if (!existsSync(liveDir)) {
 				console.warn(
-					`[svelte-realtime] Plugin loaded but no live modules found in ${dir}/`
+					`[svelte-realtime] Plugin loaded but no live modules found in ${dir}/\n  See: https://svti.me/start`
 				);
 			} else {
 				if (typedImports) {
@@ -756,12 +756,12 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		if (name.startsWith('_')) {
 			// Reserved names starting with _ (except _guard)
 			console.warn(
-				`[svelte-realtime] ${dir}/${modulePath} exports '${name}' starting with _ -- reserved for internal use`
+				`[svelte-realtime] ${dir}/${modulePath} exports '${name}' starting with _ -- reserved for internal use\n  See: https://svti.me/rpc`
 			);
 			continue;
 		}
 		console.warn(
-			`[svelte-realtime] ${dir}/${modulePath} exports '${name}' which is not wrapped in live() -- it won't be callable from the client. Did you forget live()?`
+			`[svelte-realtime] ${dir}/${modulePath} exports '${name}' which is not wrapped in live() -- it won't be callable from the client. Did you forget live()?\n  See: https://svti.me/rpc`
 		);
 	}
 
@@ -905,7 +905,7 @@ function _extractTopLevelKeys(body) {
 					if (/^[a-zA-Z0-9_]+$/.test(keyName)) {
 						keys.push(keyName);
 					} else if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-						console.warn(`[svelte-realtime] Action name '${keyName}' contains characters not allowed in RPC paths -- skipped`);
+						console.warn(`[svelte-realtime] Action name '${keyName}' contains characters not allowed in RPC paths -- skipped\n  See: https://svti.me/rooms`);
 					}
 					i = closeIdx + 1 + afterClose[0].length;
 					// If the match ended with '(' (quoted method shorthand), track depth
@@ -929,7 +929,7 @@ function _extractTopLevelKeys(body) {
 				if (/^[a-zA-Z0-9_]+$/.test(m[1])) {
 					keys.push(m[1]);
 				} else if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn(`[svelte-realtime] Action name '${m[1]}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped`);
+					console.warn(`[svelte-realtime] Action name '${m[1]}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped\n  See: https://svti.me/rooms`);
 				}
 				i += m[0].length;
 				// If the match ended with '(' (method shorthand), account for the
@@ -1321,12 +1321,12 @@ function _generateRegistry(liveDir, dir) {
 				const topic = topicMatch[1];
 				if (topic.startsWith('__')) {
 					throw new Error(
-						`[svelte-realtime] ${dir}/${rel} uses reserved topic '${topic}' -- topics starting with __ are reserved for internal use`
+						`[svelte-realtime] ${dir}/${rel} uses reserved topic '${topic}' -- topics starting with __ are reserved for internal use\n  See: https://svti.me/streams`
 					);
 				}
 				if (seenTopics.has(topic)) {
 					throw new Error(
-						`[svelte-realtime] Duplicate stream topic '${topic}' in ${dir}/${rel} -- each topic must be unique across all modules`
+						`[svelte-realtime] Duplicate stream topic '${topic}' in ${dir}/${rel} -- each topic must be unique across all modules\n  See: https://svti.me/streams`
 					);
 				}
 				seenTopics.add(topic);
@@ -1482,7 +1482,8 @@ function _checkHooksFile(root, liveDir, dir) {
 			`WebSocket RPC will not work without it.\n` +
 			`  Create src/hooks.ws.js with at minimum:\n` +
 			`    export { message } from 'svelte-realtime/server';\n` +
-			`    export function upgrade() { return {}; }`
+			`    export function upgrade() { return {}; }\n` +
+			`  See: https://svti.me/hooks`
 		);
 		return;
 	}
@@ -1498,7 +1499,8 @@ function _checkHooksFile(root, liveDir, dir) {
 		console.warn(
 			`[svelte-realtime] ${name} exists but does not export a \`message\` handler -- ` +
 			`WebSocket RPC calls from ${dir}/ will go unhandled.\n` +
-			`  Add: export { message } from 'svelte-realtime/server';`
+			`  Add: export { message } from 'svelte-realtime/server';\n` +
+			`  See: https://svti.me/hooks`
 		);
 	}
 }
@@ -2267,7 +2269,7 @@ async function _hmrReloadRegistry(server, liveDir, dir, rel) {
 	try {
 		serverMod = await server.ssrLoadModule('svelte-realtime/server');
 	} catch {
-		console.error('[svelte-realtime] HMR failed: could not load svelte-realtime/server');
+		console.error('[svelte-realtime] HMR failed: could not load svelte-realtime/server\n  See: https://svti.me/vite');
 		return;
 	}