svelte-realtime 0.4.6 → 0.4.7

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.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 }