svelte-realtime 0.1.7 → 0.1.9

package/README.md

@@ -75,6 +75,8 @@ export function upgrade({ cookies }) {
 
 `message` is a ready-made hook that routes incoming WebSocket messages to your live functions. `upgrade` decides who can connect and attaches user data to the connection.
 
+> **This file is required.** The Vite plugin will warn at startup if it finds live modules in `src/live/` but no `src/hooks.ws.js` (or `.ts`). Without it, WebSocket messages have nothing on the server side to route them, and all RPC calls will silently time out.
+
 ### Step 5: Write a server function
 
 Create the `src/live/` directory. Every `.js` file in this directory becomes a module of callable server functions.
@@ -1025,6 +1027,21 @@ export const stats = live.stream('stats', async (ctx) => {
 }, { merge: 'set' });
 ```
 
+The function receives a `ctx` object with `publish`, `throttle`, `debounce`, and `signal` -- the same helpers available in RPC handlers (minus `user` and `ws`, since cron runs outside a connection). Use `ctx.publish` for fine-grained control, e.g. publishing individual `created`/`deleted` events on a crud stream:
+
+```js
+export const cleanup = live.cron('0 * * * *', 'boards', async (ctx) => {
+  const stale = await listStaleBoards();
+  for (const board of stale) {
+    await deleteBoard(board.board_id);
+    ctx.publish('boards', 'deleted', { board_id: board.board_id });
+  }
+  // returning undefined skips the automatic 'set' publish
+});
+```
+
+If the function returns a value, it is published as a `set` event (same as before). If it returns `undefined`, no automatic publish happens -- this lets you use `ctx.publish` exclusively without an unwanted `set` event overwriting your crud updates.
+
 Cron expressions use 5 fields: `minute hour day month weekday`. Supported syntax: `*`, single values, ranges (`9-17`), lists (`0,15,30`), and steps (`*/5`).
 
 The platform is captured automatically from the first RPC call. If your app starts cron jobs before any WebSocket connections, call `setCronPlatform(platform)` in your `open` hook.

package/package.json

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

package/server.d.ts

@@ -1,5 +1,22 @@
 import type { Platform, WebSocket } from 'svelte-adapter-uws';
 
+/**
+ * Context passed to `live.cron()` functions.
+ * No `user` or `ws` since cron jobs run outside a connection.
+ */
+export interface CronContext {
+	/** The platform API (publish, send, topic helpers). */
+	platform: Platform;
+	/** Shorthand for `platform.publish` -- delegates to whatever platform was passed in. */
+	publish: Platform['publish'];
+	/** Throttled publish -- sends at most once per `ms` milliseconds. */
+	throttle(topic: string, event: string, data: any, ms: number): void;
+	/** Debounced publish -- sends after `ms` milliseconds of silence. */
+	debounce(topic: string, event: string, data: any, ms: number): void;
+	/** Send a point-to-point signal to a specific user. */
+	signal(userId: string, event: string, data: any): void;
+}
+
 /**
  * Context passed to every `live()` and `live.stream()` function.
  */
@@ -372,18 +389,32 @@ export namespace live {
 	/**
 	 * Create a server-side scheduled function that publishes to a topic on a cron schedule.
 	 *
+	 * The function receives a `ctx` object with `publish`, `throttle`, `debounce`, and `signal`.
+	 * If the function returns a value, it is published as a `set` event on the topic.
+	 * If the function returns `undefined`, no automatic publish happens (use `ctx.publish` instead).
+	 *
 	 * @param schedule - Cron expression (5 fields: minute hour day month weekday)
 	 * @param topic - Topic to publish results to
 	 * @param fn - Async function to run on schedule
 	 *
 	 * @example
 	 * ```js
+	 * // Return a value -- published as 'set' automatically
 	 * export const refreshStats = live.cron('*\/5 * * * *', 'stats', async () => {
 	 *   return db.stats();
 	 * });
+	 *
+	 * // Use ctx.publish for fine-grained control (e.g. crud streams)
+	 * export const cleanup = live.cron('0 * * * *', 'boards', async (ctx) => {
+	 *   const stale = await listStaleBoards();
+	 *   for (const board of stale) {
+	 *     await deleteBoard(board.board_id);
+	 *     ctx.publish('boards', 'deleted', { board_id: board.board_id });
+	 *   }
+	 * });
 	 * ```
 	 */
-	function cron<T extends () => any>(
+	function cron<T extends ((ctx: CronContext) => any) | (() => any)>(
 		schedule: string,
 		topic: string,
 		fn: T
@@ -773,6 +804,11 @@ export function _activateDerived(platform: Platform): void;
  */
 export function _clearCron(): void;
 
+/**
+ * Run all matching cron jobs for the current minute. Exported for testing.
+ */
+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.

package/server.js

@@ -1270,7 +1270,7 @@ export function _restoreHmr(snap) {
 	}
 }
 
-async function _tickCron() {
+export async function _tickCron() {
 	if (_lazyQueue.length) await _resolveAllLazy();
 	const now = new Date();
 	const minute = now.getMinutes();
@@ -1296,8 +1296,18 @@ async function _tickCron() {
 					}
 					return;
 				}
-				const result = await entry.fn();
-				_cronPlatform.publish(entry.topic, 'set', result);
+				const _h = _getCtxHelpers(_cronPlatform);
+				const ctx = {
+					platform: _cronPlatform,
+					publish: _h.publish,
+					throttle: _h.throttle,
+					debounce: _h.debounce,
+					signal: _h.signal
+				};
+				const result = await entry.fn(ctx);
+				if (result !== undefined) {
+					_cronPlatform.publish(entry.topic, 'set', result);
+				}
 			} catch (err) {
 				if (_cronErrorHandler) {
 					_cronErrorHandler(path, err);

package/vite.js

@@ -76,8 +76,11 @@ export default function svelteRealtime(options) {
 				console.warn(
 					`[svelte-realtime] Plugin loaded but no live modules found in ${dir}/`
 				);
-			} else if (typedImports) {
-				_writeTypeDeclarations(liveDir, dir);
+			} else {
+				if (typedImports) {
+					_writeTypeDeclarations(liveDir, dir);
+				}
+				_checkHooksFile(root, liveDir, dir);
 			}
 		},
 
@@ -940,6 +943,49 @@ function _findLiveFiles(dir) {
 	return results;
 }
 
+/**
+ * Check that src/hooks.ws.{js,ts} exists and exports the `message` handler.
+ * Warns at build/dev startup if the file is missing or misconfigured.
+ * @param {string} root
+ * @param {string} liveDir
+ * @param {string} dir
+ */
+function _checkHooksFile(root, liveDir, dir) {
+	const files = _findLiveFiles(liveDir);
+	if (files.length === 0) return;
+
+	const hooksPath = resolve(root, 'src/hooks.ws');
+	const hooksJs = hooksPath + '.js';
+	const hooksTs = hooksPath + '.ts';
+	const found = existsSync(hooksJs) ? hooksJs : existsSync(hooksTs) ? hooksTs : null;
+
+	if (!found) {
+		console.warn(
+			`[svelte-realtime] Found live modules in ${dir}/ but no src/hooks.ws.js -- ` +
+			`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 {}; }`
+		);
+		return;
+	}
+
+	let source;
+	try { source = readFileSync(found, 'utf-8'); } catch { return; }
+
+	const hasMessage = /export\s*\{[^}]*\bmessage\b[^}]*\}\s*from\s+['"]svelte-realtime\/server['"]/.test(source)
+		|| /export\s+(?:const|function|async\s+function)\s+message\b/.test(source);
+
+	if (!hasMessage) {
+		const name = found.endsWith('.ts') ? 'src/hooks.ws.ts' : 'src/hooks.ws.js';
+		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';`
+		);
+	}
+}
+
 /**
  * Generate and write type declarations for all $live/ modules.
  * Creates `$types.d.ts` in the live directory with ambient module declarations.