iterate-com/safe-durable-objects

README

Safe Durable Objects

tRPC-style Safe RPC methods for Cloudflare Durable Objects

Safe Durable Objects brings type-safe, validated RPC methods to Cloudflare Durable Objects with a developer experience inspired by tRPC. It uses Zod for runtime validation and provides full TypeScript support.

You can access the router and schemas via YourClass.prototype._def or YourClass.prototype.route._def as you would with tRPC. This is extremely powerful as you can convert the schemas to a JSON schema and use them to convert your durable object methods into callable tools for your AI agents.

Features

🔒 Type-safe: Full TypeScript support with end-to-end type safety
✅ Runtime validation: Input and output validation using Zod schemas
🎯 tRPC-inspired API: Familiar developer experience with .input(), .output(), and .implement()

Installation

npm install safe-durable-objects zod
# or
pnpm add safe-durable-objects zod
# or
yarn add safe-durable-objects zod
# or
bun add safe-durable-objects zod

You'll also need @cloudflare/workers-types for TypeScript support:

npm install -D @cloudflare/workers-types

Quick Start

Here's a complete example of how to use Safe Durable Objects:

import { z } from "zod/v4";
import { SafeDurableObjectBuilder } from "safe-durable-objects";
import { DurableObject } from "cloudflare:workers";

type State = {
  count: number;
  lastMessage: string;
};

type Env = {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
};

export class MyDurableObject extends SafeDurableObjectBuilder(
  // This is the base class
  class extends DurableObject<Env> {
    state: State;

    // important: make sure to make the ctx and env public, else you won't be able to access them in the router and typescript will complain
    constructor(public ctx: DurableObjectState, public env: Env) {
      super(ctx, env);
      this.state = {
        count: 0,
        lastMessage: "",
      };
    }

    setState(state: State) {
      this.state = state;
    }
  },
  (fn) => ({
    hello: fn
      .input(z.string())
      .output(z.object({ message: z.string(), id: z.string() }))
      .implement(function ({ ctx, input }) {
        // You can access the base class methods via `this`
        const state = this.state;
        this.setState({
          count: state.count + 1,
          lastMessage: input,
        });
        return {
          message: `Hello, ${input}!! state: ${JSON.stringify(state)}`,
          id: ctx.id.toString(),
        };
      }),
    ping: fn.output(z.object({ message: z.string() })).implement(function () {
      return {
        message: "pong",
      };
    }),
  })
) {}

export default {
  async fetch(request, env, ctx) {
    const stub = env.MY_DURABLE_OBJECT.get(
      env.MY_DURABLE_OBJECT.idFromName("test")
    );
    const res = await stub.hello("world");
    return Response.json(res);
  },
} as ExportedHandler<Env>;

API Reference

`SafeDurableObjectBuilder(BaseClass, routerBuilder)`

Creates a new Durable Object class with safe RPC methods.

Parameters

BaseClass: Your base Durable Object class
routerBuilder: A function that receives a route builder and returns an object with your RPC methods

Route Builder API

The route builder provides a fluent API for defining RPC methods:

fn.input(inputSchema).output(outputSchema).implement(handler);
// or
fn.input(inputSchema).implement(handler); // output schema is optional

Note: Only zod/v4 schemas are supported

`.input(schema)` (optional)

Defines the input validation schema using Zod. The input will be validated at runtime.

`.output(schema)` (optional)

Defines the output validation schema using Zod. The output will be validated at runtime.

`.implement(handler)`

Implements the actual RPC method logic. The handler receives:

ctx: The DurableObjectState
env: The environment bindings
input: The validated input (typed according to your input schema)

If you use a function instead of an arrow function in the implement block, you can access the base class via this

Examples

Basic Counter

import { z } from "zod/v4";
import { SafeDurableObjectBuilder } from "safe-durable-objects";
import { DurableObject } from "cloudflare:workers";

export class Counter extends SafeDurableObjectBuilder(
  class extends DurableObject<Env> {
    private count = 0;

    // important: make sure to make the ctx and env public, else you won't be able to access them in the router and typescript will complain
    constructor(public ctx: DurableObjectState, public env: Env) {
      super(ctx, env);
    }

    async getCount() {
      return this.count;
    }

    async setCount(value: number) {
      this.count = value;
    }
  },
  (fn) => ({
    increment: fn
      .input(z.object({ by: z.number().optional().default(1) }))
      .output(z.object({ count: z.number() }))
      .implement(async function ({ input }) {
        const currentCount = await this.getCount();
        const newCount = currentCount + input.by;
        await this.setCount(newCount);
        return { count: newCount };
      }),

    getCount: fn
      .input(z.void())
      .output(z.object({ count: z.number() }))
      .implement(async function () {
        const count = await this.getCount();
        return { count };
      }),
  })
) {}

Error Handling

Safe Durable Objects automatically handles validation errors. If input validation fails, a ZodError will be thrown. If output validation fails, it will also throw a ZodError.

const result = await stub.hello("invalid input").catch((error) => {
  /*handle here*/
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Iterate

Support

If you have any questions or need help, please open an issue on GitHub.