REST vs GraphQL vs tRPC

npm install @asteasolutions/zod-to-openapi zod

// lib/openapi/registry.ts
import {
  OpenAPIRegistry,
  OpenApiGeneratorV3,
} from "@asteasolutions/zod-to-openapi";
import { z } from "zod";

export const registry = new OpenAPIRegistry();

// Define shared schemas — registered once, reused in route definitions
export const ProductSchema = registry.register(
  "Product",
  z.object({
    id: z.string().uuid(),
    name: z.string(),
    price: z.number().positive(),
    stock: z.number().int().min(0),
  }),
);

export const CreateProductSchema = ProductSchema.omit({ id: true });

// app/api/products/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import {
  registry,
  ProductSchema,
  CreateProductSchema,
} from "@/lib/openapi/registry";
import { db } from "@/lib/db";

// Register the route in the OpenAPI registry for spec generation
registry.registerPath({
  method: "get",
  path: "/api/products",
  tags: ["Products"],
  responses: {
    200: {
      description: "List of products",
      content: { "application/json": { schema: z.array(ProductSchema) } },
    },
  },
});

export async function GET() {
  const products = await db.product.findMany({
    select: { id: true, name: true, price: true, stock: true },
    orderBy: { name: "asc" },
  });
  return NextResponse.json(products);
}

registry.registerPath({
  method: "post",
  path: "/api/products",
  tags: ["Products"],
  request: {
    body: { content: { "application/json": { schema: CreateProductSchema } } },
  },
  responses: {
    201: {
      description: "Created product",
      content: { "application/json": { schema: ProductSchema } },
    },
  },
});

export async function POST(req: NextRequest) {
  const body = CreateProductSchema.parse(await req.json());
  const product = await db.product.create({ data: body });
  return NextResponse.json(product, { status: 201 });
}

// app/api/openapi.json/route.ts — generate spec at runtime
import { OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
import { registry } from "@/lib/openapi/registry";

export function GET() {
  const generator = new OpenApiGeneratorV3(registry.definitions);
  const spec = generator.generateDocument({
    openapi: "3.0.0",
    info: { title: "Products API", version: "1.0.0" },
    servers: [{ url: process.env.NEXT_PUBLIC_APP_URL! }],
  });
  return Response.json(spec);
}

// app/api/v1/products/route.ts  → /api/v1/products
// app/api/v2/products/route.ts  → /api/v2/products (new response shape)

// app/api/products/route.ts
export async function GET(req: NextRequest) {
  const version = req.headers.get("api-version") ?? "1";

  if (version === "2") {
    return NextResponse.json(await getProductsV2());
  }
  return NextResponse.json(await getProductsV1());
}

// ❌ N+1: 50 orders → 50 separate user queries
resolvers: {
  Order: {
    customer: (order) => db.user.findUnique({ where: { id: order.userId } }),
  },
}

// lib/graphql/loaders.ts
import DataLoader from "dataloader";
import { db } from "@/lib/db";

// One loader per request — instantiate fresh per request context to avoid cross-request caching
export function createLoaders() {
  const userLoader = new DataLoader(async (ids: readonly string[]) => {
    const users = await db.user.findMany({ where: { id: { in: [...ids] } } });
    // DataLoader requires results in the same order as the input keys
    return ids.map((id) => users.find((u) => u.id === id) ?? null);
  });

  const productLoader = new DataLoader(async (ids: readonly string[]) => {
    const products = await db.product.findMany({
      where: { id: { in: [...ids] } },
    });
    return ids.map((id) => products.find((p) => p.id === id) ?? null);
  });

  return { userLoader, productLoader };
}

// app/api/graphql/route.ts — pass loaders via context
import { createSchema, createYoga } from "graphql-yoga";
import { createLoaders } from "@/lib/graphql/loaders";

const schema = createSchema({
  typeDefs: /* GraphQL */ `
    type Order {
      id: ID!
      total: Float!
      customer: User!
    }
    type User {
      id: ID!
      name: String!
      email: String!
    }
    type Query {
      orders: [Order!]!
    }
  `,
  resolvers: {
    Query: {
      orders: () => db.order.findMany(),
    },
    Order: {
      // DataLoader batches all customer loads from the same tick into one DB query
      customer: (order, _args, ctx) =>
        ctx.loaders.userLoader.load(order.userId),
    },
  },
});

const { handleRequest } = createYoga({
  schema,
  context: () => ({ loaders: createLoaders() }), // fresh loaders per request
  graphqlEndpoint: "/api/graphql",
});

export const GET = handleRequest;
export const POST = handleRequest;

// lib/graphql/persisted-queries.ts — generated at build time from .graphql files
export const PERSISTED_QUERIES: Record<string, string> = {
  a1b2c3d4: `query GetProduct($id: ID!) { product(id: $id) { id name price } }`,
  e5f6g7h8: `query ListOrders { orders { id total customer { name } } }`,
};

// app/api/graphql/route.ts — only allow persisted queries in production
const { handleRequest } = createYoga({
  schema,
  context: () => ({ loaders: createLoaders() }),
  graphqlEndpoint: "/api/graphql",
  plugins: [
    {
      onParams({ params, setParams }) {
        if (process.env.NODE_ENV !== "production") return;

        // In production: only allow requests that include a known query hash
        const hash = (params.extensions as any)?.persistedQuery?.sha256Hash;
        if (!hash || !PERSISTED_QUERIES[hash]) {
          throw new Error("Only persisted queries are allowed in production");
        }
        // Replace the hash with the actual query
        setParams({ ...params, query: PERSISTED_QUERIES[hash] });
      },
    },
  ],
});

// server/trpc.ts
import { initTRPC, TRPCError } from "@trpc/server";
import { auth } from "@/auth";

export const t = initTRPC.context<{ userId: string | null }>().create();

export const router = t.router;
export const publicProcedure = t.procedure;

// Protected procedure — throws 401 if not authenticated
export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
  if (!ctx.userId) throw new TRPCError({ code: "UNAUTHORIZED" });
  return next({ ctx: { userId: ctx.userId } });
});

// server/routers/product.ts
import { z } from "zod";
import { router, publicProcedure, protectedProcedure } from "../trpc";
import { db } from "@/lib/db";

export const productRouter = router({
  list: publicProcedure
    .input(
      z.object({
        cursor: z.string().optional(),
        limit: z.number().max(50).default(20),
      }),
    )
    .query(async ({ input }) => {
      const products = await db.product.findMany({
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        orderBy: { createdAt: "desc" },
      });

      const hasMore = products.length > input.limit;
      return {
        items: hasMore ? products.slice(0, -1) : products,
        nextCursor: hasMore ? products[products.length - 2].id : null,
      };
    }),

  update: protectedProcedure
    .input(z.object({ id: z.string(), price: z.number().positive() }))
    .mutation(async ({ input, ctx }) => {
      // ctx.userId is guaranteed non-null by protectedProcedure
      return db.product.update({
        where: { id: input.id },
        data: { price: input.price },
      });
    }),
});

// server/root.ts
import { router } from "./trpc";
import { productRouter } from "./routers/product";

export const appRouter = router({ product: productRouter });
export type AppRouter = typeof appRouter;

// createCallerFactory: call procedures directly in Server Components without HTTP
export const createCaller = appRouter.createCaller;

// app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
import { appRouter } from "@/server/root";
import { auth } from "@/auth";

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: "/api/trpc",
    req,
    router: appRouter,
    createContext: async () => {
      const session = await auth();
      return { userId: session?.user?.id ?? null };
    },
  });

export { handler as GET, handler as POST };

// app/products/page.tsx — Server Component: call tRPC directly, no HTTP round-trip
import { createCaller } from "@/server/root";
import { auth } from "@/auth";

export default async function ProductsPage() {
  const session = await auth();

  // createCaller bypasses HTTP — calls the procedure function directly
  const caller = createCaller({ userId: session?.user?.id ?? null });
  const { items } = await caller.product.list({ limit: 20 });

  return (
    <ul>
      {items.map((p) => (
        <li key={p.id}>
          {p.name} — ${p.price}
        </li>
      ))}
    </ul>
  );
}

// server/routers/notifications.ts
import { observable } from "@trpc/server/observable";
import { router, protectedProcedure } from "../trpc";
import { EventEmitter } from "events";

const notificationEmitter = new EventEmitter();

export const notificationsRouter = router({
  onNew: protectedProcedure.subscription(({ ctx }) => {
    return observable<{ message: string; createdAt: Date }>((emit) => {
      const listener = (notification: { userId: string; message: string }) => {
        if (notification.userId === ctx.userId) {
          emit.next({ message: notification.message, createdAt: new Date() });
        }
      };

      notificationEmitter.on("notification", listener);
      // Cleanup when the subscription is unsubscribed
      return () => notificationEmitter.off("notification", listener);
    });
  }),
});

// Emit from anywhere in the server
export function pushNotification(userId: string, message: string) {
  notificationEmitter.emit("notification", { userId, message });
}

// Client component subscribing
"use client";
import { trpc } from "@/lib/trpc-client";

export function NotificationBell() {
  trpc.notifications.onNew.useSubscription(undefined, {
    onData: (notification) => {
      console.log("New notification:", notification.message);
    },
  });

  return <button>🔔</button>;
}