Feature Request: Runtime Type Validation for Method Arguments

[lbguilherme]

Problem

Currently, Cap'n Web allows using TypeScript for compile-time type checking, a common use case would be importing the server types wither directly in a mono-repo or using a generated.d.ts file. But it lacks runtime validation for method arguments. This creates potential security vulnerabilities as input from network boundaries should never be trusted implicitly. In production TypeScript applications, type mismatches can occur due to:

• External API responses that don't match expected schemas
• Client-side tampering with RPC payloads
• Version mismatches between client and server code
• JavaScript clients calling TypeScript servers

Proposed Solution

Add optional runtime type validation for RPC method arguments, similar to how tRPC handles it - where you can define validators that run on both input and output to ensure type safety across network boundaries.

Implementation Suggestion

Support https://github.com/standard-schema/standard-schema as the validation interface. This would allow users to choose from any compatible validation library (Zod, Valibot, Arktype, etc.) without locking them into a specific ecosystem. Since Standard Schema is just a specification, it wouldn't add runtime dependencies to Cap'n Web itself.

I'm not sure about the actual API DX.

[SwappyHolmes]

This proposal makes a lot of sense. Compile-time type safety is valuable, but once data crosses a network boundary, runtime validation becomes important to prevent subtle bugs or security issues.

Using a Standard Schema approach is a smart choice, as it keeps Cap’n Web lightweight while allowing developers to integrate their preferred validators (Zod, Valibot, Arktype, etc.). From a developer experience perspective, supporting per-method validators for both inputs and outputs—similar to tRPC—could make validation opt-in but easy to adopt.

It would be helpful to hear maintainers’ thoughts on whether this should be incorporated into the core library or initially offered as an optional extension.

[kentonv]

Ideally, what we're really hoping to do is auto-generate runtime type checks directly from TypeScript types, but how to do this exactly is still TBD.

I'm also happy to consider supporting Standard Schema as an option, but I do wonder what the DX would actually be?

Could it just be a decorator? Like:

class MyApi extends RpcTarget {
  @validateParams([z.number(), z.number()])
  add(a, b) {
    return a + b;
  }
}

Could such a decorator inject the appropriate type checks?

This seems like it doesn't even need to be explicitly supported by Cap'n Web. This decorator could work on any TS interface.

Is there something Cap'n Web itself could do that is better than this?

[tom-sherman]

For standard schema, I'd propose a new API that's similar to tRPC where you define the schema and handler in an object.

const MyApi = target({
  add: input(z.number(), z.number()).handler((a, b) => a + b)
})

I don't think this necessarily needs to be included in capnweb core though.

[lbguilherme]

There is ts-zod-decorators that does something similar and can already be used today:

import { ZodInput, Validate, ZodOutput } from 'ts-zod-decorators';
import { RpcTarget } from "capnweb";
import * as z from 'zod';

const inputSchema = z.object({ name: z.string(), age: z.number() });
const outputSchema = z.string();

class Foo extends RpcTarget {
  @Validate
  @ZodOutput(outputSchema)
  async bar(@ZodInput(inputSchema) input: z.infer<typeof inputSchema>): Promise<z.infer<typeof outputSchema>> {
    return input.name;
  }
}

But it is quite ugly to get runtime AND compile-time checking from the schemas because decorators can't affect TypeScript's types of a method. You need to either use z.infer or specify the type twice.

---

The other solution would be to move away from class methods like this and create member functions, similar to what @tom-sherman suggested:

import { RpcTarget } from "capnweb";

class Foo extends RpcTarget {
  bar: rpcProcedure()
    .input(z.object({ name: z.string(), age: z.number() }))
    .output(z.string())
    .handler(async input => {
      return input.name;
    });
}

This is too much different from standard classes. But I believe that it would already work without changes to Cap'n Web because it would look like a property that holds a 'callback function'. Maybe it just wouldn't well optimized because it might create many new references? Not sure.

[kentonv]

Hmm, personally I'm not a big fan of the input(...).output(...).handler(...) syntax, it seems pretty hard to read.

The decorators would be nice if not for the repetition. That's pretty disappointing. :/

But I suppose either of these approaches doesn't really require any special support in Cap'n Web, right? So maybe people can just pick their poison for now, maybe with some guidance documentation? Meanwhile we can work towards the magic TypeScript-based approach which I feel like is the ideal solution.

[Bethel-nz]

Hi all, this is a fascinating discussion. I agree with @kentonv that the core library should remain simple, and that the builder syntax (input().output().handler()) can be hard to read.

I was thinking about a slightly different approach that still avoids the "two sources of truth" problem from decorators but maintains a cleaner separation of concerns. What if we used a helper or factory function?

We could have a function createValidatedProcedure that takes a schema and a handler. The schema could follow the Standard Schema proposal @lbguilherme made, allowing users to bring their own validation library (Zod, Valibot, etc.).

A user's RpcTarget would look something like this:

import { RpcTarget } from "capnweb";
import { createValidatedProcedure } from "some-helper-library";
import { s } from "valibot"; // Or any other standard-schema library

// The schema is the single source of truth for types.
const barInputSchema = s.object({ name: s.string(), age: s.number() });

class MyApi extends RpcTarget {
  // The RPC method is defined as a property.
  // The `input` type is automatically inferred from the schema.
  bar = createValidatedProcedure(barInputSchema, async (input) => {
    // `input` is now guaranteed to be runtime-validated and type-safe.
    return `Hello, ${input.name}!`;
  });
}

The advantages of this approach are:

• No Changes to Cap'n Web Core: This could live in a separate, optional helper library (capnweb-validation-helpers or similar). It respects the goal of keeping the core simple.
• Single Source of Truth: The schema defines the types once.
• Library Agnostic: By using Standard Schema, it's not tied to just Zod.

This seems to align with the idea of letting "people pick their poison for now, maybe with some guidance documentation." This could be one of those guided options.

What are your thoughts on this pattern? @kentonv