@firtoz/socka 2.0.0

package/README.md

@@ -0,0 +1,120 @@
+# @firtoz/socka
+
+[![npm version](https://img.shields.io/npm/v/%40firtoz%2Fsocka.svg)](https://www.npmjs.com/package/@firtoz/socka)
+[![npm downloads](https://img.shields.io/npm/dm/%40firtoz%2Fsocka.svg)](https://www.npmjs.com/package/@firtoz/socka)
+[![license](https://img.shields.io/npm/l/%40firtoz%2Fsocka.svg)](https://github.com/firtoz/fullstack-toolkit/blob/main/LICENSE)
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![WebSocket](https://img.shields.io/badge/WebSocket-RPC-6366f1)](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+[![Standard Schema](https://img.shields.io/badge/Standard_Schema-v1-1e293b)](https://standardschema.dev)
+
+![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.
+
+**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)
+
+**`contract.ts`** (shared):
+
+```ts
+import { defineSocka } from "@firtoz/socka/core";
+import * as z from "zod";
+
+export const myContract = defineSocka({
+	calls: {
+		echo: {
+			input: z.object({ text: z.string() }),
+			output: z.object({ text: z.string() }),
+		},
+	},
+});
+```
+
+**`server.ts`**:
+
+```ts
+import { createSockaBunWebSocketHandlers } from "@firtoz/socka/bun";
+import { myContract } from "./contract";
+
+const { websocket } = createSockaBunWebSocketHandlers({
+	contract: myContract,
+	handlers: {
+		echo: async (input) => ({ text: input.text }),
+	},
+	handleClose: async () => {},
+});
+
+Bun.serve({
+	port: 3450,
+	fetch(req, server) {
+		if (new URL(req.url).pathname === "/ws") {
+			if (server.upgrade(req)) return undefined;
+			return new Response("WebSocket upgrade failed", { status: 400 });
+		}
+		return new Response("OK");
+	},
+	websocket,
+});
+```
+
+**`client.ts`** (browser or Bun):
+
+```ts
+import { SockaSession } from "@firtoz/socka/client";
+import { myContract } from "./contract";
+
+const session = new SockaSession({
+	contract: myContract,
+	url: "ws://localhost:3450/ws",
+});
+const { text } = await session.send.echo({ text: "hello" });
+console.log(text);
+```
+
+Run **`bun run server.ts`**, then point the client at **`ws://localhost:3450/ws`**.
+
+## Install
+
+```bash
+npm install @firtoz/socka
+```
+
+Also: `pnpm add @firtoz/socka` · `bun add @firtoz/socka`
+
+Optional peers depend on which subpath you import—see **[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)** |
+| **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).
+
+## 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/).
+
+## 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** |
+
+Each app: **`bun run dev`** (or **`wrangler dev`** for the DO example).

package/dist/SockaWebSocketSession-Bru8yFcK.d.ts

@@ -0,0 +1,107 @@
+import { S as SockaContract, a as SockaContractConfig, b as SockaWireFormat, e as InferSockaHandlers, y as SockaReportError, g as InferSockaPushPayload } from './socka-report-error-DzFI2Tr7.js';
+
+/** Session data with no fields — `createData` may be omitted (defaults to `{}`). */
+type EmptySockaSessionData$1 = Record<string, never>;
+/** Optional upgrade context for {@link SockaWebSocketSession}. */
+type SockaWebSocketInit = {
+    /** Original HTTP request for the WebSocket upgrade, when available. */
+    request?: Request;
+};
+type SockaWebSocketCreateData<TData> = [TData] extends [EmptySockaSessionData$1] ? {
+    createData?: (init: SockaWebSocketInit) => TData;
+} : {
+    createData: (init: SockaWebSocketInit) => TData;
+};
+type SockaSessionForHandlers<TContract extends SockaContract<SockaContractConfig>, TData> = SockaWebSocketSession<TContract, TData>;
+/**
+ * Configuration for {@link SockaWebSocketSession}. Handlers receive the session
+ * instance as the second argument (or the only argument when the procedure has no input).
+ */
+type SockaWebSocketSessionConfig<TContract extends SockaContract<SockaContractConfig>, TData = EmptySockaSessionData$1> = {
+    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>;
+} & SockaWebSocketCreateData<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: SockaWebSocketSessionConfig<TContract, TData>, init?: SockaWebSocketInit);
+    get data(): TData;
+    /**
+     * 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: SockaWebSocketSessionConfig<TContract, TData>, session: SockaWebSocketSession<TContract, TData>): void;
+
+export { SockaWebSocketSession as S, type SockaWebSocketSessionConfig as a, type SockaWebSocketInit as b, broadcastSockaEventToPeers as c, type SockaEmitCapable as d, type SockaPushSession as e, runSockaSessionOnAttached as r };

package/dist/bun/index.d.ts

@@ -0,0 +1,38 @@
+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 '@standard-schema/spec';
+
+type SockaBunResolveScope<TContract extends SockaContract<SockaContractConfig>, TData, TWsData = undefined> = (ws: ServerWebSocket<TWsData>) => {
+    sessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
+    config: SockaWebSocketSessionConfig<TContract, TData>;
+};
+type SockaBunWebSocketHandlers<TContract extends SockaContract<SockaContractConfig>, TData, TWsData = undefined> = {
+    sessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;
+    /** Pass into `Bun.serve({ ..., websocket })`. */
+    websocket: {
+        open: (ws: ServerWebSocket<TWsData>) => void;
+        message: (ws: ServerWebSocket<TWsData>, message: unknown) => void | Promise<void>;
+        close: (ws: ServerWebSocket<TWsData>) => void | Promise<void>;
+    };
+    wireFormat: SockaWireFormat;
+};
+/**
+ * WebSocket handlers for `Bun.serve` when using `ServerWebSocket` (no
+ * `addEventListener`). Inbound frames are dispatched with the same logic as
+ * `attachSockaWebSocket`.
+ *
+ * **Single-room:** pass a {@link SockaWebSocketSessionConfig} and optional shared `sessionMap`.
+ *
+ * **Multi-room:** pass `{ resolveScope }` where `resolveScope(ws)` returns the
+ * `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?: {
+    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 };

package/dist/bun/index.js

@@ -0,0 +1,121 @@
+import { dispatchSockaInboundMessage } from '../chunk-5WQTYLIC.js';
+import { SockaWebSocketSession, runSockaSessionOnAttached } from '../chunk-45D4T232.js';
+import { reportSockaError } from '../chunk-MZCQHJXY.js';
+
+// src/bun/index.ts
+function bunHandlersFromResolveScope(resolveScope) {
+  const websocket = {
+    open(ws) {
+      const { sessionMap, config } = resolveScope(ws);
+      const domWs = ws;
+      const session = new SockaWebSocketSession(domWs, sessionMap, config);
+      sessionMap.set(domWs, session);
+      runSockaSessionOnAttached(config, session);
+    },
+    async message(ws, message) {
+      const { sessionMap, config } = resolveScope(ws);
+      const domWs = ws;
+      const session = sessionMap.get(domWs);
+      if (!session) return;
+      const wireFormat = config.wireFormat ?? "json";
+      try {
+        await dispatchSockaInboundMessage(
+          session,
+          wireFormat,
+          message
+        );
+      } catch (error) {
+        reportSockaError(config.reportError, {
+          kind: "serverInboundMessage",
+          adapter: "bun",
+          error
+        });
+      }
+    },
+    async close(ws) {
+      const { sessionMap, config } = resolveScope(ws);
+      const domWs = ws;
+      const session = sessionMap.get(domWs);
+      try {
+        if (session) {
+          await session.invokeHandleClose();
+        }
+      } catch (error) {
+        reportSockaError(config.reportError, {
+          kind: "serverHandleClose",
+          error
+        });
+      } finally {
+        sessionMap.delete(domWs);
+      }
+    }
+  };
+  return {
+    sessionMap: /* @__PURE__ */ new Map(),
+    websocket,
+    wireFormat: "json"
+  };
+}
+function bunHandlersFromConfig(config, maybeOptions) {
+  const sessionMap = maybeOptions?.sessionMap ?? /* @__PURE__ */ new Map();
+  const wireFormat = config.wireFormat ?? "json";
+  const websocket = {
+    open(ws) {
+      const domWs = ws;
+      const session = new SockaWebSocketSession(domWs, sessionMap, config);
+      sessionMap.set(domWs, session);
+      runSockaSessionOnAttached(config, session);
+    },
+    async message(ws, message) {
+      const domWs = ws;
+      const session = sessionMap.get(domWs);
+      if (!session) return;
+      try {
+        await dispatchSockaInboundMessage(
+          session,
+          wireFormat,
+          message
+        );
+      } catch (error) {
+        reportSockaError(config.reportError, {
+          kind: "serverInboundMessage",
+          adapter: "bun",
+          error
+        });
+      }
+    },
+    async close(ws) {
+      const domWs = ws;
+      const session = sessionMap.get(domWs);
+      try {
+        if (session) {
+          await session.invokeHandleClose();
+        }
+      } catch (error) {
+        reportSockaError(config.reportError, {
+          kind: "serverHandleClose",
+          error
+        });
+      } finally {
+        sessionMap.delete(domWs);
+      }
+    }
+  };
+  return { sessionMap, websocket, wireFormat };
+}
+function createSockaBunWebSocketHandlers(configOrOptions, maybeOptions) {
+  const isResolveScope = typeof configOrOptions === "object" && configOrOptions !== null && "resolveScope" in configOrOptions && typeof configOrOptions.resolveScope === "function";
+  if (isResolveScope) {
+    return bunHandlersFromResolveScope(
+      configOrOptions.resolveScope
+    );
+  }
+  return bunHandlersFromConfig(
+    configOrOptions,
+    maybeOptions
+  );
+}
+
+export { createSockaBunWebSocketHandlers };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/bun/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bun/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { ServerWebSocket } from \"bun\";\nimport type { SockaContract, SockaContractConfig } from \"../core/contract\";\nimport { reportSockaError } from \"../core/socka-report-error\";\nimport type { SockaWireFormat } from \"../core/wire-codec\";\nimport { dispatchSockaInboundMessage } from \"../server/dispatchSockaInboundMessage\";\nimport {\n\tSockaWebSocketSession,\n\trunSockaSessionOnAttached,\n\ttype SockaWebSocketSessionConfig,\n} from \"../server/SockaWebSocketSession\";\n\nexport type SockaBunResolveScope<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n\tTWsData = undefined,\n> = (ws: ServerWebSocket<TWsData>) => {\n\tsessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;\n\tconfig: SockaWebSocketSessionConfig<TContract, TData>;\n};\n\nexport type SockaBunWebSocketHandlers<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n\tTWsData = undefined,\n> = {\n\tsessionMap: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;\n\t/** Pass into `Bun.serve({ ..., websocket })`. */\n\twebsocket: {\n\t\topen: (ws: ServerWebSocket<TWsData>) => void;\n\t\tmessage: (\n\t\t\tws: ServerWebSocket<TWsData>,\n\t\t\tmessage: unknown,\n\t\t) => void | Promise<void>;\n\t\tclose: (ws: ServerWebSocket<TWsData>) => void | Promise<void>;\n\t};\n\twireFormat: SockaWireFormat;\n};\n\nfunction bunHandlersFromResolveScope<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n\tTWsData,\n>(\n\tresolveScope: SockaBunResolveScope<TContract, TData, TWsData>,\n): SockaBunWebSocketHandlers<TContract, TData, TWsData> {\n\tconst websocket: SockaBunWebSocketHandlers<\n\t\tTContract,\n\t\tTData,\n\t\tTWsData\n\t>[\"websocket\"] = {\n\t\topen(ws: ServerWebSocket<TWsData>) {\n\t\t\tconst { sessionMap, config } = resolveScope(ws);\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = new SockaWebSocketSession(domWs, sessionMap, config);\n\t\t\tsessionMap.set(domWs, session);\n\t\t\trunSockaSessionOnAttached(config, session);\n\t\t},\n\t\tasync message(ws: ServerWebSocket<TWsData>, message: unknown) {\n\t\t\tconst { sessionMap, config } = resolveScope(ws);\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = sessionMap.get(domWs);\n\t\t\tif (!session) return;\n\t\t\tconst wireFormat = config.wireFormat ?? \"json\";\n\t\t\ttry {\n\t\t\t\tawait dispatchSockaInboundMessage(\n\t\t\t\t\tsession,\n\t\t\t\t\twireFormat,\n\t\t\t\t\tmessage as MessageEvent[\"data\"],\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treportSockaError(config.reportError, {\n\t\t\t\t\tkind: \"serverInboundMessage\",\n\t\t\t\t\tadapter: \"bun\",\n\t\t\t\t\terror,\n\t\t\t\t});\n\t\t\t}\n\t\t},\n\t\tasync close(ws: ServerWebSocket<TWsData>) {\n\t\t\tconst { sessionMap, config } = resolveScope(ws);\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = sessionMap.get(domWs);\n\t\t\ttry {\n\t\t\t\tif (session) {\n\t\t\t\t\tawait session.invokeHandleClose();\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\treportSockaError(config.reportError, {\n\t\t\t\t\tkind: \"serverHandleClose\",\n\t\t\t\t\terror,\n\t\t\t\t});\n\t\t\t} finally {\n\t\t\t\tsessionMap.delete(domWs);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn {\n\t\tsessionMap: new Map(),\n\t\twebsocket,\n\t\twireFormat: \"json\",\n\t};\n}\n\nfunction bunHandlersFromConfig<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n>(\n\tconfig: SockaWebSocketSessionConfig<TContract, TData>,\n\tmaybeOptions?: {\n\t\tsessionMap?: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;\n\t},\n): SockaBunWebSocketHandlers<TContract, TData, undefined> {\n\tconst sessionMap =\n\t\tmaybeOptions?.sessionMap ??\n\t\tnew Map<WebSocket, SockaWebSocketSession<TContract, TData>>();\n\tconst wireFormat = config.wireFormat ?? \"json\";\n\n\tconst websocket: SockaBunWebSocketHandlers<\n\t\tTContract,\n\t\tTData,\n\t\tundefined\n\t>[\"websocket\"] = {\n\t\topen(ws: ServerWebSocket<undefined>) {\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = new SockaWebSocketSession(domWs, sessionMap, config);\n\t\t\tsessionMap.set(domWs, session);\n\t\t\trunSockaSessionOnAttached(config, session);\n\t\t},\n\t\tasync message(ws: ServerWebSocket<undefined>, message: unknown) {\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = sessionMap.get(domWs);\n\t\t\tif (!session) return;\n\t\t\ttry {\n\t\t\t\tawait dispatchSockaInboundMessage(\n\t\t\t\t\tsession,\n\t\t\t\t\twireFormat,\n\t\t\t\t\tmessage as MessageEvent[\"data\"],\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treportSockaError(config.reportError, {\n\t\t\t\t\tkind: \"serverInboundMessage\",\n\t\t\t\t\tadapter: \"bun\",\n\t\t\t\t\terror,\n\t\t\t\t});\n\t\t\t}\n\t\t},\n\t\tasync close(ws: ServerWebSocket<undefined>) {\n\t\t\tconst domWs = ws as unknown as WebSocket;\n\t\t\tconst session = sessionMap.get(domWs);\n\t\t\ttry {\n\t\t\t\tif (session) {\n\t\t\t\t\tawait session.invokeHandleClose();\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\treportSockaError(config.reportError, {\n\t\t\t\t\tkind: \"serverHandleClose\",\n\t\t\t\t\terror,\n\t\t\t\t});\n\t\t\t} finally {\n\t\t\t\tsessionMap.delete(domWs);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn { sessionMap, websocket, wireFormat };\n}\n\n/**\n * WebSocket handlers for `Bun.serve` when using `ServerWebSocket` (no\n * `addEventListener`). Inbound frames are dispatched with the same logic as\n * `attachSockaWebSocket`.\n *\n * **Single-room:** pass a {@link SockaWebSocketSessionConfig} and optional shared `sessionMap`.\n *\n * **Multi-room:** pass `{ resolveScope }` where `resolveScope(ws)` returns the\n * `sessionMap` and `config` for that socket’s scope (e.g. from `ws.data.roomId`).\n * The returned `sessionMap` is an empty placeholder; real maps come from `resolveScope`.\n */\nexport function createSockaBunWebSocketHandlers<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n>(\n\tconfig: SockaWebSocketSessionConfig<TContract, TData>,\n\toptions?: {\n\t\tsessionMap?: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;\n\t},\n): SockaBunWebSocketHandlers<TContract, TData, undefined>;\n\nexport function createSockaBunWebSocketHandlers<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n\tTWsData,\n>(options: {\n\tresolveScope: SockaBunResolveScope<TContract, TData, TWsData>;\n}): SockaBunWebSocketHandlers<TContract, TData, TWsData>;\n\nexport function createSockaBunWebSocketHandlers<\n\tTContract extends SockaContract<SockaContractConfig>,\n\tTData,\n>(\n\tconfigOrOptions:\n\t\t| SockaWebSocketSessionConfig<TContract, TData>\n\t\t| { resolveScope: SockaBunResolveScope<TContract, TData, unknown> },\n\tmaybeOptions?: {\n\t\tsessionMap?: Map<WebSocket, SockaWebSocketSession<TContract, TData>>;\n\t},\n):\n\t| SockaBunWebSocketHandlers<TContract, TData, undefined>\n\t| SockaBunWebSocketHandlers<TContract, TData, unknown> {\n\tconst isResolveScope =\n\t\ttypeof configOrOptions === \"object\" &&\n\t\tconfigOrOptions !== null &&\n\t\t\"resolveScope\" in configOrOptions &&\n\t\ttypeof (configOrOptions as { resolveScope: unknown }).resolveScope ===\n\t\t\t\"function\";\n\n\tif (isResolveScope) {\n\t\treturn bunHandlersFromResolveScope(\n\t\t\t(\n\t\t\t\tconfigOrOptions as {\n\t\t\t\t\tresolveScope: SockaBunResolveScope<TContract, TData, unknown>;\n\t\t\t\t}\n\t\t\t).resolveScope,\n\t\t);\n\t}\n\treturn bunHandlersFromConfig(\n\t\tconfigOrOptions as SockaWebSocketSessionConfig<TContract, TData>,\n\t\tmaybeOptions,\n\t);\n}\n"]}

package/dist/chunk-45D4T232.js

@@ -0,0 +1,236 @@
+import { parseWirePayload, decodeSockaWire, SockaWireError, encodeServerError, parseStandardSchema, SockaError, encodeServerResponse, encodeSockaWire, encodeServerEvent, reportSockaError } from './chunk-MZCQHJXY.js';
+import { exhaustiveGuard } from '@firtoz/maybe-error';
+
+function broadcastSockaEventToPeers(sessions, self, event, body, excludeSelf = false) {
+  for (const [ws, session] of sessions) {
+    if (excludeSelf && ws === self.websocket) continue;
+    session.emitWireEvent(event, body);
+  }
+}
+var SockaWebSocketSession = class {
+  constructor(websocket, sessions, config, init) {
+    this.websocket = websocket;
+    this.sessions = sessions;
+    this.config = config;
+    this.wireFormat = config.wireFormat ?? "json";
+    const create = config.createData ?? ((_i) => ({}));
+    this._data = create(init ?? {});
+  }
+  get data() {
+    return this._data;
+  }
+  /**
+   * 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.
+   */
+  async invokeHandleClose() {
+    await this.config.handleClose(this);
+  }
+  async handleRawMessage(rawMessage) {
+    if (this.wireFormat !== "json") {
+      await this.reportValidationError(
+        new Error("socka: unexpected JSON frame in msgpack mode"),
+        rawMessage
+      );
+      return;
+    }
+    const deserialize = this.config.deserializeJson ?? JSON.parse;
+    let parsed;
+    try {
+      parsed = deserialize(rawMessage);
+    } catch {
+      await this.reportValidationError(
+        new Error("socka: invalid JSON"),
+        rawMessage
+      );
+      return;
+    }
+    await this.dispatchAfterParsed(parsed, rawMessage);
+  }
+  async handleBinaryMessage(buffer) {
+    if (this.wireFormat !== "msgpack") {
+      await this.reportValidationError(
+        new Error("socka: unexpected binary frame in JSON mode"),
+        buffer
+      );
+      return;
+    }
+    let parsed;
+    try {
+      parsed = parseWirePayload(buffer, "msgpack");
+    } catch (err) {
+      await this.reportValidationError(
+        err instanceof Error ? err : new Error("socka: msgpack decode failed"),
+        buffer
+      );
+      return;
+    }
+    await this.dispatchAfterParsed(parsed, buffer);
+  }
+  async dispatchAfterParsed(parsed, originalWire) {
+    let decoded;
+    try {
+      decoded = decodeSockaWire(parsed);
+    } catch (err) {
+      if (err instanceof SockaWireError) {
+        await this.reportValidationError(err, originalWire);
+        return;
+      }
+      throw err;
+    }
+    switch (decoded.kind) {
+      case "clientRequest":
+        await this.dispatchClientRequest(decoded.frame, originalWire);
+        return;
+      case "serverResponse":
+      case "serverError":
+      case "serverEvent":
+        await this.reportValidationError(
+          new Error("socka: unexpected server-originated frame from client"),
+          parsed
+        );
+        return;
+      default:
+        exhaustiveGuard(decoded);
+    }
+  }
+  async dispatchClientRequest(frame, _originalWire) {
+    const rpcName = frame.rpc;
+    const procedure = this.config.contract.calls[rpcName];
+    if (!procedure) {
+      const errorFrame = encodeServerError(
+        frame.id,
+        `Unknown call: ${rpcName}`
+      );
+      this.sendWireFrame(errorFrame);
+      return;
+    }
+    let validatedInput;
+    if (procedure.input) {
+      try {
+        validatedInput = await parseStandardSchema(procedure.input, frame.body);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Input validation failed";
+        const errorFrame = encodeServerError(frame.id, msg);
+        this.sendWireFrame(errorFrame);
+        return;
+      }
+    }
+    let result;
+    try {
+      if (procedure.input) {
+        const handler = this.config.handlers[rpcName];
+        result = await handler(validatedInput, this);
+      } else {
+        const handler = this.config.handlers[rpcName];
+        result = await handler(this);
+      }
+    } catch (err) {
+      this.config.onHandlerError?.(err, rpcName, validatedInput, this);
+      const sockaErr = err instanceof SockaError ? err : new SockaError(
+        err instanceof Error ? err.message : "Handler failed"
+      );
+      const errorFrame = encodeServerError(frame.id, sockaErr.message);
+      this.sendWireFrame(errorFrame);
+      return;
+    }
+    let validatedOutput;
+    try {
+      validatedOutput = await parseStandardSchema(procedure.output, result);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Output validation failed";
+      const errorFrame = encodeServerError(frame.id, msg);
+      this.sendWireFrame(errorFrame);
+      return;
+    }
+    const responseFrame = encodeServerResponse(
+      frame.id,
+      rpcName,
+      validatedOutput
+    );
+    this.sendWireFrame(responseFrame);
+  }
+  encodeOutgoing(frame) {
+    return encodeSockaWire(
+      frame,
+      this.wireFormat,
+      this.config.serializeJson ?? JSON.stringify
+    );
+  }
+  sendWireFrame(frame) {
+    if (this.websocket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const encoded = this.encodeOutgoing(frame);
+    if (typeof encoded === "string") {
+      this.websocket.send(encoded);
+      return;
+    }
+    const copy = new Uint8Array(encoded.byteLength);
+    copy.set(encoded);
+    this.websocket.send(copy.buffer);
+  }
+  /**
+   * Send a server event frame (wire). Prefer {@link emitPush} so
+   * payloads are validated against the contract.
+   */
+  emitWireEvent(event, body) {
+    const frame = encodeServerEvent(event, body);
+    this.sendWireFrame(frame);
+  }
+  async emitPush(name, body) {
+    const schema = this.config.contract.pushes[name];
+    if (!schema) {
+      throw new Error(`socka: unknown push ${String(name)}`);
+    }
+    const validated = await parseStandardSchema(
+      schema,
+      body
+    );
+    this.emitWireEvent(name, validated);
+  }
+  async broadcastPush(name, body, excludeSelf = false) {
+    const schema = this.config.contract.pushes[name];
+    if (!schema) {
+      throw new Error(`socka: unknown push ${String(name)}`);
+    }
+    const validated = await parseStandardSchema(
+      schema,
+      body
+    );
+    broadcastSockaEventToPeers(
+      this.sessions,
+      this,
+      name,
+      validated,
+      excludeSelf
+    );
+  }
+  async reportValidationError(error, originalMessage) {
+    if (this.config.onValidationError) {
+      await this.config.onValidationError(error, originalMessage);
+    } else {
+      console.error("socka: validation error:", error, originalMessage);
+    }
+  }
+};
+function runSockaSessionOnAttached(config, session) {
+  const cb = config.onAttached;
+  if (!cb) return;
+  try {
+    const result = cb(session);
+    void Promise.resolve(result).catch((error) => {
+      reportSockaError(config.reportError, {
+        kind: "serverOnAttached",
+        error
+      });
+    });
+  } catch (error) {
+    reportSockaError(config.reportError, { kind: "serverOnAttached", error });
+  }
+}
+
+export { SockaWebSocketSession, broadcastSockaEventToPeers, runSockaSessionOnAttached };
+//# sourceMappingURL=chunk-45D4T232.js.map
+//# sourceMappingURL=chunk-45D4T232.js.map