feat: make builder more type safe and add metadata

Author: BlankParticle

example/worker.ts

@@ -29,6 +29,7 @@ export class MyDurableObject extends SafeDurableObjectBuilder(
     hello: fn
       .input(z.string())
       .output(z.object({ message: z.string(), id: z.string() }))
+      .meta({ description: "Say hello to the server" })
       .implement(function ({ ctx, input }) {
         const state = this.state;
         this.setState({

package.json

@@ -42,8 +42,8 @@
   "license": "MIT",
   "packageManager": "pnpm@10.12.4",
   "peerDependencies": {
-    "@cloudflare/workers-types": "^4.20250705.0",
-    "zod": "^3.25.74"
+    "@cloudflare/workers-types": "^4",
+    "zod": "^3.25"
   },
   "devDependencies": {
     "tsdown": "^0.12.9",

pnpm-lock.yaml

@@ -12,12 +12,14 @@ export type ImplArgs<I extends z.ZodType, Env> = {
 export type SafeRpcHandler<
   I extends z.ZodType,
   O extends z.ZodType,
-  InferredOutput = z.infer<O>
+  InferredOutput = z.infer<O>,
+  Meta = unknown
 > = {
   (input: z.infer<I>): Promise<InferredOutput>;
   _def: {
     input: I;
     output: O;
+    meta: Meta;
   };
   [SafeRpcMethodSymbol]: true;
 };
@@ -28,11 +30,13 @@ function createHandler<
   I extends z.ZodType,
   O extends z.ZodType,
   Env,
-  T extends DurableObject<Env>
+  T extends DurableObject<Env>,
+  Meta = unknown
 >(
   fn: (args: ImplArgs<I, Env>) => MaybePromise<z.infer<O>>,
   inputSchema: I,
-  outputSchema?: O
+  outputSchema?: O,
+  meta?: Meta
 ) {
   const handler = async function (this: T, rawInput: z.infer<I>) {
     const parsedInput = await inputSchema.parseAsync(rawInput);
@@ -49,6 +53,7 @@ function createHandler<
       value: {
         input: inputSchema,
         output: outputSchema ?? z.unknown(),
+        meta: meta ?? {},
       },
       enumerable: true,
     },
@@ -61,39 +66,88 @@ function createHandler<
   return handlerWithDef;
 }
 
-function routeBuilder<Env, T extends DurableObject<Env>>() {
-  return {
-    input<I extends z.ZodType>(inputSchema: I) {
-      return {
-        output<O extends z.ZodType>(outputSchema: O) {
-          return {
-            implement(
-              fn: (this: T, args: ImplArgs<I, Env>) => MaybePromise<z.infer<O>>
-            ) {
-              return createHandler(
-                fn,
-                inputSchema,
-                outputSchema
-              ) as SafeRpcHandler<I, O>;
-            },
-          };
-        },
-        implement<R>(fn: (this: T, args: ImplArgs<I, Env>) => MaybePromise<R>) {
-          return createHandler(fn, inputSchema) as SafeRpcHandler<
-            I,
-            z.ZodUnknown,
-            R
-          >;
-        },
-      };
-    },
-  };
+class RouteBuilder<
+  Env,
+  T extends DurableObject<Env>,
+  I extends z.ZodType | undefined = undefined,
+  O extends z.ZodType | undefined = undefined,
+  Meta = unknown
+> {
+  private inputSchema?: I;
+  private outputSchema?: O;
+  private metaData?: Meta;
+
+  constructor(inputSchema?: I, outputSchema?: O, metaData?: Meta) {
+    this.inputSchema = inputSchema;
+    this.outputSchema = outputSchema;
+    this.metaData = metaData;
+    return this;
+  }
+
+  input<InputSchema extends z.ZodType>(
+    inputSchema: InputSchema
+  ): RouteBuilder<Env, T, InputSchema, O, Meta> {
+    if (this.inputSchema) throw new Error("Input schema already set");
+    return new RouteBuilder<Env, T, InputSchema, O, Meta>(
+      inputSchema,
+      this.outputSchema,
+      this.metaData
+    );
+  }
+
+  output<OutputSchema extends z.ZodType>(
+    this: RouteBuilder<Env, T, I, undefined, Meta>,
+    outputSchema: OutputSchema
+  ): RouteBuilder<Env, T, I, OutputSchema, Meta> {
+    if (this.outputSchema) throw new Error("Output schema already set");
+    return new RouteBuilder<Env, T, I, OutputSchema, Meta>(
+      this.inputSchema,
+      outputSchema,
+      this.metaData
+    );
+  }
+
+  meta<MetaData>(metaData: MetaData): RouteBuilder<Env, T, I, O, MetaData> {
+    if (this.metaData) throw new Error("Metadata already set");
+    return new RouteBuilder<Env, T, I, O, MetaData>(
+      this.inputSchema,
+      this.outputSchema,
+      metaData
+    );
+  }
+
+  implement<R>(
+    this: RouteBuilder<Env, T, I, undefined, Meta>,
+    fn: I extends z.ZodType
+      ? (this: T, args: ImplArgs<I, Env>) => MaybePromise<R>
+      : never
+  ): I extends z.ZodType ? SafeRpcHandler<I, z.ZodUnknown, R, Meta> : never;
+
+  implement(
+    this: RouteBuilder<Env, T, I, O, Meta>,
+    fn: I extends z.ZodType
+      ? O extends z.ZodType
+        ? (this: T, args: ImplArgs<I, Env>) => MaybePromise<z.infer<O>>
+        : never
+      : never
+  ): I extends z.ZodType
+    ? O extends z.ZodType
+      ? SafeRpcHandler<I, O, z.infer<O>, Meta>
+      : never
+    : never;
+
+  implement(
+    fn: (this: T, args: ImplArgs<any, Env>) => MaybePromise<any>
+  ): SafeRpcHandler<any, any, any, Meta> {
+    if (!this.inputSchema) throw new Error("Input schema is required");
+    return createHandler(
+      fn,
+      this.inputSchema as z.ZodType,
+      this.outputSchema as z.ZodType | undefined,
+      this.metaData
+    ) as SafeRpcHandler<any, any, any, Meta>;
+  }
 }
-
-type RouteBuilder<Env, T extends DurableObject<Env>> = ReturnType<
-  typeof routeBuilder<Env, T>
->;
-
 type AnyDurableClass<T extends DurableObject, Env> = new (
   ctx: DurableObjectState,
   env: Env
@@ -102,15 +156,15 @@ type AnyDurableClass<T extends DurableObject, Env> = new (
 export function SafeDurableObjectBuilder<
   Env,
   T extends DurableObject<Env>,
-  Router extends Record<string, SafeRpcHandler<any, any>>
+  Router extends Record<string, SafeRpcHandler<any, any, any, any>>
 >(
   BaseClass: AnyDurableClass<T, Env>,
   routerBuilder: (builder: RouteBuilder<Env, T>) => Router
 ) {
   // create a extended class so that we don't pollute the base class with the router
   class BaseClassWithSafeRpc extends BaseClass {}
 
-  const router = routerBuilder(routeBuilder());
+  const router = routerBuilder(new RouteBuilder<Env, T>());
 
   Object.defineProperties(
     BaseClassWithSafeRpc.prototype,
@@ -135,6 +189,6 @@ export function SafeDurableObjectBuilder<
 
 export function isSafeDurableObjectMethod(
   method: any
-): method is SafeRpcHandler<any, any> {
+): method is SafeRpcHandler<any, any, any, any> {
   return method && method[SafeRpcMethodSymbol] === true;
 }