@kyneta/websocket-transport 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @kyneta/websocket-network-adapter
+
+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).
+
+## 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 |
+
+## Server Setup
+
+### Bun (recommended)
+
+Use `createBunWebsocketHandlers` for zero-boilerplate integration with `Bun.serve()`:
+
+```/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"
+
+const serverAdapter = new WebsocketServerAdapter()
+
+const exchange = new Exchange({
+  identity: { peerId: "server", name: "server", type: "service" },
+  adapters: [serverAdapter],
+})
+
+Bun.serve<BunWebsocketData>({
+  fetch(req, server) {
+    server.upgrade(req)
+    return new Response("upgrade failed", { status: 400 })
+  },
+  websocket: createBunWebsocketHandlers(serverAdapter),
+})
+```
+
+For more control, use `wrapBunWebsocket` directly:
+
+```/dev/null/bun-server-manual.ts#L1-17
+import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+
+Bun.serve<BunWebsocketData>({
+  fetch(req, server) {
+    server.upgrade(req)
+    return new Response("upgrade failed", { status: 400 })
+  },
+  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)
+    },
+  },
+})
+```
+
+### Node.js (`ws` library)
+
+Use `wrapNodeWebsocket` to adapt the `ws` library's `WebSocket` to the framework-agnostic `Socket` interface:
+
+```/dev/null/node-server.ts#L1-16
+import { WebSocketServer } from "ws"
+import { WebsocketServerAdapter, wrapNodeWebsocket } from "@kyneta/websocket-network-adapter/server"
+
+const serverAdapter = new WebsocketServerAdapter()
+
+const exchange = new Exchange({
+  identity: { peerId: "server", name: "server", type: "service" },
+  adapters: [serverAdapter],
+})
+
+const wss = new WebSocketServer({ port: 3000 })
+
+wss.on("connection", (ws) => {
+  const { start } = serverAdapter.handleConnection({ socket: wrapNodeWebsocket(ws) })
+  start()
+})
+```
+
+## Client Setup
+
+### Browser
+
+Use `createWebsocketClient` for browser-to-server connections:
+
+```/dev/null/browser-client.ts#L1-12
+import { Exchange } from "@kyneta/exchange"
+import { createWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+
+const adapter = createWebsocketClient({
+  url: "ws://localhost:3000/ws",
+  reconnect: { enabled: true },
+})
+
+const exchange = new Exchange({
+  identity: { peerId: "browser-client", name: "Alice", type: "user" },
+  adapters: [adapter],
+})
+```
+
+### Service-to-Service
+
+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"
+
+const adapter = createServiceWebsocketClient({
+  url: "ws://primary-server:3000/ws",
+  headers: {
+    Authorization: "Bearer <token>",
+  },
+  reconnect: { enabled: true },
+})
+
+const exchange = new Exchange({
+  identity: { peerId: "worker-1", name: "worker-1", type: "service" },
+  adapters: [adapter],
+})
+```
+
+> For browser clients, authenticate via URL query parameters instead of headers.
+
+## Connection Lifecycle
+
+The client adapter manages connection state through a validated state machine with async-observable transitions:
+
+```/dev/null/state-machine.txt#L1-8
+disconnected → connecting → connected → ready
+                   ↓            ↓         ↓
+              reconnecting ← ─ ┴ ─ ─ ─ ─ ┘
+                   ↓
+              connecting (retry)
+                   ↓
+              disconnected (max retries)
+```
+
+| State | Description |
+|-------|-------------|
+| `disconnected` | No active connection. Optional `reason` field describes why. |
+| `connecting` | Websocket handshake in progress. Tracks `attempt` number. |
+| `connected` | TCP connection open, waiting for server "ready" signal. |
+| `ready` | Server sent `"ready"` text frame — protocol messages can flow. |
+| `reconnecting` | Connection lost, scheduling next attempt. Tracks `attempt` and `nextAttemptMs`. |
+
+### Connection Handshake
+
+1. Client opens Websocket, transitions to `connecting`
+2. Websocket `open` event fires, transitions to `connected`
+3. Server sends text `"ready"` frame, client transitions to `ready`
+4. Client creates its channel, calls `establishChannel()`
+5. Synchronizer exchanges `establish-request` / `establish-response`
+
+### Observing State
+
+```/dev/null/observe-state.ts#L1-18
+import { createWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+
+const adapter = createWebsocketClient({
+  url: "ws://localhost:3000/ws",
+  lifecycle: {
+    onStateChange: ({ from, to }) => console.log(`${from.status} → ${to.status}`),
+    onDisconnect: (reason) => console.log("disconnected:", reason.type),
+    onReconnecting: (attempt, nextMs) => console.log(`retry #${attempt} in ${nextMs}ms`),
+    onReconnected: () => console.log("reconnected"),
+    onReady: () => console.log("ready"),
+  },
+})
+
+// Or subscribe to transitions programmatically
+const unsub = adapter.subscribeToTransitions(({ from, to }) => {
+  console.log(`${from.status} → ${to.status}`)
+})
+
+await adapter.waitForStatus("ready", { timeoutMs: 5000 })
+```
+
+## The Socket Interface
+
+`Socket` is the framework-agnostic abstraction that decouples the adapter from any specific Websocket library. Platform-specific wrappers adapt concrete implementations to this interface:
+
+| Wrapper | Input | Export |
+|---------|-------|--------|
+| `wrapStandardWebsocket(ws)` | Browser `WebSocket` | `./client`, `./server` |
+| `wrapNodeWebsocket(ws)` | Node.js `ws` library | `./server` |
+| `wrapBunWebsocket(ws)` | Bun `ServerWebSocket` | `./bun` |
+
+```/dev/null/socket-interface.ts#L1-8
+interface Socket {
+  send(data: Uint8Array | string): void
+  close(code?: number, reason?: string): void
+  onMessage(handler: (data: Uint8Array | string) => void): void
+  onClose(handler: (code: number, reason: string) => void): void
+  onError(handler: (error: Error) => void): void
+  readonly readyState: "connecting" | "open" | "closing" | "closed"
+}
+```
+
+## Configuration
+
+### Client Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `url` | — | Websocket URL. String or `(peerId) => string` function. |
+| `WebSocket` | `globalThis.WebSocket` | Custom WebSocket constructor (for Node.js or testing). |
+| `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. |
+| `reconnect.maxDelay` | `30000` | Maximum delay cap in ms. |
+| `keepaliveInterval` | `30000` | Interval in ms for keepalive ping frames. |
+| `fragmentThreshold` | `102400` | Payload size threshold for fragmentation (bytes). |
+| `headers` | — | Upgrade headers (`ServiceWebsocketClientOptions` only). |
+
+### Server Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `fragmentThreshold` | `102400` | Payload size threshold for fragmentation (bytes). |
+
+### Fragment Thresholds by Environment
+
+| Environment | Recommended threshold | Reason |
+|-------------|----------------------|--------|
+| AWS API Gateway | `100KB` (default) | 128KB frame limit |
+| Cloudflare | `500KB` | 1MB frame limit |
+| Self-hosted | `0` (disabled) | No infrastructure limits |
+
+### Keepalive
+
+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.
+
+## Peer Dependencies
+
+```/dev/null/package.json#L1-4
+{
+  "peerDependencies": {
+    "@kyneta/exchange": ">=0.0.1",
+    "@kyneta/wire": ">=0.0.1"
+  }
+}
+```
+
+## License
+
+MIT

package/dist/bun.d.ts

@@ -0,0 +1,91 @@
+import { ServerWebSocket } from 'bun';
+import { S as Socket } from './types-DG_89zA4.js';
+export { D as DisconnectReason, a as SocketReadyState } from './types-DG_89zA4.js';
+import '@kyneta/exchange';
+
+/**
+ * Data structure stored in `ws.data` for handler callbacks.
+ * Use this type when defining your `Bun.serve()` generic.
+ *
+ * @example
+ * ```typescript
+ * Bun.serve<BunWebsocketData>({
+ *   websocket: { ... }
+ * })
+ * ```
+ */
+type BunWebsocketData = {
+    handlers: {
+        onMessage?: (data: Uint8Array | string) => void;
+        onClose?: (code: number, reason: string) => void;
+    };
+};
+/**
+ * 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-network-adapter/server"
+ * import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-network-adapter/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)
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function wrapBunWebsocket(ws: ServerWebSocket<BunWebsocketData>): Socket;
+/**
+ * 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-network-adapter/server"
+ * import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+ *
+ * const serverAdapter = new WebsocketServerTransport()
+ *
+ * Bun.serve<BunWebsocketData>({
+ *   fetch(req, server) {
+ *     server.upgrade(req)
+ *     return new Response("upgrade failed", { status: 400 })
+ *   },
+ *   websocket: createBunWebsocketHandlers(serverAdapter),
+ * })
+ * ```
+ */
+declare function createBunWebsocketHandlers(wsAdapter: {
+    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;
+};
+
+export { type BunWebsocketData, Socket, createBunWebsocketHandlers, wrapBunWebsocket };

package/dist/bun.js

@@ -0,0 +1,48 @@
+// src/bun-websocket.ts
+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";
+    }
+  };
+}
+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);
+    }
+  };
+}
+export {
+  createBunWebsocketHandlers,
+  wrapBunWebsocket
+};
+//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -0,0 +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":[]}

package/dist/chunk-5FHT54WT.js

@@ -0,0 +1,109 @@
+// src/types.ts
+function wrapStandardWebsocket(ws) {
+  return {
+    send(data) {
+      ws.send(data);
+    },
+    close(code, reason) {
+      ws.close(code, reason);
+    },
+    onMessage(handler) {
+      ws.addEventListener("message", (event) => {
+        if (event.data instanceof ArrayBuffer) {
+          handler(new Uint8Array(event.data));
+        } else if (typeof Blob !== "undefined" && event.data instanceof Blob) {
+          event.data.arrayBuffer().then((buffer) => {
+            handler(new Uint8Array(buffer));
+          });
+        } else {
+          handler(event.data);
+        }
+      });
+    },
+    onClose(handler) {
+      ws.addEventListener("close", (event) => {
+        handler(event.code, event.reason);
+      });
+    },
+    onError(handler) {
+      ws.addEventListener("error", (_event) => {
+        handler(new Error("WebSocket error"));
+      });
+    },
+    get readyState() {
+      switch (ws.readyState) {
+        case WebSocket.CONNECTING:
+          return "connecting";
+        case WebSocket.OPEN:
+          return "open";
+        case WebSocket.CLOSING:
+          return "closing";
+        case WebSocket.CLOSED:
+          return "closed";
+        default:
+          return "closed";
+      }
+    }
+  };
+}
+function wrapNodeWebsocket(ws) {
+  const CONNECTING = 0;
+  const OPEN = 1;
+  const CLOSING = 2;
+  return {
+    send(data) {
+      ws.send(data);
+    },
+    close(code, reason) {
+      ws.close(code, reason);
+    },
+    onMessage(handler) {
+      ws.on(
+        "message",
+        (data, isBinary) => {
+          if (isBinary) {
+            if (data instanceof ArrayBuffer) {
+              handler(new Uint8Array(data));
+            } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
+              handler(new Uint8Array(data));
+            } else {
+              handler(new Uint8Array(data));
+            }
+          } else {
+            if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
+              handler(data.toString("utf-8"));
+            } else {
+              handler(data);
+            }
+          }
+        }
+      );
+    },
+    onClose(handler) {
+      ws.on("close", (code, reason) => {
+        handler(code, reason.toString());
+      });
+    },
+    onError(handler) {
+      ws.on("error", handler);
+    },
+    get readyState() {
+      switch (ws.readyState) {
+        case CONNECTING:
+          return "connecting";
+        case OPEN:
+          return "open";
+        case CLOSING:
+          return "closing";
+        default:
+          return "closed";
+      }
+    }
+  };
+}
+
+export {
+  wrapStandardWebsocket,
+  wrapNodeWebsocket
+};
+//# sourceMappingURL=chunk-5FHT54WT.js.map

package/dist/chunk-5FHT54WT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// types — framework-agnostic Websocket abstractions for @kyneta/websocket-network-adapter.\n//\n// The `Socket` interface decouples the adapter from any specific Websocket\n// library (browser WebSocket, Node `ws`, Bun ServerWebSocket). Platform-\n// specific wrappers (`wrapStandardWebsocket`, `wrapNodeWebsocket`,\n// `wrapBunWebsocket`) adapt concrete implementations to this interface.\n//\n// Ported from @loro-extended/adapter-websocket's WsSocket with kyneta\n// naming conventions applied.\n\nimport type {\n  TransitionListener as GenericTransitionListener,\n  PeerId,\n  StateTransition,\n} from \"@kyneta/exchange\"\n\n// ---------------------------------------------------------------------------\n// Socket ready states\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket ready states — mirrors the standard WebSocket readyState\n * values as human-readable strings.\n */\nexport type SocketReadyState = \"connecting\" | \"open\" | \"closing\" | \"closed\"\n\n// ---------------------------------------------------------------------------\n// Socket interface\n// ---------------------------------------------------------------------------\n\n/**\n * Framework-agnostic Websocket interface.\n *\n * This allows the adapter to work with any Websocket library:\n * - Browser `WebSocket` via `wrapStandardWebsocket()`\n * - Node.js `ws` library via `wrapNodeWebsocket()`\n * - Bun `ServerWebSocket` via `wrapBunWebsocket()`\n *\n * The interface is intentionally minimal — only the operations the\n * adapter needs are exposed.\n */\nexport interface Socket {\n  /** Send binary or text data through the Websocket. */\n  send(data: Uint8Array | string): void\n\n  /** Close the Websocket connection. */\n  close(code?: number, reason?: string): void\n\n  /** Register a handler for incoming messages (binary or text). */\n  onMessage(handler: (data: Uint8Array | string) => void): void\n\n  /** Register a handler for connection close. */\n  onClose(handler: (code: number, reason: string) => void): void\n\n  /** Register a handler for errors. */\n  onError(handler: (error: Error) => void): void\n\n  /** The current ready state of the Websocket. */\n  readonly readyState: SocketReadyState\n}\n\n// ---------------------------------------------------------------------------\n// Connection types — used by server adapter\n// ---------------------------------------------------------------------------\n\n/**\n * Options for handling a new Websocket connection on the server.\n */\nexport interface WebsocketConnectionOptions {\n  /** The Websocket instance, wrapped in the Socket interface. */\n  socket: Socket\n\n  /** Optional peer ID extracted from the upgrade request. */\n  peerId?: PeerId\n\n  /** Optional authentication token from the upgrade request. */\n  authToken?: string\n}\n\n/**\n * Handle for an active Websocket connection.\n */\nexport interface WebsocketConnectionHandle {\n  /** The peer ID for this connection. */\n  readonly peerId: PeerId\n\n  /** The channel ID for this connection. */\n  readonly channelId: number\n\n  /** Close the connection. */\n  close(code?: number, reason?: string): void\n}\n\n/**\n * Result of handling a Websocket connection on the server.\n */\nexport interface WebsocketConnectionResult {\n  /** The connection handle for managing this peer. */\n  connection: WebsocketConnectionHandle\n\n  /** Call this to start processing messages. */\n  start(): void\n}\n\n// ---------------------------------------------------------------------------\n// Disconnect reason\n// ---------------------------------------------------------------------------\n\n/**\n * Discriminated union describing why a Websocket connection was lost.\n */\nexport type DisconnectReason =\n  | { type: \"intentional\" }\n  | { type: \"error\"; error: Error }\n  | { type: \"closed\"; code: number; reason: string }\n  | { type: \"max-retries-exceeded\"; attempts: number }\n  | { type: \"not-started\" }\n\n// ---------------------------------------------------------------------------\n// Connection state (for client adapter observability)\n// ---------------------------------------------------------------------------\n\n/**\n * All possible states of the Websocket client.\n *\n * State machine transitions:\n * ```\n * disconnected → connecting → connected → ready\n *                    ↓            ↓         ↓\n *               reconnecting ← ─ ┴ ─ ─ ─ ─ ┘\n *                    ↓\n *               connecting (retry)\n *                    ↓\n *               disconnected (max retries)\n * ```\n */\nexport type WebsocketClientState =\n  | { status: \"disconnected\"; reason?: DisconnectReason }\n  | { status: \"connecting\"; attempt: number }\n  | { status: \"connected\" }\n  | { status: \"ready\" }\n  | { status: \"reconnecting\"; attempt: number; nextAttemptMs: number }\n\n/**\n * A state transition event for websocket client states.\n * Specialized from the generic `StateTransition<S>`.\n */\nexport type WebsocketClientStateTransition =\n  StateTransition<WebsocketClientState>\n\n/**\n * Listener for websocket client state transitions.\n * Specialized from the generic `TransitionListener<S>`.\n */\nexport type TransitionListener = GenericTransitionListener<WebsocketClientState>\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — standard WebSocket API (browser + Node ws)\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a standard `WebSocket` (browser or Node.js `ws` via `ws` package\n * in `WebSocket`-compatible mode) into the `Socket` interface.\n *\n * Handles `ArrayBuffer`, `Blob`, and string messages.\n */\nexport function wrapStandardWebsocket(ws: WebSocket): Socket {\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.addEventListener(\"message\", event => {\n        if (event.data instanceof ArrayBuffer) {\n          handler(new Uint8Array(event.data))\n        } else if (typeof Blob !== \"undefined\" && event.data instanceof Blob) {\n          // Handle Blob data (browser)\n          event.data.arrayBuffer().then(buffer => {\n            handler(new Uint8Array(buffer))\n          })\n        } else {\n          handler(event.data as string)\n        }\n      })\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.addEventListener(\"close\", event => {\n        handler(event.code, event.reason)\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.addEventListener(\"error\", _event => {\n        handler(new Error(\"WebSocket error\"))\n      })\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case WebSocket.CONNECTING:\n          return \"connecting\"\n        case WebSocket.OPEN:\n          return \"open\"\n        case WebSocket.CLOSING:\n          return \"closing\"\n        case WebSocket.CLOSED:\n          return \"closed\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — Node.js `ws` library (raw API, not WebSocket-compat)\n// ---------------------------------------------------------------------------\n\n/**\n * The minimal interface we need from the Node.js `ws` library's `WebSocket`.\n *\n * Using a structural type rather than importing `ws` — consumers provide\n * the actual `ws` instance, we just need these methods.\n */\nexport interface NodeWebsocketLike {\n  send(data: Uint8Array | string): void\n  close(code?: number, reason?: string): void\n  on(\n    event: \"message\",\n    handler: (data: Buffer | ArrayBuffer | string, isBinary: boolean) => void,\n  ): void\n  on(event: \"close\", handler: (code: number, reason: Buffer) => void): void\n  on(event: \"error\", handler: (error: Error) => void): void\n  readyState: number\n}\n\n/**\n * Wrap a Node.js `ws` library WebSocket into the `Socket` interface.\n *\n * Handles `Buffer` → `Uint8Array` conversion for binary messages.\n */\nexport function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket {\n  const CONNECTING = 0\n  const OPEN = 1\n  const CLOSING = 2\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.on(\n        \"message\",\n        (data: Buffer | ArrayBuffer | string, isBinary: boolean) => {\n          if (isBinary) {\n            if (data instanceof ArrayBuffer) {\n              handler(new Uint8Array(data))\n            } else if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(new Uint8Array(data))\n            } else {\n              handler(new Uint8Array(data as unknown as ArrayBuffer))\n            }\n          } else {\n            if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(data.toString(\"utf-8\"))\n            } else {\n              handler(data as string)\n            }\n          }\n        },\n      )\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.on(\"close\", (code: number, reason: Buffer) => {\n        handler(code, reason.toString())\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.on(\"error\", handler)\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case CONNECTING:\n          return \"connecting\"\n        case OPEN:\n          return \"open\"\n        case CLOSING:\n          return \"closing\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n"],"mappings":";AAsKO,SAAS,sBAAsB,IAAuB;AAC3D,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,iBAAiB,WAAW,WAAS;AACtC,YAAI,MAAM,gBAAgB,aAAa;AACrC,kBAAQ,IAAI,WAAW,MAAM,IAAI,CAAC;AAAA,QACpC,WAAW,OAAO,SAAS,eAAe,MAAM,gBAAgB,MAAM;AAEpE,gBAAM,KAAK,YAAY,EAAE,KAAK,YAAU;AACtC,oBAAQ,IAAI,WAAW,MAAM,CAAC;AAAA,UAChC,CAAC;AAAA,QACH,OAAO;AACL,kBAAQ,MAAM,IAAc;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,iBAAiB,SAAS,WAAS;AACpC,gBAAQ,MAAM,MAAM,MAAM,MAAM;AAAA,MAClC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,iBAAiB,SAAS,YAAU;AACrC,gBAAQ,IAAI,MAAM,iBAAiB,CAAC;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;AA6BO,SAAS,kBAAkB,IAA+B;AAC/D,QAAM,aAAa;AACnB,QAAM,OAAO;AACb,QAAM,UAAU;AAEhB,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;AAAA,QACD;AAAA,QACA,CAAC,MAAqC,aAAsB;AAC1D,cAAI,UAAU;AACZ,gBAAI,gBAAgB,aAAa;AAC/B,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,WAAW,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AACjE,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,OAAO;AACL,sBAAQ,IAAI,WAAW,IAA8B,CAAC;AAAA,YACxD;AAAA,UACF,OAAO;AACL,gBAAI,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AAC1D,sBAAQ,KAAK,SAAS,OAAO,CAAC;AAAA,YAChC,OAAO;AACL,sBAAQ,IAAc;AAAA,YACxB;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,GAAG,SAAS,CAAC,MAAc,WAAmB;AAC/C,gBAAQ,MAAM,OAAO,SAAS,CAAC;AAAA,MACjC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,GAAG,SAAS,OAAO;AAAA,IACxB;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;","names":[]}