Prisma Generator Express

This tool helps you quickly create API endpoints in your Express app using your Prisma models.

When you run npx prisma generate, it automatically creates two things:

• Exposes Prisma API to clients - all operations with database is available, including all relationships at any depth.
• Service functions that you can import into your Express routes. By default, these functions handle CRUD operations and output validation. This behavior can be controlled.
• Router generator function that lets you select which routes to add to the application and which middlewares to apply.

Table of Contents

• Installation
• Basic Usage
• Router Generator Usage
• Request Object Properties
• Router Schema

Installation

Using npm:

1 npm install prisma-generator-express

Using yarn:

1 yarn add prisma-generator-express

Basic usage

• Include this generator in your schema.prisma file:

1generator express {
2  provider = "prisma-generator-express"
3}

• Generate your middleware functions by running:

1  npx prisma generate

• Attach Prisma instance

1import { PrismaClient } from '@prisma/client'
2import express from 'express'
3
4const prisma = new PrismaClient()
5const app = express()
6
7app.use(express.json()) // for parsing application/json
8
9// Attach Prisma to every request
10app.use((req, res, next) => {
11  req.prisma = prisma
12  next()
13})

• Here’s how you can use a generated function in your Express app:

1import { UserFindUnique } from './generated/api/UserFindUnique' // Adjust the path as necessary
2import { FindUniqueUserSchema } from './prisma-zod-generator/schemas/FindUniqueUser.schema' // Adjust the path as necessary
3import { FindUniqueUserSchemaOutput } from './prisma-zod-generator/schemas/FindUniqueUserOutput.schema' // Adjust the path as necessary
4
5// move this to /helpers
6export function validateQuery(schema: ZodSchema) {
7  return async (req: Request, res: Response, next: NextFunction) => {
8    try {
9      req.query = schema.parse(req.query)
10      next()
11    } catch (error) {
12      res.status(400).json({
13        error: 'Input Validation failed',
14        details: error.errors,
15      })
16    }
17  }
18}
19
20app.get(
21  '/user/:id',
22  validateQuery(FindUniqueUserSchema),
23  async (req, res, next) => {
24    // Attach generated Zod schema for output validation
25    req.outputValidation = FindUniqueUserOutput
26
27    // Use the generated middleware to handle the request
28    await UserFindUnique(req, res, next)
29  },
30)

The UserFindUnique function will fetch the user details from the database, validate the output with Zod, and handle the API response.

Router generator usage

The library will create functions to generate routers per each model in schema. Each route can accept middleware that will be injected right before generated handler is invoked. You can use it to modify/remove/validate request payload. The output validation can be also attached to req object on this step.

1import express, { json } from 'express'
2import type { Response, Request, NextFunction, RequestHandler } from 'express'
3
4import { PrismaClient } from '../prisma/generated/client'
5import { UserAccountRouter } from '../prisma/generated/express/UserAccount'
6import { RouteConfig } from '~prisma/generated/express/routeConfig'
7import { UserAccountFindFirstSchema } from '../prisma/generated/prisma-zod-generator/schemas'
8
9const app = express()
10
11const prisma = new PrismaClient()
12
13/**
14 * Middleware to attach Prisma client instance to the request object.
15 * This ensures that Prisma client is available in all subsequent middleware and route handlers.
16 */
17const addPrisma: RequestHandler = (
18  req: Request,
19  res: Response,
20  next: NextFunction,
21) => {
22  req.prisma = prisma
23  next()
24}
25
26/**
27 * Run context-related operations or modify `req` properties to control the behavior of the route
28 */
29const beforeFindFirst: RequestHandler = (
30  req: Request,
31  res: Response,
32  next: NextFunction,
33) => {
34  req.passToNext = true
35  next()
36}
37
38/**
39 * if `req.passToNext` is true, then the result of generated middleware
40 * will be available in req.locals?.data for modifications
41 */
42const afterFindFirst: RequestHandler = (
43  req: Request,
44  res: Response,
45  next: NextFunction,
46) => {
47  console.log('req.locals?.data :>> ', req.locals?.data)
48  next()
49}
50
51/**
52 * For generated route the middleware order will be as follows:
53 * 1. Query parser (kicks in for GET requests)
54 * 2. Custom middlewares: config.{method}.before[]
55 * 3. Input validator middleware (Optional): config.{method}.input. For GET request validates `req.query`, for others - `req.body`
56 * 4. Generated middleware
57 * 5. Output validator middleware: config.{method}.input
58 * 6. Custom middlewares: config.{method}.after[] (not available if req.passToNext is falsy)
59 */
60const userAccounRouterConfig: RouteConfig<RequestHandler> = {
61  FindFirst: {
62    before: [beforeFindFirst],
63    after: [afterFindFirst],
64    input: {
65      schema: UserAccountFindFirstSchema, // make sure you set `isGenerateSelect = true` in prisma-zod-generator
66      allow: [
67        'select.id',
68        'select.full_name',
69        'select.emailAddress',
70        'select.orders[].ProductName',
71        'select.orders[].quantity',
72        'where.id',
73        'where.createdAt',
74      ],
75    },
76  },
77  addModelPrefix: true,
78  enableAll: true,
79  customUrlPrefix: '/v1',
80}
81
82app.use(addPrisma)
83app.use(UserAccountRouter(userAccounRouterConfig))
84
85app.listen(3000, () => {
86  console.log('Server is running on http://localhost:3000')
87})

Request Object Properties

The following properties can be attached to the req object to control the behavior of generated middleware:

Property	Type	Description
prisma	PrismaClient	An instance of PrismaClient that allows the middleware to interact with your database.
passToNext	boolean	Optional, if true - the result of a Prisma request will be passed to the next middleware as if (req.locals) req.locals.data
outputValidation	ZodTypeAny	(Optional) A Zod schema used to validate the data returned from the Prisma query before sending it to the client.

Router Schema

Function	Method	URL
findUnique	GET	/:id
findFirst	GET	/first
findMany	GET	/
aggregate	GET	/aggregate
count	GET	/count
groupBy	GET	/groupby
create	POST	/
createMany	POST	/many
update	PUT	/
updateMany	PUT	/many
upsert	PATCH	/
delete	DELETE	/
deleteMany	DELETE	/many

Skip generation

1/// generator off
2model UserAccount {
3  ID           Int         @id @default(autoincrement())
4  full_name    String
5  emailAddress String      @unique
6  createdAt    DateTime    @default(now())
7  orders       orderItem[]
8}

Helper functions

createValidatorMiddleware(validatorOptions: ValidatorOptions)

Simple wrapper that internally uses allow or forbid logic for filtering incoming queries and data payloads. Helps to make sure that schemas from prisma-zod-generator is not too permissive.

1interface ValidatorOptions {
2  schema: ZodSchema<any>
3  allowedPaths?: string[] // Fobids all except allowed. For example [`where.user.id`, `select.id`], all other provided inputs will throw an error
4  forbiddenPaths?: string[] // Similar, but allows all, except forbidden
5  target?: 'body' | 'query'
6}

encodeQueryParams(params: Params)

It can be used on the frontend to encode Prisma-compatible queries. Alternatively qs can be used, but it probably won't work with OR: [{ blah: false }, { blah: null }] or some other edge cases.

1type RecursiveUrlParams = {
2  [key: string]: RecursiveUrlParams | string | boolean | unknown
3}
4type Params = Record<string, RecursiveUrlParams | string>

parseQueryParams(params: QueryParams)

1type QueryParams = string | ParsedQs | string[] | ParsedQs[] | undefined

Recursively converts strings "true", "false", "null", and "number" into correct formats.

allow( schema: T, allowedPaths: string[] ): ZodEffects<T, any, any>

Accepts schema and ['array.of.allowed.paths']. Throws an error if provided something that doesn't fit allowed schema.

forbid( schema: T, forbiddenPaths: string[] ): ZodEffects<T, any, any>

Same as allow but works in opposite way.

---

Credits:

• Super Kick Gym - Brazilian Jiu Jitsu in Bangkok

• Rememo - Free Task Management and Corporate Chat