@firtoz/socka 2.0.0 → 3.0.0

package/README.md

@@ -10,11 +10,15 @@
 
 ![Socka — WebSocket RPC, Standard Schema](./assets/banner.png)
 
-**Typed WebSocket RPC for TypeScript.** Define one contract, get **`session.send.*`** in the client and **`handlers`** on the server—validated, correlated, done.
+**Typed WebSocket RPC and pushes for TypeScript.** One **`defineSocka`** contract gives you **`session.send.*`** for RPCs and **`session.subscribe`** for **typed server pushes**—validated, correlated, same schema on client and server.
+
+**Validation is [Standard Schema](https://standardschema.dev) v1**, not Zod-specific: any compliant library works (e.g. **Zod**, **Valibot**, or others). Examples below use **Zod** for familiarity.
 
 **npm:** [`@firtoz/socka`](https://www.npmjs.com/package/@firtoz/socka). *Socka* is the project name in prose; **install and `import` paths always use `@firtoz/socka` or `@firtoz/socka/...`**. The published artifact is **compiled ESM + `.d.ts` in `dist/`** (see `package.json` `exports`).
 
-## 30-second example (Bun)
+## Minimal example: multi-room chat (Bun)
+
+Join/leave and live messages use **`pushes`**; persisted lines use **`listHistory`**; who is connected uses **`listPresence`**; **`clearHistory`** wipes stored messages and **`historyCleared`** notifies the room (examples also show presence in the UI). This snippet keeps **history in memory** so it stays short—see **[chatroom-bun](../../examples/chatroom-bun)** for **SQLite**, **[chatroom-hono](../../examples/chatroom-hono)** for **file JSON**, and **[chatroom-do](../../examples/chatroom-do)** for **Durable Object SQLite**.
 
 **`contract.ts`** (shared):
 
@@ -22,35 +26,158 @@
 import { defineSocka } from "@firtoz/socka/core";
 import * as z from "zod";
 
-export const myContract = defineSocka({
+export const messageRow = z.object({
+	id: z.string(),
+	ts: z.number(),
+	userId: z.string(),
+	displayName: z.string(),
+	text: z.string(),
+});
+
+export type ChatMessageRow = z.infer<typeof messageRow>;
+
+const onlineUser = z.object({
+	userId: z.string(),
+	displayName: z.string(),
+});
+
+export const chatContract = defineSocka({
 	calls: {
-		echo: {
-			input: z.object({ text: z.string() }),
-			output: z.object({ text: z.string() }),
+		listHistory: {
+			input: z.object({ limit: z.number().int().min(1).max(500).optional() }),
+			output: z.object({ messages: z.array(messageRow) }),
+		},
+		listPresence: {
+			input: z.object({}).optional(),
+			output: z.object({
+				selfUserId: z.string(),
+				users: z.array(onlineUser),
+			}),
+		},
+		sendMessage: {
+			input: z.object({ text: z.string().min(1) }),
+			output: z.object({ ok: z.literal(true) }),
 		},
+		clearHistory: {
+			input: z.object({}).optional(),
+			output: z.object({ ok: z.literal(true) }),
+		},
+	},
+	pushes: {
+		userJoined: z.object({ userId: z.string(), displayName: z.string() }),
+		userLeft: z.object({
+			userId: z.string(),
+			displayName: z.string(),
+		}),
+		roomMessage: messageRow,
+		historyCleared: z.object({
+			ts: z.number(),
+			clearedByUserId: z.string(),
+			clearedByDisplayName: z.string(),
+		}),
 	},
 });
 ```
 
-**`server.ts`**:
+**Fire-and-forget vs `output: z.void()`** — Omit **`output`** on a call when you want one-way success semantics: the server does not send a **`serverResponse`**, and **`await session.send.*` resolves after the frame is sent** (it does not wait for server processing). Server failures still return a correlated **`serverError`**; use **`reportError`** on **`SockaSession`** / **`useSockaSession`** to observe those when using output-less calls. Use **`output: z.void()`** when you still want a normal request/response **`await`** that completes only after the server acknowledges.
+
+**`server.ts`** — **`createSockaRoomRegistry`** gives each room its own **`sessionMap`** and **config**. By default **`createData`** receives **`SockaStrictWebSocketInit`**: **`init.request`** is the upgrade **`Request`** (Bun/Hono/adapters pass it through; see **[Server — Strict upgrade request](./docs/server.md#strict-upgrade-request)**). Set **`strictUpgradeRequest: false`** when you have no **`Request`**. **`session.listPeers()`** returns **`session.data`** for other sockets in the same room—use it to implement **`listPresence`**-style calls (see **[Presence](./docs/presence.md)**).
 
 ```ts
+import type { ServerWebSocket } from "bun";
 import { createSockaBunWebSocketHandlers } from "@firtoz/socka/bun";
-import { myContract } from "./contract";
+import {
+	createSockaRoomRegistry,
+	type SockaWebSocketSessionConfig,
+} from "@firtoz/socka/server";
+import { type ChatMessageRow, chatContract } from "./contract";
+
+type SessionData = { roomId: string; userId: string; displayName: string };
+
+/** In-memory demo store — swap for SQLite / files / DO in real apps. */
+const history = new Map<string, ChatMessageRow[]>();
+
+const registry = createSockaRoomRegistry(
+	(roomId): SockaWebSocketSessionConfig<typeof chatContract, SessionData> => ({
+		contract: chatContract,
+		createData: (init) => {
+			const u = new URL(init.request.url);
+			const displayName = u.searchParams.get("name")?.trim() || "anon";
+			return { roomId, userId: crypto.randomUUID(), displayName };
+		},
+		onAttached: async (session) => {
+			await session.broadcastPush(
+				"userJoined",
+				{ userId: session.data.userId, displayName: session.data.displayName },
+				true,
+			);
+		},
+		handlers: {
+			listHistory: async (input, session) => {
+				const lim = input.limit ?? 200;
+				const rows = history.get(session.data.roomId) ?? [];
+				return { messages: rows.slice(-lim) };
+			},
+			listPresence: async (_input, session) => {
+				const users = session.listPeers().map((d) => ({
+					userId: d.userId,
+					displayName: d.displayName,
+				}));
+				users.sort((a, b) => a.displayName.localeCompare(b.displayName));
+				return { selfUserId: session.data.userId, users };
+			},
+			sendMessage: async (input, session) => {
+				const row = {
+					id: crypto.randomUUID(),
+					ts: Date.now(),
+					userId: session.data.userId,
+					displayName: session.data.displayName,
+					text: input.text,
+				};
+				const list = history.get(session.data.roomId) ?? [];
+				list.push(row);
+				history.set(session.data.roomId, list);
+				await session.broadcastPush("roomMessage", row);
+				return { ok: true as const };
+			},
+			clearHistory: async (_input, session) => {
+				history.set(session.data.roomId, []);
+				const ts = Date.now();
+				await session.broadcastPush("historyCleared", {
+					ts,
+					clearedByUserId: session.data.userId,
+					clearedByDisplayName: session.data.displayName,
+				});
+				return { ok: true as const };
+			},
+		},
+		handleClose: async (session) => {
+			await session.broadcastPush(
+				"userLeft",
+				{ userId: session.data.userId, displayName: session.data.displayName },
+				true,
+			);
+		},
+	}),
+);
+
+type BunWsData = { roomId: string; request: Request };
 
 const { websocket } = createSockaBunWebSocketHandlers({
-	contract: myContract,
-	handlers: {
-		echo: async (input) => ({ text: input.text }),
+	resolveScope(ws: ServerWebSocket<BunWsData>) {
+		const { roomId } = ws.data;
+		const room = registry.get(roomId);
+		return { sessionMap: room.sessionMap, config: room.config };
 	},
-	handleClose: async () => {},
 });
 
-Bun.serve({
+Bun.serve<BunWsData>({
 	port: 3450,
 	fetch(req, server) {
-		if (new URL(req.url).pathname === "/ws") {
-			if (server.upgrade(req)) return undefined;
+		const url = new URL(req.url);
+		if (url.pathname.startsWith("/ws/")) {
+			const roomId = decodeURIComponent(url.pathname.slice(4)) || "default";
+			if (server.upgrade(req, { data: { roomId, request: req } })) return undefined;
 			return new Response("WebSocket upgrade failed", { status: 400 });
 		}
 		return new Response("OK");
@@ -59,62 +186,88 @@ Bun.serve({
 });
 ```
 
+*Ports: this minimal snippet listens on **3450**; the [full-stack examples](#full-stack-examples) use **3461–3466**.*
+
 **`client.ts`** (browser or Bun):
 
 ```ts
 import { SockaSession } from "@firtoz/socka/client";
-import { myContract } from "./contract";
+import { chatContract } from "./contract";
 
 const session = new SockaSession({
-	contract: myContract,
-	url: "ws://localhost:3450/ws",
+	contract: chatContract,
+	url: "ws://localhost:3450/ws/lobby?name=Ada",
 });
-const { text } = await session.send.echo({ text: "hello" });
-console.log(text);
+
+session.subscribe.on("userJoined", (p) => console.log("joined", p));
+session.subscribe.on("userLeft", (p) => console.log("left", p.displayName));
+session.subscribe.on("roomMessage", (m) => console.log(`${m.displayName}: ${m.text}`));
+session.subscribe.on("historyCleared", (p) =>
+	console.log("history cleared by", p.clearedByDisplayName, "at", p.ts),
+);
+
+const { messages } = await session.send.listHistory({});
+console.log("history", messages);
+const { selfUserId, users } = await session.send.listPresence({});
+console.log("online", selfUserId, users);
+await session.send.sendMessage({ text: "hello room" });
+await session.send.clearHistory({});
 ```
 
-Run **`bun run server.ts`**, then point the client at **`ws://localhost:3450/ws`**.
+Run **`bun run server.ts`**, then point the client at the same **`ws://…/ws/<room>?name=…`** path you upgrade in **`fetch`**.
+
+**More examples:** **[chatroom-bun](../../examples/chatroom-bun)** (SQLite + multi-room UI) · **[chatroom-hono](../../examples/chatroom-hono)** · **[chatroom-do](../../examples/chatroom-do)** · tic-tac-toe **[Bun](../../examples/tic-tac-toe-bun)** · **[Hono + Node](../../examples/tic-tac-toe-hono)** · **[Cloudflare DO](../../examples/tic-tac-toe-do)**.
 
 ## Install
 
-```bash
-npm install @firtoz/socka
-```
+Always install **`@firtoz/socka`**, then add **only** what your imports need (`npm` / `pnpm` / `bun add` as you prefer):
 
-Also: `pnpm add @firtoz/socka` · `bun add @firtoz/socka`
+| You are building… | Install |
+|-------------------|---------|
+| **Browser / Vite SPA** (client only) | `npm install @firtoz/socka` |
+| **React** (`@firtoz/socka/react`) | `npm install @firtoz/socka react` — add **`@types/react`** as a dev dependency if TypeScript asks |
+| **Bun** (`Bun.serve`, `@firtoz/socka/bun`) | `npm install @firtoz/socka` — add **`bun-types`** as a dev dependency if you type-check Bun APIs |
+| **Node + Hono + `@hono/node-ws`** | `npm install @firtoz/socka hono @hono/node-ws @hono/node-server ws` — add **`@types/ws`** as a dev dependency when you use **`ws`** on Node |
+| **Cloudflare Workers + Hono** (`@firtoz/socka/hono/cloudflare`) | `npm install @firtoz/socka hono` |
+| **Cloudflare Durable Objects** (`@firtoz/socka/do`) | `npm install @firtoz/socka hono @firtoz/websocket-do` |
 
-Optional peers depend on which subpath you import—see **[Peers](./docs/peers.md)**.
+For **Cloudflare TypeScript types**, prefer **`wrangler types`** (or your app’s typegen) so globals and bindings match your Worker — see [Cloudflare’s TypeScript guide](https://developers.cloudflare.com/workers/languages/typescript). More detail: **[Peers](./docs/peers.md)**.
 
 ## Other runtimes
 
-| Runtime | Subpath | Guide |
-|--------|---------|--------|
-| **Node** + [`ws`](https://github.com/websockets/ws), or any standard **`WebSocket`** | `@firtoz/socka/server` | **[Server](./docs/server.md)** — `attachSockaWebSocket` |
-| **Bun** `Bun.serve` / `ServerWebSocket` | `@firtoz/socka/bun` | **[Server](./docs/server.md)** |
-| **Hono** on Node (`@hono/node-ws`) | `@firtoz/socka/hono` | **[Server](./docs/server.md)** |
-| **Hono** on Cloudflare Workers | `@firtoz/socka/hono/cloudflare` | **[Server](./docs/server.md)** |
+Pick how the socket is upgraded, then use the matching import path and guide:
+
+| Runtime | Import path | Quick start |
+|---------|-------------|-------------|
+| **Node + [`ws`](https://github.com/websockets/ws)** (or any standard **`WebSocket`** after upgrade) | `@firtoz/socka/server` | [`attachSockaWebSocket`](./docs/server.md) |
+| **Bun** (`Bun.serve` / `ServerWebSocket`) | `@firtoz/socka/bun` | [`createSockaBunWebSocketHandlers`](./docs/server.md#firtoz-socka-bun-bunserve) |
+| **Hono on Node** (`@hono/node-ws`) | `@firtoz/socka/hono` | [`sockaHonoNodeWs`](./docs/server.md#firtoz-socka-hono-node-hono-node-ws) |
+| **Hono on Cloudflare Workers** | `@firtoz/socka/hono/cloudflare` | [`sockaHonoCloudflare`](./docs/server.md#firtoz-socka-hono-cloudflare-workers) |
 | **Cloudflare Durable Objects** | `@firtoz/socka/do` | **[Durable Objects](./docs/durable-objects.md)** |
 
 ## Why not socket.io, tRPC, or DIY?
 
 - **Schema-first RPC + push** — one contract; no parallel “event” protocol for server pushes.
 - **Correlated envelopes** — request/response IDs and validation hooks are built in.
-- **Same contract** across Bun, Hono, Node `ws`, and Durable Objects (see **[Comparison](./docs/comparison.md)** for socket.io / tRPC / hand-rolled).
+- **Same contract** across Bun, Hono, Node `ws`, and Durable Objects (see **[Comparison](./docs/comparison.md)** for socket.io, tRPC, and custom WebSocket stacks).
+- **Room registry + presence helpers** — **`createSockaRoomRegistry`** for per-room **`sessionMap`** / config; **`session.listPeers()`** to list other peers in the room (see **[Presence](./docs/presence.md)**).
+- **Strict upgrade typing + optional reconnect** — by default **`createData`** sees **`init.request`** on the upgrade; **`SockaWebSocketClient`** / **`SockaSession`** can **`reconnect`** with exponential backoff (see **[Reconnection](./docs/reconnection.md)**).
 
 ## Documentation
 
 Hub: **[`docs/README.md`](./docs/README.md)** (getting started, peers, lifecycle, multi-room, reference).
 
-**Roadmap:** [post–v1 and deferred work](./roadmap.md). Agent skills: [`skills/`](./skills/).
+**Roadmap:** [deferred ideas and future work](./roadmap.md). Agent skills: [`skills/`](./skills/).
 
 ## Full-stack examples
 
-Self-contained **tic-tac-toe** apps in the monorepo [`examples/`](../../examples/) (same game, different servers):
-
-| Stack | Folder | Port |
-|--------|--------|------|
-| **Bun** (`@firtoz/socka/bun`) | [`tic-tac-toe-bun`](../../examples/tic-tac-toe-bun) | **3461** |
-| **Hono + Node** (`@firtoz/socka/hono`) | [`tic-tac-toe-hono`](../../examples/tic-tac-toe-hono) | **3462** |
-| **Cloudflare DO** (`@firtoz/socka/do`) | [`tic-tac-toe-do`](../../examples/tic-tac-toe-do) | **3463** |
+| Topic | Stack | Folder | Port |
+|-------|--------|--------|------|
+| **Chat + history** | **Bun** + SQLite | [`chatroom-bun`](../../examples/chatroom-bun) | **3464** |
+| **Chat + history** | **Hono + Node** + JSON files | [`chatroom-hono`](../../examples/chatroom-hono) | **3465** |
+| **Chat + history** | **Cloudflare DO** + Drizzle SQLite | [`chatroom-do`](../../examples/chatroom-do) | **3466** |
+| Tic-tac-toe | **Bun** | [`tic-tac-toe-bun`](../../examples/tic-tac-toe-bun) | **3461** |
+| Tic-tac-toe | **Hono + Node** | [`tic-tac-toe-hono`](../../examples/tic-tac-toe-hono) | **3462** |
+| Tic-tac-toe | **Cloudflare DO** | [`tic-tac-toe-do`](../../examples/tic-tac-toe-do) | **3463** |
 
-Each app: **`bun run dev`** (or **`wrangler dev`** for the DO example).
+Chat apps: **`bun run dev`** (or **`wrangler dev`** for **`chatroom-do`**). Tic-tac-toe: same.

package/dist/SockaWebSocketSession-B1w7RAid.d.ts

@@ -0,0 +1,209 @@
+import { S as SockaContract, a as SockaContractConfig, w as SockaWireFormat, c as InferSockaHandlers, z as SockaReportError, f as InferSockaPushPayload } from './socka-report-error-CXwpAUgl.js';
+
+/** Session data with no fields — `createData` may be omitted (defaults to `{}`). */
+type EmptySockaSessionData$1 = Record<string, never>;
+/**
+ * Upgrade context passed into `createData` for {@link SockaWebSocketSession} when
+ * **`strictUpgradeRequest: false`** is set (opt out of the default strict upgrade).
+ *
+ * **`request` is optional** because some call sites attach a socket without an HTTP upgrade
+ * (custom tests, unusual adapters, Node **`ws`** without a **`Request`**, inner DO engine).
+ * If you read query params or headers from the upgrade, either handle a missing
+ * **`request`** here, or use the default strict mode (omit **`strictUpgradeRequest: false`**)
+ * so {@link SockaStrictWebSocketInit} applies.
+ */
+type SockaWebSocketInit = {
+    /**
+     * Original HTTP **`Request`** for the WebSocket upgrade, when the adapter supplies it
+     * (e.g. the optional fourth argument to **`attachSockaWebSocket`**).
+     */
+    request?: Request;
+};
+/**
+ * Upgrade context for {@link SockaWebSocketSession} when using the default strict config
+ * ({@link SockaWebSocketSessionConfig} — no `strictUpgradeRequest` field).
+ *
+ * **What this enables:** `createData` is typed so **`init.request` is always defined**.
+ * You can use **`new URL(init.request.url)`**, read search params, and use **`Request`**
+ * headers without optional chaining or a dummy base URL for **`URL`** parsing.
+ *
+ * **Runtime behavior:** If the adapter does not pass a `Request` while strict mode is on,
+ * socka throws an error explaining how to wire the upgrade (e.g. Bun `data: { request: req }`,
+ * or Hono default `sockaInit`).
+ *
+ * **Typical use:** Bun **`Bun.serve`** upgrades and Hono **`sockaHonoNodeWs`** /
+ * **`sockaHonoCloudflare`** where the incoming HTTP request is available and should drive
+ * `session.data` (names, cookies, etc.).
+ */
+type SockaStrictWebSocketInit = {
+    request: Request;
+};
+type SockaWebSocketCreateData<TData> = [TData] extends [EmptySockaSessionData$1] ? {
+    createData?: (init: SockaWebSocketInit) => TData;
+} : {
+    createData: (init: SockaWebSocketInit) => TData;
+};
+type SockaWebSocketCreateDataStrict<TData> = [TData] extends [
+    EmptySockaSessionData$1
+] ? {
+    createData?: (init: SockaStrictWebSocketInit) => TData;
+} : {
+    createData: (init: SockaStrictWebSocketInit) => TData;
+};
+type SockaSessionForHandlers<TContract extends SockaContract<SockaContractConfig>, TData> = SockaWebSocketSession<TContract, TData>;
+type SockaWebSocketSessionConfigBase<TContract extends SockaContract<SockaContractConfig>, TData> = {
+    contract: TContract;
+    /** Default `"json"`. Use `"msgpack"` for binary frames (must match client). */
+    wireFormat?: SockaWireFormat;
+    handlers: InferSockaHandlers<TContract, SockaSessionForHandlers<TContract, TData>>;
+    /** Called when this WebSocket closes, before the socket is removed from `sessions`. */
+    handleClose: (session: SockaSessionForHandlers<TContract, TData>) => Promise<void>;
+    onHandlerError?: (error: unknown, rpcName: string, input: unknown, session: SockaSessionForHandlers<TContract, TData>) => void;
+    onValidationError?: (error: unknown, originalMessage: unknown) => Promise<void>;
+    /**
+     * Optional sink for non-RPC failures (onAttached, adapter I/O). Defaults to
+     * `console.error` with `socka:` prefixes; see `SockaReportError` in `@firtoz/socka/core`.
+     */
+    reportError?: (event: SockaReportError) => void;
+    serializeJson?: (value: unknown) => string;
+    deserializeJson?: (raw: string) => unknown;
+    /**
+     * Called once after this session is registered in the shared `sessions` map
+     * (safe to broadcast to peers). Sync or async; async rejections are logged.
+     */
+    onAttached?: (session: SockaSessionForHandlers<TContract, TData>) => void | Promise<void>;
+};
+/**
+ * Configuration for {@link SockaWebSocketSession} — **default (strict upgrade)**.
+ *
+ * Handlers receive the session as the second argument, or the only argument when the call
+ * has no input schema.
+ *
+ * **`createData`** receives {@link SockaStrictWebSocketInit}: **`init.request`** is the
+ * HTTP upgrade **`Request`**, required in TypeScript and enforced at runtime. Use for
+ * normal Bun/Hono apps and **`attachSockaWebSocket(websocket, sessions, config, { request })`**.
+ *
+ * Bun helpers: store **`request`** on **`ServerWebSocket`** `data` and use
+ * **`sockaBunInitFromWsData`** (see **`@firtoz/socka/bun`**). Hono: **`sockaHonoNodeWs`** /
+ * **`sockaHonoCloudflare`** can supply **`sockaInit`** from the context so **`createData`**
+ * still sees a **`Request`**.
+ *
+ * To allow a missing upgrade **`Request`** (tests, Node **`ws`**, inner DO engine), use
+ * {@link SockaWebSocketSessionConfigLoose} instead. See the **Server** guide section
+ * **Strict upgrade request** in the package docs.
+ */
+type SockaWebSocketSessionConfig<TContract extends SockaContract<SockaContractConfig>, TData = EmptySockaSessionData$1> = SockaWebSocketSessionConfigBase<TContract, TData> & SockaWebSocketCreateDataStrict<TData>;
+/**
+ * Configuration for {@link SockaWebSocketSession} — **loose upgrade** (opt out of strict).
+ *
+ * Sets **`strictUpgradeRequest: false`**. **`createData`** receives {@link SockaWebSocketInit};
+ * **`init.request` may be `undefined`**.
+ *
+ * Use when:
+ *
+ * - Custom **`attachSockaWebSocket`** call sites or tests that do not attach an HTTP
+ *   **`Request`**
+ * - Node **`ws`** or other adapters where you only have a **`WebSocket`**
+ * - The inner **`SockaWebSocketSession`** constructed inside **`SockaDoSession`** (socka sets
+ *   this mode for you)
+ *
+ * If you read query params or headers from the upgrade, guard for a missing **`request`**
+ * or switch to {@link SockaWebSocketSessionConfig} and wire the real **`Request`** through.
+ */
+type SockaWebSocketSessionConfigLoose<TContract extends SockaContract<SockaContractConfig>, TData = EmptySockaSessionData$1> = SockaWebSocketSessionConfigBase<TContract, TData> & {
+    strictUpgradeRequest: false;
+} & SockaWebSocketCreateData<TData>;
+/**
+ * Union of {@link SockaWebSocketSessionConfig} (strict) and {@link SockaWebSocketSessionConfigLoose}.
+ * This is the type accepted by {@link SockaWebSocketSession}'s constructor,
+ * **`attachSockaWebSocket`**, **`createSockaBunWebSocketHandlers`**, and Hono socka helpers.
+ */
+type SockaWebSocketSessionConfigUnion<TContract extends SockaContract<SockaContractConfig>, TData = EmptySockaSessionData$1> = SockaWebSocketSessionConfig<TContract, TData> | SockaWebSocketSessionConfigLoose<TContract, TData>;
+
+/** Session data with no fields — `createData` may be omitted (defaults to `{}`). */
+type EmptySockaSessionData = Record<string, never>;
+
+/** Session that can send a wire-level server event (already validated). */
+type SockaEmitCapable = {
+    emitWireEvent(event: string, body: unknown): void;
+};
+/**
+ * Contract-typed session surface for handlers that push to clients.
+ */
+interface SockaPushSession<TContract extends SockaContract<SockaContractConfig>> {
+    emitPush<K extends keyof TContract["pushes"] & string>(name: K, body: InferSockaPushPayload<TContract, K>): Promise<void>;
+    broadcastPush<K extends keyof TContract["pushes"] & string>(name: K, body: InferSockaPushPayload<TContract, K>, excludeSelf?: boolean): Promise<void>;
+}
+/**
+ * Broadcast a socka server event to every session in the map (optionally
+ * excluding the caller). Payload must already be contract-validated.
+ *
+ * Exclusion uses the **WebSocket** identity (`self.websocket`), not the session
+ * object reference, so the same `sessions` map can hold `SockaDoSession` while
+ * `broadcastPush` runs on `this.socka` (inner {@link SockaWebSocketSession}).
+ */
+declare function broadcastSockaEventToPeers(sessions: Map<WebSocket, SockaEmitCapable>, self: SockaEmitCapable & {
+    readonly websocket: WebSocket;
+}, event: string, body: unknown, excludeSelf?: boolean): void;
+/**
+ * Runtime-agnostic socka server session: standard {@link WebSocket} wire
+ * dispatch without Cloudflare Durable Object APIs.
+ */
+declare class SockaWebSocketSession<TContract extends SockaContract<SockaContractConfig>, TData = EmptySockaSessionData> implements SockaPushSession<TContract> {
+    readonly websocket: WebSocket;
+    protected readonly sessions: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
+    private readonly config;
+    private readonly wireFormat;
+    private _data;
+    constructor(websocket: WebSocket, sessions: Map<WebSocket, SockaWebSocketSession<TContract, TData>>, config: SockaWebSocketSessionConfigUnion<TContract, TData>, init?: SockaWebSocketInit);
+    get data(): TData;
+    /**
+     * Session data for every connection in the same {@link sessions} map (same room),
+     * optionally excluding this socket.
+     */
+    listPeers(options?: {
+        excludeSelf?: boolean;
+    }): TData[];
+    /**
+     * Like {@link listPeers} but maps each peer {@link SockaWebSocketSession}
+     * (e.g. when you need more than {@link #data}).
+     */
+    listPeersWith<R>(map: (session: SockaWebSocketSession<TContract, TData>) => R, options?: {
+        excludeSelf?: boolean;
+    }): R[];
+    /** Count of sessions in this room (same {@link sessions} map), optionally excluding self. */
+    peerCount(options?: {
+        excludeSelf?: boolean;
+    }): number;
+    /** Whether any peer sessions exist (optionally excluding self). */
+    hasPeers(options?: {
+        excludeSelf?: boolean;
+    }): boolean;
+    /**
+     * Invokes the user {@link typeof SockaWebSocketSessionConfig.handleClose} callback.
+     * Server adapters should call this when the WebSocket closes, **before** deleting
+     * this session from the shared `sessions` map.
+     */
+    invokeHandleClose(): Promise<void>;
+    handleRawMessage(rawMessage: string): Promise<void>;
+    handleBinaryMessage(buffer: ArrayBuffer): Promise<void>;
+    private dispatchAfterParsed;
+    private dispatchClientRequest;
+    private encodeOutgoing;
+    private sendWireFrame;
+    /**
+     * Send a server event frame (wire). Prefer {@link emitPush} so
+     * payloads are validated against the contract.
+     */
+    emitWireEvent(event: string, body: unknown): void;
+    emitPush<K extends keyof TContract["pushes"] & string>(name: K, body: InferSockaPushPayload<TContract, K>): Promise<void>;
+    broadcastPush<K extends keyof TContract["pushes"] & string>(name: K, body: InferSockaPushPayload<TContract, K>, excludeSelf?: boolean): Promise<void>;
+    private reportValidationError;
+}
+/**
+ * Invoke {@link SockaWebSocketSessionConfig.onAttached} after the session is
+ * registered in the shared map.
+ */
+declare function runSockaSessionOnAttached<TContract extends SockaContract<SockaContractConfig>, TData>(config: SockaWebSocketSessionConfigUnion<TContract, TData>, session: SockaWebSocketSession<TContract, TData>): void;
+
+export { type SockaStrictWebSocketInit as S, SockaWebSocketSession as a, type SockaWebSocketSessionConfigUnion as b, type SockaWebSocketInit as c, type SockaPushSession as d, type SockaWebSocketSessionConfig as e, broadcastSockaEventToPeers as f, type SockaEmitCapable as g, type SockaWebSocketSessionConfigLoose as h, runSockaSessionOnAttached as r };

package/dist/bun/index.d.ts

@@ -1,11 +1,36 @@
 import { ServerWebSocket } from 'bun';
-import { S as SockaContract, a as SockaContractConfig, b as SockaWireFormat } from '../socka-report-error-DzFI2Tr7.js';
-import { S as SockaWebSocketSession, a as SockaWebSocketSessionConfig } from '../SockaWebSocketSession-Bru8yFcK.js';
+import { S as SockaContract, a as SockaContractConfig, w as SockaWireFormat } from '../socka-report-error-CXwpAUgl.js';
+import { S as SockaStrictWebSocketInit, a as SockaWebSocketSession, b as SockaWebSocketSessionConfigUnion } from '../SockaWebSocketSession-B1w7RAid.js';
 import '@standard-schema/spec';
 
+/**
+ * Reads the upgrade {@link Request} from Bun **`ServerWebSocket.data`** when your
+ * **`fetch`** handler stored it there (e.g. **`server.upgrade(req, { data: { roomId, request: req } })`**).
+ *
+ * Pair with the default strict upgrade on {@link SockaWebSocketSessionConfig} so
+ * **`createData`** is typed with {@link SockaStrictWebSocketInit} and **`init.request`**
+ * is always defined. If **`request`** is missing from **`data`**, this returns **`undefined`**
+ * and the session constructor will throw — that usually means you forgot
+ * to pass **`request`** on upgrade (or set **`strictUpgradeRequest: false`**).
+ */
+declare function sockaBunInitFromWsData(ws: ServerWebSocket<unknown>): SockaStrictWebSocketInit | undefined;
+/** `ServerWebSocket.data` shape after {@link sockaBunUpgrade}. */
+type SockaBunUpgradeData<TExtra> = TExtra & {
+    request: Request;
+};
+/**
+ * Calls {@link Bun.Server.upgrade} with **`request: req`** merged into **`data`**, so
+ * {@link sockaBunInitFromWsData} and the default strict upgrade always see the HTTP
+ * upgrade request (query params, cookies path).
+ */
+declare function sockaBunUpgrade<TExtra extends Record<string, unknown>>(server: {
+    upgrade: (req: Request, opts: {
+        data: SockaBunUpgradeData<TExtra>;
+    }) => boolean;
+}, req: Request, data?: TExtra): boolean;
 type SockaBunResolveScope<TContract extends SockaContract<SockaContractConfig>, TData, TWsData = undefined> = (ws: ServerWebSocket<TWsData>) => {
     sessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
-    config: SockaWebSocketSessionConfig<TContract, TData>;
+    config: SockaWebSocketSessionConfigUnion<TContract, TData>;
 };
 type SockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConfig>, TData, TWsData = undefined> = {
     sessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
@@ -28,11 +53,11 @@ type SockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConf
  * `sessionMap` and `config` for that socket’s scope (e.g. from `ws.data.roomId`).
  * The returned `sessionMap` is an empty placeholder; real maps come from `resolveScope`.
  */
-declare function createSockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConfig>, TData>(config: SockaWebSocketSessionConfig<TContract, TData>, options?: {
+declare function createSockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConfig>, TData>(config: SockaWebSocketSessionConfigUnion<TContract, TData>, options?: {
     sessionMap?: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
 }): SockaBunWebSocketHandlers<TContract, TData, undefined>;
 declare function createSockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConfig>, TData, TWsData>(options: {
     resolveScope: SockaBunResolveScope<TContract, TData, TWsData>;
 }): SockaBunWebSocketHandlers<TContract, TData, TWsData>;
 
-export { type SockaBunResolveScope, type SockaBunWebSocketHandlers, createSockaBunWebSocketHandlers };
+export { type SockaBunResolveScope, type SockaBunUpgradeData, type SockaBunWebSocketHandlers, createSockaBunWebSocketHandlers, sockaBunInitFromWsData, sockaBunUpgrade };

package/dist/bun/index.js

@@ -1,14 +1,31 @@
 import { dispatchSockaInboundMessage } from '../chunk-5WQTYLIC.js';
-import { SockaWebSocketSession, runSockaSessionOnAttached } from '../chunk-45D4T232.js';
-import { reportSockaError } from '../chunk-MZCQHJXY.js';
+import { SockaWebSocketSession, runSockaSessionOnAttached } from '../chunk-LVVCHLNW.js';
+import { reportSockaError } from '../chunk-IFIGKR3W.js';
 
 // src/bun/index.ts
+function sockaBunInitFromWsData(ws) {
+  const d = ws.data;
+  if (d && "request" in d && d.request instanceof Request) {
+    return { request: d.request };
+  }
+  return void 0;
+}
+function sockaBunUpgrade(server, req, data) {
+  const extra = data ?? {};
+  return server.upgrade(req, { data: { ...extra, request: req } });
+}
 function bunHandlersFromResolveScope(resolveScope) {
   const websocket = {
     open(ws) {
       const { sessionMap, config } = resolveScope(ws);
       const domWs = ws;
-      const session = new SockaWebSocketSession(domWs, sessionMap, config);
+      const init = sockaBunInitFromWsData(ws);
+      const session = new SockaWebSocketSession(
+        domWs,
+        sessionMap,
+        config,
+        init
+      );
       sessionMap.set(domWs, session);
       runSockaSessionOnAttached(config, session);
     },
@@ -62,7 +79,13 @@ function bunHandlersFromConfig(config, maybeOptions) {
   const websocket = {
     open(ws) {
       const domWs = ws;
-      const session = new SockaWebSocketSession(domWs, sessionMap, config);
+      const init = sockaBunInitFromWsData(ws);
+      const session = new SockaWebSocketSession(
+        domWs,
+        sessionMap,
+        config,
+        init
+      );
       sessionMap.set(domWs, session);
       runSockaSessionOnAttached(config, session);
     },
@@ -116,6 +139,6 @@ function createSockaBunWebSocketHandlers(configOrOptions, maybeOptions) {
   );
 }
 
-export { createSockaBunWebSocketHandlers };
+export { createSockaBunWebSocketHandlers, sockaBunInitFromWsData, sockaBunUpgrade };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map