@trpc/server 11.14.0 → 11.14.1

package/skills/server-side-calls/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: server-side-calls
+description: >
+  Call tRPC procedures directly from server code using t.createCallerFactory()
+  and router.createCaller(context) for integration testing, internal server logic,
+  and custom API endpoints. Catch TRPCError and extract HTTP status with
+  getHTTPStatusCodeFromError(). Error handling via onError option.
+type: core
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+sources:
+  - 'trpc/trpc:www/docs/server/server-side-calls.md'
+---
+
+# tRPC -- Server-Side Calls
+
+## Setup
+
+```ts
+// server/trpc.ts
+import { initTRPC } from '@trpc/server';
+
+type Context = { user?: { id: string } };
+
+const t = initTRPC.context<Context>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+export const createCallerFactory = t.createCallerFactory;
+```
+
+```ts
+// server/appRouter.ts
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { createCallerFactory, publicProcedure, router } from './trpc';
+
+interface Post {
+  id: string;
+  title: string;
+}
+
+const posts: Post[] = [{ id: '1', title: 'Hello world' }];
+
+export const appRouter = router({
+  post: router({
+    add: publicProcedure
+      .input(z.object({ title: z.string().min(2) }))
+      .mutation(({ input }) => {
+        const post: Post = { ...input, id: `${Math.random()}` };
+        posts.push(post);
+        return post;
+      }),
+    byId: publicProcedure
+      .input(z.object({ id: z.string() }))
+      .query(({ input }) => {
+        const post = posts.find((p) => p.id === input.id);
+        if (!post) throw new TRPCError({ code: 'NOT_FOUND' });
+        return post;
+      }),
+    list: publicProcedure.query(() => posts),
+  }),
+});
+
+export type AppRouter = typeof appRouter;
+export const createCaller = createCallerFactory(appRouter);
+```
+
+```ts
+// usage
+import { createCaller } from './appRouter';
+
+const caller = createCaller({ user: { id: '1' } });
+const postList = await caller.post.list();
+const newPost = await caller.post.add({ title: 'New post' });
+```
+
+## Core Patterns
+
+### Integration test with createCallerFactory
+
+```ts
+// server/appRouter.test.ts
+import type { inferProcedureInput } from '@trpc/server';
+import { createCaller } from './appRouter';
+import type { AppRouter } from './appRouter';
+import { createContextInner } from './context';
+
+async function testAddAndGetPost() {
+  const ctx = await createContextInner({ user: undefined });
+  const caller = createCaller(ctx);
+
+  const input: inferProcedureInput<AppRouter['post']['add']> = {
+    title: 'Test post',
+  };
+
+  const post = await caller.post.add(input);
+  const allPosts = await caller.post.list();
+
+  console.assert(allPosts.some((p) => p.id === post.id));
+}
+```
+
+### Using router.createCaller() directly
+
+```ts
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+
+const t = initTRPC.create();
+
+const appRouter = t.router({
+  greeting: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => `Hello ${input.name}`),
+});
+
+const caller = appRouter.createCaller({});
+const result = await caller.greeting({ name: 'tRPC' });
+```
+
+### Error handling in a custom API endpoint
+
+```ts
+import { TRPCError } from '@trpc/server';
+import { getHTTPStatusCodeFromError } from '@trpc/server/http';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { appRouter } from './appRouter';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  const caller = appRouter.createCaller({});
+
+  try {
+    const post = await caller.post.byId({ id: req.query.id as string });
+    res.status(200).json({ data: { postTitle: post.title } });
+  } catch (cause) {
+    if (cause instanceof TRPCError) {
+      const httpStatusCode = getHTTPStatusCodeFromError(cause);
+      res.status(httpStatusCode).json({ error: { message: cause.message } });
+      return;
+    }
+    res.status(500).json({ error: { message: 'Internal server error' } });
+  }
+}
+```
+
+### Caller with onError callback
+
+```ts
+import { initTRPC } from '@trpc/server';
+import { z } from 'zod';
+
+const t = initTRPC.create();
+
+const appRouter = t.router({
+  greeting: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => {
+      if (input.name === 'invalid') {
+        throw new Error('Invalid name');
+      }
+      return `Hello ${input.name}`;
+    }),
+});
+
+const caller = appRouter.createCaller(
+  {},
+  {
+    onError: (opts) => {
+      console.error('An error occurred:', opts.error);
+    },
+  },
+);
+```
+
+## Common Mistakes
+
+### [HIGH] Using createCaller inside another procedure
+
+Wrong:
+
+```ts
+import { appRouter } from './appRouter';
+import { createCallerFactory, publicProcedure } from './trpc';
+
+const createCaller = createCallerFactory(appRouter);
+
+const proc = publicProcedure.query(async () => {
+  const caller = createCaller({});
+  return caller.post.list();
+});
+```
+
+Correct:
+
+```ts
+import type { Context } from './context';
+import { publicProcedure } from './trpc';
+
+async function listPosts(ctx: Context) {
+  return ctx.db.post.findMany();
+}
+
+const proc = publicProcedure.query(async ({ ctx }) => {
+  return listPosts(ctx);
+});
+```
+
+Calling createCaller from within a procedure re-creates context, re-runs all middleware, and re-validates input; extract shared logic into a plain function instead.
+
+Source: www/docs/server/server-side-calls.md
+
+### [MEDIUM] Not providing context to createCaller
+
+Wrong:
+
+```ts
+import { appRouter } from './appRouter';
+
+const caller = appRouter.createCaller({});
+await caller.protectedRoute();
+// middleware throws UNAUTHORIZED because ctx.user is undefined
+```
+
+Correct:
+
+```ts
+import { appRouter } from './appRouter';
+import { createContextInner } from './context';
+
+const ctx = await createContextInner({ user: { id: '1' } });
+const caller = appRouter.createCaller(ctx);
+await caller.protectedRoute();
+```
+
+`createCaller` requires a context object matching what procedures and middleware expect; passing an empty object when procedures require auth context causes runtime errors.
+
+Source: www/docs/server/server-side-calls.md
+
+## See Also
+
+- `server-setup` -- initTRPC, routers, context configuration
+- `middlewares` -- auth middleware that callers must satisfy
+- `error-handling` -- TRPCError and getHTTPStatusCodeFromError

package/skills/service-oriented-architecture/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: service-oriented-architecture
+description: >
+  Break a tRPC backend into multiple services with custom routing links that
+  split on the first path segment (op.path.split('.')) to route to different
+  backend service URLs. Define a faux gateway router that merges service routers
+  for the AppRouter type without running them in the same process. Share
+  procedure and router definitions via a server-lib package with a single
+  initTRPC instance. Each service runs its own standalone/Express/Fastify server.
+type: composition
+library: trpc
+library_version: '11.14.0'
+requires:
+  - server-setup
+  - client-setup
+  - links
+sources:
+  - examples/soa/
+---
+
+# tRPC — Service-Oriented Architecture
+
+## Setup
+
+### Shared library (single initTRPC instance)
+
+```ts
+// packages/server-lib/index.ts
+import { initTRPC } from '@trpc/server';
+
+type Context = {
+  requestId?: string;
+};
+
+const t = initTRPC.context<Context>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+export const mergeRouters = t.mergeRouters;
+```
+
+### Service A (own server)
+
+```ts
+// services/service-a/router.ts
+import { publicProcedure, router } from '@myorg/server-lib';
+import { z } from 'zod';
+
+export const serviceARouter = router({
+  greet: publicProcedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+```
+
+```ts
+// services/service-a/index.ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { serviceARouter } from './router';
+
+createHTTPServer({
+  router: serviceARouter,
+  createContext() {
+    return {};
+  },
+}).listen(2021);
+```
+
+### Service B (own server)
+
+```ts
+// services/service-b/router.ts
+import { publicProcedure, router } from '@myorg/server-lib';
+
+export const serviceBRouter = router({
+  status: publicProcedure.query(() => ({ status: 'ok' })),
+});
+```
+
+```ts
+// services/service-b/index.ts
+import { createHTTPServer } from '@trpc/server/adapters/standalone';
+import { serviceBRouter } from './router';
+
+createHTTPServer({
+  router: serviceBRouter,
+  createContext() {
+    return {};
+  },
+}).listen(2022);
+```
+
+### Gateway (type-only, not a running server)
+
+```ts
+// gateway/index.ts
+import { router } from '@myorg/server-lib';
+import { serviceARouter } from '../services/service-a/router';
+import { serviceBRouter } from '../services/service-b/router';
+
+const appRouter = router({
+  serviceA: serviceARouter,
+  serviceB: serviceBRouter,
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+The gateway merges routers only for type inference. It does not run as a server process. The client uses the `AppRouter` type for full type safety.
+
+### Client with custom routing link
+
+```ts
+// client/client.ts
+import { createTRPCClient, httpBatchLink } from '@trpc/client';
+import type { AppRouter } from '../gateway';
+
+export const client = createTRPCClient<AppRouter>({
+  links: [
+    (runtime) => {
+      const servers = {
+        serviceA: httpBatchLink({ url: 'http://localhost:2021' })(runtime),
+        serviceB: httpBatchLink({ url: 'http://localhost:2022' })(runtime),
+      };
+
+      return (ctx) => {
+        const { op } = ctx;
+        const pathParts = op.path.split('.');
+        const serverName = pathParts.shift() as keyof typeof servers;
+        const path = pathParts.join('.');
+
+        const link = servers[serverName];
+        if (!link) {
+          throw new Error(
+            `Unknown service: ${String(serverName)}. Known: ${Object.keys(servers).join(', ')}`,
+          );
+        }
+        return link({
+          ...ctx,
+          op: { ...op, path },
+        });
+      };
+    },
+  ],
+});
+```
+
+```ts
+// Usage
+const greeting = await client.serviceA.greet.query({ name: 'World' });
+const status = await client.serviceB.status.query();
+```
+
+## Core Patterns
+
+### Path-based routing convention
+
+```ts
+(runtime) => {
+  const servers = {
+    users: httpBatchLink({ url: 'http://users-service:3000' })(runtime),
+    billing: httpBatchLink({ url: 'http://billing-service:3000' })(runtime),
+    notifications: httpBatchLink({ url: 'http://notifications-service:3000' })(
+      runtime,
+    ),
+  };
+
+  return (ctx) => {
+    const { op } = ctx;
+    const [serverName, ...rest] = op.path.split('.');
+    const link = servers[serverName as keyof typeof servers];
+
+    if (!link) {
+      throw new Error(`Unknown service: ${serverName}`);
+    }
+
+    return link({
+      ...ctx,
+      op: { ...op, path: rest.join('.') },
+    });
+  };
+};
+```
+
+The first segment of the procedure path (before the first `.`) maps to a service name. The remaining path is forwarded to the target service.
+
+### Adding shared headers across services
+
+```ts
+(runtime) => {
+  const servers = {
+    serviceA: httpBatchLink({
+      url: 'http://localhost:2021',
+      headers() {
+        return { 'x-request-id': crypto.randomUUID() };
+      },
+    })(runtime),
+    serviceB: httpBatchLink({
+      url: 'http://localhost:2022',
+      headers() {
+        return { 'x-request-id': crypto.randomUUID() };
+      },
+    })(runtime),
+  };
+
+  return (ctx) => {
+    const [serverName, ...rest] = ctx.op.path.split('.');
+    return servers[serverName as keyof typeof servers]({
+      ...ctx,
+      op: { ...ctx.op, path: rest.join('.') },
+    });
+  };
+};
+```
+
+## Common Mistakes
+
+### MEDIUM Path routing assumes first segment is server name
+
+Wrong:
+
+```ts
+const serverName = op.path.split('.').shift();
+// Breaks if router structure changes or has nested namespaces
+```
+
+Correct:
+
+```ts
+const [serverName, ...rest] = op.path.split('.');
+const link = servers[serverName as keyof typeof servers];
+if (!link) {
+  throw new Error(`Unknown service: ${serverName}. Known: ${Object.keys(servers).join(', ')}`);
+}
+return link({ ...ctx, op: { ...op, path: rest.join('.') } });
+```
+
+Custom routing links that split on the first path segment break silently if the router structure changes. Add validation and clear error messages when the server name is unrecognized. The path convention must be documented and enforced across teams.
+
+Source: examples/soa/client/client.ts
+
+## See Also
+
+- **server-setup** -- single `initTRPC.create()` instance shared across services
+- **links** -- `httpBatchLink`, custom link authoring
+- **client-setup** -- `createTRPCClient`, type-safe client with `AppRouter`
+- **adapter-standalone** -- running individual service servers