Add newWorkersWebSocketRpcSession for bidirectional server-side WebSockets + typescript fixes (#8)

- Add newWorkersWebSocketRpcSession — new export for bidirectional
WebSocket RPC in Workers. Returns { response, remote } so server-side
code can call back to the client with a typed proxy.
newWorkersWebSocketRpcResponse is now a thin wrapper that discards the
remote.
- Unify tsconfig — single tsconfig.json covers both library and test
files so the editor/language server picks up Cloudflare Workers types.
Add npm run typecheck script.
- Eliminate as any from production code — replace with Record<string,
unknown> casts in type guards. Reduce test as any from 20 to 5 justified
instances.

  Before/after: bidirectional worker fixture


```ts
  // Before (20 lines, manual plumbing, untyped)
  if (request.headers.get("Upgrade") !== "websocket") {
    return new Response("Expected WebSocket upgrade", { status: 400 });
  }
  const pair = new WebSocketPair();
  const [client, server] = Object.values(pair);
  server.accept();
  const transport = createWebSocketTransport(server);
  const biService = {
    async addWithClientMultiplier(a: number, b: number): Promise<number> {
      const multiplier: number = await (session.remote as any).getMultiplier();
      return (a + b) * multiplier;
    },
  };
  const session = new RpcSession(transport, biService, { role: "acceptor" });
  return new Response(null, { status: 101, webSocket: client });

  // After (8 lines, fully typed)
  const biService = {
    async addWithClientMultiplier(a: number, b: number): Promise<number> {
      const multiplier = await remote.getMultiplier();
      return (a + b) * multiplier;
    },
  };
  const { response, remote } = newWorkersWebSocketRpcSession<ClientService>(request, biService);
  return response;
```

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jmorrell

AGENTS.md

@@ -29,7 +29,7 @@ Last verified: 2026-02-15
 - `src/core.ts` - Shared types, error classes, and transport-agnostic JSON-RPC 2.0 engine (wire format types, type guards, request/response builders, RpcProtocolError, RPC processor)
 - `src/http-batch.ts` - HTTP batch transport: newHttpBatchRpcResponse (server) + newHttpBatchRpcSession (client with auto-batching)
 - `src/session.ts` - Bidirectional RPC over message transports (defines session-specific types: RpcMessageTransport, RpcSessionOptions, RpcSession)
-- `src/websocket.ts` - WebSocket transport: newWorkersWebSocketRpcResponse (server) + newWebSocketRpcSession (client with Disposable proxy)
+- `src/websocket.ts` - WebSocket transport: newWorkersWebSocketRpcResponse (server, fire-and-forget) + newWorkersWebSocketRpcSession (server, bidirectional with typed remote proxy) + newWebSocketRpcSession (client with Disposable proxy)
 - `src/__tests__/` - Test files
 - `src/__tests__/fixtures/worker.ts` - Test worker entry point for Workers runtime tests
 - `docs/` - Design documents and implementation plans
@@ -39,7 +39,7 @@ Last verified: 2026-02-15
 
 Single public entry point via index.ts:
 
-- `@jmorrell/jsonrpc` - newHttpBatchRpcResponse, newHttpBatchRpcSession, newWorkersWebSocketRpcResponse, newWebSocketRpcSession, newWorkersRpcResponse, RpcError, RpcProtocolError
+- `@jmorrell/jsonrpc` - newHttpBatchRpcResponse, newHttpBatchRpcSession, newWorkersWebSocketRpcResponse, newWorkersWebSocketRpcSession, newWebSocketRpcSession, newWorkersRpcResponse, RpcError, RpcProtocolError
 
 ## Conventions
 

package.json

@@ -13,6 +13,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "lint": "oxlint",

src/__tests__/core.test.ts

@@ -7,6 +7,7 @@ import {
   processRpc,
   RpcProtocolError,
 } from "../core.js";
+import type { JsonRpcResponse } from "../core.js";
 
 // --- isJsonRpcResponse ---
 
@@ -202,18 +203,15 @@ const service = {
     throw new Error("Something went wrong");
   },
   throwsWithCode() {
-    const err = new Error("Custom error");
-    (err as any).code = 42;
-    (err as any).data = { detail: "extra info" };
-    throw err;
+    throw Object.assign(new Error("Custom error"), { code: 42, data: { detail: "extra info" } });
   },
   returnsUndefined() {
     return undefined;
   },
   async asyncAdd(a: number, b: number) {
     return a + b;
   },
-  notAFunction: 42 as any,
+  notAFunction: 42 as any, // deliberate type violation to test non-function method error handling
 };
 
 describe("processRpc single requests", () => {
@@ -508,13 +506,14 @@ describe("processRpc batch", () => {
       service,
     );
     expect(result).toHaveLength(3);
-    expect((result as any)[0]).toEqual({ jsonrpc: "2.0", id: 1, result: 3 });
-    expect((result as any)[1]).toMatchObject({
+    const arr = result as JsonRpcResponse[];
+    expect(arr[0]).toEqual({ jsonrpc: "2.0", id: 1, result: 3 });
+    expect(arr[1]).toMatchObject({
       jsonrpc: "2.0",
       id: 2,
       error: { code: -32000, message: "Something went wrong" },
     });
-    expect((result as any)[2]).toEqual({ jsonrpc: "2.0", id: 3, result: 2 });
+    expect(arr[2]).toEqual({ jsonrpc: "2.0", id: 3, result: 2 });
   });
 
   it("executes batch items concurrently", async () => {

src/__tests__/fixtures/worker.ts

@@ -1,7 +1,5 @@
 // Test worker for Workers runtime tests
-import { newWorkersRpcResponse } from "../../index.js";
-import { RpcSession } from "../../session.js";
-import { createWebSocketTransport } from "../../websocket.js";
+import { newWorkersRpcResponse, newWorkersWebSocketRpcSession } from "../../index.js";
 
 // Test service shared between HTTP and WebSocket transports
 const service = {
@@ -16,32 +14,26 @@ const service = {
   },
 };
 
+type ClientService = { getMultiplier(): number };
+
 export default {
   async fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
 
     // Bidirectional test endpoint: server method calls back to client
     if (url.pathname === "/bidirectional") {
-      if (request.headers.get("Upgrade") !== "websocket") {
-        return new Response("Expected WebSocket upgrade", { status: 400 });
-      }
-
-      const pair = new WebSocketPair();
-      const [client, server] = Object.values(pair);
-      server.accept();
-
-      const transport = createWebSocketTransport(server);
-
       const biService = {
         async addWithClientMultiplier(a: number, b: number): Promise<number> {
-          const multiplier: number = await (session.remote as any).getMultiplier();
+          const multiplier = await remote.getMultiplier();
           return (a + b) * multiplier;
         },
       };
 
-      const session = new RpcSession(transport, biService, { role: "acceptor" });
-
-      return new Response(null, { status: 101, webSocket: client });
+      const { response, remote } = newWorkersWebSocketRpcSession<ClientService, typeof biService>(
+        request,
+        biService,
+      );
+      return response;
     }
 
     return newWorkersRpcResponse(request, service);

src/__tests__/property.test.ts

@@ -16,7 +16,7 @@ const service = {
 
 function isValidResponse(res: unknown): res is JsonRpcResponse {
   if (typeof res !== "object" || res === null) return false;
-  const r = res as any;
+  const r = res as Record<string, unknown>;
   if (r.jsonrpc !== "2.0") return false;
   if (!("id" in r)) return false;
   if ("result" in r && !("error" in r)) return true;
@@ -25,8 +25,8 @@ function isValidResponse(res: unknown): res is JsonRpcResponse {
     return (
       typeof e === "object" &&
       e !== null &&
-      typeof e.code === "number" &&
-      typeof e.message === "string"
+      typeof (e as Record<string, unknown>).code === "number" &&
+      typeof (e as Record<string, unknown>).message === "string"
     );
   }
   return false;
@@ -67,7 +67,7 @@ describe("property-based tests", () => {
         async (batch) => {
           const result = await processRpc(batch, service);
           expect(Array.isArray(result)).toBe(true);
-          expect((result as any[]).length).toBe(batch.length);
+          expect((result as JsonRpcResponse[]).length).toBe(batch.length);
         },
       ),
       { numRuns: 200 },
@@ -109,7 +109,7 @@ describe("property-based tests", () => {
         }),
         async (request) => {
           const result = await processRpc(request, service);
-          if (result && "error" in (result as any)) {
+          if (result && !Array.isArray(result) && "error" in result) {
             const err = (result as JsonRpcErrorResponse).error;
             expect(typeof err.code).toBe("number");
             expect(typeof err.message).toBe("string");

src/__tests__/session.test.ts

@@ -425,10 +425,10 @@ describe("Remote method that throws", () => {
 
     const acceptorService: ThrowService = {
       throwWithData(): Promise<never> {
-        const err = new Error("Something went wrong");
-        (err as any).code = -32000;
-        (err as any).data = { details: "extra info" };
-        throw err;
+        throw Object.assign(new Error("Something went wrong"), {
+          code: -32000,
+          data: { details: "extra info" },
+        });
       },
     };
 
@@ -907,8 +907,8 @@ describe("session lifecycle", () => {
     // Verify error was logged via onError (send failed because transport is closed)
     expect(onErrorCalled).toBe(true);
     expect(errorLogged).toBeInstanceOf(RpcProtocolError);
-    expect((errorLogged as RpcProtocolError).code).toBe("SEND_FAILED");
-    expect((errorLogged as RpcProtocolError).cause).toBeInstanceOf(Error);
+    expect((errorLogged as unknown as RpcProtocolError).code).toBe("SEND_FAILED");
+    expect((errorLogged as unknown as RpcProtocolError).cause).toBeInstanceOf(Error);
 
     sessionA.close();
     sessionB.close();
@@ -1785,17 +1785,13 @@ describe("Bidirectional RPC", () => {
 
     const serviceA: ServiceA = {
       failA() {
-        const err = new Error("Error from A");
-        (err as any).code = -32001;
-        throw err;
+        throw Object.assign(new Error("Error from A"), { code: -32001 });
       },
     };
 
     const serviceB: ServiceB = {
       failB() {
-        const err = new Error("Error from B");
-        (err as any).code = -32002;
-        throw err;
+        throw Object.assign(new Error("Error from B"), { code: -32002 });
       },
     };
 

src/__tests__/spec.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { processRpc } from "../core.js";
+import type { JsonRpcResponse } from "../core.js";
 import { newHttpBatchRpcResponse } from "../http-batch.js";
 
 // Service for spec compliance tests
@@ -34,7 +35,7 @@ describe("spec compliance: error codes", () => {
       body: '{"jsonrpc": "2.0", "method": "foobar, "id": "1"}',
     });
     const res = await newHttpBatchRpcResponse(req, service);
-    const json = await res.json();
+    const json = (await res.json()) as any; // Response.json() returns unknown
     expect(json.error.code).toBe(-32700);
     expect(json.error.message).toBe("Parse error");
     expect(json.id).toBeNull();
@@ -194,12 +195,12 @@ describe("spec examples (adapted for by-position params only)", () => {
       service,
     );
     expect(Array.isArray(result)).toBe(true);
-    const arr = result as any[];
+    const arr = result as JsonRpcResponse[];
     // Should have 5 responses (notification produces none)
     expect(arr).toHaveLength(5);
 
     // sum(1,2,4) = 7
-    expect(arr.find((r: any) => r.id === "1")).toEqual({
+    expect(arr.find((r) => r.id === "1")).toEqual({
       jsonrpc: "2.0",
       result: 7,
       id: "1",

src/__tests__/websocket.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 import {
   newWorkersWebSocketRpcResponse,
+  newWorkersWebSocketRpcSession,
   newWebSocketRpcSession,
   createWebSocketTransport,
 } from "../websocket.js";
@@ -21,4 +22,31 @@ describe("WebSocket transport and RPC", () => {
       expect(response.status).toBe(400);
     });
   });
+
+  describe("newWorkersWebSocketRpcSession", () => {
+    it("should return 400 response for non-upgrade requests", () => {
+      const request = new Request("http://example.com", { method: "GET" });
+      const { response } = newWorkersWebSocketRpcSession(request);
+
+      expect(response.status).toBe(400);
+    });
+
+    it("should return a remote that allows dispose/close on non-upgrade requests", () => {
+      const request = new Request("http://example.com", { method: "GET" });
+      const { remote } = newWorkersWebSocketRpcSession(request);
+
+      // dispose and close should be no-ops, not throw
+      expect(() => remote[Symbol.dispose]()).not.toThrow();
+      expect(() => remote.close()).not.toThrow();
+    });
+
+    it("should return a remote that throws on method access for non-upgrade requests", () => {
+      const request = new Request("http://example.com", { method: "GET" });
+      const { remote } = newWorkersWebSocketRpcSession<{ add(a: number, b: number): number }>(
+        request,
+      );
+
+      expect(() => (remote as any).add).toThrow(); // bypass typed proxy to test dead proxy behavior
+    });
+  });
 });

src/__tests__/workers.workers.test.ts

@@ -4,14 +4,15 @@ import {
   newHttpBatchRpcResponse,
   newHttpBatchRpcSession,
   newWorkersWebSocketRpcResponse,
+  newWorkersWebSocketRpcSession,
   newWebSocketRpcSession,
   newWorkersRpcResponse,
   RpcError,
   RpcProtocolError,
 } from "../index.js";
 
-describe("All 7 exports resolve from entry point", () => {
-  it("should export all 7 required symbols with correct types", () => {
+describe("All exports resolve from entry point", () => {
+  it("should export all required symbols with correct types", () => {
     // newHttpBatchRpcResponse (function)
     expect(typeof newHttpBatchRpcResponse).toBe("function");
 
@@ -21,6 +22,9 @@ describe("All 7 exports resolve from entry point", () => {
     // newWorkersWebSocketRpcResponse (function)
     expect(typeof newWorkersWebSocketRpcResponse).toBe("function");
 
+    // newWorkersWebSocketRpcSession (function)
+    expect(typeof newWorkersWebSocketRpcSession).toBe("function");
+
     // newWebSocketRpcSession (function)
     expect(typeof newWebSocketRpcSession).toBe("function");
 
@@ -34,17 +38,18 @@ describe("All 7 exports resolve from entry point", () => {
     expect(typeof RpcProtocolError).toBe("function");
   });
 
-  it("should instantiate RpcError with message", () => {
-    const error = new RpcError("test error");
+  it("should instantiate RpcError with message and code", () => {
+    const error = new RpcError("test error", -32600);
     expect(error).toBeInstanceOf(RpcError);
     expect(error.message).toBe("test error");
+    expect(error.code).toBe(-32600);
   });
 
-  it("should instantiate RpcProtocolError with message", () => {
-    const error = new RpcProtocolError(-32700, "protocol error");
+  it("should instantiate RpcProtocolError with code and message", () => {
+    const error = new RpcProtocolError("PARSE_ERROR", "protocol error");
     expect(error).toBeInstanceOf(RpcProtocolError);
     expect(error.message).toBe("protocol error");
-    expect(error.code).toBe(-32700);
+    expect(error.code).toBe("PARSE_ERROR");
   });
 });
 
@@ -86,7 +91,7 @@ describe("Workers runtime integration tests", () => {
 
       expect(response.status).toBe(200);
 
-      const data = await response.json();
+      const data = (await response.json()) as any; // Response.json() returns unknown
       expect(Array.isArray(data)).toBe(true);
       expect(data).toHaveLength(3);
       expect(data[0]).toEqual({ jsonrpc: "2.0", id: 1, result: 3 });
@@ -112,7 +117,7 @@ describe("Workers runtime integration tests", () => {
 
       expect(response.status).toBe(200);
 
-      const data = await response.json();
+      const data = (await response.json()) as any; // Response.json() returns unknown
       expect(data.error).toBeDefined();
       expect(data.error.code).toBe(-32601); // Method not found
     });

src/core.ts

@@ -68,12 +68,11 @@ export type RpcHandlerOptions = {
  */
 export function isJsonRpcResponse(res: unknown): res is JsonRpcResponse {
   if (typeof res !== "object" || res === null) return false;
-  if (!("jsonrpc" in res) || (res as any).jsonrpc !== "2.0") return false; // narrowing unknown in type guard
+  const obj = res as Record<string, unknown>;
+  if (obj.jsonrpc !== "2.0") return false;
   if (
-    !("id" in res) ||
-    (typeof (res as any).id !== "string" && // narrowing unknown in type guard
-      typeof (res as any).id !== "number" &&
-      (res as any).id !== null)
+    !("id" in obj) ||
+    (typeof obj.id !== "string" && typeof obj.id !== "number" && obj.id !== null)
   )
     return false;
 
@@ -176,24 +175,10 @@ export function extractError(err: unknown): {
   message: string;
   data?: unknown;
 } {
-  const code =
-    typeof err === "object" &&
-    err !== null &&
-    "code" in err &&
-    typeof (err as any).code === "number" // narrowing unknown in type guard
-      ? (err as any).code // narrowing unknown in type guard
-      : -32000;
-  const message =
-    typeof err === "object" &&
-    err !== null &&
-    "message" in err &&
-    typeof (err as any).message === "string" // narrowing unknown in type guard
-      ? (err as any).message // narrowing unknown in type guard
-      : "";
-  const data =
-    typeof err === "object" && err !== null && "data" in err
-      ? (err as any).data // narrowing unknown in type guard
-      : undefined;
+  const obj = typeof err === "object" && err !== null ? (err as Record<string, unknown>) : null;
+  const code = obj && typeof obj.code === "number" ? obj.code : -32000;
+  const message = obj && typeof obj.message === "string" ? obj.message : "";
+  const data = obj && "data" in obj ? obj.data : undefined;
   return { code, message, data };
 }