svelte-adapter-uws 0.6.0-next.39 → 0.6.0-next.40

package/README.md

@@ -1205,6 +1205,13 @@ Every published frame is also stamped with a monotonic per-topic `seq` field in
 platform.publish(`cursor:${userId}`, 'move', pos, { seq: false });
 ```
 
+Pass `{ jitterMs }` to de-herd a thundering-herd broadcast: the frame carries a de-herd WINDOW, and each receiving client rolls its own random delay in `[0, jitterMs)` before dispatching, so a broadcast that makes N clients all react ramps across the window instead of spiking at t+0. The outbound fan-out stays a single native publish - the window is carried verbatim, never a server-rolled offset (which would defer every subscriber identically). Omit / `0` = immediate; the no-jitter frame is byte-identical to before. `svelte-realtime`'s `ctx.publish(..., { jitterMs })` validates the window to a 60s ceiling and the client clamps it again:
+
+```js
+// One reroute event; 50k clients ramp their re-fetch across 5s instead of at once
+platform.publish('route:i95-incident', 'reroute', detour, { jitterMs: 5000 });
+```
+
 ```js
 // src/routes/todos/+page.server.js
 export const actions = {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-adapter-uws",
-	"version": "0.6.0-next.39",
+	"version": "0.6.0-next.40",
 	"publishConfig": {
 		"tag": "next"
 	},

package/src/index.d.ts

@@ -1407,6 +1407,12 @@ export interface Platform {
 	 *     unless `websocket.compression` is configured, where text frames
 	 *     compress by default; pass `false` for a high-frequency,
 	 *     high-fan-out topic (deflate CPU scales per subscriber).
+	 *   - `jitterMs: <ms>` stamps a de-herd window on the frame. Each receiving
+	 *     client rolls its own random delay in `[0, jitterMs)` before handing the
+	 *     frame to its subscribers, so a single broadcast that makes N clients all
+	 *     act (retry, refetch, re-render) ramps across the window instead of
+	 *     spiking at t+0. The outbound fan-out stays one native publish; only the
+	 *     clients' local dispatch is staggered. Omit / `0` = immediate (default).
 	 *
 	 * @example
 	 * ```js
@@ -1417,7 +1423,7 @@ export interface Platform {
 	 * }
 	 * ```
 	 */
-	publish(topic: string, event: string, data?: unknown, options?: { relay?: boolean; seq?: boolean; compress?: boolean }): boolean;
+	publish(topic: string, event: string, data?: unknown, options?: { relay?: boolean; seq?: boolean; compress?: boolean; jitterMs?: number }): boolean;
 
 	/**
 	 * Publish via a plugin-declared binary wire codec. Subscribers that

package/src/runtime/handler/platform.js

@@ -30,7 +30,12 @@ export const platform = {
 		// is a bare set with no compare. Skipped when stamping is off so a
 		// {seq:false}-only topic never enters the convergence comparison.
 		if (seq !== null) maxSeenSeq.set(topic, seq);
-		const envelope = completeEnvelope(envelopePrefix(topic, event), data, seq);
+		// `{ jitterMs }` de-herd window: stamp it on the frame so each client rolls its
+		// own delay before dispatching (spreads N receivers' follow-up actions across
+		// the window). The window is carried verbatim - NOT a server-rolled offset,
+		// which would defer every subscriber of this one frame identically.
+		const jitterMs = (options && typeof options.jitterMs === 'number' && options.jitterMs > 0) ? options.jitterMs : null;
+		const envelope = completeEnvelope(envelopePrefix(topic, event), data, seq, jitterMs);
 		// A zero-length frame at a send site would broadcast garbage to every
 		// subscriber - unrecoverable framing corruption. One length guard, identical
 		// in cost to the assert it replaces.

package/src/runtime/utils/epoch.js

@@ -101,18 +101,26 @@ export function createHlc() {
  * `{topic,event,data}` envelope verbatim. When `seq` is a number the
  * resulting envelope is `{topic,event,data,seq}`.
  *
- * No JSON.stringify on the seq itself: numbers serialize identically
- * via plain string concatenation, saving a stringify call on the
- * publish hot path.
+ * An optional `jitterMs` stamps a `j` field carrying the de-herd WINDOW (not a
+ * pre-rolled offset - one frame fans out to every subscriber, so a single rolled
+ * value would defer them all identically and spread nothing). Each client rolls
+ * its own delay in `[0, j)` before dispatching, so the receivers ramp instead of
+ * spiking. Omitted (`null`/`undefined`) leaves the wire shape unchanged.
+ *
+ * No JSON.stringify on seq/jitter: numbers serialize identically via plain string
+ * concatenation, saving a stringify call on the publish hot path. The no-jitter
+ * tail is byte-identical to the legacy envelope.
  *
  * @param {string} prefix  output of envelopePrefix(topic, event)
  * @param {unknown} data
  * @param {number | null | undefined} seq
+ * @param {number | null | undefined} [jitterMs]  de-herd window in ms
  * @returns {string}
  */
-export function completeEnvelope(prefix, data, seq) {
+export function completeEnvelope(prefix, data, seq, jitterMs) {
 	const body = prefix + JSON.stringify(data ?? null);
-	return seq == null ? body + '}' : body + ',"seq":' + seq + '}';
+	const tail = jitterMs == null ? '}' : ',"j":' + jitterMs + '}';
+	return seq == null ? body + tail : body + ',"seq":' + seq + tail;
 }
 
 /**

package/src/testing.d.ts

@@ -207,9 +207,10 @@ export function esc(s: string): string;
  * brace to a prebuilt envelope prefix. Pairs with the wire shape
  * `{topic, event, data, seq?}`. When `seq` is `null` / `undefined` the
  * field is omitted entirely so the envelope matches the legacy
- * `{topic,event,data}` shape verbatim. Pure.
+ * `{topic,event,data}` shape verbatim. An optional `jitterMs` stamps a `j`
+ * de-herd window the client uses to roll its own dispatch delay. Pure.
  */
-export function completeEnvelope(prefix: string, data: unknown, seq?: number | null): string;
+export function completeEnvelope(prefix: string, data: unknown, seq?: number | null, jitterMs?: number | null): string;
 
 /**
  * Wrap an array of pre-built per-event envelope strings into a single

package/src/vite.js

@@ -119,7 +119,10 @@ export default function uws(options = {}) {
 	 * @returns {boolean}
 	 */
 	function publish(topic, event, data, options) {
-		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + '}';
+		// Mirror the production `{ jitterMs }` de-herd window stamp (platform.publish):
+		// carry the window so each client rolls its own dispatch delay.
+		const jitterMs = (options && typeof options.jitterMs === 'number' && options.jitterMs > 0) ? options.jitterMs : null;
+		const envelope = '{"topic":' + esc(topic) + ',"event":' + esc(event) + ',"data":' + JSON.stringify(data ?? null) + (jitterMs == null ? '}' : ',"j":' + jitterMs + '}');
 		const excludeWs = (options && options.excludeWs) || null;
 		let sent = false;
 		for (const [ws, topics] of subscriptions) {