svelte-realtime 0.1.6 → 0.1.8

package/README.md

@@ -647,7 +647,7 @@ const [board, column] = await batch(() => [
 ], { sequential: true });
 ```
 
-Each call resolves or rejects independently -- one failure does not cancel the others. Batches are limited to 50 calls per frame.
+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.
 
 ---
 
@@ -1025,6 +1025,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.
@@ -1511,7 +1526,7 @@ The adapter's `sendQueued()` drops the oldest item if the queue exceeds 1000. Un
 
 ### Batch size (max 50 calls)
 
-A single `batch()` call is limited to 50 RPC calls. If exceeded, the server rejects the entire batch. Split into multiple `batch()` calls if you need more.
+A single `batch()` call is limited to 50 RPC calls. The client rejects before sending if the limit is exceeded, and the server enforces the same limit as a safety net. Split into multiple `batch()` calls if you need more.
 
 ### ws.subscribe() vs the subscribe hook
 
@@ -1773,6 +1788,14 @@ What gets measured:
 
 Merge strategies use an internal `Map<key, index>` for O(1) lookups instead of linear scans. Updates and upserts on keyed strategies (crud, presence, cursor) are constant-time regardless of array size. Deletes and prepends require an index rebuild (linear), which matches the cost of the delete itself.
 
+### Event batching (browser)
+
+In the browser, incoming pub/sub events are queued and flushed once per `requestAnimationFrame` instead of triggering a Svelte store update per event. This is automatic -- no configuration needed.
+
+With high-frequency streams (e.g. 1000 cursors at 20 updates/sec), this reduces reactive store updates from ~20,000/sec to ~60/sec (one per frame). All merge operations still run, but Svelte only diffs and re-renders once per frame.
+
+In Node/SSR (tests, `__directCall`, etc.), events apply synchronously -- no batching overhead.
+
 These benchmarks run in-process with mock objects (no real network). They isolate the framework overhead from network latency. See [bench/rpc.js](bench/rpc.js) for the full source.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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);