svelte-realtime 0.1.9 → 0.4.1

package/README.md

@@ -6,7 +6,19 @@ Write server functions. Import them in components. Call them over WebSocket. No
 
 ---
 
-## Getting started
+## Quick start
+
+```bash
+npx svelte-realtime my-app
+cd my-app
+npm run dev
+```
+
+This creates a SvelteKit project with svelte-realtime fully wired: adapter, vite plugins, WebSocket hooks, and a working counter example you can open in your browser right away.
+
+---
+
+## Manual setup
 
 Starting from a SvelteKit project. If you do not have one yet, run `npx sv create my-app && cd my-app && npm install` first.
 
@@ -19,7 +31,7 @@ npm install -D ws
 ```
 
 What each package does:
-- `svelte-adapter-uws` -- the SvelteKit adapter that runs your app on uWebSockets.js with built-in WebSocket support
+- `svelte-adapter-uws` (>=0.4.0) -- the SvelteKit adapter that runs your app on uWebSockets.js with built-in WebSocket support
 - `svelte-realtime` -- this library (RPC + streams on top of the adapter)
 - `uWebSockets.js` -- the native C++ HTTP/WebSocket server (installed from GitHub, not npm)
 - `ws` -- dev dependency used by the adapter during `npm run dev` (not needed in production)
@@ -164,6 +176,9 @@ The `ctx` object passed to every server function contains:
 | `ctx.throttle` | `(topic, event, data, ms)` -- publish at most once per `ms` ms |
 | `ctx.debounce` | `(topic, event, data, ms)` -- publish after `ms` ms of silence |
 | `ctx.signal` | `(userId, event, data)` -- point-to-point message |
+| `ctx.batch` | `(messages)` -- publish multiple messages in one call via `platform.batch()` |
+
+Note: `ctx.user` may contain adapter-injected properties (`__subscriptions`, `remoteAddress`) in addition to whatever your `upgrade()` function returned. These are stripped automatically by the adapter before broadcasting to other clients.
 
 ---
 
@@ -387,6 +402,16 @@ try {
 }
 ```
 
+### Terminal close codes
+
+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
+- 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:
@@ -651,6 +676,20 @@ const [board, column] = await batch(() => [
 
 Each call resolves or rejects independently -- one failure does not cancel the others. Batches are limited to 50 calls -- enforced both client-side (rejects before sending) and server-side.
 
+### Server-side batching
+
+Use `ctx.batch()` inside RPC handlers to publish multiple messages in a single call:
+
+```js
+export const resetBoard = live(async (ctx, boardId) => {
+  await db.boards.reset(boardId);
+  ctx.batch([
+    { topic: `board:${boardId}`, event: 'set', data: [] },
+    { topic: `board:${boardId}:presence`, event: 'set', data: [] }
+  ]);
+});
+```
+
 ---
 
 ## Optimistic updates
@@ -913,13 +952,13 @@ export const presence = live.stream('room:lobby', async (ctx) => {
 });
 ```
 
-`onSubscribe` fires after `ws.subscribe(topic)` and the initial data fetch. `onUnsubscribe` fires when the WebSocket closes (requires exporting `close` from your `hooks.ws.js`):
+`onSubscribe` fires after `ws.subscribe(topic)` and the initial data fetch. `onUnsubscribe` fires in real time when a client unsubscribes from a topic (adapter 0.4.0+), and also when the WebSocket closes for any remaining topics. Export both hooks from your `hooks.ws.js`:
 
 ```js
-export { message, close } from 'svelte-realtime/server';
+export { message, close, unsubscribe } from 'svelte-realtime/server';
 ```
 
-`onUnsubscribe` fires for both static and dynamic topics. For dynamic topics, the server tracks which stream produced each subscription and only fires the correct hook on disconnect.
+`onUnsubscribe` fires for both static and dynamic topics. For dynamic topics, the server tracks which stream produced each subscription and fires the correct hook. The `unsubscribe` hook fires as soon as the client drops a topic; `close` only fires for topics still active at disconnect time. There is no double-firing.
 
 ---
 
@@ -1007,6 +1046,49 @@ export const message = createMessage({
 
 ---
 
+## Prometheus metrics
+
+Opt-in instrumentation for RPC calls, stream subscriptions, and cron executions. Zero overhead if not called.
+
+```js
+import { live } from 'svelte-realtime/server';
+import { createMetricsRegistry } from 'svelte-adapter-uws-extensions/prometheus';
+
+const registry = createMetricsRegistry();
+live.metrics(registry);
+```
+
+This registers counters/histograms for:
+- `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_cron_total` -- cron execution count by path and status
+- `svelte_realtime_cron_errors_total` -- cron errors by path
+
+---
+
+## Circuit breaker
+
+Wrap a stream or RPC init function with a circuit breaker from `svelte-adapter-uws-extensions`. When the breaker is open, returns a fallback value or throws `SERVICE_UNAVAILABLE`.
+
+```js
+import { live } from 'svelte-realtime/server';
+import { createBreaker } from 'svelte-adapter-uws-extensions/breaker';
+
+const dbBreaker = createBreaker({ threshold: 5, resetMs: 30000 });
+
+export const items = live.stream('items',
+  live.breaker({ breaker: dbBreaker, fallback: [] }, async (ctx) => {
+    return db.items.list();
+  })
+);
+```
+
+If `fallback` is omitted and the circuit is open, the call throws `LiveError('SERVICE_UNAVAILABLE', ...)`.
+
+---
+
 ## Cron scheduling
 
 Use `live.cron()` to run server-side functions on a schedule and publish results to a topic.
@@ -1275,6 +1357,17 @@ On the client, the room export becomes an object with sub-streams and actions. R
 <button onclick={() => board.addCard(boardId, 'New card')}>Add</button>
 ```
 
+### Room hooks shortcut
+
+Rooms expose a `.hooks` property for one-liner wiring in `hooks.ws.js`:
+
+```js
+// src/hooks.ws.js
+import { board } from './live/collab.js';
+
+export const { message, close, unsubscribe } = board.hooks;
+```
+
 ---
 
 ## Webhooks
@@ -1411,6 +1504,8 @@ export const feed = live.stream('feed', async (ctx) => {
 
 Replay requires the replay extension from `svelte-adapter-uws-extensions`. When replay is not available or the gap is too large, the client falls back to a full refetch automatically.
 
+With adapter 0.4.0+, the replay end marker sends `{ reqId }` (replay complete) or `{ reqId, truncated: true }` (cache miss). When truncated, the client automatically resets its sequence number and triggers a full refetch.
+
 ---
 
 ## Redis multi-instance
@@ -1716,11 +1811,14 @@ Import from `svelte-realtime/server`.
 | `message` | Ready-made message hook |
 | `createMessage(options?)` | Custom message hook factory |
 | `pipe(stream, ...transforms)` | Composable stream transforms |
-| `close` | Ready-made close hook (fires onUnsubscribe) |
+| `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 |
 | `enableSignals(ws)` | Enable point-to-point signal delivery |
 | `_activateDerived(platform)` | Enable derived stream listeners |
+| `live.metrics(registry)` | Opt-in Prometheus metrics |
+| `live.breaker(options, fn)` | Circuit breaker wrapper |
 
 ---
 
@@ -1735,6 +1833,7 @@ Import from `svelte-realtime/client`.
 | `configure(config)` | Connection hooks and offline queue setup |
 | `combine(...stores, fn)` | Multi-store composition |
 | `onSignal(userId, callback)` | Listen for point-to-point signals |
+| `onDerived` | Re-exported from adapter: reactive derived topic subscription |
 
 **Stream store methods** (on `$live/` stream imports):
 
@@ -1810,6 +1909,43 @@ npm test
 
 ---
 
+## Tauri and Capacitor
+
+svelte-realtime works with Tauri and Capacitor without any static build or architectural changes.
+
+Both runtimes let you point their webview at a live URL instead of local files. Your SvelteKit app runs on the server as normal -- SSR, WebSocket hydration, live stores, RPC -- and the native wrapper adds platform APIs (camera, push notifications, filesystem, etc.) on top.
+
+**Capacitor** -- `capacitor.config.ts`:
+
+```ts
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.app',
+  appName: 'My App',
+  server: {
+    url: 'https://yourapp.com'
+  }
+};
+
+export default config;
+```
+
+**Tauri** -- `tauri.conf.json`:
+
+```json
+{
+  "build": {
+    "devPath": "https://yourapp.com",
+    "distDir": "https://yourapp.com"
+  }
+}
+```
+
+The webview loads your server directly. No static adapter, no URL configuration in the client, nothing special in your SvelteKit code.
+
+---
+
 ## License
 
 MIT

package/cli-utils.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+const VALID_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+const VALID_TEMPLATES = ['minimal', 'example', 'demo'];
+
+/**
+ * @param {string} [ua]
+ * @returns {'npm' | 'pnpm' | 'yarn' | 'bun'}
+ */
+export function detectAgent(ua) {
+	const agent = ua ?? '';
+	if (agent.startsWith('pnpm')) return 'pnpm';
+	if (agent.startsWith('yarn')) return 'yarn';
+	if (agent.startsWith('bun')) return 'bun';
+	return 'npm';
+}
+
+/**
+ * Parse and validate CLI arguments. Returns an object or an error string.
+ * Parses in one pass so that flag values (e.g. --template minimal) are consumed
+ * and not mistaken for positional args.
+ * @param {string[]} argv - arguments (without node/script prefix)
+ * @param {{ dirExists?: (name: string) => boolean }} [opts]
+ * @returns {{ help: true } | { error: string } | { name?: string, template?: string }}
+ */
+export function parseArgs(argv, opts) {
+	const positional = [];
+	let template;
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+
+		if (arg === '--help' || arg === '-h') {
+			return { help: true };
+		}
+
+		if (arg === '--template') {
+			const next = argv[i + 1];
+			if (next === undefined || next.startsWith('-')) {
+				if (next === '--help' || next === '-h') return { help: true };
+				return { error: '--template requires a value: minimal, example, or demo.' };
+			}
+			template = argv[++i];
+			if (!VALID_TEMPLATES.includes(template)) {
+				return { error: `Unknown template: "${template}". Use minimal, example, or demo.` };
+			}
+			continue;
+		}
+
+		if (arg.startsWith('--template=')) {
+			template = arg.slice('--template='.length);
+			if (!template) {
+				return { error: '--template requires a value: minimal, example, or demo.' };
+			}
+			if (!VALID_TEMPLATES.includes(template)) {
+				return { error: `Unknown template: "${template}". Use minimal, example, or demo.` };
+			}
+			continue;
+		}
+
+		if (arg.startsWith('-')) continue;
+
+		positional.push(arg);
+	}
+
+	const name = positional[0];
+	if (name !== undefined) {
+		if (!VALID_NAME_RE.test(name)) {
+			return { error: `Invalid project name: "${name}". Use only letters, numbers, hyphens, and underscores.` };
+		}
+		if (opts?.dirExists?.(name)) {
+			return { error: `Directory "${name}" already exists.` };
+		}
+	}
+
+	return { name, template };
+}

package/cli.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// @ts-check
+import { execSync } from 'child_process';
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+import * as p from '@clack/prompts';
+import { detectAgent, parseArgs } from './cli-utils.js';
+
+const DEMO_REPO = 'https://github.com/lanteanio/svelte-realtime-demo.git';
+
+const parsed = parseArgs(process.argv.slice(2), {
+	dirExists: (name) => existsSync(resolve(process.cwd(), name))
+});
+
+if ('help' in parsed) {
+	console.log(`
+  Usage: npx svelte-realtime [project-name] [--template minimal|example|demo]
+
+  Scaffolds a SvelteKit project with svelte-realtime wired up and ready to go.
+`);
+	process.exit(0);
+}
+
+if ('error' in parsed) {
+	console.error(parsed.error);
+	process.exit(1);
+}
+
+p.intro('svelte-realtime');
+
+const name =
+	parsed.name ||
+	/** @type {string} */ (
+		await p.text({
+			message: 'Project name',
+			placeholder: 'my-app',
+			validate(value) {
+				if (!value) return 'Required.';
+				if (!/^[a-zA-Z0-9_-]+$/.test(value))
+					return 'Use only letters, numbers, hyphens, and underscores.';
+				if (existsSync(resolve(process.cwd(), value))) return `Directory "${value}" already exists.`;
+			}
+		})
+	);
+
+if (p.isCancel(name)) {
+	p.cancel('Cancelled.');
+	process.exit(0);
+}
+
+const dest = resolve(process.cwd(), name);
+
+const template =
+	parsed.template ||
+	/** @type {string} */ (
+		await p.select({
+			message: 'Which template would you like?',
+			options: [
+				{
+					value: 'minimal',
+					label: 'Wiring only',
+					hint: 'SvelteKit + svelte-realtime, no example code'
+				},
+				{
+					value: 'example',
+					label: 'Barebones example',
+					hint: 'SvelteKit + svelte-realtime with a working counter'
+				},
+				{
+					value: 'demo',
+					label: 'Full demo app',
+					hint: 'clone svelte-realtime-demo'
+				}
+			]
+		})
+	);
+
+if (p.isCancel(template)) {
+	p.cancel('Cancelled.');
+	process.exit(0);
+}
+
+const agent = detectAgent(process.env.npm_config_user_agent);
+
+if (template === 'demo') {
+	const s = p.spinner();
+	s.start('Cloning demo repository');
+	run(`git clone ${DEMO_REPO} "${name}"`);
+	s.stop('Cloned.');
+
+	s.start('Installing dependencies');
+	run(`${agent} install`, dest);
+	s.stop('Installed.');
+
+	p.outro(`Done. cd ${name} && ${agent} run dev`);
+	process.exit(0);
+}
+
+const s = p.spinner();
+
+s.start('Creating SvelteKit project');
+run(`npx -y sv create "${name}" --template minimal --types ts`);
+s.stop('Project created.');
+
+s.start('Installing dependencies');
+const add = agent === 'npm' ? 'install' : 'add';
+run(`${agent} ${add} svelte-adapter-uws svelte-realtime`, dest);
+run(`${agent} ${add} uNetworking/uWebSockets.js#v20.60.0`, dest);
+run(`${agent} ${add} -D ws`, dest);
+s.stop('Dependencies installed.');
+
+s.start('Configuring svelte-realtime');
+
+writeFileSync(
+	join(dest, 'svelte.config.js'),
+	`import adapter from 'svelte-adapter-uws';
+import { vitePreprocess } from '@sveltejs/kit/vite';
+
+export default {
+\tkit: {
+\t\tadapter: adapter({ websocket: true })
+\t},
+\tpreprocess: [vitePreprocess()]
+};
+`
+);
+
+writeFileSync(
+	join(dest, 'vite.config.ts'),
+	`import { sveltekit } from '@sveltejs/kit/vite';
+import uws from 'svelte-adapter-uws/vite';
+import realtime from 'svelte-realtime/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+\tplugins: [sveltekit(), uws(), realtime()]
+});
+`
+);
+
+writeFileSync(
+	join(dest, 'src', 'hooks.ws.ts'),
+	`import { message } from 'svelte-realtime/server';
+export { message };
+
+export function upgrade() {
+\treturn { id: crypto.randomUUID() };
+}
+`
+);
+
+if (template === 'example') {
+	mkdirSync(join(dest, 'src', 'live'), { recursive: true });
+
+	writeFileSync(
+		join(dest, 'src', 'live', 'counter.ts'),
+		`import { live } from 'svelte-realtime/server';
+
+let count = 0;
+
+export const increment = live((ctx) => {
+\tcount++;
+\tctx.publish('count', 'set', count);
+\treturn count;
+});
+
+export const counter = live.stream('count', () => {
+\treturn count;
+}, { merge: 'set' });
+`
+	);
+
+	writeFileSync(
+		join(dest, 'src', 'routes', '+page.svelte'),
+		`<script lang="ts">
+\timport { increment, counter } from '$live/counter';
+</script>
+
+<h1>svelte-realtime</h1>
+
+{#if $counter === undefined}
+\t<p>Connecting...</p>
+{:else}
+\t<p>Count: {$counter}</p>
+{/if}
+
+<button onclick={() => increment()}>+1</button>
+`
+	);
+}
+
+s.stop('Configured.');
+
+p.outro(`Done. cd ${name} && ${agent} run dev`);
+
+// ---------------------------------------------------------------------------
+
+function run(cmd, cwd) {
+	try {
+		execSync(cmd, { cwd, stdio: 'pipe' });
+	} catch (e) {
+		p.cancel(`Command failed: ${cmd}\n${e.stderr || e.message}`);
+		process.exit(1);
+	}
+}

package/client.d.ts

@@ -129,7 +129,7 @@ export function batch<T extends Promise<any>[]>(
  *
  * @internal
  */
-export function __binaryRpc(path: string): (buffer: ArrayBuffer, ...args: any[]) => Promise<any>;
+export function __binaryRpc(path: string): (buffer: ArrayBuffer | ArrayBufferView, ...args: any[]) => Promise<any>;
 
 /**
  * Configure client-side connection hooks.