@kyneta/websocket-transport 1.3.0 → 1.4.0

package/README.md

@@ -1,14 +1,14 @@
-# @kyneta/websocket-network-adapter
+# @kyneta/websocket-transport
 
-Websocket adapter for `@kyneta/exchange` — client, server, and Bun integration. Provides bidirectional real-time sync over Websockets using the `@kyneta/wire` binary protocol (CBOR codec + framing + fragmentation).
+Websocket transport for `@kyneta/exchange` — browser, server, and Bun integration. Provides bidirectional real-time sync over Websockets using the `@kyneta/wire` binary protocol (CBOR codec + framing + fragmentation).
 
 ## Subpath Exports
 
 | Export | Entry point | Environment |
 |--------|-------------|-------------|
-| `@kyneta/websocket-network-adapter/client` | `./dist/client.js` | Browser, Bun, Node.js |
-| `@kyneta/websocket-network-adapter/server` | `./dist/server.js` | Bun, Node.js |
-| `@kyneta/websocket-network-adapter/bun` | `./dist/bun.js` | Bun only |
+| `@kyneta/websocket-transport/browser` | `./dist/browser.js` | Browser, Bun, Node.js |
+| `@kyneta/websocket-transport/server` | `./dist/server.js` | Bun, Node.js |
+| `@kyneta/websocket-transport/bun` | `./dist/bun.js` | Bun only |
 
 ## Server Setup
 
@@ -18,8 +18,8 @@ Use `createBunWebsocketHandlers` for zero-boilerplate integration with `Bun.serv
 
 ```/dev/null/bun-server.ts#L1-18
 import { Exchange } from "@kyneta/exchange"
-import { WebsocketServerAdapter } from "@kyneta/websocket-network-adapter/server"
-import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+import { WebsocketServerAdapter } from "@kyneta/websocket-transport/server"
+import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
 
 const serverAdapter = new WebsocketServerAdapter()
 
@@ -40,7 +40,7 @@ Bun.serve<BunWebsocketData>({
 For more control, use `wrapBunWebsocket` directly:
 
 ```/dev/null/bun-server-manual.ts#L1-17
-import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
 
 Bun.serve<BunWebsocketData>({
   fetch(req, server) {
@@ -69,7 +69,7 @@ Use `wrapNodeWebsocket` to adapt the `ws` library's `WebSocket` to the framework
 
 ```/dev/null/node-server.ts#L1-16
 import { WebSocketServer } from "ws"
-import { WebsocketServerAdapter, wrapNodeWebsocket } from "@kyneta/websocket-network-adapter/server"
+import { WebsocketServerAdapter, wrapNodeWebsocket } from "@kyneta/websocket-transport/server"
 
 const serverAdapter = new WebsocketServerAdapter()
 
@@ -92,12 +92,13 @@ wss.on("connection", (ws) => {
 
 Use `createWebsocketClient` for browser-to-server connections:
 
-```/dev/null/browser-client.ts#L1-12
+```/dev/null/browser-client.ts#L1-13
 import { Exchange } from "@kyneta/exchange"
-import { createWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
 
 const adapter = createWebsocketClient({
   url: "ws://localhost:3000/ws",
+  WebSocket,
   reconnect: { enabled: true },
 })
 
@@ -112,7 +113,7 @@ const exchange = new Exchange({
 Use `createServiceWebsocketClient` for backend connections that need authentication headers during the Websocket upgrade. Headers are a Bun/Node-specific extension — the browser `WebSocket` API does not support custom headers.
 
 ```/dev/null/service-client.ts#L1-13
-import { createServiceWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+import { createServiceWebsocketClient } from "@kyneta/websocket-transport/server"
 
 const adapter = createServiceWebsocketClient({
   url: "ws://primary-server:3000/ws",
@@ -180,7 +181,7 @@ The server may send `"ready"` before the client's `open` event fires (server-rea
 The public observation API is powered by `createObservableProgram` from `@kyneta/machine`:
 
 ```/dev/null/observe-state.ts#L1-18
-import { createWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
 
 const adapter = createWebsocketClient({
   url: "ws://localhost:3000/ws",
@@ -207,7 +208,7 @@ await adapter.waitForStatus("ready", { timeoutMs: 5000 })
 
 | Wrapper | Input | Export |
 |---------|-------|--------|
-| `wrapStandardWebsocket(ws)` | Browser `WebSocket` | `./client`, `./server` |
+| `wrapStandardWebsocket(ws)` | Browser `WebSocket` | `./server` |
 | `wrapNodeWebsocket(ws)` | Node.js `ws` library | `./server` |
 | `wrapBunWebsocket(ws)` | Bun `ServerWebSocket` | `./bun` |
 
@@ -229,7 +230,7 @@ interface Socket {
 | Option | Default | Description |
 |--------|---------|-------------|
 | `url` | — | Websocket URL. String or `(peerId) => string` function. |
-| `WebSocket` | `globalThis.WebSocket` | Custom WebSocket constructor (for Node.js or testing). |
+| `WebSocket` | — | WebSocket constructor (**required**). In browsers, pass `WebSocket`. In Node.js, pass `ws`'s `WebSocket`. |
 | `reconnect.enabled` | `true` | Enable automatic reconnection. |
 | `reconnect.maxAttempts` | `10` | Maximum reconnection attempts before giving up. |
 | `reconnect.baseDelay` | `1000` | Base delay in ms for exponential backoff. |
@@ -256,6 +257,18 @@ interface Socket {
 
 The client sends text `"ping"` frames at the configured interval. The server responds with text `"pong"`. This keeps connections alive through proxies and load balancers that terminate idle connections.
 
+## Runtime Agnosticism
+
+Every entry point (`./browser`, `./server`, `./bun`) is safe to import in any JavaScript runtime — no top-level side effects, no `globalThis` probes. The transport package has zero runtime dependencies; callers provide all implementations:
+
+| Entry Point | Purpose | Caller Provides |
+|-------------|---------|----------------|
+| `./browser` | Browser-to-server connections | `WebSocket` constructor (the global `WebSocket` in browsers) |
+| `./server` | Server transport + service-to-service client | `Socket` wrapper via `wrapNodeWebsocket()` or `wrapStandardWebsocket()` |
+| `./bun` | Bun-optimized server handlers | `ServerWebSocket` from Bun's callback API |
+
+This follows the same structural-typing principle used throughout: `wrapNodeWebsocket` takes a `NodeWebsocketLike` — it never imports `ws`. `wrapBunWebsocket` takes a Bun `ServerWebSocket` — it never imports Bun APIs at the top level.
+
 ## Peer Dependencies
 
 ```/dev/null/package.json#L1-4

package/dist/browser.d.ts

@@ -0,0 +1,59 @@
+import { a as SocketReadyState, c as WebSocketConstructor, d as WebsocketClientState, f as WebsocketClientStateTransition, i as Socket, l as WebSocketLike, o as TransitionListener, r as READY_STATE, s as WebSocketCloseEvent, t as DisconnectReason, u as WebSocketMessageEvent } from "./types-CJAcr1Df.js";
+import { a as createWebsocketClient, i as WebsocketClientTransport, n as WebsocketClientLifecycleEvents, r as WebsocketClientOptions, t as DEFAULT_FRAGMENT_THRESHOLD } from "./client-transport-CKjXedwS.js";
+import { ReconnectOptions } from "@kyneta/transport";
+import { Program } from "@kyneta/machine";
+
+//#region src/client-program.d.ts
+type WsClientMsg = {
+  type: "start";
+} | {
+  type: "socket-opened";
+} | {
+  type: "server-ready";
+} | {
+  type: "socket-closed";
+  code: number;
+  reason: string;
+} | {
+  type: "socket-error";
+  error: Error;
+} | {
+  type: "reconnect-timer-fired";
+} | {
+  type: "stop";
+};
+type WsClientEffect = {
+  type: "create-websocket";
+  attempt: number;
+} | {
+  type: "close-websocket";
+} | {
+  type: "add-channel-and-establish";
+} | {
+  type: "remove-channel";
+} | {
+  type: "start-reconnect-timer";
+  delayMs: number;
+} | {
+  type: "cancel-reconnect-timer";
+} | {
+  type: "start-keepalive";
+} | {
+  type: "stop-keepalive";
+};
+interface WsClientProgramOptions {
+  reconnect?: Partial<ReconnectOptions>;
+  /** Inject jitter source for deterministic testing. Default: () => Math.random() * 1000 */
+  jitterFn?: () => number;
+}
+/**
+ * Create the websocket client connection lifecycle program — a pure Mealy machine.
+ *
+ * The returned `Program<WsClientMsg, WebsocketClientState, WsClientEffect>`
+ * encodes every state transition and effect as inspectable data. The imperative
+ * shell interprets `WsClientEffect` as actual I/O.
+ */
+declare function createWsClientProgram(options?: WsClientProgramOptions): Program<WsClientMsg, WebsocketClientState, WsClientEffect>;
+//#endregion
+export { DEFAULT_FRAGMENT_THRESHOLD, type DisconnectReason, READY_STATE, type Socket, type SocketReadyState, type TransitionListener, type WebSocketCloseEvent, type WebSocketConstructor, type WebSocketLike, type WebSocketMessageEvent, type WebsocketClientLifecycleEvents, type WebsocketClientOptions, type WebsocketClientState, type WebsocketClientStateTransition, WebsocketClientTransport, type WsClientEffect, type WsClientMsg, type WsClientProgramOptions, createWebsocketClient, createWsClientProgram };
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","names":[],"sources":["../src/client-program.ts"],"mappings":";;;;;;KA4BY,WAAA;EACN,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAAuB,IAAA;EAAc,MAAA;AAAA;EACrC,IAAA;EAAsB,KAAA,EAAO,KAAA;AAAA;EAC7B,IAAA;AAAA;EACA,IAAA;AAAA;AAAA,KAMM,cAAA;EACN,IAAA;EAA0B,OAAA;AAAA;EAC1B,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;EAA+B,OAAA;AAAA;EAC/B,IAAA;AAAA;EACA,IAAA;AAAA;EACA,IAAA;AAAA;AAAA,UAMW,sBAAA;EACf,SAAA,GAAY,OAAA,CAAQ,gBAAA;EAAD;EAEnB,QAAA;AAAA;;;;;AAUF;;;iBAAgB,qBAAA,CACd,OAAA,GAAS,sBAAA,GACR,OAAA,CAAQ,WAAA,EAAa,oBAAA,EAAsB,cAAA"}

package/dist/browser.js

@@ -0,0 +1,2 @@
+import { i as READY_STATE, n as WebsocketClientTransport, r as createWebsocketClient, s as createWsClientProgram, t as DEFAULT_FRAGMENT_THRESHOLD } from "./client-transport-DIZ-LJxs.js";
+export { DEFAULT_FRAGMENT_THRESHOLD, READY_STATE, WebsocketClientTransport, createWebsocketClient, createWsClientProgram };

package/dist/bun.d.ts

@@ -1,8 +1,7 @@
-import { ServerWebSocket } from 'bun';
-import { S as Socket } from './types-DdNb8cAz.js';
-export { D as DisconnectReason, a as SocketReadyState } from './types-DdNb8cAz.js';
-import '@kyneta/transport';
+import { a as SocketReadyState, i as Socket, t as DisconnectReason } from "./types-CJAcr1Df.js";
+import { ServerWebSocket } from "bun";
 
+//#region src/bun-websocket.d.ts
 /**
  * Data structure stored in `ws.data` for handler callbacks.
  * Use this type when defining your `Bun.serve()` generic.
@@ -15,10 +14,10 @@ import '@kyneta/transport';
  * ```
  */
 type BunWebsocketData = {
-    handlers: {
-        onMessage?: (data: Uint8Array | string) => void;
-        onClose?: (code: number, reason: string) => void;
-    };
+  handlers: {
+    onMessage?: (data: Uint8Array | string) => void;
+    onClose?: (code: number, reason: string) => void;
+  };
 };
 /**
  * Wrap Bun's `ServerWebSocket` to match the `Socket` interface.
@@ -30,8 +29,8 @@ type BunWebsocketData = {
  *
  * @example
  * ```typescript
- * import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
- * import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+ * import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+ * import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
  *
  * const serverAdapter = new WebsocketServerTransport()
  *
@@ -62,8 +61,8 @@ declare function wrapBunWebsocket(ws: ServerWebSocket<BunWebsocketData>): Socket
  *
  * @example
  * ```typescript
- * import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
- * import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+ * import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+ * import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
  *
  * const serverAdapter = new WebsocketServerTransport()
  *
@@ -77,15 +76,16 @@ declare function wrapBunWebsocket(ws: ServerWebSocket<BunWebsocketData>): Socket
  * ```
  */
 declare function createBunWebsocketHandlers(wsAdapter: {
-    handleConnection: (opts: {
-        socket: Socket;
-    }) => {
-        start: () => void;
-    };
+  handleConnection: (opts: {
+    socket: Socket;
+  }) => {
+    start: () => void;
+  };
 }): {
-    open(ws: ServerWebSocket<BunWebsocketData>): void;
-    message(ws: ServerWebSocket<BunWebsocketData>, msg: string | ArrayBuffer | Buffer): void;
-    close(ws: ServerWebSocket<BunWebsocketData>, code: number, reason: string): void;
+  open(ws: ServerWebSocket<BunWebsocketData>): void;
+  message(ws: ServerWebSocket<BunWebsocketData>, msg: string | ArrayBuffer | Buffer): void;
+  close(ws: ServerWebSocket<BunWebsocketData>, code: number, reason: string): void;
 };
-
-export { type BunWebsocketData, Socket, createBunWebsocketHandlers, wrapBunWebsocket };
+//#endregion
+export { type BunWebsocketData, type DisconnectReason, type Socket, type SocketReadyState, createBunWebsocketHandlers, wrapBunWebsocket };
+//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","names":[],"sources":["../src/bun-websocket.ts"],"mappings":";;;;;;AA+BA;;;;;;;;;KAAY,gBAAA;EACV,QAAA;IACE,SAAA,IAAa,IAAA,EAAM,UAAA;IACnB,OAAA,IAAW,IAAA,UAAc,MAAA;EAAA;AAAA;;;;;;;;;;;;;AAyG7B;;;;;;;;;;;;;;;;;;;;iBAjEgB,gBAAA,CACd,EAAA,EAAI,eAAA,CAAgB,gBAAA,IACnB,MAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA+Da,0BAAA,CAA2B,SAAA;EACzC,gBAAA,GAAmB,IAAA;IAAQ,MAAA,EAAQ,MAAA;EAAA;IAAe,KAAA;EAAA;AAAA;WAGvC,eAAA,CAAgB,gBAAA;cAInB,eAAA,CAAgB,gBAAA,GAAiB,GAAA,WACvB,WAAA,GAAc,MAAA;YAUpB,eAAA,CAAgB,gBAAA,GAAiB,IAAA,UAAc,MAAA;AAAA"}

package/dist/bun.js

@@ -1,48 +1,100 @@
-// src/bun-websocket.ts
+//#region src/bun-websocket.ts
+/**
+* Wrap Bun's `ServerWebSocket` to match the `Socket` interface.
+*
+* Bun's WebSocket API uses server-level callbacks (`websocket: { message, close }`)
+* rather than per-socket event handlers. This wrapper bridges that gap by
+* storing handlers in `ws.data` and having the server-level callbacks delegate
+* to them.
+*
+* @example
+* ```typescript
+* import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+* import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
+*
+* const serverAdapter = new WebsocketServerTransport()
+*
+* Bun.serve<BunWebsocketData>({
+*   websocket: {
+*     open(ws) {
+*       const socket = wrapBunWebsocket(ws)
+*       serverAdapter.handleConnection({ socket }).start()
+*     },
+*     message(ws, msg) {
+*       const data = msg instanceof ArrayBuffer ? new Uint8Array(msg) : msg
+*       ws.data?.handlers?.onMessage?.(data)
+*     },
+*     close(ws, code, reason) {
+*       ws.data?.handlers?.onClose?.(code, reason)
+*     },
+*   },
+* })
+* ```
+*/
 function wrapBunWebsocket(ws) {
-  ws.data = { handlers: {} };
-  return {
-    send(data) {
-      ws.send(data);
-    },
-    close(code, reason) {
-      ws.close(code, reason);
-    },
-    onMessage(handler) {
-      ws.data.handlers.onMessage = handler;
-    },
-    onClose(handler) {
-      ws.data.handlers.onClose = handler;
-    },
-    onError(_handler) {
-    },
-    get readyState() {
-      const states = [
-        "connecting",
-        "open",
-        "closing",
-        "closed"
-      ];
-      return states[ws.readyState] ?? "closed";
-    }
-  };
+	ws.data = { handlers: {} };
+	return {
+		send(data) {
+			ws.send(data);
+		},
+		close(code, reason) {
+			ws.close(code, reason);
+		},
+		onMessage(handler) {
+			ws.data.handlers.onMessage = handler;
+		},
+		onClose(handler) {
+			ws.data.handlers.onClose = handler;
+		},
+		onError(_handler) {},
+		get readyState() {
+			return [
+				"connecting",
+				"open",
+				"closing",
+				"closed"
+			][ws.readyState] ?? "closed";
+		}
+	};
 }
+/**
+* Create Bun Websocket handlers that integrate with `WebsocketServerTransport`.
+*
+* This helper eliminates boilerplate by providing pre-configured handlers
+* for `open`, `message`, and `close` events that automatically wire up
+* to the adapter's `handleConnection()` method.
+*
+* @example
+* ```typescript
+* import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+* import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
+*
+* const serverAdapter = new WebsocketServerTransport()
+*
+* Bun.serve<BunWebsocketData>({
+*   fetch(req, server) {
+*     server.upgrade(req)
+*     return new Response("upgrade failed", { status: 400 })
+*   },
+*   websocket: createBunWebsocketHandlers(serverAdapter),
+* })
+* ```
+*/
 function createBunWebsocketHandlers(wsAdapter) {
-  return {
-    open(ws) {
-      wsAdapter.handleConnection({ socket: wrapBunWebsocket(ws) }).start();
-    },
-    message(ws, msg) {
-      const data = msg instanceof ArrayBuffer ? new Uint8Array(msg) : Buffer.isBuffer(msg) ? new Uint8Array(msg) : msg;
-      ws.data.handlers.onMessage?.(data);
-    },
-    close(ws, code, reason) {
-      ws.data.handlers.onClose?.(code, reason);
-    }
-  };
+	return {
+		open(ws) {
+			wsAdapter.handleConnection({ socket: wrapBunWebsocket(ws) }).start();
+		},
+		message(ws, msg) {
+			const data = msg instanceof ArrayBuffer ? new Uint8Array(msg) : Buffer.isBuffer(msg) ? new Uint8Array(msg) : msg;
+			ws.data.handlers.onMessage?.(data);
+		},
+		close(ws, code, reason) {
+			ws.data.handlers.onClose?.(code, reason);
+		}
+	};
 }
-export {
-  createBunWebsocketHandlers,
-  wrapBunWebsocket
-};
+//#endregion
+export { createBunWebsocketHandlers, wrapBunWebsocket };
+
 //# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/bun-websocket.ts"],"sourcesContent":["// bun-websocket — Bun-specific Websocket wrapper for @kyneta/websocket-network-adapter.\n//\n// Provides a wrapper to adapt Bun's ServerWebSocket to the Socket interface\n// expected by WebsocketServerTransport.\n//\n// Bun's WebSocket API is callback-based at the server level (not per-socket),\n// so we bridge that gap by storing handlers in ws.data.\n//\n// Ported from @loro-extended/adapter-websocket's bun.ts with kyneta\n// naming conventions applied.\n\n/// <reference types=\"bun-types\" />\n\nimport type { ServerWebSocket } from \"bun\"\nimport type { Socket, SocketReadyState } from \"./types.js\"\n\n// ---------------------------------------------------------------------------\n// BunWebsocketData — stored in ws.data for per-socket handler callbacks\n// ---------------------------------------------------------------------------\n\n/**\n * Data structure stored in `ws.data` for handler callbacks.\n * Use this type when defining your `Bun.serve()` generic.\n *\n * @example\n * ```typescript\n * Bun.serve<BunWebsocketData>({\n *   websocket: { ... }\n * })\n * ```\n */\nexport type BunWebsocketData = {\n  handlers: {\n    onMessage?: (data: Uint8Array | string) => void\n    onClose?: (code: number, reason: string) => void\n  }\n}\n\n// ---------------------------------------------------------------------------\n// wrapBunWebsocket\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap Bun's `ServerWebSocket` to match the `Socket` interface.\n *\n * Bun's WebSocket API uses server-level callbacks (`websocket: { message, close }`)\n * rather than per-socket event handlers. This wrapper bridges that gap by\n * storing handlers in `ws.data` and having the server-level callbacks delegate\n * to them.\n *\n * @example\n * ```typescript\n * import { WebsocketServerTransport } from \"@kyneta/websocket-network-adapter/server\"\n * import { wrapBunWebsocket, type BunWebsocketData } from \"@kyneta/websocket-network-adapter/bun\"\n *\n * const serverAdapter = new WebsocketServerTransport()\n *\n * Bun.serve<BunWebsocketData>({\n *   websocket: {\n *     open(ws) {\n *       const socket = wrapBunWebsocket(ws)\n *       serverAdapter.handleConnection({ socket }).start()\n *     },\n *     message(ws, msg) {\n *       const data = msg instanceof ArrayBuffer ? new Uint8Array(msg) : msg\n *       ws.data?.handlers?.onMessage?.(data)\n *     },\n *     close(ws, code, reason) {\n *       ws.data?.handlers?.onClose?.(code, reason)\n *     },\n *   },\n * })\n * ```\n */\nexport function wrapBunWebsocket(\n  ws: ServerWebSocket<BunWebsocketData>,\n): Socket {\n  ws.data = { handlers: {} }\n\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(data)\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.data.handlers.onMessage = handler\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.data.handlers.onClose = handler\n    },\n\n    onError(_handler: (error: Error) => void): void {\n      // Bun handles errors at the server level, not per-socket\n    },\n\n    get readyState(): SocketReadyState {\n      const states: SocketReadyState[] = [\n        \"connecting\",\n        \"open\",\n        \"closing\",\n        \"closed\",\n      ]\n      return states[ws.readyState] ?? \"closed\"\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// createBunWebsocketHandlers\n// ---------------------------------------------------------------------------\n\n/**\n * Create Bun Websocket handlers that integrate with `WebsocketServerTransport`.\n *\n * This helper eliminates boilerplate by providing pre-configured handlers\n * for `open`, `message`, and `close` events that automatically wire up\n * to the adapter's `handleConnection()` method.\n *\n * @example\n * ```typescript\n * import { WebsocketServerTransport } from \"@kyneta/websocket-network-adapter/server\"\n * import { createBunWebsocketHandlers, type BunWebsocketData } from \"@kyneta/websocket-network-adapter/bun\"\n *\n * const serverAdapter = new WebsocketServerTransport()\n *\n * Bun.serve<BunWebsocketData>({\n *   fetch(req, server) {\n *     server.upgrade(req)\n *     return new Response(\"upgrade failed\", { status: 400 })\n *   },\n *   websocket: createBunWebsocketHandlers(serverAdapter),\n * })\n * ```\n */\nexport function createBunWebsocketHandlers(wsAdapter: {\n  handleConnection: (opts: { socket: Socket }) => { start: () => void }\n}) {\n  return {\n    open(ws: ServerWebSocket<BunWebsocketData>) {\n      wsAdapter.handleConnection({ socket: wrapBunWebsocket(ws) }).start()\n    },\n    message(\n      ws: ServerWebSocket<BunWebsocketData>,\n      msg: string | ArrayBuffer | Buffer,\n    ) {\n      const data =\n        msg instanceof ArrayBuffer\n          ? new Uint8Array(msg)\n          : Buffer.isBuffer(msg)\n            ? new Uint8Array(msg)\n            : msg\n      ws.data.handlers.onMessage?.(data)\n    },\n    close(ws: ServerWebSocket<BunWebsocketData>, code: number, reason: string) {\n      ws.data.handlers.onClose?.(code, reason)\n    },\n  }\n}\n"],"mappings":";AA0EO,SAAS,iBACd,IACQ;AACR,KAAG,OAAO,EAAE,UAAU,CAAC,EAAE;AAEzB,SAAO;AAAA,IACL,KAAK,MAAiC;AACpC,SAAG,KAAK,IAAI;AAAA,IACd;AAAA,IAEA,MAAM,MAAe,QAAuB;AAC1C,SAAG,MAAM,MAAM,MAAM;AAAA,IACvB;AAAA,IAEA,UAAU,SAAoD;AAC5D,SAAG,KAAK,SAAS,YAAY;AAAA,IAC/B;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,KAAK,SAAS,UAAU;AAAA,IAC7B;AAAA,IAEA,QAAQ,UAAwC;AAAA,IAEhD;AAAA,IAEA,IAAI,aAA+B;AACjC,YAAM,SAA6B;AAAA,QACjC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AACA,aAAO,OAAO,GAAG,UAAU,KAAK;AAAA,IAClC;AAAA,EACF;AACF;AA6BO,SAAS,2BAA2B,WAExC;AACD,SAAO;AAAA,IACL,KAAK,IAAuC;AAC1C,gBAAU,iBAAiB,EAAE,QAAQ,iBAAiB,EAAE,EAAE,CAAC,EAAE,MAAM;AAAA,IACrE;AAAA,IACA,QACE,IACA,KACA;AACA,YAAM,OACJ,eAAe,cACX,IAAI,WAAW,GAAG,IAClB,OAAO,SAAS,GAAG,IACjB,IAAI,WAAW,GAAG,IAClB;AACR,SAAG,KAAK,SAAS,YAAY,IAAI;AAAA,IACnC;AAAA,IACA,MAAM,IAAuC,MAAc,QAAgB;AACzE,SAAG,KAAK,SAAS,UAAU,MAAM,MAAM;AAAA,IACzC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"file":"bun.js","names":[],"sources":["../src/bun-websocket.ts"],"sourcesContent":["// bun-websocket — Bun-specific Websocket wrapper for @kyneta/websocket-transport.\n//\n// Provides a wrapper to adapt Bun's ServerWebSocket to the Socket interface\n// expected by WebsocketServerTransport.\n//\n// Bun's WebSocket API is callback-based at the server level (not per-socket),\n// so we bridge that gap by storing handlers in ws.data.\n//\n// Ported from @loro-extended/adapter-websocket's bun.ts with kyneta\n// naming conventions applied.\n\n/// <reference types=\"bun-types\" />\n\nimport type { ServerWebSocket } from \"bun\"\nimport type { Socket, SocketReadyState } from \"./types.js\"\n\n// ---------------------------------------------------------------------------\n// BunWebsocketData — stored in ws.data for per-socket handler callbacks\n// ---------------------------------------------------------------------------\n\n/**\n * Data structure stored in `ws.data` for handler callbacks.\n * Use this type when defining your `Bun.serve()` generic.\n *\n * @example\n * ```typescript\n * Bun.serve<BunWebsocketData>({\n *   websocket: { ... }\n * })\n * ```\n */\nexport type BunWebsocketData = {\n  handlers: {\n    onMessage?: (data: Uint8Array | string) => void\n    onClose?: (code: number, reason: string) => void\n  }\n}\n\n// ---------------------------------------------------------------------------\n// wrapBunWebsocket\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap Bun's `ServerWebSocket` to match the `Socket` interface.\n *\n * Bun's WebSocket API uses server-level callbacks (`websocket: { message, close }`)\n * rather than per-socket event handlers. This wrapper bridges that gap by\n * storing handlers in `ws.data` and having the server-level callbacks delegate\n * to them.\n *\n * @example\n * ```typescript\n * import { WebsocketServerTransport } from \"@kyneta/websocket-transport/server\"\n * import { wrapBunWebsocket, type BunWebsocketData } from \"@kyneta/websocket-transport/bun\"\n *\n * const serverAdapter = new WebsocketServerTransport()\n *\n * Bun.serve<BunWebsocketData>({\n *   websocket: {\n *     open(ws) {\n *       const socket = wrapBunWebsocket(ws)\n *       serverAdapter.handleConnection({ socket }).start()\n *     },\n *     message(ws, msg) {\n *       const data = msg instanceof ArrayBuffer ? new Uint8Array(msg) : msg\n *       ws.data?.handlers?.onMessage?.(data)\n *     },\n *     close(ws, code, reason) {\n *       ws.data?.handlers?.onClose?.(code, reason)\n *     },\n *   },\n * })\n * ```\n */\nexport function wrapBunWebsocket(\n  ws: ServerWebSocket<BunWebsocketData>,\n): Socket {\n  ws.data = { handlers: {} }\n\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(data)\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.data.handlers.onMessage = handler\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.data.handlers.onClose = handler\n    },\n\n    onError(_handler: (error: Error) => void): void {\n      // Bun handles errors at the server level, not per-socket\n    },\n\n    get readyState(): SocketReadyState {\n      const states: SocketReadyState[] = [\n        \"connecting\",\n        \"open\",\n        \"closing\",\n        \"closed\",\n      ]\n      return states[ws.readyState] ?? \"closed\"\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// createBunWebsocketHandlers\n// ---------------------------------------------------------------------------\n\n/**\n * Create Bun Websocket handlers that integrate with `WebsocketServerTransport`.\n *\n * This helper eliminates boilerplate by providing pre-configured handlers\n * for `open`, `message`, and `close` events that automatically wire up\n * to the adapter's `handleConnection()` method.\n *\n * @example\n * ```typescript\n * import { WebsocketServerTransport } from \"@kyneta/websocket-transport/server\"\n * import { createBunWebsocketHandlers, type BunWebsocketData } from \"@kyneta/websocket-transport/bun\"\n *\n * const serverAdapter = new WebsocketServerTransport()\n *\n * Bun.serve<BunWebsocketData>({\n *   fetch(req, server) {\n *     server.upgrade(req)\n *     return new Response(\"upgrade failed\", { status: 400 })\n *   },\n *   websocket: createBunWebsocketHandlers(serverAdapter),\n * })\n * ```\n */\nexport function createBunWebsocketHandlers(wsAdapter: {\n  handleConnection: (opts: { socket: Socket }) => { start: () => void }\n}) {\n  return {\n    open(ws: ServerWebSocket<BunWebsocketData>) {\n      wsAdapter.handleConnection({ socket: wrapBunWebsocket(ws) }).start()\n    },\n    message(\n      ws: ServerWebSocket<BunWebsocketData>,\n      msg: string | ArrayBuffer | Buffer,\n    ) {\n      const data =\n        msg instanceof ArrayBuffer\n          ? new Uint8Array(msg)\n          : Buffer.isBuffer(msg)\n            ? new Uint8Array(msg)\n            : msg\n      ws.data.handlers.onMessage?.(data)\n    },\n    close(ws: ServerWebSocket<BunWebsocketData>, code: number, reason: string) {\n      ws.data.handlers.onClose?.(code, reason)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,iBACd,IACQ;AACR,IAAG,OAAO,EAAE,UAAU,EAAE,EAAE;AAE1B,QAAO;EACL,KAAK,MAAiC;AACpC,MAAG,KAAK,KAAK;;EAGf,MAAM,MAAe,QAAuB;AAC1C,MAAG,MAAM,MAAM,OAAO;;EAGxB,UAAU,SAAoD;AAC5D,MAAG,KAAK,SAAS,YAAY;;EAG/B,QAAQ,SAAuD;AAC7D,MAAG,KAAK,SAAS,UAAU;;EAG7B,QAAQ,UAAwC;EAIhD,IAAI,aAA+B;AAOjC,UANmC;IACjC;IACA;IACA;IACA;IACD,CACa,GAAG,eAAe;;EAEnC;;;;;;;;;;;;;;;;;;;;;;;;;AA8BH,SAAgB,2BAA2B,WAExC;AACD,QAAO;EACL,KAAK,IAAuC;AAC1C,aAAU,iBAAiB,EAAE,QAAQ,iBAAiB,GAAG,EAAE,CAAC,CAAC,OAAO;;EAEtE,QACE,IACA,KACA;GACA,MAAM,OACJ,eAAe,cACX,IAAI,WAAW,IAAI,GACnB,OAAO,SAAS,IAAI,GAClB,IAAI,WAAW,IAAI,GACnB;AACR,MAAG,KAAK,SAAS,YAAY,KAAK;;EAEpC,MAAM,IAAuC,MAAc,QAAgB;AACzE,MAAG,KAAK,SAAS,UAAU,MAAM,OAAO;;EAE3C"}

package/dist/client-transport-CKjXedwS.d.ts

@@ -0,0 +1,134 @@
+import { c as WebSocketConstructor, d as WebsocketClientState, f as WebsocketClientStateTransition, t as DisconnectReason } from "./types-CJAcr1Df.js";
+import { GeneratedChannel, PeerId, Transport, TransportFactory } from "@kyneta/transport";
+import { TransitionListener as TransitionListener$1 } from "@kyneta/machine";
+
+//#region src/client-transport.d.ts
+/**
+ * Default fragment threshold in bytes.
+ * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.
+ */
+declare const DEFAULT_FRAGMENT_THRESHOLD: number;
+/**
+ * Options for the Websocket client transport (browser connections).
+ */
+interface WebsocketClientOptions {
+  /** Websocket URL to connect to. Can be a string or a function of peerId. */
+  url: string | ((peerId: PeerId) => string);
+  /**
+   * WebSocket constructor — caller must provide explicitly.
+   *
+   * In browsers, pass the global `WebSocket`. In Node.js, pass `ws`'s
+   * `WebSocket`. In Bun, pass `globalThis.WebSocket`. The transport
+   * never probes `globalThis` on its own.
+   */
+  WebSocket: WebSocketConstructor;
+  /**
+   * Headers to send during Websocket upgrade.
+   * Used for authentication in service-to-service communication.
+   *
+   * Note: Headers are a Bun/Node-specific extension. The browser WebSocket
+   * API does not support custom headers per the WHATWG spec.
+   */
+  headers?: Record<string, string>;
+  /** Reconnection options. */
+  reconnect?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+  };
+  /** Keepalive interval in ms (default: 30000). */
+  keepaliveInterval?: number;
+  /**
+   * Fragment threshold in bytes. Messages larger than this are fragmented.
+   * Set to 0 to disable fragmentation (not recommended for cloud deployments).
+   * Default: 100KB
+   */
+  fragmentThreshold?: number;
+  /** Lifecycle event callbacks. */
+  lifecycle?: WebsocketClientLifecycleEvents;
+}
+/**
+ * Lifecycle event callbacks for the Websocket client.
+ */
+interface WebsocketClientLifecycleEvents {
+  /** Called on every state transition (delivered async via microtask). */
+  onStateChange?: (transition: WebsocketClientStateTransition) => void;
+  /** Called when the connection is lost. */
+  onDisconnect?: (reason: DisconnectReason) => void;
+  /** Called when a reconnection attempt is scheduled. */
+  onReconnecting?: (attempt: number, nextAttemptMs: number) => void;
+  /** Called when reconnection succeeds after a previous connection. */
+  onReconnected?: () => void;
+  /** Called when the server sends the "ready" signal. */
+  onReady?: () => void;
+}
+/**
+ * Websocket client network transport for @kyneta/exchange.
+ *
+ * Connects to a Websocket server, sends and receives ChannelMsg via
+ * the kyneta wire format (CBOR codec + framing + fragmentation).
+ *
+ * Internally, the connection lifecycle is a `Program<Msg, Model, Fx>` —
+ * a pure Mealy machine whose transitions are deterministically testable.
+ * This class is the imperative shell that interprets data effects as I/O.
+ *
+ * Prefer the factory functions for construction:
+ * - `createWebsocketClient()` — browser-to-server (from `./browser`)
+ * - `createServiceWebsocketClient()` — service-to-service with headers (from `./server`)
+ */
+declare class WebsocketClientTransport extends Transport<void> {
+  #private;
+  constructor(options: WebsocketClientOptions);
+  /**
+   * Get the current connection state.
+   */
+  getState(): WebsocketClientState;
+  /**
+   * Subscribe to state transitions.
+   */
+  subscribeToTransitions(listener: TransitionListener$1<WebsocketClientState>): () => void;
+  /**
+   * Wait for a specific state.
+   */
+  waitForState(predicate: (state: WebsocketClientState) => boolean, options?: {
+    timeoutMs?: number;
+  }): Promise<WebsocketClientState>;
+  /**
+   * Wait for a specific status.
+   */
+  waitForStatus(status: WebsocketClientState["status"], options?: {
+    timeoutMs?: number;
+  }): Promise<WebsocketClientState>;
+  /**
+   * Whether the client is ready (server ready signal received).
+   */
+  get isReady(): boolean;
+  protected generate(): GeneratedChannel;
+  onStart(): Promise<void>;
+  onStop(): Promise<void>;
+}
+/**
+ * Create a Websocket client transport factory for browser-to-server
+ * connections.
+ *
+ * Returns an `TransportFactory` — a closure that creates a fresh transport
+ * instance when called. Pass directly to `Exchange({ transports: [...] })`.
+ *
+ * @example
+ * ```typescript
+ * import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
+ *
+ * const exchange = new Exchange({
+ *   transports: [createWebsocketClient({
+ *     url: "ws://localhost:3000/ws",
+ *     WebSocket,
+ *     reconnect: { enabled: true },
+ *   })],
+ * })
+ * ```
+ */
+declare function createWebsocketClient(options: WebsocketClientOptions): TransportFactory;
+//#endregion
+export { createWebsocketClient as a, WebsocketClientTransport as i, WebsocketClientLifecycleEvents as n, WebsocketClientOptions as r, DEFAULT_FRAGMENT_THRESHOLD as t };
+//# sourceMappingURL=client-transport-CKjXedwS.d.ts.map

package/dist/client-transport-CKjXedwS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-transport-CKjXedwS.d.ts","names":[],"sources":["../src/client-transport.ts"],"mappings":";;;;;;;;;cA6Da,0BAAA;;;;UAKI,sBAAA;EAoBL;EAlBV,GAAA,aAAgB,MAAA,EAAQ,MAAA;EAuCkB;;;;;;;EA9B1C,SAAA,EAAW,oBAAA;EASD;;;;;;;EAAV,OAAA,GAAU,MAAA;EAqBV;EAlBA,SAAA;IACE,OAAA;IACA,WAAA;IACA,SAAA;IACA,QAAA;EAAA;EAyBsC;EArBxC,iBAAA;EAkB6B;;;;;EAX7B,iBAAA;EAiBkB;EAdlB,SAAA,GAAY,8BAAA;AAAA;;;;UAMG,8BAAA;EAmCqB;EAjCpC,aAAA,IAAiB,UAAA,EAAY,8BAAA;EAmDR;EAhDrB,YAAA,IAAgB,MAAA,EAAQ,gBAAA;EA8XO;EA3X/B,cAAA,IAAkB,OAAA,UAAiB,aAAA;EAoYd;EAjYrB,aAAA;EAmYG;EAhYH,OAAA;AAAA;;;;;;;;;;;;;;;cAqBW,wBAAA,SAAiC,SAAA;EAAA;cAkBhC,OAAA,EAAS,sBAAA;EA8UnB;;;EARF,QAAA,CAAA,GAAY,oBAAA;EAiBV;;;EAVF,sBAAA,CACE,QAAA,EAAU,oBAAA,CAAmB,oBAAA;EAWpB;;;EAHX,YAAA,CACE,SAAA,GAAY,KAAA,EAAO,oBAAA,cACnB,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,oBAAA;EAUR;;;EAHH,aAAA,CACE,MAAA,EAAQ,oBAAA,YACR,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,oBAAA;EAoCM;;;EAAA,IA7Bb,OAAA,CAAA;EAAA,UAQM,QAAA,CAAA,GAAY,gBAAA;EAqBhB,OAAA,CAAA,GAAW,OAAA;EAUX,MAAA,CAAA,GAAU,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;iBA8BF,qBAAA,CACd,OAAA,EAAS,sBAAA,GACR,gBAAA"}