Add capnweb-typecheck for TypeScript RPC validation codegen

[teamchong]

Summary

Adds opt-in runtime validation for Cap'n Web RPC method arguments and return values.

Running capnweb typecheck gen src/worker.ts generates validators from RpcTarget TypeScript signatures into the capnweb-typecheck placeholder package.
The runtime auto-loads those validators by RPC class name. If validators are not generated, capnweb-typecheck exports validators = null and validation
is skipped.

How it works

• capnweb typecheck gen extracts reachable RpcTarget classes and public RPC methods.
• Generated validators are written into capnweb-typecheck.
• core.ts imports validators from capnweb-typecheck.
• On first RPC call for a class, getRpcValidator() looks up validators by constructor name and caches them in the existing WeakMap.
• Arguments are validated before method invocation.
• Return values are validated after resolution. Nested RpcPromise placeholders are allowed initially and validated after they resolve.
• capnweb typecheck reset restores the null stub and disables validation.

No worker entry swap, no generated .capnweb/ entry wrapper, and no wrangler config changes are required for the default package-based flow.

Review fixes included

• The published placeholder now exports validators = null, so examples are not accidentally loaded for users who did not run codegen.
• Return validation handles nested RPC promises without rejecting valid pipelined returns.
• ECMAScript private methods (#helper()) are ignored during extraction.
• Map and Set signatures are rejected until serialization supports them.

Generated code

The generated code is plain JavaScript:

• helper validators such as __capnweb_validate_N
• a validators object keyed by class and method name
• structured validation errors with path, expected type, actual type, and value

Example shape:

export const validators = {
  "Api": {
    "authenticate": {
      args(args) {
        // validate args
      },
      returns(value) {
        // validate return
      }
    }
  }
};

Example debug flow

examples/worker-react/dev-debug.sh keeps the normal src/worker.ts wrangler entry.

• Without --typecheck, it runs capnweb typecheck reset.
• With --typecheck, it runs capnweb typecheck gen src/worker.ts.

The script then builds the React assets and starts wrangler dev normally. The app is served by wrangler at:

http://127.0.0.1:8787/

Testing

  npm run build
  npm run test:types
  npm test
  ./examples/worker-react/dev-debug.sh
  ./examples/worker-react/dev-debug.sh --typecheck

[changeset-bot]

🦋 Changeset detected

Latest commit: d13b590

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
capnweb	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/capnweb@169

commit: d13b590