svelte-realtime 0.4.6 → 0.4.8

package/README.md

@@ -1662,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
@@ -1828,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/package.json

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

package/server.d.ts

@@ -83,26 +83,26 @@ export interface StreamOptions {
 	 * Called when a client subscribes to this stream.
 	 * Receives the context and resolved topic string.
 	 */
-	onSubscribe?(ctx: LiveContext, topic: string): void | Promise<void>;
+	onSubscribe?(ctx: LiveContext<any>, topic: string): void | Promise<void>;
 
 	/**
 	 * Called when a client disconnects from this stream.
 	 * Fires for both static and dynamic topics.
 	 */
-	onUnsubscribe?(ctx: LiveContext, topic: string): void | Promise<void>;
+	onUnsubscribe?(ctx: LiveContext<any>, topic: string): void | Promise<void>;
 
 	/**
 	 * Subscribe-time access predicate. Checked once when a client subscribes.
 	 * Return `false` to deny the subscription with an "Access denied" error.
 	 * For per-event filtering, use `pipe.filter()`.
 	 */
-	filter?(ctx: LiveContext): boolean;
+	filter?(ctx: LiveContext<any>): boolean;
 
 	/**
 	 * Subscribe-time access predicate (alias for `filter`).
 	 * Use `live.access` helpers to build predicates.
 	 */
-	access?(ctx: LiveContext): boolean;
+	access?(ctx: LiveContext<any>): boolean;
 
 	/**
 	 * Schema version number. Increment when the data shape changes.
@@ -143,7 +143,7 @@ export interface HandleRpcOptions {
 	 * Called when an RPC handler throws a non-LiveError.
 	 * Use for error reporting (Sentry, logging, etc.).
 	 */
-	onError?(path: string, error: unknown, ctx: LiveContext): void;
+	onError?(path: string, error: unknown, ctx: LiveContext<any>): void;
 }
 
 /**
@@ -171,7 +171,7 @@ export interface CreateMessageOptions {
 	 * Called when an RPC handler throws a non-LiveError.
 	 * Use for error reporting (Sentry, logging, etc.).
 	 */
-	onError?(path: string, error: unknown, ctx: LiveContext): void;
+	onError?(path: string, error: unknown, ctx: LiveContext<any>): void;
 
 	/**
 	 * Called when a message is not an RPC request.
@@ -195,7 +195,7 @@ export interface CreateMessageOptions {
  * });
  * ```
  */
-export function live<T extends (ctx: LiveContext, ...args: any[]) => any>(fn: T): T;
+export function live<T extends (ctx: LiveContext<any>, ...args: any[]) => any>(fn: T): T;
 
 export namespace live {
 	/**
@@ -212,7 +212,7 @@ export namespace live {
 	 * }, { merge: 'crud', key: 'id', prepend: true });
 	 * ```
 	 */
-	function stream<T extends (ctx: LiveContext, ...args: any[]) => any>(
+	function stream<T extends (ctx: LiveContext<any>, ...args: any[]) => any>(
 		topic: string,
 		initFn: T,
 		options?: StreamOptions
@@ -237,8 +237,8 @@ export namespace live {
 	 * );
 	 * ```
 	 */
-	function stream<T extends (ctx: LiveContext, ...args: any[]) => any>(
-		topicFn: (ctx: LiveContext, ...args: any[]) => string,
+	function stream<T extends (ctx: LiveContext<any>, ...args: any[]) => any>(
+		topicFn: (ctx: LiveContext<any>, ...args: any[]) => string,
 		initFn: T,
 		options?: StreamOptions
 	): T;
@@ -275,7 +275,7 @@ export namespace live {
 	 * ```
 	 */
 	function channel(
-		topicFn: (ctx: LiveContext, ...args: any[]) => string,
+		topicFn: (ctx: LiveContext<any>, ...args: any[]) => string,
 		options?: { merge?: 'crud' | 'latest' | 'set' | 'presence' | 'cursor'; key?: string; max?: number }
 	): Function;
 
@@ -293,7 +293,7 @@ export namespace live {
 	 * });
 	 * ```
 	 */
-	function binary<T extends (ctx: LiveContext, buffer: ArrayBuffer, ...args: any[]) => any>(
+	function binary<T extends (ctx: LiveContext<any>, buffer: ArrayBuffer, ...args: any[]) => any>(
 		fn: T
 	): T;
 
@@ -314,7 +314,7 @@ export namespace live {
 	 * });
 	 * ```
 	 */
-	function middleware(fn: (ctx: LiveContext, next: () => Promise<any>) => Promise<any>): void;
+	function middleware(fn: (ctx: LiveContext<any>, next: () => Promise<any>) => Promise<any>): void;
 
 	/**
 	 * Wrap a stream with a server-side gate predicate.
@@ -333,7 +333,7 @@ export namespace live {
 	 * ```
 	 */
 	function gate<T extends Function>(
-		predicate: (ctx: LiveContext, ...args: any[]) => boolean,
+		predicate: (ctx: LiveContext<any>, ...args: any[]) => boolean,
 		fn: T
 	): T;
 
@@ -353,14 +353,14 @@ export namespace live {
 	 * });
 	 * ```
 	 */
-	function rateLimit<T extends (ctx: LiveContext, ...args: any[]) => any>(
+	function rateLimit<T extends (ctx: LiveContext<any>, ...args: any[]) => any>(
 		config: {
 			/** Maximum number of calls allowed within the window. */
 			points: number;
 			/** Time window in milliseconds. */
 			window: number;
 			/** Custom key function. Defaults to `ctx.user.id`. */
-			key?(ctx: LiveContext): string;
+			key?(ctx: LiveContext<any>): string;
 		},
 		fn: T
 	): T;
@@ -381,7 +381,7 @@ export namespace live {
 	 * });
 	 * ```
 	 */
-	function validated<S, T extends (ctx: LiveContext, input: any, ...args: any[]) => any>(
+	function validated<S, T extends (ctx: LiveContext<any>, input: any, ...args: any[]) => any>(
 		schema: S,
 		fn: T
 	): T;
@@ -529,21 +529,58 @@ 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()`.
 	 */
 	const access: {
 		/** Only allow subscription if `ctx.user[field]` is present. Default field: `'id'`. */
-		owner(field?: string): (ctx: LiveContext) => boolean;
+		owner(field?: string): (ctx: LiveContext<any>) => boolean;
 		/** Role-based access: map role names to boolean or predicate. */
-		role(map: Record<string, true | ((ctx: LiveContext) => boolean)>): (ctx: LiveContext) => boolean;
+		role(map: Record<string, true | ((ctx: LiveContext<any>) => boolean)>): (ctx: LiveContext<any>) => boolean;
 		/** Only allow subscription if `ctx.user.teamId` is present. */
-		team(): (ctx: LiveContext) => boolean;
+		team(): (ctx: LiveContext<any>) => boolean;
 		/** OR logic: any predicate returning true allows the subscription. */
-		any(...predicates: Array<(ctx: LiveContext) => boolean>): (ctx: LiveContext) => boolean;
+		any(...predicates: Array<(ctx: LiveContext<any>) => boolean>): (ctx: LiveContext<any>) => boolean;
 		/** AND logic: all predicates must return true. */
-		all(...predicates: Array<(ctx: LiveContext) => boolean>): (ctx: LiveContext) => boolean;
+		all(...predicates: Array<(ctx: LiveContext<any>) => boolean>): (ctx: LiveContext<any>) => boolean;
 	};
 }
 
@@ -552,21 +589,21 @@ export namespace live {
  */
 export interface RoomConfig {
 	/** Function that computes the room topic from context and args. */
-	topic: (ctx: LiveContext, ...args: any[]) => string;
+	topic: (ctx: LiveContext<any>, ...args: any[]) => string;
 	/** Function that returns initial data for the room. */
-	init: (ctx: LiveContext, ...args: any[]) => Promise<any>;
+	init: (ctx: LiveContext<any>, ...args: any[]) => Promise<any>;
 	/** Function that returns presence data for the connecting user. */
-	presence?: (ctx: LiveContext) => any;
+	presence?: (ctx: LiveContext<any>) => any;
 	/** Enable cursor tracking. Pass `true` or `{ throttle: ms }`. */
 	cursors?: boolean | { throttle?: number };
 	/** Room-scoped RPC actions. */
-	actions?: Record<string, (ctx: LiveContext, ...args: any[]) => any>;
+	actions?: Record<string, (ctx: LiveContext<any>, ...args: any[]) => any>;
 	/** Guard function run before data access and actions. */
-	guard?: (ctx: LiveContext, ...args: any[]) => void | Promise<void>;
+	guard?: (ctx: LiveContext<any>, ...args: any[]) => void | Promise<void>;
 	/** Called when a user joins the room. */
-	onJoin?: (ctx: LiveContext, ...args: any[]) => void | Promise<void>;
+	onJoin?: (ctx: LiveContext<any>, ...args: any[]) => void | Promise<void>;
 	/** Called when a user leaves the room. */
-	onLeave?: (ctx: LiveContext, topic: string) => void | Promise<void>;
+	onLeave?: (ctx: LiveContext<any>, topic: string) => void | Promise<void>;
 	/** Merge strategy for the data stream. @default 'crud' */
 	merge?: string;
 	/** Key field for the data stream. @default 'id' */
@@ -612,8 +649,8 @@ export interface WebhookHandler {
  * A stream transform step created by `pipe.filter`, `pipe.sort`, etc.
  */
 export interface PipeTransform {
-	transformInit?(data: any[], ctx: LiveContext): any[] | Promise<any[]>;
-	transformEvent?(ctx: LiveContext, event: string, data: any): boolean;
+	transformInit?(data: any[], ctx: LiveContext<any>): any[] | Promise<any[]>;
+	transformEvent?(ctx: LiveContext<any>, event: string, data: any): boolean;
 }
 
 /**
@@ -635,7 +672,7 @@ export interface PipeTransform {
 export function pipe<T extends Function>(stream: T, ...transforms: PipeTransform[]): T;
 export namespace pipe {
 	/** Filter items from initial data and drop non-matching live events. */
-	function filter(predicate: (ctx: LiveContext, item: any) => boolean): PipeTransform;
+	function filter(predicate: (ctx: LiveContext<any>, item: any) => boolean): PipeTransform;
 	/** Sort initial data by a field. */
 	function sort(field: string, direction?: 'asc' | 'desc'): PipeTransform;
 	/** Cap initial data to N items. */
@@ -655,8 +692,8 @@ export namespace pipe {
  * ```
  */
 export function guard(
-	...fns: Array<(ctx: LiveContext) => void | Promise<void>>
-): (ctx: LiveContext) => void | Promise<void>;
+	...fns: Array<(ctx: LiveContext<any>) => void | Promise<void>>
+): (ctx: LiveContext<any>) => void | Promise<void>;
 
 /**
  * Typed error that propagates `code` and `message` to the client.
@@ -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/vite.js

@@ -1551,7 +1551,7 @@ function _generateTypeDeclarations(liveDir, dir) {
 		const exports = [];
 		/** @type {Set<string>} */
 		const handledNames = new Set();
-		let needsReadable = false;
+		let needsStreamStore = false;
 		let needsRpcError = false;
 
 		// Detect live() exports
@@ -1597,23 +1597,25 @@ function _generateTypeDeclarations(liveDir, dir) {
 		while ((match = STREAM_EXPORT_RE.exec(source)) !== null) {
 			const name = match[1];
 			handledNames.add(name);
-			needsReadable = true;
+			needsStreamStore = true;
 			needsRpcError = true;
 			const isDynamic = _isDynamicExport(source, name, 'live\\.stream');
 			if (isTS) {
 				const returnType = _extractStreamReturnType(source, name);
-				const storeType = `Readable<${returnType} | undefined | { error: RpcError }>`;
+				const storeType = `StreamStore<${returnType} | undefined | { error: RpcError }>`;
+				const loadSig = `{ load(platform: any, options?: { args?: any[] }): Promise<${returnType}> }`;
 				if (isDynamic) {
 					const factoryParams = _extractDynamicFactoryParams(source, name, 'live\\.stream');
-					exports.push(`  export const ${name}: ${factoryParams} => ${storeType};`);
+					exports.push(`  export const ${name}: (${factoryParams} => ${storeType}) & ${loadSig};`);
 				} else {
-					exports.push(`  export const ${name}: ${storeType};`);
+					exports.push(`  export const ${name}: ${storeType} & ${loadSig};`);
 				}
 			} else {
+				const loadSig = `{ load(platform: any, options?: { args?: any[] }): Promise<any> }`;
 				if (isDynamic) {
-					exports.push(`  export const ${name}: (...args: any[]) => Readable<any>;`);
+					exports.push(`  export const ${name}: ((...args: any[]) => StreamStore<any>) & ${loadSig};`);
 				} else {
-					exports.push(`  export const ${name}: Readable<any>;`);
+					exports.push(`  export const ${name}: StreamStore<any> & ${loadSig};`);
 				}
 			}
 		}
@@ -1624,17 +1626,18 @@ function _generateTypeDeclarations(liveDir, dir) {
 			const name = match[1];
 			handledNames.add(name);
 			if (!exports.some(e => e.includes(`export const ${name}:`))) {
-				needsReadable = true;
+				needsStreamStore = true;
 				const isDynamic = _isDynamicExport(source, name, 'live\\.channel');
+				const loadSig = `{ load(platform: any, options?: { args?: any[] }): Promise<any> }`;
 				if (isDynamic) {
 					if (isTS) {
 						const factoryParams = _extractDynamicFactoryParams(source, name, 'live\\.channel');
-						exports.push(`  export const ${name}: ${factoryParams} => Readable<any>;`);
+						exports.push(`  export const ${name}: (${factoryParams} => StreamStore<any>) & ${loadSig};`);
 					} else {
-						exports.push(`  export const ${name}: (...args: any[]) => Readable<any>;`);
+						exports.push(`  export const ${name}: ((...args: any[]) => StreamStore<any>) & ${loadSig};`);
 					}
 				} else {
-					exports.push(`  export const ${name}: Readable<any>;`);
+					exports.push(`  export const ${name}: StreamStore<any> & ${loadSig};`);
 				}
 			}
 		}
@@ -1645,8 +1648,8 @@ function _generateTypeDeclarations(liveDir, dir) {
 			const name = match[1];
 			handledNames.add(name);
 			if (!exports.some(e => e.includes(`export const ${name}:`))) {
-				needsReadable = true;
-				exports.push(`  export const ${name}: Readable<any>;`);
+				needsStreamStore = true;
+				exports.push(`  export const ${name}: StreamStore<any> & { load(platform: any, options?: { args?: any[] }): Promise<any> };`);
 			}
 		}
 
@@ -1656,8 +1659,8 @@ function _generateTypeDeclarations(liveDir, dir) {
 			const name = match[1];
 			handledNames.add(name);
 			if (!exports.some(e => e.includes(`export const ${name}:`))) {
-				needsReadable = true;
-				exports.push(`  export const ${name}: Readable<any>;`);
+				needsStreamStore = true;
+				exports.push(`  export const ${name}: StreamStore<any> & { load(platform: any, options?: { args?: any[] }): Promise<any> };`);
 			}
 		}
 
@@ -1692,8 +1695,8 @@ function _generateTypeDeclarations(liveDir, dir) {
 			const name = match[1];
 			handledNames.add(name);
 			if (!exports.some(e => e.includes(`export const ${name}:`))) {
-				needsReadable = true;
-				exports.push(`  export const ${name}: { data: (...args: any[]) => Readable<any>, presence?: (...args: any[]) => Readable<any>, cursors?: (...args: any[]) => Readable<any>, [action: string]: (...args: any[]) => Promise<any> | ((...args: any[]) => Readable<any>) };`);
+				needsStreamStore = true;
+				exports.push(`  export const ${name}: { data: (...args: any[]) => StreamStore<any>, presence?: (...args: any[]) => StreamStore<any>, cursors?: (...args: any[]) => StreamStore<any>, [action: string]: (...args: any[]) => Promise<any> | ((...args: any[]) => StreamStore<any>) };`);
 			}
 		}
 
@@ -1702,13 +1705,13 @@ function _generateTypeDeclarations(liveDir, dir) {
 
 		if (exports.length > 0) {
 			declarations.push(`declare module '$live/${rel}' {`);
-			if (needsReadable) {
-				declarations.push("  import type { Readable } from 'svelte/store';");
+			if (needsStreamStore || needsRpcError) {
+				const clientImports = [];
+				if (needsStreamStore) clientImports.push('StreamStore');
+				if (needsRpcError) clientImports.push('RpcError');
+				declarations.push(`  import type { ${clientImports.join(', ')} } from 'svelte-realtime/client';`);
 			}
-			if (needsRpcError) {
-				declarations.push("  import type { RpcError } from 'svelte-realtime/client';");
-			}
-			if (needsReadable || needsRpcError) {
+			if (needsStreamStore || needsRpcError) {
 				declarations.push('');
 			}
 			declarations.push(...exports);