Add capnweb-typecheck for TypeScript RPC validation codegen

.changeset/typescript-rpc-validators.md

@@ -0,0 +1,12 @@
+---
+"capnweb": minor
+---
+
+Add build-time TypeScript RPC validation codegen.
+
+A new opt-in `capnweb typecheck gen` CLI command and `capnweb/vite` plugin generate runtime validators for `RpcTarget` methods from your TypeScript types. The `capnweb` runtime stays dependency-free; the typecheck tooling uses the project's TypeScript compiler via an optional peer.
+
+- `capnweb typecheck gen`: `capnweb typecheck gen src/worker.ts --out .capnweb` for Wrangler-style builds.
+- `capnweb/vite` plugin: transforms client modules in memory and registers server validators via the worker entry module.
+- Server-side: validators are keyed by `RpcTarget` constructor and check arguments before invocation and return values before serialization.
+- Client-side: typed factory and `new RpcSession<T>(...)` call sites bind validators to the original `RpcStub`, preserving `RpcPromise` pipelining, disposal, and `StubBase` behavior.

.gitignore

@@ -3,3 +3,7 @@ node_modules
 examples/worker-react/web/dist/
 notes.txt
 /dist/
+packages/*/dist/
+.capnweb/
+examples/**/.capnweb/
+examples/worker-react/wrangler.typecheck-dev.toml

__tests__/typecheck-package.test.ts

@@ -0,0 +1,170 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the MIT license found in the LICENSE.txt file or at:
+//     https://opensource.org/license/mit
+//
+// Tests for the `generateForPackage` flow: validators are written into
+// capnweb's `_typecheck-validators` subpath and the runtime auto-binds them
+// by class name without an explicit registration call.
+
+import { linkSync, mkdtempSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  generateForPackage,
+  resetTypecheckPackage,
+} from "../src/typecheck/generate.js";
+
+const FIXTURE = `
+import { RpcTarget } from "capnweb";
+
+export class Echo extends RpcTarget {
+  ping(input: string): string {
+    return input;
+  }
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+`;
+
+describe("generateForPackage", () => {
+  let workDir: string;
+  let inputFile: string;
+
+  beforeAll(() => {
+    workDir = mkdtempSync(join(tmpdir(), "capnweb-typecheck-"));
+    inputFile = join(workDir, "worker.ts");
+    writeFileSync(inputFile, FIXTURE);
+  });
+
+  afterAll(() => {
+    resetTypecheckPackage();
+  });
+
+  it("writes validators that load and reject wrong arg shapes", async () => {
+    generateForPackage({ input: inputFile });
+    // Cache-bust on every import so we read the file we just wrote.
+    let mod = await import("capnweb/_typecheck-validators?nocache=" + Date.now()) as any;
+
+    expect(Object.keys(mod.validators.Echo).sort()).toEqual(["add", "ping"]);
+    expect(() => mod.validators.Echo.ping.args(["hello"])).not.toThrow();
+    expect(() => mod.validators.Echo.ping.args([])).toThrow(/expected 1 argument/);
+    expect(() => mod.validators.Echo.ping.args([42])).toThrow(/expected string/);
+  });
+
+  it("reset restores the null-validators stub", async () => {
+    generateForPackage({ input: inputFile });
+    resetTypecheckPackage();
+
+    let mod = await import("capnweb/_typecheck-validators?nocache=" + Date.now()) as any;
+    expect(mod.validators).toBeNull();
+  });
+
+  it("validates recursive types through hoisted named validators", async () => {
+    let recursiveDir = mkdtempSync(join(tmpdir(), "capnweb-recursive-"));
+    let recursiveInput = join(recursiveDir, "worker.ts");
+    writeFileSync(recursiveInput, `
+import { RpcTarget } from "capnweb";
+
+interface Tree { name: string; children: Tree[]; }
+
+export class TreeApi extends RpcTarget {
+  size(value: Tree): number { return 0; }
+}
+`);
+    generateForPackage({ input: recursiveInput });
+    let m = await import("capnweb/_typecheck-validators?nocache=" + Date.now()) as any;
+
+    // Valid deeply nested tree.
+    let tree = { name: "root", children: [{ name: "leaf", children: [] }] };
+    expect(() => m.validators.TreeApi.size.args([tree])).not.toThrow();
+
+    // Invalid: bad type at a deep level. Must reach the validator via the
+    // hoisted named function calling itself recursively.
+    let bad = { name: "root", children: [{ name: 42, children: [] }] };
+    expect(() => m.validators.TreeApi.size.args([bad])).toThrow(/expected string/);
+  });
+
+  it("throws RpcValidationError with structured payload on argument failures", async () => {
+    generateForPackage({ input: inputFile });
+    let m = await import("capnweb/_typecheck-validators?nocache=" + Date.now()) as any;
+    // Import RpcValidationError from `capnweb` (i.e., the built dist) — that's
+    // the same module the generated validators import from. Importing from
+    // `../src/index.js` would give a different class even though both
+    // construct errors with the same shape, and instanceof would fail.
+    let cw = await import("capnweb") as typeof import("../src/index.js");
+
+    try {
+      m.validators.Echo.ping.args([42]);
+      throw new Error("expected validator to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(cw.RpcValidationError);
+      expect(err).toBeInstanceOf(TypeError);
+      let v = (err as InstanceType<typeof cw.RpcValidationError>);
+      expect(v.name).toBe("RpcValidationError");
+      expect(v.rpcValidation.expected).toBe("string");
+      expect(v.rpcValidation.actual).toBe("number");
+      expect(v.rpcValidation.path).toEqual(["input"]);
+      expect(v.rpcValidation.value).toBe(42);
+    }
+  });
+
+  it("disambiguates two unrelated types that share a display name", async () => {
+    let fixturePath = join(workDir, "name-collision.ts");
+    writeFileSync(fixturePath, `
+import { RpcTarget } from "capnweb";
+
+// Two distinct shapes both called User. Codegen must keep them functionally
+// separate while keeping the names readable.
+namespace Account { export interface User { id: string; } }
+namespace Billing { export interface User { customerId: string; } }
+
+export class Api extends RpcTarget {
+  accountUser(value: Account.User): void {}
+  billingUser(value: Billing.User): void {}
+}
+`);
+    generateForPackage({ input: fixturePath });
+    let m = await import("capnweb/_typecheck-validators?nocache=" + Date.now()) as any;
+
+    // The Account.User validator should accept its shape and reject the
+    // Billing.User shape (and vice versa). If naming collided incorrectly
+    // (both mapped to the same function), one of these would let the wrong
+    // shape through.
+    expect(() => m.validators.Api.accountUser.args([{ id: "u_1" }])).not.toThrow();
+    expect(() => m.validators.Api.accountUser.args([{ customerId: "c_1" }])).toThrow(/expected string/);
+    expect(() => m.validators.Api.billingUser.args([{ customerId: "c_1" }])).not.toThrow();
+    expect(() => m.validators.Api.billingUser.args([{ id: "u_1" }])).toThrow(/expected string/);
+  });
+
+  // pnpm installs packages as hardlinks to a content-addressable store. A
+  // naive `writeFileSync` would truncate the shared inode, corrupting every
+  // other project that depends on the same capnweb version. The generate
+  // path must unlink first so the store entry stays intact.
+  it("does not corrupt a hardlinked sibling of the validators file", () => {
+    let req = createRequire(__filename);
+    let validatorsPath = req.resolve("capnweb/_typecheck-validators");
+    // Hardlinks can't cross filesystems (`EXDEV`). On GitHub Actions
+    // `tmpdir()` (`/tmp`) sits on a different volume from the project
+    // (`/__w/...`), so put the sentinel next to the file we're linking.
+    let sentinel = join(dirname(validatorsPath), "__hardlink-sentinel.js");
+
+    writeFileSync(validatorsPath, "export const validators = null;\n");
+    let beforeInode = statSync(validatorsPath).ino;
+    try { unlinkSync(sentinel); } catch {}
+    linkSync(validatorsPath, sentinel);
+    expect(statSync(sentinel).ino).toBe(beforeInode);
+
+    try {
+      generateForPackage({ input: inputFile });
+
+      expect(statSync(validatorsPath).ino).not.toBe(beforeInode);
+      expect(readFileSync(sentinel, "utf8")).toContain("export const validators = null");
+      expect(readFileSync(validatorsPath, "utf8")).toContain("Echo");
+    } finally {
+      unlinkSync(sentinel);
+    }
+  });
+});