svelte-realtime 0.4.22 → 0.4.23

package/README.md

@@ -1219,22 +1219,51 @@ export const message = createMessage({
 
 Opt-in instrumentation for RPC calls, stream subscriptions, and cron executions. Zero overhead if not called.
 
+`live.metrics(registry)` is a one-time setup call. The top of `src/hooks.ws.{js,ts}` is a natural place, since it loads once when the server boots. Pair it with the `createMetrics()` registry from `svelte-adapter-uws-extensions/prometheus`:
+
 ```js
+// src/hooks.ws.js
 import { live } from 'svelte-realtime/server';
-import { createMetricsRegistry } from 'svelte-adapter-uws-extensions/prometheus';
+import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
+
+const metrics = createMetrics();
+
+live.metrics({
+  counter:   ({ name, help, labelNames }) => metrics.counter(name, help, labelNames),
+  histogram: ({ name, help, labelNames }) => metrics.histogram(name, help, labelNames),
+  gauge:     ({ name, help, labelNames }) => metrics.gauge(name, help, labelNames)
+});
+
+export { message, close, unsubscribe } from 'svelte-realtime/server';
+```
 
-const registry = createMetricsRegistry();
-live.metrics(registry);
+Mount the metrics endpoint on your uWS app (typically in `svelte.config.js` or wherever you build the app):
+
+```js
+app.get('/metrics', metrics.handler);
 ```
 
-This registers counters/histograms for:
+The six-line shim adapts realtime's options-object call shape to the extensions registry's positional create methods. Once a metric is registered, every increment, observation, and gauge update flows directly to the extensions registry, so the emitted Prometheus output is exactly what `metrics.serialize()` produces.
+
+### Registered metrics
+
 - `svelte_realtime_rpc_total` -- RPC call count by path and status
 - `svelte_realtime_rpc_duration_seconds` -- RPC latency by path
 - `svelte_realtime_rpc_errors_total` -- RPC errors by path and code
-- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge by topic
+- `svelte_realtime_stream_subscriptions` -- active stream subscription gauge
 - `svelte_realtime_cron_total` -- cron execution count by path and status
 - `svelte_realtime_cron_errors_total` -- cron errors by path
 
+### Registry shape
+
+`live.metrics()` accepts any object exposing:
+
+- `counter({ name, help, labelNames }) -> { inc(labels?) }`
+- `histogram({ name, help, labelNames }) -> { observe(labels, valueSeconds) }`
+- `gauge({ name, help }) -> { inc(), dec() }`
+
+If you prefer `prom-client`, wire it the same way: `counter: ({ name, help, labelNames }) => new client.Counter({ name, help, labelNames, registers: [register] })`, and likewise for `Histogram` and `Gauge`.
+
 ---
 
 ## Circuit breaker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",
@@ -72,6 +72,7 @@
     "svelte-adapter-uws": ">=0.4.12"
   },
   "devDependencies": {
+    "svelte-adapter-uws-extensions": "^0.4.2",
     "vitest": "^4.0.18"
   },
   "keywords": [

package/server.d.ts

@@ -182,6 +182,25 @@ export interface CreateMessageOptions {
 	onUnhandled?(ws: WebSocket<any>, data: ArrayBuffer, platform: Platform): void;
 }
 
+/**
+ * Shape accepted by `live.metrics()`. Any object matching this contract works
+ * (hand-rolled, prom-client adapter, or the `createMetrics()` registry from
+ * `svelte-adapter-uws-extensions/prometheus` wrapped to forward options as
+ * positional args -- see the README "Prometheus metrics" section).
+ */
+export interface MetricsRegistry {
+	counter(opts: { name: string; help: string; labelNames?: string[] }): {
+		inc(labels?: Record<string, string | number>): void;
+	};
+	histogram(opts: { name: string; help: string; labelNames?: string[]; buckets?: number[] }): {
+		observe(labels: Record<string, string | number>, valueSeconds: number): void;
+	};
+	gauge(opts: { name: string; help: string; labelNames?: string[] }): {
+		inc(): void;
+		dec(): void;
+	};
+}
+
 /**
  * Mark a function as RPC-callable over WebSocket.
  *
@@ -561,21 +580,29 @@ 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.
+	 * Opt-in Prometheus metrics integration. Instruments RPC calls, stream
+	 * subscriptions, and cron executions. Zero overhead if never called.
 	 *
-	 * Zero overhead if never called.
+	 * Call once at server start (e.g. the top of `src/hooks.ws.{js,ts}`).
+	 * See the README "Prometheus metrics" section for a working example
+	 * that pairs this with `createMetrics()` from
+	 * `svelte-adapter-uws-extensions/prometheus`.
 	 *
-	 * @param registry - A MetricsRegistry instance with counter(), histogram(), gauge()
+	 * @param registry - Object matching the {@link MetricsRegistry} shape
 	 *
 	 * @example
 	 * ```js
-	 * import { createRegistry } from 'svelte-adapter-uws-extensions/prometheus';
-	 * live.metrics(createRegistry());
+	 * import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
+	 *
+	 * const metrics = createMetrics();
+	 * live.metrics({
+	 *   counter:   ({ name, help, labelNames }) => metrics.counter(name, help, labelNames),
+	 *   histogram: ({ name, help, labelNames }) => metrics.histogram(name, help, labelNames),
+	 *   gauge:     ({ name, help, labelNames }) => metrics.gauge(name, help, labelNames)
+	 * });
 	 * ```
 	 */
-	function metrics(registry: any): void;
+	function metrics(registry: MetricsRegistry): void;
 
 	/**
 	 * Wrap a stream initFn call with a circuit breaker.

package/server.js

@@ -1338,13 +1338,20 @@ live.room = function room(config) {
 let _metricsInstruments = null;
 
 /**
- * Opt-in Prometheus metrics integration.
- * Accepts a MetricsRegistry from `svelte-adapter-uws-extensions/prometheus`
- * and instruments RPC calls, stream subscriptions, and cron executions.
+ * Opt-in Prometheus metrics integration. Instruments RPC calls, stream
+ * subscriptions, and cron executions. Zero overhead if never called.
  *
- * Zero overhead if never called.
+ * Call once at server start (e.g. the top of `src/hooks.ws.{js,ts}`).
  *
- * @param {any} registry - A MetricsRegistry instance with counter(), histogram(), gauge()
+ * The registry is any object exposing:
+ *   counter({ name, help, labelNames }) -> { inc(labels?) }
+ *   histogram({ name, help, labelNames }) -> { observe(labels, valueSeconds) }
+ *   gauge({ name, help }) -> { inc(), dec() }
+ *
+ * See the README "Prometheus metrics" section for a working example that
+ * pairs this with `createMetrics()` from `svelte-adapter-uws-extensions/prometheus`.
+ *
+ * @param {any} registry - Object with counter, histogram, and gauge factories
  */
 live.metrics = function metrics(registry) {
 	_metricsInstruments = {