@rivetkit/virtual-websocket 0.0.0-pr.4600.db261bc

package/dist/mod.cjs

@@ -0,0 +1,262 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/mod.ts
+var mod_exports = {};
+__export(mod_exports, {
+  VirtualWebSocket: () => VirtualWebSocket
+});
+module.exports = __toCommonJS(mod_exports);
+
+// src/virtual-websocket.ts
+var VirtualWebSocket = class {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  CONNECTING = 0;
+  OPEN = 1;
+  CLOSING = 2;
+  CLOSED = 3;
+  #options;
+  #listeners = /* @__PURE__ */ new Map();
+  #onopen = null;
+  #onclose = null;
+  #onerror = null;
+  #onmessage = null;
+  constructor(options) {
+    this.#options = options;
+  }
+  // UniversalWebSocket properties
+  get readyState() {
+    return this.#options.getReadyState();
+  }
+  /**
+   * Binary type for message data. Only "arraybuffer" is supported.
+   * Setting to "blob" will throw an error.
+   */
+  get binaryType() {
+    return "arraybuffer";
+  }
+  set binaryType(value) {
+    if (value !== "arraybuffer") {
+      throw new DOMException(
+        'VirtualWebSocket only supports binaryType "arraybuffer"',
+        "NotSupportedError"
+      );
+    }
+  }
+  get bufferedAmount() {
+    return 0;
+  }
+  get extensions() {
+    return "";
+  }
+  get protocol() {
+    return "";
+  }
+  get url() {
+    return "";
+  }
+  // UniversalWebSocket methods
+  send(data) {
+    const state = this.readyState;
+    if (state === this.CONNECTING) {
+      throw new DOMException(
+        "WebSocket is still in CONNECTING state",
+        "InvalidStateError"
+      );
+    }
+    if (state === this.CLOSING || state === this.CLOSED) {
+      return;
+    }
+    this.#options.onSend(data);
+  }
+  close(code = 1e3, reason = "") {
+    const state = this.readyState;
+    if (state === this.CLOSED || state === this.CLOSING) {
+      return;
+    }
+    if (code !== 1e3 && (code < 3e3 || code > 4999) && code !== 1001 && code !== 1002 && code !== 1003 && code !== 1007 && code !== 1008 && code !== 1009 && code !== 1010 && code !== 1011) {
+      throw new DOMException("Invalid close code", "InvalidAccessError");
+    }
+    if (new TextEncoder().encode(reason).length > 123) {
+      throw new DOMException("Close reason too long", "SyntaxError");
+    }
+    this.#options.onClose(code, reason);
+  }
+  /** @experimental Immediate close without close frame */
+  terminate() {
+    if (this.#options.onTerminate) {
+      this.#options.onTerminate();
+    } else {
+      this.#options.onClose(1006, "Abnormal Closure");
+    }
+  }
+  addEventListener(type, listener) {
+    if (!this.#listeners.has(type)) {
+      this.#listeners.set(type, []);
+    }
+    this.#listeners.get(type).push(listener);
+  }
+  removeEventListener(type, listener) {
+    const listeners = this.#listeners.get(type);
+    if (listeners) {
+      const index = listeners.indexOf(listener);
+      if (index !== -1) {
+        listeners.splice(index, 1);
+      }
+    }
+  }
+  dispatchEvent(event) {
+    this.#dispatch(event.type, event);
+    return true;
+  }
+  // on* property getters/setters
+  get onopen() {
+    return this.#onopen;
+  }
+  set onopen(fn) {
+    this.#onopen = fn;
+  }
+  get onclose() {
+    return this.#onclose;
+  }
+  set onclose(fn) {
+    this.#onclose = fn;
+  }
+  get onerror() {
+    return this.#onerror;
+  }
+  set onerror(fn) {
+    this.#onerror = fn;
+  }
+  get onmessage() {
+    return this.#onmessage;
+  }
+  set onmessage(fn) {
+    this.#onmessage = fn;
+  }
+  // Helper methods to trigger events from the other side
+  triggerOpen() {
+    const event = {
+      type: "open",
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("open", event);
+  }
+  triggerMessage(data, rivetMessageIndex) {
+    const event = {
+      type: "message",
+      data,
+      rivetMessageIndex,
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("message", event);
+  }
+  triggerClose(code, reason, wasClean) {
+    const event = {
+      type: "close",
+      code,
+      reason,
+      wasClean: wasClean ?? code === 1e3,
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("close", event);
+  }
+  triggerError(error) {
+    const event = {
+      type: "error",
+      target: this,
+      currentTarget: this,
+      error,
+      message: error instanceof Error ? error.message : String(error)
+    };
+    this.#dispatch("error", event);
+  }
+  #dispatch(type, event) {
+    const listeners = this.#listeners.get(type);
+    if (listeners && listeners.length > 0) {
+      for (const listener of listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          console.error("Error in WebSocket event listener:", err);
+        }
+      }
+    }
+    switch (type) {
+      case "open":
+        if (this.#onopen) {
+          try {
+            this.#onopen(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onopen handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "close":
+        if (this.#onclose) {
+          try {
+            this.#onclose(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onclose handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "error":
+        if (this.#onerror) {
+          try {
+            this.#onerror(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onerror handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "message":
+        if (this.#onmessage) {
+          try {
+            this.#onmessage(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onmessage handler:",
+              err
+            );
+          }
+        }
+        break;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VirtualWebSocket
+});

package/dist/mod.d.cts

@@ -0,0 +1,112 @@
+interface RivetEvent {
+    type: string;
+    target?: any;
+    currentTarget?: any;
+    /**
+     * @experimental
+     * Gateway ID for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetGatewayId?: ArrayBuffer;
+    /**
+     * @experimental
+     * Request ID for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetRequestId?: ArrayBuffer;
+}
+interface RivetMessageEvent extends RivetEvent {
+    data: any;
+    /**
+     * @experimental
+     * Message index for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetMessageIndex?: number;
+}
+interface RivetCloseEvent extends RivetEvent {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/**
+ * Common WebSocket interface that can be implemented by different WebSocket-like classes
+ * This is compatible with the standard WebSocket API but allows for custom implementations
+ */
+interface UniversalWebSocket {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    readonly readyState: 0 | 1 | 2 | 3;
+    binaryType: "arraybuffer" | "blob";
+    readonly bufferedAmount: number;
+    readonly extensions: string;
+    readonly protocol: string;
+    readonly url: string;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void | Promise<void>): void;
+    removeEventListener(type: string, listener: (event: any) => void | Promise<void>): void;
+    dispatchEvent(event: RivetEvent): boolean;
+    onopen?: ((event: RivetEvent) => void | Promise<void>) | null;
+    onclose?: ((event: RivetCloseEvent) => void | Promise<void>) | null;
+    onerror?: ((event: RivetEvent) => void | Promise<void>) | null;
+    onmessage?: ((event: RivetMessageEvent) => void | Promise<void>) | null;
+}
+
+interface VirtualWebSocketOptions {
+    /** Get the current ready state */
+    getReadyState: () => 0 | 1 | 2 | 3;
+    /** Called when send() is invoked */
+    onSend: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+    /** Called when close() is invoked */
+    onClose: (code: number, reason: string) => void;
+    /** Called when terminate() is invoked (immediate close without close frame) */
+    onTerminate?: () => void;
+}
+/**
+ * Virtual WebSocket implementation that dispatches events and delegates
+ * send/close to callbacks. Used to create linked WebSocket pairs.
+ */
+declare class VirtualWebSocket implements UniversalWebSocket {
+    #private;
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    static readonly CLOSING: 2;
+    static readonly CLOSED: 3;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    constructor(options: VirtualWebSocketOptions);
+    get readyState(): 0 | 1 | 2 | 3;
+    /**
+     * Binary type for message data. Only "arraybuffer" is supported.
+     * Setting to "blob" will throw an error.
+     */
+    get binaryType(): "arraybuffer" | "blob";
+    set binaryType(value: "arraybuffer" | "blob");
+    get bufferedAmount(): number;
+    get extensions(): string;
+    get protocol(): string;
+    get url(): string;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    /** @experimental Immediate close without close frame */
+    terminate(): void;
+    addEventListener(type: string, listener: (ev: any) => void | Promise<void>): void;
+    removeEventListener(type: string, listener: (ev: any) => void | Promise<void>): void;
+    dispatchEvent(event: RivetEvent): boolean;
+    get onopen(): ((event: RivetEvent) => void | Promise<void>) | null;
+    set onopen(fn: ((event: RivetEvent) => void | Promise<void>) | null);
+    get onclose(): ((event: RivetCloseEvent) => void | Promise<void>) | null;
+    set onclose(fn: ((event: RivetCloseEvent) => void | Promise<void>) | null);
+    get onerror(): ((event: RivetEvent) => void | Promise<void>) | null;
+    set onerror(fn: ((event: RivetEvent) => void | Promise<void>) | null);
+    get onmessage(): ((event: RivetMessageEvent) => void | Promise<void>) | null;
+    set onmessage(fn: ((event: RivetMessageEvent) => void | Promise<void>) | null);
+    triggerOpen(): void;
+    triggerMessage(data: any, rivetMessageIndex?: number): void;
+    triggerClose(code: number, reason: string, wasClean?: boolean): void;
+    triggerError(error: unknown): void;
+}
+
+export { type RivetCloseEvent, type RivetEvent, type RivetMessageEvent, type UniversalWebSocket, VirtualWebSocket, type VirtualWebSocketOptions };

package/dist/mod.d.ts

@@ -0,0 +1,112 @@
+interface RivetEvent {
+    type: string;
+    target?: any;
+    currentTarget?: any;
+    /**
+     * @experimental
+     * Gateway ID for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetGatewayId?: ArrayBuffer;
+    /**
+     * @experimental
+     * Request ID for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetRequestId?: ArrayBuffer;
+}
+interface RivetMessageEvent extends RivetEvent {
+    data: any;
+    /**
+     * @experimental
+     * Message index for hibernatable websockets (provided by engine envoy)
+     **/
+    rivetMessageIndex?: number;
+}
+interface RivetCloseEvent extends RivetEvent {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/**
+ * Common WebSocket interface that can be implemented by different WebSocket-like classes
+ * This is compatible with the standard WebSocket API but allows for custom implementations
+ */
+interface UniversalWebSocket {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    readonly readyState: 0 | 1 | 2 | 3;
+    binaryType: "arraybuffer" | "blob";
+    readonly bufferedAmount: number;
+    readonly extensions: string;
+    readonly protocol: string;
+    readonly url: string;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void | Promise<void>): void;
+    removeEventListener(type: string, listener: (event: any) => void | Promise<void>): void;
+    dispatchEvent(event: RivetEvent): boolean;
+    onopen?: ((event: RivetEvent) => void | Promise<void>) | null;
+    onclose?: ((event: RivetCloseEvent) => void | Promise<void>) | null;
+    onerror?: ((event: RivetEvent) => void | Promise<void>) | null;
+    onmessage?: ((event: RivetMessageEvent) => void | Promise<void>) | null;
+}
+
+interface VirtualWebSocketOptions {
+    /** Get the current ready state */
+    getReadyState: () => 0 | 1 | 2 | 3;
+    /** Called when send() is invoked */
+    onSend: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+    /** Called when close() is invoked */
+    onClose: (code: number, reason: string) => void;
+    /** Called when terminate() is invoked (immediate close without close frame) */
+    onTerminate?: () => void;
+}
+/**
+ * Virtual WebSocket implementation that dispatches events and delegates
+ * send/close to callbacks. Used to create linked WebSocket pairs.
+ */
+declare class VirtualWebSocket implements UniversalWebSocket {
+    #private;
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    static readonly CLOSING: 2;
+    static readonly CLOSED: 3;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+    constructor(options: VirtualWebSocketOptions);
+    get readyState(): 0 | 1 | 2 | 3;
+    /**
+     * Binary type for message data. Only "arraybuffer" is supported.
+     * Setting to "blob" will throw an error.
+     */
+    get binaryType(): "arraybuffer" | "blob";
+    set binaryType(value: "arraybuffer" | "blob");
+    get bufferedAmount(): number;
+    get extensions(): string;
+    get protocol(): string;
+    get url(): string;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    /** @experimental Immediate close without close frame */
+    terminate(): void;
+    addEventListener(type: string, listener: (ev: any) => void | Promise<void>): void;
+    removeEventListener(type: string, listener: (ev: any) => void | Promise<void>): void;
+    dispatchEvent(event: RivetEvent): boolean;
+    get onopen(): ((event: RivetEvent) => void | Promise<void>) | null;
+    set onopen(fn: ((event: RivetEvent) => void | Promise<void>) | null);
+    get onclose(): ((event: RivetCloseEvent) => void | Promise<void>) | null;
+    set onclose(fn: ((event: RivetCloseEvent) => void | Promise<void>) | null);
+    get onerror(): ((event: RivetEvent) => void | Promise<void>) | null;
+    set onerror(fn: ((event: RivetEvent) => void | Promise<void>) | null);
+    get onmessage(): ((event: RivetMessageEvent) => void | Promise<void>) | null;
+    set onmessage(fn: ((event: RivetMessageEvent) => void | Promise<void>) | null);
+    triggerOpen(): void;
+    triggerMessage(data: any, rivetMessageIndex?: number): void;
+    triggerClose(code: number, reason: string, wasClean?: boolean): void;
+    triggerError(error: unknown): void;
+}
+
+export { type RivetCloseEvent, type RivetEvent, type RivetMessageEvent, type UniversalWebSocket, VirtualWebSocket, type VirtualWebSocketOptions };

package/dist/mod.js

@@ -0,0 +1,235 @@
+// src/virtual-websocket.ts
+var VirtualWebSocket = class {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  CONNECTING = 0;
+  OPEN = 1;
+  CLOSING = 2;
+  CLOSED = 3;
+  #options;
+  #listeners = /* @__PURE__ */ new Map();
+  #onopen = null;
+  #onclose = null;
+  #onerror = null;
+  #onmessage = null;
+  constructor(options) {
+    this.#options = options;
+  }
+  // UniversalWebSocket properties
+  get readyState() {
+    return this.#options.getReadyState();
+  }
+  /**
+   * Binary type for message data. Only "arraybuffer" is supported.
+   * Setting to "blob" will throw an error.
+   */
+  get binaryType() {
+    return "arraybuffer";
+  }
+  set binaryType(value) {
+    if (value !== "arraybuffer") {
+      throw new DOMException(
+        'VirtualWebSocket only supports binaryType "arraybuffer"',
+        "NotSupportedError"
+      );
+    }
+  }
+  get bufferedAmount() {
+    return 0;
+  }
+  get extensions() {
+    return "";
+  }
+  get protocol() {
+    return "";
+  }
+  get url() {
+    return "";
+  }
+  // UniversalWebSocket methods
+  send(data) {
+    const state = this.readyState;
+    if (state === this.CONNECTING) {
+      throw new DOMException(
+        "WebSocket is still in CONNECTING state",
+        "InvalidStateError"
+      );
+    }
+    if (state === this.CLOSING || state === this.CLOSED) {
+      return;
+    }
+    this.#options.onSend(data);
+  }
+  close(code = 1e3, reason = "") {
+    const state = this.readyState;
+    if (state === this.CLOSED || state === this.CLOSING) {
+      return;
+    }
+    if (code !== 1e3 && (code < 3e3 || code > 4999) && code !== 1001 && code !== 1002 && code !== 1003 && code !== 1007 && code !== 1008 && code !== 1009 && code !== 1010 && code !== 1011) {
+      throw new DOMException("Invalid close code", "InvalidAccessError");
+    }
+    if (new TextEncoder().encode(reason).length > 123) {
+      throw new DOMException("Close reason too long", "SyntaxError");
+    }
+    this.#options.onClose(code, reason);
+  }
+  /** @experimental Immediate close without close frame */
+  terminate() {
+    if (this.#options.onTerminate) {
+      this.#options.onTerminate();
+    } else {
+      this.#options.onClose(1006, "Abnormal Closure");
+    }
+  }
+  addEventListener(type, listener) {
+    if (!this.#listeners.has(type)) {
+      this.#listeners.set(type, []);
+    }
+    this.#listeners.get(type).push(listener);
+  }
+  removeEventListener(type, listener) {
+    const listeners = this.#listeners.get(type);
+    if (listeners) {
+      const index = listeners.indexOf(listener);
+      if (index !== -1) {
+        listeners.splice(index, 1);
+      }
+    }
+  }
+  dispatchEvent(event) {
+    this.#dispatch(event.type, event);
+    return true;
+  }
+  // on* property getters/setters
+  get onopen() {
+    return this.#onopen;
+  }
+  set onopen(fn) {
+    this.#onopen = fn;
+  }
+  get onclose() {
+    return this.#onclose;
+  }
+  set onclose(fn) {
+    this.#onclose = fn;
+  }
+  get onerror() {
+    return this.#onerror;
+  }
+  set onerror(fn) {
+    this.#onerror = fn;
+  }
+  get onmessage() {
+    return this.#onmessage;
+  }
+  set onmessage(fn) {
+    this.#onmessage = fn;
+  }
+  // Helper methods to trigger events from the other side
+  triggerOpen() {
+    const event = {
+      type: "open",
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("open", event);
+  }
+  triggerMessage(data, rivetMessageIndex) {
+    const event = {
+      type: "message",
+      data,
+      rivetMessageIndex,
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("message", event);
+  }
+  triggerClose(code, reason, wasClean) {
+    const event = {
+      type: "close",
+      code,
+      reason,
+      wasClean: wasClean ?? code === 1e3,
+      target: this,
+      currentTarget: this
+    };
+    this.#dispatch("close", event);
+  }
+  triggerError(error) {
+    const event = {
+      type: "error",
+      target: this,
+      currentTarget: this,
+      error,
+      message: error instanceof Error ? error.message : String(error)
+    };
+    this.#dispatch("error", event);
+  }
+  #dispatch(type, event) {
+    const listeners = this.#listeners.get(type);
+    if (listeners && listeners.length > 0) {
+      for (const listener of listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          console.error("Error in WebSocket event listener:", err);
+        }
+      }
+    }
+    switch (type) {
+      case "open":
+        if (this.#onopen) {
+          try {
+            this.#onopen(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onopen handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "close":
+        if (this.#onclose) {
+          try {
+            this.#onclose(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onclose handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "error":
+        if (this.#onerror) {
+          try {
+            this.#onerror(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onerror handler:",
+              err
+            );
+          }
+        }
+        break;
+      case "message":
+        if (this.#onmessage) {
+          try {
+            this.#onmessage(event);
+          } catch (err) {
+            console.error(
+              "Error in WebSocket onmessage handler:",
+              err
+            );
+          }
+        }
+        break;
+    }
+  }
+};
+export {
+  VirtualWebSocket
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@rivetkit/virtual-websocket",
+	"version": "0.0.0-pr.4600.db261bc",
+	"description": "Virtual WebSocket implementation for creating linked WebSocket pairs",
+	"license": "Apache-2.0",
+	"type": "module",
+	"files": [
+		"dist",
+		"src",
+		"package.json"
+	],
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/mod.d.ts",
+				"default": "./dist/mod.js"
+			},
+			"require": {
+				"types": "./dist/mod.d.cts",
+				"default": "./dist/mod.cjs"
+			}
+		}
+	},
+	"scripts": {
+		"build": "tsup src/mod.ts",
+		"check-types": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "^22.13.1",
+		"tsup": "^8.4.0",
+		"typescript": "^5.7.3"
+	},
+	"stableVersion": "0.8.0"
+}

package/src/interface.ts

@@ -0,0 +1,70 @@
+// Define minimal event interfaces to avoid conflicts between different WebSocket implementations
+export interface RivetEvent {
+	type: string;
+	target?: any;
+	currentTarget?: any;
+	/**
+	 * @experimental
+	 * Gateway ID for hibernatable websockets (provided by engine envoy)
+	 **/
+	rivetGatewayId?: ArrayBuffer;
+	/**
+	 * @experimental
+	 * Request ID for hibernatable websockets (provided by engine envoy)
+	 **/
+	rivetRequestId?: ArrayBuffer;
+}
+
+export interface RivetMessageEvent extends RivetEvent {
+	data: any;
+	/**
+	 * @experimental
+	 * Message index for hibernatable websockets (provided by engine envoy)
+	 **/
+	rivetMessageIndex?: number;
+}
+
+export interface RivetCloseEvent extends RivetEvent {
+	code: number;
+	reason: string;
+	wasClean: boolean;
+}
+
+/**
+ * Common WebSocket interface that can be implemented by different WebSocket-like classes
+ * This is compatible with the standard WebSocket API but allows for custom implementations
+ */
+export interface UniversalWebSocket {
+	// WebSocket readyState values
+	readonly CONNECTING: 0;
+	readonly OPEN: 1;
+	readonly CLOSING: 2;
+	readonly CLOSED: 3;
+
+	// Properties
+	readonly readyState: 0 | 1 | 2 | 3;
+	binaryType: "arraybuffer" | "blob";
+	readonly bufferedAmount: number;
+	readonly extensions: string;
+	readonly protocol: string;
+	readonly url: string;
+
+	// Methods
+	send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+	close(code?: number, reason?: string): void;
+	addEventListener(
+		type: string,
+		listener: (event: any) => void | Promise<void>,
+	): void;
+	removeEventListener(
+		type: string,
+		listener: (event: any) => void | Promise<void>,
+	): void;
+	dispatchEvent(event: RivetEvent): boolean;
+
+	// Event handlers (optional)
+	onopen?: ((event: RivetEvent) => void | Promise<void>) | null;
+	onclose?: ((event: RivetCloseEvent) => void | Promise<void>) | null;
+	onerror?: ((event: RivetEvent) => void | Promise<void>) | null;
+	onmessage?: ((event: RivetMessageEvent) => void | Promise<void>) | null;
+}

package/src/mod.ts

@@ -0,0 +1,11 @@
+export type {
+	RivetEvent,
+	RivetMessageEvent,
+	RivetCloseEvent,
+	UniversalWebSocket,
+} from "./interface";
+
+export {
+	VirtualWebSocket,
+	type VirtualWebSocketOptions,
+} from "./virtual-websocket";

package/src/virtual-websocket.ts

@@ -0,0 +1,315 @@
+import type {
+	RivetCloseEvent,
+	RivetEvent,
+	RivetMessageEvent,
+	UniversalWebSocket,
+} from "./interface";
+
+export interface VirtualWebSocketOptions {
+	/** Get the current ready state */
+	getReadyState: () => 0 | 1 | 2 | 3;
+	/** Called when send() is invoked */
+	onSend: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+	/** Called when close() is invoked */
+	onClose: (code: number, reason: string) => void;
+	/** Called when terminate() is invoked (immediate close without close frame) */
+	onTerminate?: () => void;
+}
+
+/**
+ * Virtual WebSocket implementation that dispatches events and delegates
+ * send/close to callbacks. Used to create linked WebSocket pairs.
+ */
+export class VirtualWebSocket implements UniversalWebSocket {
+	static readonly CONNECTING = 0 as const;
+	static readonly OPEN = 1 as const;
+	static readonly CLOSING = 2 as const;
+	static readonly CLOSED = 3 as const;
+
+	readonly CONNECTING = 0 as const;
+	readonly OPEN = 1 as const;
+	readonly CLOSING = 2 as const;
+	readonly CLOSED = 3 as const;
+
+	#options: VirtualWebSocketOptions;
+	#listeners: Map<string, ((ev: any) => void | Promise<void>)[]> =
+		new Map();
+	#onopen: ((event: RivetEvent) => void | Promise<void>) | null = null;
+	#onclose:
+		| ((event: RivetCloseEvent) => void | Promise<void>)
+		| null = null;
+	#onerror: ((event: RivetEvent) => void | Promise<void>) | null = null;
+	#onmessage:
+		| ((event: RivetMessageEvent) => void | Promise<void>)
+		| null = null;
+
+	constructor(options: VirtualWebSocketOptions) {
+		this.#options = options;
+	}
+
+	// UniversalWebSocket properties
+	get readyState(): 0 | 1 | 2 | 3 {
+		return this.#options.getReadyState();
+	}
+
+	/**
+	 * Binary type for message data. Only "arraybuffer" is supported.
+	 * Setting to "blob" will throw an error.
+	 */
+	get binaryType(): "arraybuffer" | "blob" {
+		return "arraybuffer";
+	}
+
+	set binaryType(value: "arraybuffer" | "blob") {
+		if (value !== "arraybuffer") {
+			throw new DOMException(
+				'VirtualWebSocket only supports binaryType "arraybuffer"',
+				"NotSupportedError",
+			);
+		}
+	}
+
+	get bufferedAmount(): number {
+		return 0;
+	}
+
+	get extensions(): string {
+		return "";
+	}
+
+	get protocol(): string {
+		return "";
+	}
+
+	get url(): string {
+		return "";
+	}
+
+	// UniversalWebSocket methods
+	send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void {
+		const state = this.readyState;
+		if (state === this.CONNECTING) {
+			throw new DOMException(
+				"WebSocket is still in CONNECTING state",
+				"InvalidStateError",
+			);
+		}
+		if (state === this.CLOSING || state === this.CLOSED) {
+			return;
+		}
+		this.#options.onSend(data);
+	}
+
+	close(code = 1000, reason = ""): void {
+		const state = this.readyState;
+		if (state === this.CLOSED || state === this.CLOSING) {
+			return;
+		}
+		// Validate close code per WebSocket spec
+		// 1005 and 1006 are reserved and cannot be set by application code
+		if (
+			code !== 1000 &&
+			(code < 3000 || code > 4999) &&
+			code !== 1001 &&
+			code !== 1002 &&
+			code !== 1003 &&
+			code !== 1007 &&
+			code !== 1008 &&
+			code !== 1009 &&
+			code !== 1010 &&
+			code !== 1011
+		) {
+			throw new DOMException("Invalid close code", "InvalidAccessError");
+		}
+		// Validate reason length (must be ≤ 123 bytes UTF-8 encoded)
+		if (new TextEncoder().encode(reason).length > 123) {
+			throw new DOMException("Close reason too long", "SyntaxError");
+		}
+		this.#options.onClose(code, reason);
+	}
+
+	/** @experimental Immediate close without close frame */
+	terminate(): void {
+		if (this.#options.onTerminate) {
+			this.#options.onTerminate();
+		} else {
+			// Fallback to close with abnormal closure code
+			this.#options.onClose(1006, "Abnormal Closure");
+		}
+	}
+
+	addEventListener(
+		type: string,
+		listener: (ev: any) => void | Promise<void>,
+	): void {
+		if (!this.#listeners.has(type)) {
+			this.#listeners.set(type, []);
+		}
+		this.#listeners.get(type)!.push(listener);
+	}
+
+	removeEventListener(
+		type: string,
+		listener: (ev: any) => void | Promise<void>,
+	): void {
+		const listeners = this.#listeners.get(type);
+		if (listeners) {
+			const index = listeners.indexOf(listener);
+			if (index !== -1) {
+				listeners.splice(index, 1);
+			}
+		}
+	}
+
+	dispatchEvent(event: RivetEvent): boolean {
+		this.#dispatch(event.type, event);
+		return true;
+	}
+
+	// on* property getters/setters
+	get onopen(): ((event: RivetEvent) => void | Promise<void>) | null {
+		return this.#onopen;
+	}
+	set onopen(fn: ((event: RivetEvent) => void | Promise<void>) | null) {
+		this.#onopen = fn;
+	}
+
+	get onclose():
+		| ((event: RivetCloseEvent) => void | Promise<void>)
+		| null {
+		return this.#onclose;
+	}
+	set onclose(
+		fn: ((event: RivetCloseEvent) => void | Promise<void>) | null,
+	) {
+		this.#onclose = fn;
+	}
+
+	get onerror(): ((event: RivetEvent) => void | Promise<void>) | null {
+		return this.#onerror;
+	}
+	set onerror(fn: ((event: RivetEvent) => void | Promise<void>) | null) {
+		this.#onerror = fn;
+	}
+
+	get onmessage():
+		| ((event: RivetMessageEvent) => void | Promise<void>)
+		| null {
+		return this.#onmessage;
+	}
+	set onmessage(
+		fn: ((event: RivetMessageEvent) => void | Promise<void>) | null,
+	) {
+		this.#onmessage = fn;
+	}
+
+	// Helper methods to trigger events from the other side
+	triggerOpen(): void {
+		const event = {
+			type: "open",
+			target: this,
+			currentTarget: this,
+		} as unknown as RivetEvent;
+		this.#dispatch("open", event);
+	}
+
+	triggerMessage(data: any, rivetMessageIndex?: number): void {
+		const event = {
+			type: "message",
+			data,
+			rivetMessageIndex,
+			target: this,
+			currentTarget: this,
+		} as unknown as RivetMessageEvent;
+		this.#dispatch("message", event);
+	}
+
+	triggerClose(code: number, reason: string, wasClean?: boolean): void {
+		const event = {
+			type: "close",
+			code,
+			reason,
+			wasClean: wasClean ?? code === 1000,
+			target: this,
+			currentTarget: this,
+		} as unknown as RivetCloseEvent;
+		this.#dispatch("close", event);
+	}
+
+	triggerError(error: unknown): void {
+		const event = {
+			type: "error",
+			target: this,
+			currentTarget: this,
+			error,
+			message: error instanceof Error ? error.message : String(error),
+		} as unknown as RivetEvent;
+		this.#dispatch("error", event);
+	}
+
+	#dispatch(type: string, event: any): void {
+		// Dispatch to addEventListener listeners
+		const listeners = this.#listeners.get(type);
+		if (listeners && listeners.length > 0) {
+			for (const listener of listeners) {
+				try {
+					listener(event);
+				} catch (err) {
+					console.error("Error in WebSocket event listener:", err);
+				}
+			}
+		}
+
+		// Dispatch to on* property handlers
+		switch (type) {
+			case "open":
+				if (this.#onopen) {
+					try {
+						this.#onopen(event);
+					} catch (err) {
+						console.error(
+							"Error in WebSocket onopen handler:",
+							err,
+						);
+					}
+				}
+				break;
+			case "close":
+				if (this.#onclose) {
+					try {
+						this.#onclose(event);
+					} catch (err) {
+						console.error(
+							"Error in WebSocket onclose handler:",
+							err,
+						);
+					}
+				}
+				break;
+			case "error":
+				if (this.#onerror) {
+					try {
+						this.#onerror(event);
+					} catch (err) {
+						console.error(
+							"Error in WebSocket onerror handler:",
+							err,
+						);
+					}
+				}
+				break;
+			case "message":
+				if (this.#onmessage) {
+					try {
+						this.#onmessage(event);
+					} catch (err) {
+						console.error(
+							"Error in WebSocket onmessage handler:",
+							err,
+						);
+					}
+				}
+				break;
+		}
+	}
+}