Add capnweb-typecheck RPC validators

.gitignore

@@ -1,5 +1,6 @@
 node_modules
 .wrangler/
-examples/worker-react/web/dist/
+examples/worker-react/client/dist/
 notes.txt
 /dist/
+packages/*/dist/

.vscode/launch.json

@@ -0,0 +1,43 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "validate: Worker",
+      "address": "127.0.0.1",
+      "port": 9229,
+      "timeout": 60000,
+      "restart": true,
+      "preLaunchTask": "validate: Worker dev server",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "presentation": {
+        "hidden": true
+      }
+    },
+    {
+      "type": "chrome",
+      "request": "launch",
+      "name": "validate: client",
+      "url": "http://127.0.0.1:5173",
+      "webRoot": "${workspaceFolder}/examples/worker-react/client",
+      "sourceMaps": true,
+      "preLaunchTask": "validate: client dev server",
+      "presentation": {
+        "hidden": true
+      }
+    }
+  ],
+  "compounds": [
+    {
+      "name": "validate: debug all",
+      "configurations": [
+        "validate: Worker",
+        "validate: client"
+      ],
+      "stopAll": true
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,45 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "validate: Worker dev server",
+      "type": "shell",
+      "command": "npm run build && cd examples/worker-react && npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8787 --inspector-port 9229",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "validate-worker",
+        "pattern": { "regexp": "$^" },
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": ".*",
+          "endsPattern": "Ready on http://127\\.0\\.0\\.1:8787"
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated",
+        "clear": true
+      }
+    },
+    {
+      "label": "validate: client dev server",
+      "type": "shell",
+      "command": "cd examples/worker-react/client && npm install && npm run dev -- --host 127.0.0.1 --port 5173 --strictPort",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "validate-client",
+        "pattern": { "regexp": "$^" },
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": ".*",
+          "endsPattern": "Local:\\s+http://127\\.0\\.0\\.1:5173/"
+        }
+      },
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated",
+        "clear": true
+      }
+    }
+  ]
+}

examples/worker-react/README.md

@@ -1,43 +1,57 @@
-Cloudflare Workers + React Example
+# Cloudflare Workers + React example
 
-This example shows a Cloudflare Worker exposing a Cap'n Web API and a React app calling it from the browser. It demonstrates batching + promise pipelining vs sequential requests, with timing and request counts.
+This example exposes a Cap'n Web API from a Worker and calls it from a React app. It demonstrates batched promise pipelining versus sequential requests, with runtime validation enabled at both RPC boundaries through `capnweb-validate`.
 
-Prerequisites
+## Layout
 
-- Node 18+
-- Wrangler 3+ (for Workers)
-- npm
+- `server/worker.ts`: Worker RPC endpoint at `/api`.
+- `client/`: React/Vite app.
+- `wrangler.jsonc`: Worker config. Wrangler runs `capnweb-validate build` before starting and points `main` at the generated Worker copy.
 
-Overview
+## Run locally
 
-- Worker endpoint: `/api` using `newWorkersRpcResponse()`
-- Static assets (React build) served by the same Worker via Wrangler assets
-- Client demonstrates:
-  - Pipelined batch: authenticate -> get profile + notifications using the returned user.id without awaiting
-  - Sequential non-batched: authenticate, then profile, then notifications in separate round trips
+From the repo root:
 
-Run locally
+```sh
+npm run build
+cd examples/worker-react/client
+npm install
+npm run build
+cd ..
+npx wrangler dev --config wrangler.jsonc
+```
 
-1) Build the library at repo root (the example uses the local dist build):
-   npm run build
+Open `http://127.0.0.1:8787`.
 
-2) Install and build the React app (Vite aliases `capnweb` to the local `dist`):
-   cd examples/worker-react/web
-   npm install
-   npm run build
+For client debugging with Vite, run the Worker from the example directory:
 
-3) Run the Worker:
-   cd ..
-   npx wrangler dev
+```sh
+cd examples/worker-react
+npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8787 --inspector-port 9229
+```
 
-4) Open the app in your browser:
-   http://127.0.0.1:8787
+In another terminal, run Vite from the repo root:
 
-Tuning delays
+```sh
+cd examples/worker-react/client
+npm run dev
+```
 
-- The Worker simulates server-side latency. Override defaults via Wrangler vars or env:
-  - `DELAY_AUTH_MS` (default 80)
-  - `DELAY_PROFILE_MS` (default 120)
-  - `DELAY_NOTIFS_MS` (default 120)
-  - `SIMULATED_RTT_MS` per direction (default 120)
-  - `SIMULATED_RTT_JITTER_MS` per direction (default 40)
+The Vite dev server proxies `/api` to `http://127.0.0.1:8787`.
+
+## VS Code debug
+
+Use the `validate: debug all` launch configuration. It starts Wrangler and Vite without the old helper shell scripts.
+
+Worker validation output is generated under `.wrangler/validate/worker.ts`.
+The React client is transformed by the Vite plugin, not by the Wrangler CLI build step.
+
+## Tuning delays
+
+Set these in `wrangler.jsonc`:
+
+- `DELAY_AUTH_MS` (default 80)
+- `DELAY_PROFILE_MS` (default 120)
+- `DELAY_NOTIFS_MS` (default 120)
+- `SIMULATED_RTT_MS` per direction (default 120)
+- `SIMULATED_RTT_JITTER_MS` per direction (default 40)

examples/worker-react/web/package.json → examples/worker-react/client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "capnweb-react-web",
+  "name": "capnweb-react-client",
   "private": true,
   "version": "0.0.0",
   "type": "module",

examples/worker-react/web/src/main/App.tsx → examples/worker-react/client/src/main/App.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useState } from 'react'
 import { newHttpBatchRpcSession } from 'capnweb'
-import type { Api } from '../../../src/worker'
+import type { Api } from '../../../server/worker'
 import './App.css'
 
 type Result = {
@@ -21,7 +21,7 @@ export function App() {
   const [sequential, setSequential] = useState<Result | null>(null)
   const [running, setRunning] = useState(false)
 
-  // Network RTT is now simulated on the server (Worker). See wrangler.toml vars.
+  // Network RTT is now simulated on the server (Worker). See wrangler.jsonc vars.
 
   /** Count RPC POSTs and capture network timing by wrapping fetch while this component is mounted. */
   const wrapFetch = useMemo(() => {
@@ -129,7 +129,7 @@ export function App() {
   return (
     <div style={{ fontFamily: 'system-ui, sans-serif', padding: 24, lineHeight: 1.5 }}>
       <h1>Cap'n Web: Cloudflare Workers + React</h1>
-      <div style={{ opacity: 0.8 }}>Network RTT (round-trip-time) is simulated on the server (configurable via <code>SIMULATED_RTT_MS</code>/<code>SIMULATED_RTT_JITTER_MS</code> in <code>wrangler.toml</code>).</div>
+      <div style={{ opacity: 0.8 }}>Network RTT (round-trip-time) is simulated on the server (configurable via <code>SIMULATED_RTT_MS</code>/<code>SIMULATED_RTT_JITTER_MS</code> in <code>wrangler.jsonc</code>).</div>
       <p>This demo calls the Worker API in two ways:</p>
       <ul>
         <li><b>Pipelined (batched)</b>: dependent calls in one round trip</li>

examples/worker-react/web/tsconfig.json → examples/worker-react/client/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2022",
     "useDefineForClassFields": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "skipLibCheck": true,
     "moduleResolution": "Bundler",
@@ -11,9 +11,10 @@
     "noEmit": true,
     "jsx": "react-jsx",
     "strict": true,
-    "baseUrl": ".",
     "paths": {
-      "capnweb": ["../../../dist/index.d.ts"]
+      "capnweb": ["../../../src/index.ts"],
+      "capnweb-validate": ["../../../packages/capnweb-validate/src/index.ts"],
+      "capnweb-validate/internal": ["../../../packages/capnweb-validate/src/internal/runtime.ts"]
     }
   },
   "include": ["src"]

examples/worker-react/client/vite.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vite'
+import path from 'node:path'
+import { capnwebValidate } from '../../../packages/capnweb-validate/src/plugin.ts'
+
+const repoRoot = path.resolve(__dirname, '../../..')
+
+export default defineConfig({
+  plugins: [
+    capnwebValidate.vite({
+      cwd: __dirname,
+      tsconfig: 'tsconfig.json',
+    }),
+  ],
+  resolve: {
+    alias: {
+      'capnweb-validate/internal/capnweb': path.resolve(repoRoot, 'packages/capnweb-validate/src/internal/capnweb.ts'),
+      'capnweb-validate/internal/core': path.resolve(repoRoot, 'packages/capnweb-validate/src/internal/core.ts'),
+      'capnweb-validate/internal': path.resolve(repoRoot, 'packages/capnweb-validate/src/internal/runtime.ts'),
+      'capnweb-validate/capnweb': path.resolve(repoRoot, 'packages/capnweb-validate/src/capnweb.ts'),
+      'capnweb-validate': path.resolve(repoRoot, 'packages/capnweb-validate/src/index.ts'),
+      'capnweb': path.resolve(repoRoot, 'src/index.ts'),
+    },
+  },
+  build: {
+    target: 'esnext',
+  },
+  esbuild: {
+    target: 'esnext',
+    supported: {
+      'top-level-await': true,
+    },
+  },
+  server: {
+    host: '127.0.0.1',
+    port: 5173,
+    strictPort: true,
+    fs: { allow: [repoRoot] },
+    proxy: { '/api': 'http://127.0.0.1:8787' },
+  },
+})

examples/worker-react/server/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "capnweb": ["../../../dist/index-workers.d.ts"],
+      "capnweb-validate": ["../../../packages/capnweb-validate/dist/index.d.mts"],
+      "capnweb-validate/internal": ["../../../packages/capnweb-validate/dist/internal/runtime.d.mts"]
+    }
+  },
+  "files": ["worker.ts"]
+}

examples/worker-react/src/worker.ts → examples/worker-react/server/worker.ts

@@ -1,4 +1,8 @@
 import { newWorkersRpcResponse, RpcTarget } from 'capnweb';
+import { validateRpc } from 'capnweb-validate';
+
+type User = { id: string; name: string };
+type Profile = { id: string; bio: string };
 
 type Env = {
   DELAY_AUTH_MS?: string;
@@ -11,46 +15,47 @@ type Env = {
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 const jittered = (base: number, jitter: number) => base + (jitter ? Math.random() * jitter : 0);
 
-const USERS = new Map([
+const USERS = new Map<string, User>([
   ['cookie-123', { id: 'u_1', name: 'Ada Lovelace' }],
   ['cookie-456', { id: 'u_2', name: 'Alan Turing' }],
 ]);
 
-const PROFILES = new Map([
+const PROFILES = new Map<string, Profile>([
   ['u_1', { id: 'u_1', bio: 'Mathematician & first programmer' }],
   ['u_2', { id: 'u_2', bio: 'Mathematician & CS pioneer' }],
 ]);
 
-const NOTIFICATIONS = new Map([
+const NOTIFICATIONS = new Map<string, string[]>([
   ['u_1', ['Welcome to Cap\'n Web!', 'You have 2 new followers']],
   ['u_2', ['New feature: pipelining!', 'Security tips for your account']],
 ]);
 
+@validateRpc()
 export class Api extends RpcTarget {
   constructor(private env: Env) { super(); }
 
-  async authenticate(sessionToken: string) {
+  async authenticate(sessionToken: string): Promise<User> {
     await sleep(Number(this.env.DELAY_AUTH_MS ?? 80));
     const user = USERS.get(sessionToken);
     if (!user) throw new Error('Invalid session');
     return user;
   }
 
-  async getUserProfile(userId: string) {
+  async getUserProfile(userId: string): Promise<Profile> {
     await sleep(Number(this.env.DELAY_PROFILE_MS ?? 120));
     const profile = PROFILES.get(userId);
     if (!profile) throw new Error('No such user');
     return profile;
   }
 
-  async getNotifications(userId: string) {
+  async getNotifications(userId: string): Promise<string[]> {
     await sleep(Number(this.env.DELAY_NOTIFS_MS ?? 120));
     return NOTIFICATIONS.get(userId) ?? [];
   }
 }
 
 export default {
-  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+  async fetch(request: Request, env: Env): Promise<Response> {
     const url = new URL(request.url);
 
     if (request.method === 'OPTIONS' && url.pathname === '/api') {
@@ -86,7 +91,7 @@ export default {
       return new Response(resp.body, { status: resp.status, headers });
     }
 
-    // Static assets are served from web/dist by Wrangler assets config.
+    // Static assets are served from client/dist by Wrangler assets config.
     return new Response('Not found', { status: 404 });
   },
 };