svelte-adapter-uws 0.2.8 → 0.2.10

package/README.md

@@ -30,6 +30,7 @@ I've been loving Svelte and SvelteKit for a long time. I always wanted to expand
 - [Authentication](#authentication)
 - [Platform API (`event.platform`)](#platform-api-eventplatform)
 - [Client store API](#client-store-api)
+- [Seeding initial state](#seeding-initial-state)
 - [TypeScript setup](#typescript-setup)
 - [Svelte 4 support](#svelte-4-support)
 - [Deploying with Docker](#deploying-with-docker)
@@ -389,8 +390,8 @@ If you set `envPrefix: 'MY_APP_'` in the adapter config, all variables are prefi
 
 On `SIGTERM` or `SIGINT`, the server:
 1. Stops accepting new connections
-2. Emits a `sveltekit:shutdown` event on `process` (for cleanup hooks like closing database connections)
-3. Waits for in-flight SSR requests to complete (up to `SHUTDOWN_TIMEOUT` seconds)
+2. Waits for in-flight SSR requests to complete (up to `SHUTDOWN_TIMEOUT` seconds)
+3. Emits a `sveltekit:shutdown` event on `process` (for cleanup hooks like closing database connections)
 4. Exits
 
 ```js
@@ -455,7 +456,7 @@ export async function upgrade({ headers, cookies, url, remoteAddress }) {
 }
 
 // Called when a connection is established
-export function open(ws) {
+export function open(ws, { platform }) {
   const { userId } = ws.getUserData();
   console.log(`User ${userId} connected`);
 
@@ -466,27 +467,27 @@ export function open(ws) {
 // Called when a message is received
 // Note: subscribe/unsubscribe messages from the client store are
 // handled automatically BEFORE this function is called
-export function message(ws, data, isBinary) {
+export function message(ws, { data, isBinary }) {
   const msg = JSON.parse(Buffer.from(data).toString());
   console.log('Got message:', msg);
 }
 
 // Called when a client tries to subscribe to a topic (optional)
 // Return false to deny the subscription
-export function subscribe(ws, topic) {
+export function subscribe(ws, topic, { platform }) {
   const { role } = ws.getUserData();
   // Only admins can subscribe to admin topics
   if (topic.startsWith('admin') && role !== 'admin') return false;
 }
 
 // Called when the connection closes
-export function close(ws, code, message) {
+export function close(ws, { code, message, platform }) {
   const { userId } = ws.getUserData();
   console.log(`User ${userId} disconnected`);
 }
 
 // Called when backpressure has drained (optional, for flow control)
-export function drain(ws) {
+export function drain(ws, { platform }) {
   // You can resume sending large messages here
 }
 ```
@@ -583,7 +584,7 @@ export async function upgrade({ cookies }) {
   return { userId: user.id, name: user.name, role: user.role };
 }
 
-export function open(ws) {
+export function open(ws, { platform }) {
   const { userId, role } = ws.getUserData();
   console.log(`${userId} connected (${role})`);
 
@@ -592,7 +593,7 @@ export function open(ws) {
   if (role === 'admin') ws.subscribe('admin');
 }
 
-export function close(ws) {
+export function close(ws, { platform }) {
   const { userId } = ws.getUserData();
   console.log(`${userId} disconnected`);
 }
@@ -653,7 +654,7 @@ The WebSocket upgrade is an HTTP request. The browser treats it like any other r
 
 ## Platform API (`event.platform`)
 
-Available in server hooks, load functions, form actions, and API routes.
+Available in server hooks, load functions, form actions, API routes, and WebSocket hooks (`hooks.ws`).
 
 ### `platform.publish(topic, event, data)`
 
@@ -686,12 +687,12 @@ This is useful when you store WebSocket references (e.g. in a `Map`) and need to
 // src/hooks.ws.js - store connections by user ID
 const userSockets = new Map();
 
-export function open(ws) {
+export function open(ws, { platform }) {
   const { userId } = ws.getUserData();
   userSockets.set(userId, ws);
 }
 
-export function close(ws) {
+export function close(ws, { platform }) {
   const { userId } = ws.getUserData();
   userSockets.delete(userId);
 }
@@ -714,13 +715,15 @@ export async function POST({ request, platform }) {
 }
 ```
 
-To reply directly from inside `hooks.ws.js` (where `platform` isn't available), use `ws.send()` with the envelope format:
+You can also reply directly from inside `hooks.ws.js` using `platform.send()` or `ws.send()` with the envelope format:
 
 ```js
 // src/hooks.ws.js
-export function message(ws, rawData) {
-  const msg = JSON.parse(Buffer.from(rawData).toString());
-  // Reply to sender using the same envelope format the client store expects
+export function message(ws, { data, platform }) {
+  const msg = JSON.parse(Buffer.from(data).toString());
+  // Using platform.send (recommended):
+  platform.send(ws, 'echo', 'reply', { got: msg });
+  // Or using ws.send with manual envelope:
   ws.send(JSON.stringify({ topic: 'echo', event: 'reply', data: { got: msg } }));
 }
 ```
@@ -980,13 +983,22 @@ Handles `set`, `increment`, and `decrement` events:
 <p>{$online} users online</p>
 ```
 
-Server:
+Server (from any hook or handler that has `platform`):
 ```js
-platform.topic('online-users').increment();
-platform.topic('online-users').decrement();
+// In hooks.ws.js - track connected users:
+export function open(ws, { platform }) {
+  platform.topic('online-users').increment();
+}
+export function close(ws, { platform }) {
+  platform.topic('online-users').decrement();
+}
+
+// Or from a SvelteKit handler:
 platform.topic('online-users').set(42);
 ```
 
+> **Heads up:** The increment/decrement pattern above has a subtle race condition - a newly connected client won't see the current count because its `subscribe` message hasn't been processed yet when `open` fires. See [Seeding initial state](#seeding-initial-state) for the fix.
+
 ### `once(topic, event?, options?)` - wait for one event
 
 Returns a promise that resolves with the first matching event and then unsubscribes:
@@ -1077,6 +1089,78 @@ ws.close();
 
 ---
 
+## Seeding initial state
+
+When a client connects, there's a window between the WebSocket opening and the client's topic subscriptions being processed. Any `platform.publish()` calls that happen during `open` will be missed by the connecting client, because it hasn't subscribed to those topics yet.
+
+This matters most with `count()`. If your `open` hook does `platform.topic('online').set(total)`, the connecting client won't see it - the `set` event is broadcast before the client's `subscribe` message arrives.
+
+The fix is to use the `subscribe` hook instead of (or alongside) `open` to send the current value directly to the subscribing client:
+
+```js
+// src/hooks.ws.js
+let online = 0;
+
+export function open(ws, { platform }) {
+  online++;
+  platform.topic('online').set(online); // broadcasts to already-subscribed clients
+}
+
+export function subscribe(ws, topic, { platform }) {
+  // When a client subscribes to 'online', send it the current count
+  if (topic === 'online') {
+    platform.send(ws, 'online', 'set', online);
+  }
+}
+
+export function close(ws, { platform }) {
+  online--;
+  platform.topic('online').set(online);
+}
+```
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script>
+  import { count } from 'svelte-adapter-uws/client';
+
+  const online = count('online');
+</script>
+
+<p>{$online} online</p>
+```
+
+The `subscribe` hook fires at the right moment - after the client is actually subscribed to the topic. `platform.send()` sends only to that one client, so it gets the current value without waiting for the next broadcast.
+
+This same pattern works for any topic where new subscribers need to see the current state. For a CRUD list, you could send the full dataset in `subscribe`:
+
+```js
+// src/hooks.ws.js
+export async function subscribe(ws, topic, { platform }) {
+  if (topic === 'todos') {
+    const todos = await db.getTodos();
+    for (const todo of todos) {
+      platform.send(ws, 'todos', 'created', todo);
+    }
+  }
+}
+```
+
+```svelte
+<script>
+  import { crud } from 'svelte-adapter-uws/client';
+
+  // No need for load() data - the subscribe hook seeds the list
+  const todos = crud('todos');
+</script>
+
+{#each $todos as todo (todo.id)}
+  <p>{todo.text}</p>
+{/each}
+```
+
+---
+
 ## TypeScript setup
 
 Add the platform type to your `src/app.d.ts`:
@@ -1229,10 +1313,10 @@ The static file gap is the largest because `adapter-node` uses sirv which calls
 
 | Server | Messages delivered/s | vs adapter-uws |
 |---|---|---|
-| **uWS native** (barebones) | 3,625,000 | 1.0x |
-| **adapter-uws** (full handler) | 3,642,000 | baseline |
-| **socket.io** | 177,200 | **20.5x slower** |
-| **ws** library | 164,500 | **22.1x slower** |
+| **uWS native** (barebones) | 3,642,000 | baseline |
+| **adapter-uws** (full handler) | 3,625,000 | 1.0x |
+| **ws** library | 177,200 | **20.5x slower** |
+| **socket.io** | 164,500 | **22.1x slower** |
 
 uWS native pub/sub delivered 3.6M messages/s with perfect 50x fan-out. After optimization, the adapter matches it -- the byte-prefix check and string template envelope add near-zero overhead to the hot path. `socket.io` and `ws` both collapsed under the same load, delivering less than 1x fan-out (massive message loss/queueing).
 

package/files/handler.js

@@ -836,7 +836,7 @@ if (WS_ENABLED) {
 
 		open: (ws) => {
 			wsConnections.add(ws);
-			wsModule.open?.(ws);
+			wsModule.open?.(ws, { platform });
 		},
 
 		message: (ws, message, isBinary) => {
@@ -851,7 +851,7 @@ if (WS_ENABLED) {
 					const msg = JSON.parse(Buffer.from(message).toString());
 					if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
 						// If a subscribe hook exists, let it gate access
-						if (wsModule.subscribe && wsModule.subscribe(ws, msg.topic) === false) {
+						if (wsModule.subscribe && wsModule.subscribe(ws, msg.topic, { platform }) === false) {
 							return;
 						}
 						ws.subscribe(msg.topic);
@@ -866,14 +866,14 @@ if (WS_ENABLED) {
 				}
 			}
 			// Delegate everything else to the user's handler (if provided)
-			wsModule.message?.(ws, message, isBinary);
+			wsModule.message?.(ws, { data: message, isBinary, platform });
 		},
 
-		drain: wsModule.drain || undefined,
+		drain: wsModule.drain ? (ws) => wsModule.drain(ws, { platform }) : undefined,
 
 		close: (ws, code, message) => {
 			wsConnections.delete(ws);
-			wsModule.close?.(ws, code, message);
+			wsModule.close?.(ws, { code, message, platform });
 		},
 
 		maxPayloadLength: wsOptions.maxPayloadLength,

package/index.d.ts

@@ -189,6 +189,46 @@ export interface UpgradeContext {
 	remoteAddress: string;
 }
 
+/**
+ * Context passed to `open` and `drain` handlers.
+ */
+export interface OpenContext {
+	/** The platform API - publish, send, topic helpers, etc. */
+	platform: Platform;
+}
+
+/**
+ * Context passed to the `message` handler.
+ */
+export interface MessageContext {
+	/** The raw message data. */
+	data: ArrayBuffer;
+	/** Whether the message is binary. */
+	isBinary: boolean;
+	/** The platform API - publish, send, topic helpers, etc. */
+	platform: Platform;
+}
+
+/**
+ * Context passed to the `close` handler.
+ */
+export interface CloseContext {
+	/** The WebSocket close code. */
+	code: number;
+	/** The close reason (as ArrayBuffer). */
+	message: ArrayBuffer;
+	/** The platform API - publish, send, topic helpers, etc. */
+	platform: Platform;
+}
+
+/**
+ * Context passed to the `subscribe` handler.
+ */
+export interface SubscribeContext {
+	/** The platform API - publish, send, topic helpers, etc. */
+	platform: Platform;
+}
+
 /**
  * Shape of the user's WebSocket handler module.
  *
@@ -196,6 +236,10 @@ export interface UpgradeContext {
  * of these functions. All are optional - the built-in handler already
  * handles subscribe/unsubscribe for the client store.
  *
+ * Every hook receives `(ws, context)` where context always includes `platform`
+ * plus any hook-specific fields. This gives you full access to publish, send,
+ * and topic helpers directly in your WebSocket hooks.
+ *
  * @example
  * ```js
  * // src/hooks.ws.js - auto-discovered, no config needed
@@ -207,8 +251,13 @@ export interface UpgradeContext {
  *   return { userId: user.id }; // attach data to socket
  * }
  *
- * export function open(ws) {
+ * export function open(ws, { platform }) {
  *   ws.subscribe(`user:${ws.getUserData().userId}`);
+ *   platform.topic('users').increment();
+ * }
+ *
+ * export function close(ws, { platform }) {
+ *   platform.topic('users').decrement();
  * }
  * ```
  */
@@ -225,7 +274,7 @@ export interface WebSocketHandler<UserData = unknown> {
 	upgrade?: (ctx: UpgradeContext) => UserData | false | Promise<UserData | false>;
 
 	/** Called when a WebSocket connection is established. */
-	open?: (ws: WebSocket<UserData>) => void;
+	open?: (ws: WebSocket<UserData>, ctx: OpenContext) => void;
 
 	/**
 	 * Called when a message is received.
@@ -234,7 +283,7 @@ export interface WebSocketHandler<UserData = unknown> {
 	 * handled automatically before this is called. You only need this for
 	 * custom application-level messages.
 	 */
-	message?: (ws: WebSocket<UserData>, data: ArrayBuffer, isBinary: boolean) => void;
+	message?: (ws: WebSocket<UserData>, ctx: MessageContext) => void;
 
 	/**
 	 * Called when a client tries to subscribe to a topic.
@@ -246,22 +295,22 @@ export interface WebSocketHandler<UserData = unknown> {
 	 *
 	 * @example
 	 * ```js
-	 * export function subscribe(ws, topic) {
+	 * export function subscribe(ws, topic, { platform }) {
 	 *   const { role } = ws.getUserData();
 	 *   if (topic.startsWith('admin') && role !== 'admin') return false;
 	 * }
 	 * ```
 	 */
-	subscribe?: (ws: WebSocket<UserData>, topic: string) => boolean | void;
+	subscribe?: (ws: WebSocket<UserData>, topic: string, ctx: SubscribeContext) => boolean | void;
 
 	/**
 	 * Called when backpressure has drained (buffered data was sent).
 	 * Use this for flow control when sending large or frequent messages.
 	 */
-	drain?: (ws: WebSocket<UserData>) => void;
+	drain?: (ws: WebSocket<UserData>, ctx: OpenContext) => void;
 
 	/** Called when the connection closes. */
-	close?: (ws: WebSocket<UserData>, code: number, message: ArrayBuffer) => void;
+	close?: (ws: WebSocket<UserData>, ctx: CloseContext) => void;
 }
 
 // -- Platform type for event.platform ----------------------------------------
@@ -310,8 +359,8 @@ export interface Platform {
 	 * @example
 	 * ```js
 	 * // In hooks.ws.js - reply to sender:
-	 * export function message(ws, rawData) {
-	 *   const msg = JSON.parse(Buffer.from(rawData).toString());
+	 * export function message(ws, { data }) {
+	 *   const msg = JSON.parse(Buffer.from(data).toString());
 	 *   ws.send(JSON.stringify({ topic: 'echo', event: 'reply', data: { got: msg } }));
 	 * }
 	 * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/vite.js

@@ -310,7 +310,7 @@ export default function uws(options = {}) {
 				wsWrappers.set(ws, wrapped);
 
 				// Call user open handler
-				userHandlers.open?.(wrapped);
+				userHandlers.open?.(wrapped, { platform });
 
 				ws.on('message', async (raw, isBinary) => {
 					// Convert to ArrayBuffer (matching uWS interface)
@@ -324,7 +324,7 @@ export default function uws(options = {}) {
 						try {
 							const msg = JSON.parse(buf.toString());
 							if (msg.type === 'subscribe' && typeof msg.topic === 'string') {
-								if (userHandlers.subscribe && userHandlers.subscribe(wrapped, msg.topic) === false) {
+								if (userHandlers.subscribe && userHandlers.subscribe(wrapped, msg.topic, { platform }) === false) {
 									return;
 								}
 								subscriptions.get(ws)?.add(msg.topic);
@@ -342,14 +342,14 @@ export default function uws(options = {}) {
 					// Delegate to user handler
 					await handlerReady;
 					if (userHandlers.message) {
-						userHandlers.message(wrapped, arrayBuffer, !!isBinary);
+						userHandlers.message(wrapped, { data: arrayBuffer, isBinary: !!isBinary, platform });
 					}
 				});
 
 				ws.on('close', (code, reason) => {
 					const reasonBuf = reason || Buffer.alloc(0);
 					const reasonAB = reasonBuf.buffer.slice(reasonBuf.byteOffset, reasonBuf.byteOffset + reasonBuf.byteLength);
-					userHandlers.close?.(wrapped, code, reasonAB);
+					userHandlers.close?.(wrapped, { code, message: reasonAB, platform });
 					connections.delete(ws);
 					subscriptions.delete(ws);
 					wsWrappers.delete(ws);