Typesafe APIs Made Simple with oRPC

Typesafe APIs Made Simple with oRPC | Zuplo Blog

const getting = os
  .use(dbProvider)
  .use(requiredAuth)
  .use(rateLimit)
  .use(analytics)
  .use(sentryMonitoring)
  .use(retry({ times: 3 }))
  .route({ method: "GET", path: "/getting/{id}" })
  .input(z.object({ id: z.string() }))
  .use(canGetting, (input) => input.id)
  .errors({
    SOME_TYPE_SAFE_ERROR: {
      data: z.object({ something: z.string() }),
    },
  })
  .handler(async ({ input, errors, context }) => {
    // do something
  })
  .actionable() // server action compatible
  .callable(); // regular function compatible

import type { IncomingHttpHeaders } from "node:http";
import { ORPCError, os } from "@orpc/server";
import { z } from "zod";

const PlanetSchema = z.object({
  id: z.number().int().min(1),
  name: z.string(),
  description: z.string().optional(),
});

export const listPlanet = os
  .input(
    z.object({
      limit: z.number().int().min(1).max(100).optional(),
      cursor: z.number().int().min(0).default(0),
    }),
  )
  .handler(async ({ input }) => {
    // your list code here
    return [{ id: 1, name: "name" }];
  });

export const findPlanet = os
  .input(PlanetSchema.pick({ id: true }))
  .handler(async ({ input }) => {
    // your find code here
    return { id: 1, name: "name" };
  });

export const createPlanet = os
  .$context<{ headers: IncomingHttpHeaders }>()
  .use(({ context, next }) => {
    const user = parseJWT(context.headers.authorization?.split(" ")[1]);

    if (user) {
      return next({ context: { user } });
    }

    throw new ORPCError("UNAUTHORIZED");
  })
  .input(PlanetSchema.omit({ id: true }))
  .handler(async ({ input, context }) => {
    // your create code here
    return { id: 1, name: "name" };
  });

export const router = {
  planet: {
    list: listPlanet,
    find: findPlanet,
    create: createPlanet,
  },
};

import { createServer } from "node:http";
import { RPCHandler } from "@orpc/server/node";
import { CORSPlugin } from "@orpc/server/plugins";

const handler = new RPCHandler(router, {
  plugins: [new CORSPlugin()],
});

const server = createServer(async (req, res) => {
  const result = await handler.handle(req, res, {
    context: { headers: req.headers },
  });

  if (!result.matched) {
    res.statusCode = 404;
    res.end("No procedure matched");
  }
});

server.listen(3000, "127.0.0.1", () =>
  console.log("Listening on 127.0.0.1:3000"),
);

import type { RouterClient } from "@orpc/server";
import { createORPCClient } from "@orpc/client";
import { RPCLink } from "@orpc/client/fetch";

const link = new RPCLink({
  url: "http://127.0.0.1:3000",
  headers: { Authorization: "Bearer token" },
});

export const orpc: RouterClient<typeof router> = createORPCClient(link);

import { isDefinedError, safe } from "@orpc/client";

const planet = await orpc.planet.find({ id: 1 });
//    ^^^^^ Everything is type-safe

const { data, error } = await safe(orpc.planet.create({ name: "name" }));

if (error) {
  if (isDefinedError(error)) {
    // Handle known and type-safe errors here
  }

  // Handle unknown errors here
} else {
  // Handle success here
}

import { isDefinedError } from "@orpc/client";
import {
  useInfiniteQuery,
  useMutation,
  useQueryClient,
} from "@tanstack/react-query";

const query = useInfiniteQuery(
  orpc.planet.list.infiniteOptions({
    input: (cursor) => ({ cursor }),
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    initialPageParam: 0,
  }),
);

const queryClient = useQueryClient();

const mutation = useMutation(
  orpc.planet.update.mutationOptions({
    onError(error) {
      if (isDefinedError(error)) {
        const id = error.data.id;
        //    ^    type-safe errors
      }
    },
    onSuccess() {
      queryClient.invalidateQueries({
        queryKey: orpc.planet.key(),
      });
    },
  }),
);

Typesafe APIs Made Simple with oRPC

Related Articles

What Is Canary Routing and How Do You Implement It?

How to Route API Requests to Different Backends

The Idea behind oRPC

oRPC highlights

Why oRPC? (Performance & DX)

Quick Start

1. Install

2. Define your first router

3. Create your server

4. Create TypeScript Client

5. Consume your API

Tanstack Query Integration

Explore Further

Special Thanks to Zuplo

Try Zuplo