Model websocket adapter failures with tagged errors

ts/packages/client/src/__tests__/websocket-adapter.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  getRandomValues as fillRandomValues,
+  getWebSocketConstructor,
+  WebSocketAdapterError,
+  WS_OPEN,
+} from "../socket/websocket-adapter.js";
+
+class FakeWebSocket {
+  readonly readyState = WS_OPEN;
+
+  constructor(readonly url: string) {}
+
+  send(_data: string): void {}
+
+  close(_code?: number, _reason?: string): void {}
+
+  addEventListener(_type: string, _listener: (event: { readonly type: string }) => void): void {}
+
+  removeEventListener(_type: string, _listener: (event: { readonly type: string }) => void): void {}
+}
+
+describe("websocket adapter", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("prefers a compatible global WebSocket constructor", () => {
+    vi.stubGlobal("WebSocket", FakeWebSocket);
+
+    const Constructor = getWebSocketConstructor();
+    const socket = new Constructor("ws://example.test/rpc");
+
+    expect(socket).toBeInstanceOf(FakeWebSocket);
+    expect(socket.readyState).toBe(WS_OPEN);
+  });
+
+  it("loads the optional ws constructor when no global WebSocket exists", () => {
+    vi.stubGlobal("WebSocket", undefined);
+
+    expect(getWebSocketConstructor()).toBeTypeOf("function");
+  });
+
+  it("uses global crypto when available", () => {
+    const getRandomValues = vi.fn((target: Uint32Array) => {
+      target[0] = 42;
+      return target;
+    });
+    vi.stubGlobal("crypto", { getRandomValues });
+
+    const values = fillRandomValues(new Uint32Array(1));
+
+    expect(values[0]).toBe(42);
+    expect(getRandomValues).toHaveBeenCalledOnce();
+  });
+
+  it("raises a typed error when no crypto source is available", () => {
+    vi.stubGlobal("crypto", undefined);
+
+    expect(() => fillRandomValues(new Uint32Array(2))).toThrow(WebSocketAdapterError);
+  });
+
+  it("exposes typed adapter errors", () => {
+    const error = WebSocketAdapterError.make({
+      operation: "test",
+      message: "typed",
+    });
+
+    expect(error._tag).toBe("WebSocketAdapterError");
+    expect(error.message).toBe("typed");
+  });
+});

ts/packages/client/src/socket/websocket-adapter.ts

@@ -7,6 +7,7 @@
  * Provides its own minimal type definitions for the WebSocket API surface
  * we actually use, so the package does not require DOM lib types.
  */
+import { Result, Schema as S } from "effect";
 
 // ---------------------------------------------------------------------------
 // WebSocket readyState constants (identical in browser WebSocket and 'ws')
@@ -64,6 +65,41 @@ export interface IsomorphicWebSocketConstructor {
   new (url: string): IsomorphicWebSocket;
 }
 
+export class WebSocketAdapterError extends S.TaggedErrorClass<WebSocketAdapterError>()(
+  "WebSocketAdapterError",
+  {
+    message: S.String,
+    operation: S.String,
+  },
+) {}
+
+const adapterError = (operation: string, message: string): WebSocketAdapterError =>
+  WebSocketAdapterError.make({ operation, message });
+
+interface CryptoModule {
+  readonly randomFillSync: (array: Uint32Array) => Uint32Array;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isWebSocketConstructor(value: unknown): value is IsomorphicWebSocketConstructor {
+  return typeof value === "function";
+}
+
+function websocketConstructorFromModule(value: unknown): IsomorphicWebSocketConstructor | undefined {
+  if (isWebSocketConstructor(value)) return value;
+  if (!isRecord(value)) return undefined;
+  if (isWebSocketConstructor(value.WebSocket)) return value.WebSocket;
+  if (isWebSocketConstructor(value.default)) return value.default;
+  return undefined;
+}
+
+function isCryptoModule(value: unknown): value is CryptoModule {
+  return isRecord(value) && typeof value.randomFillSync === "function";
+}
+
 // ---------------------------------------------------------------------------
 // Runtime helpers
 // ---------------------------------------------------------------------------
@@ -74,24 +110,33 @@ export interface IsomorphicWebSocketConstructor {
  * - Browser: uses `globalThis.WebSocket` (native)
  * - Node.js: dynamically `require`s the `ws` npm package
  *
- * @throws Error if no WebSocket implementation is available
+ * @throws WebSocketAdapterError if no WebSocket implementation is available
  */
 export function getWebSocketConstructor(): IsomorphicWebSocketConstructor {
   // Browser environment (or Deno, Bun, etc. where WebSocket is global)
-  if (typeof globalThis !== "undefined" && "WebSocket" in globalThis) {
-    return (globalThis as unknown as { WebSocket: IsomorphicWebSocketConstructor }).WebSocket;
+  const globalWebSocket = typeof globalThis !== "undefined" ? globalThis.WebSocket : undefined;
+  if (isWebSocketConstructor(globalWebSocket)) {
+    return globalWebSocket;
   }
 
   // Node.js environment — dynamically require 'ws'
-  try {
+  const wsModule = Result.getOrThrow(Result.try({
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const ws = require("ws");
-    return ws as IsomorphicWebSocketConstructor;
-  } catch {
-    throw new Error(
-      'WebSocket is not available. In Node.js, install the "ws" package: npm install ws',
+    try: (): unknown => require("ws"),
+    catch: () =>
+      adapterError(
+        "websocket-constructor",
+        'WebSocket is not available. In Node.js, install the "ws" package: npm install ws',
+      ),
+  }));
+  const wsConstructor = websocketConstructorFromModule(wsModule);
+  if (wsConstructor === undefined) {
+    throw adapterError(
+      "websocket-constructor",
+      'The "ws" package did not export a compatible WebSocket constructor',
     );
   }
+  return wsConstructor;
 }
 
 /**
@@ -122,14 +167,20 @@ export function getRandomValues(array: Uint32Array): Uint32Array {
     return array;
   }
   // Node.js fallback for versions < 19 where globalThis.crypto may not exist
-  try {
+  const cryptoModule = Result.getOrThrow(Result.try({
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { randomFillSync } = require("node:crypto");
-    return randomFillSync(array) as Uint32Array;
-  } catch {
-    throw new Error(
-      "No cryptographic random source available. " +
-        "Upgrade to Node.js 19+ or ensure the 'crypto' module is available.",
+    try: (): unknown => require("node:crypto"),
+    catch: () =>
+      adapterError(
+        "random-values",
+        "No cryptographic random source available. Upgrade to Node.js 19+ or ensure the 'crypto' module is available.",
+      ),
+  }));
+  if (!isCryptoModule(cryptoModule)) {
+    throw adapterError(
+      "random-values",
+      'The "node:crypto" module did not export randomFillSync',
     );
   }
+  return cryptoModule.randomFillSync(array);
 }