@firtoz/websocket-do 12.0.0 → 13.0.1

package/README.md

@@ -4,7 +4,11 @@
 [![npm downloads](https://img.shields.io/npm/dm/%40firtoz%2Fwebsocket-do.svg)](https://www.npmjs.com/package/@firtoz/websocket-do)
 [![license](https://img.shields.io/npm/l/%40firtoz%2Fwebsocket-do.svg)](https://github.com/firtoz/fullstack-toolkit/blob/main/LICENSE)
 
-Type-safe WebSocket session management for Cloudflare Durable Objects with Hono integration.
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Cloudflare](https://img.shields.io/badge/Cloudflare-Durable_Objects-F38020?logo=cloudflare&logoColor=white)](https://developers.cloudflare.com/durable-objects/)
+[![Hono](https://img.shields.io/badge/Hono-E36002?logo=hono&logoColor=white)](https://hono.dev)
+
+**WebSocket sessions on Durable Objects** — Standard Schema message validation, broadcasting, and Hono integration.
 
 > **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
 

package/dist/BaseSession.d.ts

@@ -0,0 +1,41 @@
+import { Context } from 'hono';
+
+type SessionData<TSession extends BaseSession<any, any, any, any>> = TSession extends BaseSession<infer TData, infer _TServerMessage, infer _TClientMessage, infer _TEnv> ? TData : never;
+type SessionClientMessage<TSession extends BaseSession<any, any, any, any>> = TSession extends BaseSession<infer _TData, infer _TServerMessage, infer TClientMessage, infer _TEnv> ? TClientMessage : never;
+type SessionServerMessage<TSession extends BaseSession<any, any, any, any>> = TSession extends BaseSession<infer _TData, infer TServerMessage, infer _TClientMessage, infer _TEnv> ? TServerMessage : never;
+type SessionEnv<TSession extends BaseSession<any, any, any, any>> = TSession extends BaseSession<infer _TData, infer _TServerMessage, infer _TClientMessage, infer TEnv extends Cloudflare.Env> ? TEnv : never;
+type BaseSessionHandlers<TData, TServerMessage, TClientMessage, TEnv extends object = Cloudflare.Env> = {
+    /**
+     * Per-connection state. If omitted, `startFresh` initializes `data` as `{}`
+     * (use empty `TData`, e.g. `Record<string, never>`).
+     */
+    createData?: (ctx: Context<{
+        Bindings: TEnv;
+    }>) => TData;
+    handleMessage: (message: TClientMessage) => Promise<void>;
+    handleBufferMessage: (message: ArrayBuffer) => Promise<void>;
+    /** Called when this connection closes; `session` is this {@link BaseSession} instance. */
+    handleClose: (session: BaseSession<TData, TServerMessage, TClientMessage, TEnv>) => Promise<void>;
+};
+declare class BaseSession<TData, TServerMessage, TClientMessage, TEnv extends object = Cloudflare.Env> {
+    websocket: WebSocket;
+    protected sessions: Map<WebSocket, BaseSession<TData, TServerMessage, TClientMessage, TEnv>>;
+    private _data;
+    get data(): TData;
+    private set data(value);
+    private readonly wrapper;
+    protected readonly handlers: BaseSessionHandlers<TData, TServerMessage, TClientMessage, TEnv>;
+    constructor(websocket: WebSocket, sessions: Map<WebSocket, BaseSession<TData, TServerMessage, TClientMessage, TEnv>>, handlers: BaseSessionHandlers<TData, TServerMessage, TClientMessage, TEnv>);
+    startFresh(ctx: Context<{
+        Bindings: TEnv;
+    }>): void;
+    resume(): void;
+    update(): void;
+    broadcast(message: TServerMessage, excludeSelf?: boolean): void;
+    send(message: TServerMessage): void;
+    handleMessage(message: TClientMessage): Promise<void>;
+    handleBufferMessage(message: ArrayBuffer): Promise<void>;
+    handleClose(): Promise<void>;
+}
+
+export { BaseSession, type BaseSessionHandlers, type SessionClientMessage, type SessionData, type SessionEnv, type SessionServerMessage };

package/dist/BaseSession.js

@@ -0,0 +1,5 @@
+export { BaseSession } from './chunk-3C77OSOD.js';
+import './chunk-KCPOB32E.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=BaseSession.js.map
+//# sourceMappingURL=BaseSession.js.map

package/dist/BaseSession.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"BaseSession.js"}

package/dist/BaseWebSocketDO.d.ts

@@ -0,0 +1,42 @@
+import * as hono_hono_base from 'hono/hono-base';
+import * as hono_utils_http_status from 'hono/utils/http-status';
+import { DurableObject } from 'cloudflare:workers';
+import { DOWithHonoApp } from '@firtoz/hono-fetcher/honoDoFetcher';
+import { Context, Hono } from 'hono';
+import { BaseSession, SessionEnv } from './BaseSession.js';
+
+type BaseWebSocketDOOptions<TSession extends BaseSession<any, any, any, any>, TEnv extends SessionEnv<TSession>> = {
+    createSession: (ctx: Context<{
+        Bindings: TEnv;
+    }> | undefined, websocket: WebSocket) => TSession | Promise<TSession>;
+};
+declare abstract class BaseWebSocketDO<TSession extends BaseSession<any, any, any, any> = BaseSession<any, any, any, any>, TEnv extends SessionEnv<TSession> = SessionEnv<TSession>> extends DurableObject<TEnv> implements DOWithHonoApp {
+    #private;
+    private readonly options;
+    protected readonly sessions: Map<WebSocket, TSession>;
+    abstract readonly app: Hono<{
+        Bindings: TEnv;
+    }>;
+    constructor(ctx: DurableObjectState, env: TEnv, options: BaseWebSocketDOOptions<TSession, TEnv>);
+    protected getBaseApp(): hono_hono_base.HonoBase<{
+        Bindings: TEnv;
+    }, {
+        "/websocket": {
+            $get: {
+                input: {};
+                output: {};
+                outputFormat: string;
+                status: hono_utils_http_status.StatusCode;
+            };
+        };
+    }, "/", "/websocket">;
+    handleSession(ctx: Context<{
+        Bindings: TEnv;
+    }>, ws: WebSocket): Promise<void>;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: WebSocket, _code: number, _reason: string, _wasClean: boolean): Promise<void>;
+    webSocketError(ws: WebSocket, error: unknown): Promise<void>;
+    fetch(request: Request): Response | Promise<Response>;
+}
+
+export { BaseWebSocketDO, type BaseWebSocketDOOptions };

package/dist/BaseWebSocketDO.js

@@ -0,0 +1,4 @@
+export { BaseWebSocketDO } from './chunk-XFB6C3NZ.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=BaseWebSocketDO.js.map
+//# sourceMappingURL=BaseWebSocketDO.js.map

package/dist/BaseWebSocketDO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"BaseWebSocketDO.js"}

package/dist/StandardSchemaSession.d.ts

@@ -0,0 +1,41 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Context } from 'hono';
+import { BaseSession } from './BaseSession.js';
+
+type StandardSchemaSessionOptions<TClientMessage, TServerMessage> = {
+    clientSchema: StandardSchemaV1<unknown, TClientMessage>;
+    serverSchema: StandardSchemaV1<unknown, TServerMessage>;
+    serializeJson?: (value: unknown) => string;
+    deserializeJson?: (raw: string) => unknown;
+    enableBufferMessages?: boolean;
+    sendProtocolError?: (websocket: WebSocket, errorMessage: string) => Promise<void>;
+};
+type StandardSchemaSessionHandlers<TData, TServerMessage, TClientMessage, TEnv extends object> = {
+    createData: (ctx: Context<{
+        Bindings: TEnv;
+    }>) => TData;
+    handleValidatedMessage: (message: TClientMessage) => Promise<void>;
+    handleValidationError?: (error: unknown, originalMessage: unknown) => Promise<void>;
+    handleClose: (session: StandardSchemaSession<TData, TServerMessage, TClientMessage, TEnv>) => Promise<void>;
+};
+declare class StandardSchemaSession<TData, TServerMessage, TClientMessage, TEnv extends object = Cloudflare.Env> extends BaseSession<TData, TServerMessage, TClientMessage, TEnv> {
+    private readonly options;
+    private readonly schemaHandlers;
+    private readonly clientCodec;
+    private readonly serverCodec;
+    protected readonly enableBufferMessages: boolean;
+    constructor(websocket: WebSocket, sessions: Map<WebSocket, StandardSchemaSession<TData, TServerMessage, TClientMessage, TEnv>>, options: StandardSchemaSessionOptions<TClientMessage, TServerMessage>, schemaHandlers: StandardSchemaSessionHandlers<TData, TServerMessage, TClientMessage, TEnv>);
+    handleRawMessage(rawMessage: string): Promise<void>;
+    private _internalHandleMessage;
+    private _internalHandleBufferMessage;
+    private _internalHandleValidationError;
+    send(message: TServerMessage): void;
+    private sendJsonAsync;
+    private sendBufferAsync;
+    private sendProtocolError;
+    private serializeJson;
+    private deserializeJson;
+    broadcast(message: TServerMessage, excludeSelf?: boolean): void;
+}
+
+export { StandardSchemaSession, type StandardSchemaSessionHandlers, type StandardSchemaSessionOptions };

package/dist/StandardSchemaSession.js

@@ -0,0 +1,8 @@
+export { StandardSchemaSession } from './chunk-53MFRNQS.js';
+import './chunk-QMGIRIHJ.js';
+import './chunk-3C77OSOD.js';
+import './chunk-KCPOB32E.js';
+import './chunk-CAX4POIL.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=StandardSchemaSession.js.map
+//# sourceMappingURL=StandardSchemaSession.js.map

package/dist/StandardSchemaSession.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"StandardSchemaSession.js"}

package/dist/StandardSchemaWebSocketClient.d.ts

@@ -0,0 +1,45 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+interface StandardSchemaWebSocketClientOptions<TClientMessage, TServerMessage> {
+    /**
+     * URL to connect to (required if webSocket not provided)
+     */
+    url?: string;
+    /**
+     * Existing WebSocket to wrap (alternative to url)
+     * Useful when getting a WebSocket from honoDoFetcher
+     */
+    webSocket?: WebSocket;
+    clientSchema: StandardSchemaV1<unknown, TClientMessage>;
+    serverSchema: StandardSchemaV1<unknown, TServerMessage>;
+    serializeJson?: (value: unknown) => string;
+    deserializeJson?: (raw: string) => unknown;
+    enableBufferMessages?: boolean;
+    onMessage?: (message: TServerMessage) => void;
+    onOpen?: (event: Event) => void;
+    onClose?: (event: CloseEvent) => void;
+    onError?: (event: Event) => void;
+    onValidationError?: (error: Error, rawMessage: unknown) => void;
+}
+declare class StandardSchemaWebSocketClient<TClientMessage, TServerMessage> {
+    private ws;
+    private readonly clientSchema;
+    private readonly serverSchema;
+    private readonly serializeJson;
+    private readonly deserializeJson;
+    private readonly enableBufferMessages;
+    private readonly onMessageCallback?;
+    private readonly onValidationError?;
+    constructor(options: StandardSchemaWebSocketClientOptions<TClientMessage, TServerMessage>);
+    private handleMessageEvent;
+    /**
+     * Send a message (automatically encodes based on mode).
+     */
+    send(message: TClientMessage): Promise<void>;
+    close(code?: number, reason?: string): void;
+    get readyState(): number;
+    get socket(): WebSocket;
+    waitForOpen(): Promise<void>;
+}
+
+export { StandardSchemaWebSocketClient, type StandardSchemaWebSocketClientOptions };

package/dist/StandardSchemaWebSocketClient.js

@@ -0,0 +1,5 @@
+export { StandardSchemaWebSocketClient } from './chunk-3LWVEY3R.js';
+import './chunk-CAX4POIL.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=StandardSchemaWebSocketClient.js.map
+//# sourceMappingURL=StandardSchemaWebSocketClient.js.map

package/dist/StandardSchemaWebSocketClient.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"StandardSchemaWebSocketClient.js"}

package/dist/StandardSchemaWebSocketDO.d.ts

@@ -0,0 +1,28 @@
+import { Context } from 'hono';
+import { SessionEnv, SessionClientMessage, SessionServerMessage } from './BaseSession.js';
+import { BaseWebSocketDO } from './BaseWebSocketDO.js';
+import { StandardSchemaSessionOptions, StandardSchemaSession } from './StandardSchemaSession.js';
+import 'hono/hono-base';
+import 'hono/utils/http-status';
+import 'cloudflare:workers';
+import '@firtoz/hono-fetcher/honoDoFetcher';
+import '@standard-schema/spec';
+
+type StandardSchemaSessionOptionsOrFactory<TClientMessage, TServerMessage, TEnv extends Cloudflare.Env = Cloudflare.Env> = StandardSchemaSessionOptions<TClientMessage, TServerMessage> | ((ctx: Context<{
+    Bindings: TEnv;
+}> | undefined, websocket: WebSocket) => StandardSchemaSessionOptions<TClientMessage, TServerMessage>);
+type StandardSchemaWebSocketDOOptions<TSession extends StandardSchemaSession<any, any, any, any>, TClientMessage, TServerMessage, TEnv extends SessionEnv<TSession>> = {
+    standardSchemaSessionOptions: StandardSchemaSessionOptionsOrFactory<TClientMessage, TServerMessage, TEnv>;
+    createStandardSchemaSession: (ctx: Context<{
+        Bindings: TEnv;
+    }> | undefined, websocket: WebSocket, options: StandardSchemaSessionOptions<TClientMessage, TServerMessage>) => TSession | Promise<TSession>;
+};
+declare abstract class StandardSchemaWebSocketDO<TSession extends StandardSchemaSession<any, any, any, any>, TClientMessage extends SessionClientMessage<TSession> = SessionClientMessage<TSession>, TServerMessage extends SessionServerMessage<TSession> = SessionServerMessage<TSession>, TEnv extends SessionEnv<TSession> = SessionEnv<TSession>> extends BaseWebSocketDO<TSession, TEnv> {
+    protected readonly standardSchemaSessionOptions: StandardSchemaSessionOptionsOrFactory<TClientMessage, TServerMessage, TEnv>;
+    protected readonly createStandardSchemaSessionFn: (ctx: Context<{
+        Bindings: TEnv;
+    }> | undefined, websocket: WebSocket, options: StandardSchemaSessionOptions<TClientMessage, TServerMessage>) => TSession | Promise<TSession>;
+    constructor(ctx: DurableObjectState, env: TEnv, options: StandardSchemaWebSocketDOOptions<TSession, TClientMessage, TServerMessage, TEnv>);
+}
+
+export { type StandardSchemaSessionOptionsOrFactory, StandardSchemaWebSocketDO, type StandardSchemaWebSocketDOOptions };

package/dist/StandardSchemaWebSocketDO.js

@@ -0,0 +1,5 @@
+export { StandardSchemaWebSocketDO } from './chunk-ULGH6X42.js';
+import './chunk-XFB6C3NZ.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=StandardSchemaWebSocketDO.js.map
+//# sourceMappingURL=StandardSchemaWebSocketDO.js.map

package/dist/StandardSchemaWebSocketDO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"StandardSchemaWebSocketDO.js"}

package/dist/WebsocketWrapper.d.ts

@@ -0,0 +1,9 @@
+declare class WebsocketWrapper<TAttachment, TMessage> {
+    webSocket: WebSocket;
+    constructor(webSocket: WebSocket);
+    send(message: TMessage): void;
+    deserializeAttachment(): TAttachment;
+    serializeAttachment(attachment: TAttachment): void;
+}
+
+export { WebsocketWrapper };

package/dist/WebsocketWrapper.js

@@ -0,0 +1,4 @@
+export { WebsocketWrapper } from './chunk-KCPOB32E.js';
+import './chunk-NOUFNU2O.js';
+//# sourceMappingURL=WebsocketWrapper.js.map
+//# sourceMappingURL=WebsocketWrapper.js.map

package/dist/WebsocketWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"WebsocketWrapper.js"}

package/dist/chunk-3C77OSOD.js

@@ -0,0 +1,54 @@
+import { WebsocketWrapper } from './chunk-KCPOB32E.js';
+
+// src/BaseSession.ts
+var BaseSession = class {
+  constructor(websocket, sessions, handlers) {
+    this.websocket = websocket;
+    this.sessions = sessions;
+    this.wrapper = new WebsocketWrapper(websocket);
+    this.handlers = handlers;
+  }
+  get data() {
+    return this._data;
+  }
+  set data(data) {
+    this._data = data;
+  }
+  startFresh(ctx) {
+    this.data = this.handlers.createData !== void 0 ? this.handlers.createData(ctx) : {};
+    this.wrapper.serializeAttachment(this.data);
+  }
+  resume() {
+    const existingData = this.wrapper.deserializeAttachment();
+    if (existingData) {
+      this.data = existingData;
+    } else {
+      throw new Error("No data to resume");
+    }
+  }
+  update() {
+    this.wrapper.serializeAttachment(this.data);
+  }
+  broadcast(message, excludeSelf = false) {
+    for (const session of this.sessions.values()) {
+      if (excludeSelf && session === this) continue;
+      session.send(message);
+    }
+  }
+  send(message) {
+    this.wrapper.send(message);
+  }
+  async handleMessage(message) {
+    return this.handlers.handleMessage(message);
+  }
+  async handleBufferMessage(message) {
+    return this.handlers.handleBufferMessage(message);
+  }
+  async handleClose() {
+    return this.handlers.handleClose(this);
+  }
+};
+
+export { BaseSession };
+//# sourceMappingURL=chunk-3C77OSOD.js.map
+//# sourceMappingURL=chunk-3C77OSOD.js.map

package/dist/chunk-3C77OSOD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/BaseSession.ts"],"names":[],"mappings":";;;AAwEO,IAAM,cAAN,MAKL;AAAA,EAmBD,WAAA,CACQ,SAAA,EACG,QAAA,EAIV,QAAA,EACC;AANM,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AACG,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA;AAMV,IAAA,IAAA,CAAK,OAAA,GAAU,IAAI,gBAAA,CAAwC,SAAS,CAAA;AACpE,IAAA,IAAA,CAAK,QAAA,GAAW,QAAA;AAAA,EACjB;AAAA,EA1BA,IAAW,IAAA,GAAc;AACxB,IAAA,OAAO,IAAA,CAAK,KAAA;AAAA,EACb;AAAA,EAEA,IAAY,KAAK,IAAA,EAAa;AAC7B,IAAA,IAAA,CAAK,KAAA,GAAQ,IAAA;AAAA,EACd;AAAA,EAsBO,WAAW,GAAA,EAAkC;AACnD,IAAA,IAAA,CAAK,IAAA,GACJ,IAAA,CAAK,QAAA,CAAS,UAAA,KAAe,MAAA,GAC1B,KAAK,QAAA,CAAS,UAAA,CAAW,GAAG,CAAA,GAC3B,EAAC;AACN,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,IAAA,CAAK,IAAI,CAAA;AAAA,EAC3C;AAAA,EAEO,MAAA,GAAS;AACf,IAAA,MAAM,YAAA,GAAe,IAAA,CAAK,OAAA,CAAQ,qBAAA,EAAsB;AACxD,IAAA,IAAI,YAAA,EAAc;AACjB,MAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AAAA,IACb,CAAA,MAAO;AACN,MAAA,MAAM,IAAI,MAAM,mBAAmB,CAAA;AAAA,IACpC;AAAA,EACD;AAAA,EAEO,MAAA,GAAS;AACf,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,IAAA,CAAK,IAAI,CAAA;AAAA,EAC3C;AAAA,EAEO,SAAA,CAAU,OAAA,EAAyB,WAAA,GAAc,KAAA,EAAO;AAC9D,IAAA,KAAA,MAAW,OAAA,IAAW,IAAA,CAAK,QAAA,CAAS,MAAA,EAAO,EAAG;AAC7C,MAAA,IAAI,WAAA,IAAe,YAAY,IAAA,EAAM;AACrC,MAAA,OAAA,CAAQ,KAAK,OAAO,CAAA;AAAA,IACrB;AAAA,EACD;AAAA,EAEO,KAAK,OAAA,EAAyB;AACpC,IAAA,IAAA,CAAK,OAAA,CAAQ,KAAK,OAAO,CAAA;AAAA,EAC1B;AAAA,EAEA,MAAM,cAAc,OAAA,EAAwC;AAC3D,IAAA,OAAO,IAAA,CAAK,QAAA,CAAS,aAAA,CAAc,OAAO,CAAA;AAAA,EAC3C;AAAA,EAEA,MAAM,oBAAoB,OAAA,EAAqC;AAC9D,IAAA,OAAO,IAAA,CAAK,QAAA,CAAS,mBAAA,CAAoB,OAAO,CAAA;AAAA,EACjD;AAAA,EAEA,MAAM,WAAA,GAA6B;AAClC,IAAA,OAAO,IAAA,CAAK,QAAA,CAAS,WAAA,CAAY,IAAI,CAAA;AAAA,EACtC;AACD","file":"chunk-3C77OSOD.js","sourcesContent":["import type { Context } from \"hono\";\nimport { WebsocketWrapper } from \"./WebsocketWrapper\";\n\n// biome-ignore lint/suspicious/noExplicitAny: We are using any on purpose to allow any type of session.\nexport type SessionData<TSession extends BaseSession<any, any, any, any>> =\n\tTSession extends BaseSession<\n\t\tinfer TData,\n\t\tinfer _TServerMessage,\n\t\tinfer _TClientMessage,\n\t\tinfer _TEnv\n\t>\n\t\t? TData\n\t\t: never;\n\nexport type SessionClientMessage<\n\t// biome-ignore lint/suspicious/noExplicitAny: We are using any on purpose to allow any type of session.\n\tTSession extends BaseSession<any, any, any, any>,\n> =\n\tTSession extends BaseSession<\n\t\tinfer _TData,\n\t\tinfer _TServerMessage,\n\t\tinfer TClientMessage,\n\t\tinfer _TEnv\n\t>\n\t\t? TClientMessage\n\t\t: never;\n\nexport type SessionServerMessage<\n\t// biome-ignore lint/suspicious/noExplicitAny: We are using any on purpose to allow any type of session.\n\tTSession extends BaseSession<any, any, any, any>,\n> =\n\tTSession extends BaseSession<\n\t\tinfer _TData,\n\t\tinfer TServerMessage,\n\t\tinfer _TClientMessage,\n\t\tinfer _TEnv\n\t>\n\t\t? TServerMessage\n\t\t: never;\n\nexport type SessionEnv<\n\t// biome-ignore lint/suspicious/noExplicitAny: We are using any on purpose to allow any type of session.\n\tTSession extends BaseSession<any, any, any, any>,\n> =\n\tTSession extends BaseSession<\n\t\tinfer _TData,\n\t\tinfer _TServerMessage,\n\t\tinfer _TClientMessage,\n\t\tinfer TEnv extends Cloudflare.Env\n\t>\n\t\t? TEnv\n\t\t: never;\n\nexport type BaseSessionHandlers<\n\tTData,\n\tTServerMessage,\n\tTClientMessage,\n\tTEnv extends object = Cloudflare.Env,\n> = {\n\t/**\n\t * Per-connection state. If omitted, `startFresh` initializes `data` as `{}`\n\t * (use empty `TData`, e.g. `Record<string, never>`).\n\t */\n\tcreateData?: (ctx: Context<{ Bindings: TEnv }>) => TData;\n\thandleMessage: (message: TClientMessage) => Promise<void>;\n\thandleBufferMessage: (message: ArrayBuffer) => Promise<void>;\n\t/** Called when this connection closes; `session` is this {@link BaseSession} instance. */\n\thandleClose: (\n\t\tsession: BaseSession<TData, TServerMessage, TClientMessage, TEnv>,\n\t) => Promise<void>;\n};\n\nexport class BaseSession<\n\tTData,\n\tTServerMessage,\n\tTClientMessage,\n\tTEnv extends object = Cloudflare.Env,\n> {\n\tprivate _data!: TData;\n\n\tpublic get data(): TData {\n\t\treturn this._data;\n\t}\n\n\tprivate set data(data: TData) {\n\t\tthis._data = data;\n\t}\n\n\tprivate readonly wrapper: WebsocketWrapper<TData, TServerMessage>;\n\tprotected readonly handlers: BaseSessionHandlers<\n\t\tTData,\n\t\tTServerMessage,\n\t\tTClientMessage,\n\t\tTEnv\n\t>;\n\n\tconstructor(\n\t\tpublic websocket: WebSocket,\n\t\tprotected sessions: Map<\n\t\t\tWebSocket,\n\t\t\tBaseSession<TData, TServerMessage, TClientMessage, TEnv>\n\t\t>,\n\t\thandlers: BaseSessionHandlers<TData, TServerMessage, TClientMessage, TEnv>,\n\t) {\n\t\tthis.wrapper = new WebsocketWrapper<TData, TServerMessage>(websocket);\n\t\tthis.handlers = handlers;\n\t}\n\n\tpublic startFresh(ctx: Context<{ Bindings: TEnv }>) {\n\t\tthis.data =\n\t\t\tthis.handlers.createData !== undefined\n\t\t\t\t? this.handlers.createData(ctx)\n\t\t\t\t: ({} as TData);\n\t\tthis.wrapper.serializeAttachment(this.data);\n\t}\n\n\tpublic resume() {\n\t\tconst existingData = this.wrapper.deserializeAttachment();\n\t\tif (existingData) {\n\t\t\tthis.data = existingData;\n\t\t} else {\n\t\t\tthrow new Error(\"No data to resume\");\n\t\t}\n\t}\n\n\tpublic update() {\n\t\tthis.wrapper.serializeAttachment(this.data);\n\t}\n\n\tpublic broadcast(message: TServerMessage, excludeSelf = false) {\n\t\tfor (const session of this.sessions.values()) {\n\t\t\tif (excludeSelf && session === this) continue;\n\t\t\tsession.send(message);\n\t\t}\n\t}\n\n\tpublic send(message: TServerMessage) {\n\t\tthis.wrapper.send(message);\n\t}\n\n\tasync handleMessage(message: TClientMessage): Promise<void> {\n\t\treturn this.handlers.handleMessage(message);\n\t}\n\n\tasync handleBufferMessage(message: ArrayBuffer): Promise<void> {\n\t\treturn this.handlers.handleBufferMessage(message);\n\t}\n\n\tasync handleClose(): Promise<void> {\n\t\treturn this.handlers.handleClose(this);\n\t}\n}\n"]}

package/dist/chunk-3LWVEY3R.js

@@ -0,0 +1,130 @@
+import { parseStandardSchema } from './chunk-CAX4POIL.js';
+import { unpack, pack } from 'msgpackr';
+
+var StandardSchemaWebSocketClient = class {
+  constructor(options) {
+    this.clientSchema = options.clientSchema;
+    this.serverSchema = options.serverSchema;
+    this.serializeJson = options.serializeJson ?? JSON.stringify;
+    this.deserializeJson = options.deserializeJson ?? JSON.parse;
+    this.enableBufferMessages = options.enableBufferMessages ?? false;
+    this.onMessageCallback = options.onMessage;
+    this.onValidationError = options.onValidationError;
+    if (options.webSocket) {
+      this.ws = options.webSocket;
+    } else if (options.url) {
+      this.ws = new WebSocket(options.url);
+    } else {
+      throw new Error("Either 'url' or 'webSocket' must be provided");
+    }
+    if (this.enableBufferMessages) {
+      this.ws.binaryType = "arraybuffer";
+    }
+    this.ws.addEventListener("open", (event) => {
+      options.onOpen?.(event);
+    });
+    this.ws.addEventListener("message", (event) => {
+      void this.handleMessageEvent(event);
+    });
+    this.ws.addEventListener("close", (event) => {
+      options.onClose?.(event);
+    });
+    this.ws.addEventListener("error", (event) => {
+      options.onError?.(event);
+    });
+  }
+  async handleMessageEvent(event) {
+    try {
+      let parsedMessage;
+      if (this.enableBufferMessages) {
+        if (!(event.data instanceof ArrayBuffer)) {
+          console.error(
+            "Expected ArrayBuffer but received:",
+            typeof event.data
+          );
+          this.onValidationError?.(
+            new Error("Expected ArrayBuffer in buffer mode"),
+            event.data
+          );
+          return;
+        }
+        const unpacked = unpack(new Uint8Array(event.data));
+        parsedMessage = await parseStandardSchema(this.serverSchema, unpacked);
+      } else {
+        if (typeof event.data !== "string") {
+          console.error("Expected string but received:", typeof event.data);
+          this.onValidationError?.(
+            new Error("Expected string in JSON mode"),
+            event.data
+          );
+          return;
+        }
+        const parsed = this.deserializeJson(event.data);
+        parsedMessage = await parseStandardSchema(this.serverSchema, parsed);
+      }
+      this.onMessageCallback?.(parsedMessage);
+    } catch (error) {
+      console.error("Failed to process message:", error);
+      this.onValidationError?.(
+        error instanceof Error ? error : new Error(String(error)),
+        event.data
+      );
+    }
+  }
+  /**
+   * Send a message (automatically encodes based on mode).
+   */
+  async send(message) {
+    const validatedMessage = await parseStandardSchema(
+      this.clientSchema,
+      message
+    );
+    if (this.enableBufferMessages) {
+      const packed = pack(validatedMessage);
+      this.ws.send(new Uint8Array(packed));
+    } else {
+      this.ws.send(this.serializeJson(validatedMessage));
+    }
+  }
+  close(code, reason) {
+    this.ws.close(code, reason);
+  }
+  get readyState() {
+    return this.ws.readyState;
+  }
+  get socket() {
+    return this.ws;
+  }
+  async waitForOpen() {
+    if (this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      const abortController = new AbortController();
+      const { signal } = abortController;
+      const cleanup = () => {
+        abortController.abort();
+      };
+      this.ws.addEventListener(
+        "open",
+        () => {
+          cleanup();
+          resolve();
+        },
+        { signal }
+      );
+      this.ws.addEventListener(
+        "error",
+        () => {
+          cleanup();
+          reject(new Error("WebSocket connection failed"));
+        },
+        { signal }
+      );
+    });
+  }
+};
+
+export { StandardSchemaWebSocketClient };
+//# sourceMappingURL=chunk-3LWVEY3R.js.map
+//# sourceMappingURL=chunk-3LWVEY3R.js.map

package/dist/chunk-3LWVEY3R.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/StandardSchemaWebSocketClient.ts"],"names":[],"mappings":"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","file":"chunk-3LWVEY3R.js","sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { pack, unpack } from \"msgpackr\";\nimport { parseStandardSchema } from \"./parseStandardSchema\";\n\nexport interface StandardSchemaWebSocketClientOptions<\n\tTClientMessage,\n\tTServerMessage,\n> {\n\t/**\n\t * URL to connect to (required if webSocket not provided)\n\t */\n\turl?: string;\n\t/**\n\t * Existing WebSocket to wrap (alternative to url)\n\t * Useful when getting a WebSocket from honoDoFetcher\n\t */\n\twebSocket?: WebSocket;\n\tclientSchema: StandardSchemaV1<unknown, TClientMessage>;\n\tserverSchema: StandardSchemaV1<unknown, TServerMessage>;\n\tserializeJson?: (value: unknown) => string;\n\tdeserializeJson?: (raw: string) => unknown;\n\tenableBufferMessages?: boolean;\n\tonMessage?: (message: TServerMessage) => void;\n\tonOpen?: (event: Event) => void;\n\tonClose?: (event: CloseEvent) => void;\n\tonError?: (event: Event) => void;\n\tonValidationError?: (error: Error, rawMessage: unknown) => void;\n}\n\nexport class StandardSchemaWebSocketClient<TClientMessage, TServerMessage> {\n\tprivate ws: WebSocket;\n\tprivate readonly clientSchema: StandardSchemaV1<unknown, TClientMessage>;\n\tprivate readonly serverSchema: StandardSchemaV1<unknown, TServerMessage>;\n\tprivate readonly serializeJson: (value: unknown) => string;\n\tprivate readonly deserializeJson: (raw: string) => unknown;\n\tprivate readonly enableBufferMessages: boolean;\n\tprivate readonly onMessageCallback?: (message: TServerMessage) => void;\n\tprivate readonly onValidationError?: (\n\t\terror: Error,\n\t\trawMessage: unknown,\n\t) => void;\n\n\tconstructor(\n\t\toptions: StandardSchemaWebSocketClientOptions<\n\t\t\tTClientMessage,\n\t\t\tTServerMessage\n\t\t>,\n\t) {\n\t\tthis.clientSchema = options.clientSchema;\n\t\tthis.serverSchema = options.serverSchema;\n\t\tthis.serializeJson = options.serializeJson ?? JSON.stringify;\n\t\tthis.deserializeJson = options.deserializeJson ?? JSON.parse;\n\t\tthis.enableBufferMessages = options.enableBufferMessages ?? false;\n\t\tthis.onMessageCallback = options.onMessage;\n\t\tthis.onValidationError = options.onValidationError;\n\n\t\tif (options.webSocket) {\n\t\t\tthis.ws = options.webSocket;\n\t\t} else if (options.url) {\n\t\t\tthis.ws = new WebSocket(options.url);\n\t\t} else {\n\t\t\tthrow new Error(\"Either 'url' or 'webSocket' must be provided\");\n\t\t}\n\n\t\tif (this.enableBufferMessages) {\n\t\t\tthis.ws.binaryType = \"arraybuffer\";\n\t\t}\n\n\t\tthis.ws.addEventListener(\"open\", (event) => {\n\t\t\toptions.onOpen?.(event);\n\t\t});\n\n\t\tthis.ws.addEventListener(\"message\", (event) => {\n\t\t\tvoid this.handleMessageEvent(event);\n\t\t});\n\n\t\tthis.ws.addEventListener(\"close\", (event) => {\n\t\t\toptions.onClose?.(event);\n\t\t});\n\n\t\tthis.ws.addEventListener(\"error\", (event) => {\n\t\t\toptions.onError?.(event);\n\t\t});\n\t}\n\n\tprivate async handleMessageEvent(event: MessageEvent): Promise<void> {\n\t\ttry {\n\t\t\tlet parsedMessage: TServerMessage;\n\n\t\t\tif (this.enableBufferMessages) {\n\t\t\t\tif (!(event.data instanceof ArrayBuffer)) {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\t\"Expected ArrayBuffer but received:\",\n\t\t\t\t\t\ttypeof event.data,\n\t\t\t\t\t);\n\t\t\t\t\tthis.onValidationError?.(\n\t\t\t\t\t\tnew Error(\"Expected ArrayBuffer in buffer mode\"),\n\t\t\t\t\t\tevent.data,\n\t\t\t\t\t);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tconst unpacked = unpack(new Uint8Array(event.data));\n\t\t\t\tparsedMessage = await parseStandardSchema(this.serverSchema, unpacked);\n\t\t\t} else {\n\t\t\t\tif (typeof event.data !== \"string\") {\n\t\t\t\t\tconsole.error(\"Expected string but received:\", typeof event.data);\n\t\t\t\t\tthis.onValidationError?.(\n\t\t\t\t\t\tnew Error(\"Expected string in JSON mode\"),\n\t\t\t\t\t\tevent.data,\n\t\t\t\t\t);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tconst parsed = this.deserializeJson(event.data);\n\t\t\t\tparsedMessage = await parseStandardSchema(this.serverSchema, parsed);\n\t\t\t}\n\n\t\t\tthis.onMessageCallback?.(parsedMessage);\n\t\t} catch (error) {\n\t\t\tconsole.error(\"Failed to process message:\", error);\n\t\t\tthis.onValidationError?.(\n\t\t\t\terror instanceof Error ? error : new Error(String(error)),\n\t\t\t\tevent.data,\n\t\t\t);\n\t\t}\n\t}\n\n\t/**\n\t * Send a message (automatically encodes based on mode).\n\t */\n\tasync send(message: TClientMessage): Promise<void> {\n\t\tconst validatedMessage = await parseStandardSchema(\n\t\t\tthis.clientSchema,\n\t\t\tmessage,\n\t\t);\n\n\t\tif (this.enableBufferMessages) {\n\t\t\tconst packed = pack(validatedMessage);\n\t\t\tthis.ws.send(new Uint8Array(packed));\n\t\t} else {\n\t\t\tthis.ws.send(this.serializeJson(validatedMessage));\n\t\t}\n\t}\n\n\tclose(code?: number, reason?: string): void {\n\t\tthis.ws.close(code, reason);\n\t}\n\n\tget readyState(): number {\n\t\treturn this.ws.readyState;\n\t}\n\n\tget socket(): WebSocket {\n\t\treturn this.ws;\n\t}\n\n\tasync waitForOpen(): Promise<void> {\n\t\tif (this.ws.readyState === WebSocket.OPEN) {\n\t\t\treturn;\n\t\t}\n\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tconst abortController = new AbortController();\n\t\t\tconst { signal } = abortController;\n\n\t\t\tconst cleanup = () => {\n\t\t\t\tabortController.abort();\n\t\t\t};\n\n\t\t\tthis.ws.addEventListener(\n\t\t\t\t\"open\",\n\t\t\t\t() => {\n\t\t\t\t\tcleanup();\n\t\t\t\t\tresolve();\n\t\t\t\t},\n\t\t\t\t{ signal },\n\t\t\t);\n\n\t\t\tthis.ws.addEventListener(\n\t\t\t\t\"error\",\n\t\t\t\t() => {\n\t\t\t\t\tcleanup();\n\t\t\t\t\treject(new Error(\"WebSocket connection failed\"));\n\t\t\t\t},\n\t\t\t\t{ signal },\n\t\t\t);\n\t\t});\n\t}\n}\n"]}