zenstack-orpc

ZenStack plugin for generating oRPC routers with automatic Row Level Security support.

🎯 Features

- ✅ Generate oRPC routers directly from ZenStack schema
- ✅ Full Row Level Security (RLS) policy support
- ✅ Automatic validation via Zod schemas
- ✅ Type-safe API with complete type inference
- ✅ Access error handling (P2004)
- ✅ Support for all Prisma CRUD operations
- ✅ Simplified architecture (no adapter layer needed)

📦 Installation

``bash
npm install -D zenstack-orpc


or

pnpm add -D zenstack-orpc

or

yarn add -D zenstack-orpc
`

🚀 Usage

$3

`zmodel
plugin orpc {
provider = 'zenstack-orpc'
output = 'zenstack/orpc'
}
`

$3

`bash
npx zenstack generate
`

$3

`typescript
import { appRouter } from './zenstack/orpc/routers';
import { createORPCHandler } from '@orpc/server';
import { PrismaClient } from '@prisma/client';

const handler = createORPCHandler({
router: appRouter,
context: async (req) => ({
prisma: new PrismaClient(),
user: await getUserFromRequest(req),
}),
});
`

📁 Generated Structure

`
zenstack/orpc/
├── routers/
│ ├── index.ts # Main router (appRouter)
│ ├── User.router.ts
│ ├── Post.router.ts
│ └── ... # Router for each model
└── helper.ts # Utilities and context
`

🔧 Configuration

$3

`zmodel
plugin orpc {
provider = 'zenstack-orpc'
output = 'zenstack/orpc' // Output path
generateModels = ['User', 'Post'] // Generate only specified models
generateModelActions = ['findMany', 'create'] // Generate only specified operations
zodSchemasImport = '../../zod' // Path to Zod schemas import
baseImport = '../base' // Import base context from custom path
}
`

$3

By default, the plugin generates a basic context. You can provide your own:

`typescript
// base.ts
import { os } from '@orpc/server';
import type { PrismaClient } from '@prisma/client';

export const base = os.$context<{
prisma: PrismaClient;
user?: {
id: string;
role: string;
// Add your custom fields
};
}>();
`

Then use baseImport option:

`zmodel
plugin orpc {
provider = 'zenstack-orpc'
output = 'zenstack/orpc'
baseImport = '../base'
}
`

📚 API

$3

The plugin generates a typed context:

`typescript
type Context = {
prisma: PrismaClient;
user?: {
id: string;
role: string;
};
};
`

$3

For each model, the following operations are generated:

Queries (8 operations):
- aggregate - aggregate data
- count - count records
- findFirst - find first record
- findFirstOrThrow - find first record (throws if not found)
- findMany - find multiple records
- findUnique - find unique record
- findUniqueOrThrow - find unique record (throws if not found)
- groupBy - group data

Mutations (7 operations):
- create - create record
- createMany - create multiple records
- delete - delete record
- deleteMany - delete multiple records
- update - update record
- updateMany - update multiple records
- upsert - create or update record

$3

`typescript
// Check read operations
export async function checkRead(promise: Promise): Promise

// Check write operations
export async function checkMutate(promise: Promise): Promise
`

🔒 Row Level Security (RLS)

The plugin automatically integrates with ZenStack RLS policies:

`zmodel
model Post {
id String @id @default(cuid())
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId String

// Anyone can read published posts
@@allow('read', published)

// Only authenticated users can read all posts
@@allow('read', auth() != null)

// Only author can update/delete their posts
@@allow('update,delete', auth() == author)

// Admins have full access
@@allow('all', auth().role == 'admin')
}
`

Access errors are automatically handled:

`typescript
// Prisma error P2004 → "Access denied"
// Prisma error P2025 → "Not found"
`

🆚 Comparison with tRPC

| Feature | tRPC | oRPC |
|---------|------|------|
| Type Safety | ✅ | ✅ |
| RLS Support | Via ZenStack | Via ZenStack |
| Bundle Size | Larger | Smaller |
| Learning Curve | Steeper | Gentler |
| Middleware | Complex | Simple |

🏗️ Architecture

$3

`typescript
// Generated code
export const PostRouter = {
findMany: base
.input($Schema.PostInputSchema.findMany)
.handler(async ({ context, input }) =>
checkRead(context.prisma.post.findMany(input))
),

create: base
.input($Schema.PostInputSchema.create)
.handler(async ({ context, input }) =>
checkMutate(context.prisma.post.create(input))
),

// ... +13 operations
};
`

$3

`typescript
export const appRouter = {
user: UserRouter,
post: PostRouter,
// ... all models
};

export type AppRouter = typeof appRouter;
`

📖 Examples

$3

`typescript
const posts = await orpcClient.post.findMany({
where: { published: true },
take: 10,
});
`

$3

`typescript
// RLS automatically checks permissions
const post = await orpcClient.post.create({
data: {
title: 'Hello World',
published: false,
authorId: userId,
},
});
`

$3

`typescript
try {
await orpcClient.post.delete({
where: { id: 'post-id' }
});
} catch (err) {
if (err.message === 'Access denied') {
// RLS denied the operation
}
}
``

🤝 Contributing

Contributions are welcome! Please open an issue or PR.

📝 License

MIT

🔗 Links

- ZenStack Documentation
- oRPC Documentation
- Prisma Documentation