> Every UQL docs page, as Markdown: https://uql-orm.dev/llms.txt
> The same docs over MCP: https://uql-orm.dev/mcp
> Before writing UQL code, read the skill: https://uql-orm.dev/.well-known/agent-skills/uql-orm/SKILL.md

# tRPC

> Expose UQL entities as tRPC procedures that take the JSON query as input.

Source: https://uql-orm.dev/trpc

A UQL query is plain JSON, so it can be a tRPC procedure’s input with no adapter. Use tRPC for per-procedure contracts, and the [HTTP handler](https://uql-orm.dev/http.md) for CRUD across many entities; both fit in one app. Written for tRPC v11.

## Router

```ts title="src/router.ts"
import { initTRPC } from '@trpc/server';
import type { EntityData, Type, WireQuery } from 'uql-orm';
import { z } from 'zod';
import { User } from './shared/models/index.js';
import { pool } from './uql.config.js';

const t = initTRPC.create();

function entityRouter<E extends object>(entity: Type<E>) {
  return t.router({
    findMany: t.procedure
      .input(z.custom<WireQuery<E>>())
      .query(({ input }) => pool.findMany(entity, input)),
    insertOne: t.procedure
      .input(z.object({ data: z.custom<EntityData<E>>() })) // tRPC cannot type a bare generic input
      .mutation(({ input }) => pool.insertOne(entity, input.data)),
  });
}

export const appRouter = t.router({ user: entityRouter(User) });
export type AppRouter = typeof appRouter;
```

The client gets the whole query typed, nested relations included:

```ts title="src/client.ts"
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './router.js';

const trpc = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: '/trpc' })],
});

const users = await trpc.user.findMany.query({
  $select: { id: true, name: true },
  $populate: { posts: { $select: { title: true }, $limit: 5 } },
  $limit: 10,
});
// typed User[], each with a typed posts: Post[]
```

## Validating inputs

`z.custom<T>()` declares a type and checks nothing at runtime. For procedures an untrusted client can call, accept a few validated arguments and build the query on the server.

For tenant isolation, run the procedure body inside `withContext({ tenantId: ctx.session.tenantId }, () => ...)`, with the id from a verified session, and declare a `security` [filter](https://uql-orm.dev/querying/filters.md). Unlike a `$where` added by hand, the filter reaches every relation and fails closed. See [Multi-tenancy](https://uql-orm.dev/multi-tenancy.md).