prisma-generator-express 1.39.0 → 1.41.0

package/README.md

@@ -5,32 +5,36 @@
 [![Coverage](https://img.shields.io/codecov/c/github/multipliedtwice/prisma-generator-express/main.svg)](https://codecov.io/gh/multipliedtwice/prisma-generator-express)
 [![npm](https://img.shields.io/npm/l/prisma-generator-express.svg)](LICENSE)
 
-Prisma generator that creates Express or Fastify CRUD API routes with OpenAPI documentation from your Prisma schema.
+Prisma generator that creates Express, Fastify, or Hono CRUD API routes with OpenAPI documentation from your Prisma schema.
 
 Running `npx prisma generate` produces:
 
 - Handler functions for all Prisma operations (findMany, create, update, delete, etc.)
 - Router generator with middleware support (before/after hooks per operation)
 - POST read endpoints for all read operations (for complex queries exceeding URL length limits)
+- Express-only progressive read streaming over Server-Sent Events (SSE) for staged page-level responses
 - OpenAPI 3.1 spec (JSON and YAML endpoints registered automatically per router)
 - Documentation helpers for contract view and Scalar UI (require manual mounting)
 - Client-side query parameter encoder
 - Guard/variant shape enforcement via prisma-guard integration
 
-Supports both **Express** and **Fastify** targets via the `target` configuration option.
+Supports **Express**, **Fastify**, and **Hono** targets via the `target` configuration option.
 
 ## Table of contents
 
 - [Compatibility](#compatibility)
 - [Installation](#installation)
 - [Setup](#setup)
+- [Path casing in generated endpoints](#path-casing-in-generated-endpoints)
 - [Usage (Express)](#usage-express)
 - [Usage (Fastify)](#usage-fastify)
+- [Usage (Hono)](#usage-hono)
 - [Selective routes with middleware](#selective-routes-with-middleware)
 - [Guard shapes (prisma-guard integration)](#guard-shapes-prisma-guard-integration)
 - [Request body format](#request-body-format)
 - [Query encoding (client side)](#query-encoding-client-side)
 - [POST read endpoints](#post-read-endpoints)
+- [Progressive Endpoint Composition (Express SSE)](#progressive-endpoint-composition-express-sse)
 - [Response shaping: select, include, omit](#response-shaping-select-include-omit)
 - [BigInt and Decimal handling](#bigint-and-decimal-handling)
 - [Pagination](#pagination)
@@ -64,6 +68,11 @@ Some operations require newer versions:
 | --------- | ------------ | ---------------- |
 | Express   | `"express"`  | `express.Router()` factory function per model |
 | Fastify   | `"fastify"`  | Fastify plugin function per model |
+| Hono      | `"hono"`     | `Hono` instance factory function per model |
+
+The Hono target v1 is tested on Node.js runtimes only. See [Cloudflare Workers and edge runtimes](#cloudflare-workers-and-edge-runtimes).
+
+Progressive Endpoint Composition over Server-Sent Events is currently supported by the Express target only. Fastify and Hono continue to support normal JSON read and write routes.
 
 ### Database provider support
 
@@ -95,12 +104,18 @@ Peer dependencies for Fastify:
 npm install @prisma/client fastify
 ```
 
+Peer dependencies for Hono:
+
+```bash
+npm install @prisma/client hono
+```
+
 Optional peer dependencies:
 
 ```bash
 npm install prisma-sql         # SQL optimization
 npm install prisma-guard zod   # Guard shape enforcement
-npm install prisma-query-builder-ui  # Visual query playground
+npm install prisma-query-builder-ui  # Visual query playground (Express/Fastify only — not auto-started for Hono)
 ```
 
 ## Setup
@@ -117,7 +132,7 @@ generator express {
 }
 ```
 
-To generate Fastify routes instead of Express, set the `target` config:
+To target Fastify or Hono, set the `target` config:
 
 ```prisma
 generator express {
@@ -126,7 +141,14 @@ generator express {
 }
 ```
 
-Valid `target` values are `"express"` (default) and `"fastify"`.
+```prisma
+generator express {
+  provider = "prisma-generator-express"
+  target   = "hono"
+}
+```
+
+Valid `target` values are `"express"` (default), `"fastify"`, and `"hono"`.
 
 The generator detects the Prisma client generator automatically. All standard provider values are supported: `prisma-client-js`, `@prisma/client`, and `prisma-client`.
 
@@ -136,6 +158,26 @@ Generate:
 npx prisma generate
 ```
 
+## Path casing in generated endpoints
+
+Model names are converted to **flat lowercase** in URL paths. There is no kebab-case or snake_case conversion — the model name is lowercased character by character.
+
+| Model name        | URL path             |
+| ----------------- | -------------------- |
+| `User`            | `/user`              |
+| `BlogPost`        | `/blogpost`          |
+| `OrderItem`       | `/orderitem`         |
+| `INVOICE_RECORDS` | `/invoice_records`   |
+| `apiKey`          | `/apikey`            |
+
+Underscores in model names are preserved. Camel-case word boundaries are not preserved.
+
+Throughout this README, `{modelname}` (lowercase) represents the converted path segment. For example, the path `/{modelname}/first` refers to `/user/first` for a `User` model, or `/blogpost/first` for a `BlogPost` model.
+
+The generated directory structure preserves the original model casing — e.g. `generated/BlogPost/BlogPostRouter.ts` — but the runtime URL is `/blogpost`.
+
+To remove the model prefix entirely, set `addModelPrefix: false` in the route config. To replace it with a custom prefix, use `customUrlPrefix`.
+
 ## Usage (Express)
 
 ```ts
@@ -146,6 +188,8 @@ import { UserRouter } from './generated/User/UserRouter'
 const prisma = new PrismaClient()
 const app = express()
 
+app.use(express.json())
+
 app.use((req, res, next) => {
   req.prisma = prisma
   next()
@@ -162,6 +206,8 @@ app.listen(3000, () => {
 })
 ```
 
+`express.json()` is required because write endpoints (`create`, `update`, `delete`, `upsert`) and POST read endpoints accept JSON request bodies.
+
 ## Usage (Fastify)
 
 When `target = "fastify"`, each model produces a Fastify plugin function instead of an Express router.
@@ -195,16 +241,138 @@ fastify.listen({ port: 3000 }, () => {
 
 The generated function signature is `async function ModelRoutes(fastify: FastifyInstance, config?: RouteConfig)`. It registers routes directly on the provided Fastify instance.
 
-### Key differences between Express and Fastify targets
+## Usage (Hono)
+
+When `target = "hono"`, each model produces a function that returns a Hono instance.
+
+```ts
+import { Hono } from 'hono'
+import { PrismaClient } from '@prisma/client'
+import { UserRouter } from './generated/User/UserRouter'
+
+type Env = {
+  Variables: {
+    prisma: PrismaClient
+  }
+}
 
-| Aspect | Express | Fastify |
-| ------ | ------- | ------- |
-| Generated function | `ModelRouter(config)` returns `express.Router` | `ModelRoutes(fastify, config)` registers on instance |
-| Mounting | `app.use('/', ModelRouter(config))` | `fastify.register(async (i) => { await ModelRoutes(i, config) })` |
-| Hook types | `before`/`after` are Express `RequestHandler[]` | `before`/`after` are `FastifyHookHandler[]` |
-| Guard resolveVariant | Receives `express.Request` | Receives `FastifyRequest` |
-| Request data | `req.prisma`, `res.locals` | `request.prisma`, `request` properties |
-| Error handling | Express error middleware on the router | Fastify `setErrorHandler` on the instance |
+const prisma = new PrismaClient()
+const app = new Hono<Env>()
+
+app.use('*', async (c, next) => {
+  c.set('prisma', prisma)
+  await next()
+})
+
+const userConfig = {
+  enableAll: true,
+}
+
+app.route('/', UserRouter(userConfig))
+
+export default app
+```
+
+The generated function signature is `UserRouter(config?: RouteConfig): Hono`. Mount with `app.route(prefix, UserRouter(config))`.
+
+PrismaClient is injected via `c.set('prisma', prismaInstance)` in middleware that runs before the router. Declare `prisma` (and any optional connectors like `postgres` / `sqlite`) in your Hono app's `Variables` type so TypeScript can verify the injection. The same pattern applies to optional `postgres` / `sqlite` connectors for [prisma-sql integration](#prisma-sql-integration).
+
+### Hooks (Hono)
+
+Hono hooks are native Hono middleware functions:
+
+```ts
+import type { HonoHookHandler } from './generated/routeConfig.target'
+
+const auth: HonoHookHandler = async (c, next) => {
+  const token = c.req.header('authorization')
+  if (!token) return c.json({ message: 'Unauthorized' }, 401)
+  await next()
+}
+
+const userConfig = {
+  findMany: {
+    before: [auth],
+  },
+}
+```
+
+Call `await next()` to continue the chain. Return a `Response` to short-circuit — subsequent hooks, the main handler, and the response middleware will not run.
+
+### HTTPException normalization
+
+Throwing Hono's `HTTPException` from a hook short-circuits to a JSON error response. The router's `app.onError` catches the exception, preserves the status code, and **normalizes the response body** to `{ "message": err.message }`.
+
+```ts
+import { HTTPException } from 'hono/http-exception'
+
+const auth: HonoHookHandler = async (c, next) => {
+  const token = c.req.header('authorization')
+  if (!token) {
+    throw new HTTPException(401, { message: 'Unauthorized' })
+  }
+  await next()
+}
+```
+
+Custom response bodies attached to `HTTPException` are **not preserved** — the router always returns `{ message: err.message }` with the exception's status code. If you need a custom response body, return a `Response` directly from the hook instead of throwing.
+
+This normalization ensures all errors from generated routes share a single shape, so clients only need to handle one error format.
+
+### Cloudflare Workers and edge runtimes
+
+The Hono target v1 is tested on Node.js runtimes only. The route layer may be portable to edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge), but **production edge support is not guaranteed**. Prisma Client edge usage requires compatible Prisma setup, driver adapters, or Prisma Accelerate / Prisma Postgres depending on the database. `prisma-guard` edge compatibility is unverified.
+
+On Cloudflare Workers, you must construct an edge-compatible Prisma client yourself and expose it through your runtime environment. Cloudflare does not provide a built-in Prisma binding — the exact setup depends on your database and Prisma adapter (Prisma Accelerate, `@prisma/adapter-d1`, etc.).
+
+A minimal pattern, assuming you've already wired up an edge-compatible client behind a `PRISMA` binding:
+
+```ts
+type Env = {
+  Bindings: {
+    PRISMA: any
+  }
+  Variables: {
+    prisma: any
+  }
+}
+
+const app = new Hono<Env>()
+
+app.use('*', async (c, next) => {
+  c.set('prisma', c.env.PRISMA)
+  await next()
+})
+
+app.route('/', UserRouter({ enableAll: true }))
+
+export default app
+```
+
+Both `Bindings` (what the runtime injects) and `Variables` (what your middleware sets via `c.set`) need to be declared on the app's `Env` type.
+
+### Query Builder
+
+The Query Builder playground is Node-only and **not auto-started** by the Hono target. The generated `?ui=playground` route can render the playground iframe, but the Hono router does not start the Query Builder server. Start `prisma-query-builder-ui` manually in a separate process and point the config to that server when needed.
+
+### Query string differences
+
+Hono's `c.req.query()` returns a flat `Record<string, string>` — duplicate query keys collapse to the last value. For example, `?take=10&take=20` becomes `{ take: '20' }`. This differs from Express, which parses `?a=1&a=2` into `{ a: ['1', '2'] }`.
+
+The `encodeQueryParams` client utility does not emit duplicate keys, so this only matters for hand-built query strings. All complex Prisma arguments are JSON-encoded into single query values.
+
+### Key differences between targets
+
+| Aspect | Express | Fastify | Hono |
+| ------ | ------- | ------- | ---- |
+| Generated function | `ModelRouter(config)` returns `express.Router` | `ModelRoutes(fastify, config)` registers on instance | `ModelRouter(config)` returns `Hono` instance |
+| Mounting | `app.use('/', ModelRouter(config))` | `fastify.register(async (i) => { await ModelRoutes(i, config) })` | `app.route('/', ModelRouter(config))` |
+| Hook types | `RequestHandler[]` | `FastifyHookHandler[]` | `HonoHookHandler[]` (native middleware) |
+| Hook signature | `(req, res, next)` | `(request, reply)` | `(c, next)` |
+| Guard resolveVariant | `express.Request` | `FastifyRequest` | Hono `Context` |
+| PrismaClient injection | `req.prisma = prisma` | `request.prisma = prisma` | `c.set('prisma', prisma)` |
+| Error handling | Express error middleware | `setErrorHandler` | `app.onError` |
+| Query Builder auto-start | Yes (Node only) | Yes (Node only) | No (manual start) |
 
 ## Selective routes with middleware
 
@@ -242,15 +410,33 @@ fastify.register(async (instance) => {
 })
 ```
 
-Only operations listed in the config (or all when `enableAll: true`) are registered. Operations not listed produce no routes.
-
 Fastify hooks receive `(request: FastifyRequest, reply: FastifyReply)`. If a hook sends a reply (via `reply.send()`), subsequent hooks and the handler are skipped.
 
+### Hono
+
+```ts
+const userConfig = {
+  findMany: {
+    before: [async (c, next) => { /* auth check */ await next() }],
+  },
+  create: {
+    before: [async (c, next) => { /* auth + validation */ await next() }],
+  },
+  findUnique: {},
+}
+
+app.route('/', UserRouter(userConfig))
+```
+
+Hono hooks are native middleware functions. Call `await next()` to continue the chain. Return a `Response` (e.g. `c.json({...}, 403)`) or throw `HTTPException` to short-circuit — subsequent hooks and the handler will not run.
+
+Only operations listed in the config (or all when `enableAll: true`) are registered. Operations not listed produce no routes.
+
 ## Guard shapes (prisma-guard integration)
 
 prisma-generator-express integrates with [prisma-guard](https://github.com/multipliedtwice/prisma-guard) to enforce input validation, query shape restrictions, and tenant isolation on generated routes. When a `shape` is configured on an operation, the handler calls `prisma.model.guard(shape, caller).method(args)` instead of `prisma.model.method(args)`.
 
-Guard shapes work identically for both Express and Fastify targets. The only difference is the type of the `resolveVariant` callback parameter (`Request` vs `FastifyRequest`).
+Guard shapes work identically across all three targets. The only difference is the type of the `resolveVariant` callback parameter (`Request` for Express, `FastifyRequest` for Fastify, `Context` for Hono).
 
 ### Guard setup
 
@@ -275,7 +461,7 @@ generator express {
 }
 ```
 
-Run `npx prisma generate` to emit both the express routes and the guard artifacts.
+Run `npx prisma generate` to emit both the routes and the guard artifacts.
 
 Extend PrismaClient with the guard extension and attach it to requests:
 
@@ -293,6 +479,8 @@ const prisma = new PrismaClient().$extends(
 
 const app = express()
 
+app.use(express.json())
+
 app.use((req, res, next) => {
   req.prisma = prisma
   next()
@@ -312,16 +500,20 @@ app.use('/', UserRouter({
 app.listen(3000)
 ```
 
+For Fastify and Hono, attach the extended client the same way — via `request.prisma = prisma` (Fastify) or `c.set('prisma', prisma)` (Hono).
+
 If prisma-guard is not installed or the client is not extended with the guard extension, requests to guarded routes return 500 with the message: `Guard shapes require prisma-guard extension on PrismaClient. Install: npm install prisma-guard, then extend your client with guardExtension().`
 
 ### How guard integration works
 
 Each operation config accepts an optional `shape` property. When present, the generated handler:
 
-1. Stores the shape on the request context via middleware (Express: `res.locals.guardShape`, Fastify: `request.guardShape`)
+1. Stores the shape on the request context via middleware (Express: `res.locals.guardShape = shape`, Fastify: `request.guardShape = shape`, Hono: `c.set('guardShape', shape)`)
 2. Resolves the caller from `config.guard.resolveVariant(req)`, then from the configured header (default `x-api-variant`), falling back to `undefined`
 3. Calls `prisma.model.guard(shape, caller).method(args)` instead of `prisma.model.method(args)`
 
+The downstream handler reads these values (`res.locals.guardShape`, `request.guardShape`, `c.get('guardShape')`) when constructing the Prisma call.
+
 When `shape` is absent, the handler calls Prisma directly with no guard enforcement.
 
 Generated route config types treat `shape` as a named shape map. Use `default` for the normal single-shape case, and add other keys only when you need caller-based variants. The runtime still passes the map to `prisma-guard`; the `default` variant is selected when no caller is provided or no variant matches.
@@ -463,7 +655,7 @@ If the caller is missing or doesn't match any key, the request is rejected with
 
 ### Custom caller resolution
 
-Use `resolveVariant` for caller logic beyond a simple header:
+Use `resolveVariant` for caller logic beyond a simple header. The callback parameter type depends on the target.
 
 ```ts
 // Express
@@ -501,6 +693,27 @@ const userConfig = {
 }
 ```
 
+```ts
+// Hono
+const userConfig = {
+  findMany: {
+    shape: {
+      admin: { /* ... */ },
+      public: { /* ... */ },
+    },
+  },
+  guard: {
+    resolveVariant: (c) => {
+      const user = c.get('user')
+      if (user?.role === 'admin') return 'admin'
+      return 'public'
+    },
+  },
+}
+```
+
+When using `c.get('user')` or other custom context values in TypeScript, add them to the `Variables` type of your Hono app so the call is typed correctly. For example: `Hono<{ Variables: { prisma: PrismaClient; user?: { role: string } } }>`.
+
 `resolveVariant` takes priority over the header. If both are configured, the header is checked only when `resolveVariant` returns `undefined`.
 
 ### Parameterized caller patterns
@@ -837,6 +1050,8 @@ const prisma = new PrismaClient().$extends(
   }))
 )
 
+app.use(express.json())
+
 app.use((req, res, next) => {
   const tenantId = req.headers['x-tenant-id'] as string
   store.run({ tenantId }, () => {
@@ -883,7 +1098,7 @@ For upsert: `where`, `create`, `update`, `select`, `include`
 
 ### Guard error handling
 
-Guard errors are mapped to HTTP status codes by the generated error-handling middleware:
+Guard errors are mapped to HTTP status codes by the generated error handler:
 
 | Error type    | HTTP status | When                                                              |
 | ------------- | ----------- | ----------------------------------------------------------------- |
@@ -914,6 +1129,8 @@ const prisma = new PrismaClient().$extends(
 
 const app = express()
 
+app.use(express.json())
+
 app.use((req, res, next) => {
   const tenantId = req.headers['x-tenant-id'] as string
   const role = req.headers['x-role'] as string || 'viewer'
@@ -1013,6 +1230,8 @@ All write operations accept the full Prisma args object as the JSON request body
 
 Write operations that return records (create, update, delete, upsert, createManyAndReturn, updateManyAndReturn) support `select`, `include`, and `omit` in the request body to control the response shape.
 
+For Express, mount `express.json()` before the router so request bodies are parsed. For Hono, malformed JSON bodies are rejected with 400 (`{ "message": "Invalid JSON in request body" }`) before reaching the handler.
+
 ### Bulk operations
 
 `createMany`, `createManyAndReturn`, `updateMany`, and `updateManyAndReturn` accept scalar-only data inputs. Nested relation writes are not supported in bulk operations.
@@ -1047,17 +1266,19 @@ POST read endpoints are enabled by default. Disable them with `disablePostReads:
 
 Most read operations use the same path for both GET and POST. The only exception is `findMany`, which uses a `/read` suffix to avoid conflicting with `POST /` (create).
 
-| Operation         | GET path         | POST path        |
-| ----------------- | ---------------- | ---------------- |
-| findMany          | `/{modelName}/`              | `/{modelName}/read`          |
-| findFirst         | `/{modelName}/first`         | `/{modelName}/first`         |
-| findFirstOrThrow  | `/{modelName}/first/strict`  | `/{modelName}/first/strict`  |
-| findUnique        | `/{modelName}/unique`        | `/{modelName}/unique`        |
-| findUniqueOrThrow | `/{modelName}/unique/strict` | `/{modelName}/unique/strict` |
-| findManyPaginated | `/{modelName}/paginated`     | `/{modelName}/paginated`     |
-| count             | `/{modelName}/count`         | `/{modelName}/count`         |
-| aggregate         | `/{modelName}/aggregate`     | `/{modelName}/aggregate`     |
-| groupBy           | `/{modelName}/groupby`       | `/{modelName}/groupby`       |
+`{modelname}` in the paths below is the lowercased model name. See [Path casing in generated endpoints](#path-casing-in-generated-endpoints).
+
+| Operation         | GET path                     | POST path                    |
+| ----------------- | ---------------------------- | ---------------------------- |
+| findMany          | `/{modelname}/`              | `/{modelname}/read`          |
+| findFirst         | `/{modelname}/first`         | `/{modelname}/first`         |
+| findFirstOrThrow  | `/{modelname}/first/strict`  | `/{modelname}/first/strict`  |
+| findUnique        | `/{modelname}/unique`        | `/{modelname}/unique`        |
+| findUniqueOrThrow | `/{modelname}/unique/strict` | `/{modelname}/unique/strict` |
+| findManyPaginated | `/{modelname}/paginated`     | `/{modelname}/paginated`     |
+| count             | `/{modelname}/count`         | `/{modelname}/count`         |
+| aggregate         | `/{modelname}/aggregate`     | `/{modelname}/aggregate`     |
+| groupBy           | `/{modelname}/groupby`       | `/{modelname}/groupby`       |
 
 ### Usage
 
@@ -1106,6 +1327,385 @@ app.use('/', UserRouter({
 }))
 ```
 
+## Progressive Endpoint Composition (Express SSE)
+
+Progressive Endpoint Composition lets an Express read endpoint stream partial response fields over Server-Sent Events while still ending with a final result event.
+
+This is useful for page-level endpoints where different UI sections need different slices of data. For example, a dashboard can render profile basics first, then saved jobs, applications, invitations, and activity as each stage finishes.
+
+This feature is **Express-only** in v1.
+
+### Mental model
+
+Progressive Endpoint Composition is explicit staged data loading for a specific operation variant.
+
+It is **not** automatic Prisma include streaming. The generator does not split arbitrary `select` or `include` trees. You define stages yourself and each stage decides what query to run and which field path to patch.
+
+### Request format
+
+Use the same generated GET read endpoint and request SSE with the `Accept` header:
+
+```http
+GET /user/first
+Accept: text/event-stream
+x-api-variant: /talent/dashboard
+```
+
+No new endpoint is generated. The variant is resolved the same way as guard variants: `guard.resolveVariant(req)` first, then the configured header, defaulting to `x-api-variant`.
+
+If a GET read request accepts `text/event-stream` but the matched variant has no progressive config, the router runs the normal read query and returns a single SSE `result` event.
+
+POST read endpoints remain JSON-only.
+
+### Supported operations
+
+Progressive SSE can be configured on Express GET read operations only:
+
+- `findMany`
+- `findUnique`
+- `findUniqueOrThrow`
+- `findFirst`
+- `findFirstOrThrow`
+- `findManyPaginated`
+- `count`
+- `aggregate`
+- `groupBy`
+
+Write operations do not support progressive SSE.
+
+### Event protocol
+
+Each event is sent as a normal SSE `data:` line containing JSON.
+
+Progress event:
+
+```json
+{ "type": "progress", "stage": "profileBasics", "completed": 1, "total": 4 }
+```
+
+Field event:
+
+```json
+{ "type": "field", "key": "profile", "value": { "id": "profile-id" } }
+```
+
+Nested field event:
+
+```json
+{ "type": "field", "key": "profile.appliedTo", "value": [] }
+```
+
+Final result event:
+
+```json
+{ "type": "result", "data": { "id": "user-id", "profile": {}, "savedJobAds": [] } }
+```
+
+Error event:
+
+```json
+{ "type": "error", "message": "Could not load progressive response" }
+```
+
+The final `result.data` is the accumulated object built from all applied patches, unless a stage returns a stop result.
+
+### Route config example
+
+Progressive config lives on an Express read operation. It is keyed by the resolved variant.
+
+```ts
+import type { ProgressiveStage } from './generated/routeConfig.target'
+
+const dashboardIdentity: ProgressiveStage<{ userId: string }> = async ({
+  ctx,
+  prisma,
+}) => {
+  const user = await prisma.user.findFirst({
+    select: { id: true },
+    where: { id: ctx.userId },
+  })
+
+  if (!user) {
+    return {
+      stop: true,
+      data: null,
+    }
+  }
+
+  return {
+    key: 'id',
+    value: user.id,
+  }
+}
+
+const dashboardProfileBasics: ProgressiveStage<{ userId: string }> = async ({
+  ctx,
+  prisma,
+}) => {
+  const user = await prisma.user.findFirst({
+    select: {
+      profile: {
+        select: {
+          id: true,
+          profileName: true,
+          profilePicture: true,
+          jobTitle: true,
+          location: true,
+          skills: true,
+          isAvailableForHire: true,
+          _count: {
+            select: {
+              profileViews: true,
+              savedAt: true,
+            },
+          },
+          boost: {
+            select: {
+              boostedUntil: true,
+            },
+          },
+        },
+      },
+    },
+    where: { id: ctx.userId },
+  })
+
+  return {
+    key: 'profile',
+    value: user?.profile
+      ? {
+          ...user.profile,
+          appliedTo: [],
+          invitationsFor: [],
+          jobAdViews: [],
+          campaign_clicks: [],
+          jobAssignments: [],
+          resourceOfCompanyTalentRoster: [],
+        }
+      : null,
+  }
+}
+
+const dashboardApplications: ProgressiveStage<{ userId: string }> = async ({
+  ctx,
+  prisma,
+  accumulated,
+}) => {
+  if (accumulated.profile == null) return
+
+  const profile = await prisma.talentProfile.findFirst({
+    select: {
+      appliedTo: {
+        orderBy: { createdAt: 'desc' },
+        take: 50,
+        where: { deletedAt: null },
+        select: {
+          id: true,
+          createdAt: true,
+          viewedAt: true,
+          details: true,
+          jobAd: true,
+        },
+      },
+    },
+    where: { userId: ctx.userId },
+  })
+
+  return {
+    key: 'profile.appliedTo',
+    value: profile?.appliedTo ?? [],
+  }
+}
+
+const userConfig = {
+  resolveContext: (req) => ({
+    userId: req.user.id,
+  }),
+
+  guard: {
+    variantHeader: 'x-api-variant',
+  },
+
+  findFirst: {
+    shape: {
+      '/talent/dashboard': dashboardShape,
+      me: meShape,
+    },
+    progressive: {
+      '/talent/dashboard': {
+        enabled: true,
+        stages: [
+          'dashboardIdentity',
+          'dashboardProfileBasics',
+          'dashboardApplications',
+        ],
+      },
+    },
+    progressiveStages: {
+      dashboardIdentity,
+      dashboardProfileBasics,
+      dashboardApplications,
+    },
+  },
+}
+
+app.use('/', UserRouter(userConfig))
+```
+
+`resolveContext` is required for a variant with `progressive.enabled !== false`. It is not required for ordinary JSON requests or for single-result SSE fallback.
+
+### Stage function API
+
+```ts
+type ProgressiveStageContext<TContext = unknown, TPrisma = any> = {
+  ctx: TContext
+  req: Request
+  res: Response
+  prisma: TPrisma
+  variant: string
+  accumulated: Record<string, unknown>
+  signal: AbortSignal
+}
+
+type ProgressivePatch = {
+  key: string
+  value: unknown
+}
+
+type ProgressiveStopResult<T = unknown> = {
+  stop: true
+  data: T
+}
+
+type ProgressiveStageResult<T = unknown> =
+  | void
+  | ProgressivePatch
+  | ProgressivePatch[]
+  | ProgressiveStopResult<T>
+
+type ProgressiveStage<TContext = unknown, TPrisma = any, T = unknown> = (
+  context: ProgressiveStageContext<TContext, TPrisma>,
+) => Promise<ProgressiveStageResult<T>>
+```
+
+A stage may return:
+
+- `void` — no patch for this stage
+- one `{ key, value }` patch
+- an array of patches
+- `{ stop: true, data }` to immediately send a final `result` event and stop executing later stages
+
+### Patch path behavior
+
+Patch keys use dot paths, for example `profile.appliedTo`.
+
+Nested patches require the parent object to already exist in `accumulated`. If a stage tries to patch through `null`, `undefined`, an array, a primitive, or a non-plain object, the patch is dropped and no `field` event is sent.
+
+This means parent objects should be initialized by earlier stages:
+
+```ts
+return {
+  key: 'profile',
+  value: {
+    ...profileBasics,
+    appliedTo: [],
+    invitationsFor: [],
+  },
+}
+```
+
+Patch path segments `__proto__`, `constructor`, `prototype`, and empty path segments are rejected.
+
+### Hooks and guard behavior
+
+For SSE requests:
+
+- `before` hooks run before streaming starts
+- `after` hooks do not run, because the SSE middleware handles the response and does not continue to the normal handler
+- progressive stages receive `req.prisma` directly
+- guard shapes are not automatically applied to stage queries
+
+Stage authors are responsible for using the resolved context and enforcing ownership or tenant constraints in their stage queries.
+
+For variants without progressive config, the single-result SSE fallback uses the normal generated core read handler, so guard shape behavior matches the JSON endpoint.
+
+### Client-side usage
+
+Use `fetch` with streaming. Native browser `EventSource` cannot send custom headers like `x-api-variant`.
+
+Minimal example:
+
+```ts
+const response = await fetch('/user/first', {
+  headers: {
+    Accept: 'text/event-stream',
+    'x-api-variant': '/talent/dashboard',
+  },
+})
+
+if (!response.body) {
+  throw new Error('ReadableStream is not available')
+}
+
+const reader = response.body.getReader()
+const decoder = new TextDecoder()
+let buffer = ''
+
+while (true) {
+  const { value, done } = await reader.read()
+  if (done) break
+
+  buffer += decoder.decode(value, { stream: true })
+  const parts = buffer.split('\n\n')
+  buffer = parts.pop() ?? ''
+
+  for (const part of parts) {
+    const line = part
+      .split('\n')
+      .find((entry) => entry.startsWith('data: '))
+
+    if (!line) continue
+
+    const event = JSON.parse(line.slice('data: '.length))
+
+    if (event.type === 'field') {
+      // patch local field state
+    }
+
+    if (event.type === 'result') {
+      // replace with final result
+    }
+  }
+}
+```
+
+For React Query, include the variant and mode in the query key:
+
+```ts
+['user', 'first', { variant: '/talent/dashboard', mode: 'sse' }]
+```
+
+Do not reuse the same query key as the JSON endpoint because the same URL can return different shapes depending on `x-api-variant`.
+
+### Runtime notes
+
+The SSE response sets:
+
+```http
+Content-Type: text/event-stream
+Cache-Control: no-cache, no-transform
+Connection: keep-alive
+X-Accel-Buffering: no
+```
+
+The server sends keepalive comments periodically:
+
+```txt
+: keepalive
+```
+
+If compression middleware is used, configure it to skip `text/event-stream`, or ensure `res.flush()` is available so events are flushed promptly.
+
 ## Response shaping: select, include, omit
 
 Read and single-record write operations support three response shaping parameters:
@@ -1157,7 +1757,9 @@ All errors are returned as JSON with a `message` field:
 { "message": "Unique constraint violation" }
 ```
 
-Each generated router installs an error-handling middleware (Express) or error handler (Fastify) that normalizes errors. Prisma error codes are mapped to appropriate HTTP status codes. Guard errors are mapped as follows: `ShapeError` and `CallerError` → 400, `PolicyError` → 403.
+Each generated router installs error handling (Express middleware, Fastify `setErrorHandler`, or Hono `app.onError`) that normalizes errors. Prisma error codes are mapped to appropriate HTTP status codes. Guard errors are mapped as follows: `ShapeError` and `CallerError` → 400, `PolicyError` → 403.
+
+For the Hono target, thrown `HTTPException` instances are caught by `app.onError` and converted to `{ "message": err.message }` with the exception's status code. Custom response bodies attached to `HTTPException` are not preserved — see [HTTPException normalization](#httpexception-normalization).
 
 | Status | Description                                |
 | ------ | ------------------------------------------ |
@@ -1179,12 +1781,12 @@ All incoming JSON bodies and query parameters are sanitized to reject `__proto__
 
 Each router automatically registers OpenAPI spec endpoints when not in production:
 
-| Endpoint                | Description           |
-| ----------------------- | --------------------- |
-| `/{modelName}/openapi.json` | OpenAPI 3.1 JSON spec |
-| `/{modelName}/openapi.yaml` | OpenAPI 3.1 YAML spec |
+| Endpoint                        | Description           |
+| ------------------------------- | --------------------- |
+| `/{modelname}/openapi.json`     | OpenAPI 3.1 JSON spec |
+| `/{modelname}/openapi.yaml`     | OpenAPI 3.1 YAML spec |
 
-Actual paths depend on `customUrlPrefix` and `addModelPrefix` configuration.
+Actual paths depend on `customUrlPrefix` and `addModelPrefix` configuration. `{modelname}` is the lowercased model name (see [Path casing](#path-casing-in-generated-endpoints)).
 
 The OpenAPI spec includes POST read endpoints when they are enabled (default). Each POST read operation appears with its own `operationId` and request body schema documenting the native JSON argument types.
 
@@ -1210,6 +1812,8 @@ const postConfig = {
   enableAll: true,
 }
 
+app.use(express.json())
+
 app.use('/', UserRouter(userConfig))
 app.use('/', PostRouter(postConfig))
 
@@ -1270,14 +1874,70 @@ fastify.get('/docs', generateCombinedDocs({
 }))
 ```
 
-| Endpoint                      | Description             |
-| ----------------------------- | ----------------------- |
-| `/docs`                       | Combined index page     |
-| `/docs/{modelName}`               | Contract view (default) |
-| `/docs/{modelName}?ui=scalar`     | Scalar interactive UI   |
-| `/docs/{modelName}?ui=json`       | Raw JSON                |
-| `/docs/{modelName}?ui=yaml`       | Raw YAML                |
-| `/docs/{modelName}?ui=playground` | Query playground        |
+#### Hono
+
+```ts
+import { Hono } from 'hono'
+import { PrismaClient } from '@prisma/client'
+import {
+  generateCombinedDocs,
+  registerModelDocs,
+} from './generated/combinedDocs'
+import { UserRouter } from './generated/User/UserRouter'
+import { PostRouter } from './generated/Post/PostRouter'
+
+type Env = {
+  Variables: {
+    prisma: PrismaClient
+  }
+}
+
+const prisma = new PrismaClient()
+
+const userConfig = {
+  findMany: { before: [async (c, next) => { /* auth */ await next() }] },
+  create: {},
+  findUnique: {},
+}
+
+const postConfig = {
+  enableAll: true,
+}
+
+const app = new Hono<Env>()
+
+app.use('*', async (c, next) => {
+  c.set('prisma', prisma)
+  await next()
+})
+
+app.route('/', UserRouter(userConfig))
+app.route('/', PostRouter(postConfig))
+
+registerModelDocs(app, '/docs', {
+  User: userConfig,
+  Post: postConfig,
+})
+
+app.get('/docs', generateCombinedDocs({
+  title: 'My API',
+  modelConfigs: {
+    User: userConfig,
+    Post: postConfig,
+  },
+}))
+```
+
+| Endpoint                          | Description             |
+| --------------------------------- | ----------------------- |
+| `/docs`                           | Combined index page     |
+| `/docs/{modelname}`               | Contract view (default) |
+| `/docs/{modelname}?ui=scalar`     | Scalar interactive UI   |
+| `/docs/{modelname}?ui=json`       | Raw JSON                |
+| `/docs/{modelname}?ui=yaml`       | Raw YAML                |
+| `/docs/{modelname}?ui=playground` | Query playground        |
+
+The `?ui=playground` endpoint requires `prisma-query-builder-ui`. For Express and Fastify, the builder is auto-started in development. For Hono, the builder must be started manually in a separate process (see [Query Builder](#query-builder)).
 
 Disable in production via `NODE_ENV=production` or `DISABLE_OPENAPI=true`. Override with `disableOpenApi: false` in config to force-enable.
 
@@ -1298,18 +1958,20 @@ When `specBasePath` is not set, `customUrlPrefix` is used for both runtime route
 
 ## prisma-sql integration
 
-When `prisma-sql` is installed, the generated handlers automatically attempt to use its `speedExtension` for optimized SQL execution. The extension activates only when a database connector is provided on the request object.
+When `prisma-sql` is installed, the generated handlers automatically attempt to use its `speedExtension` for optimized SQL execution. The extension activates only when a database connector is provided on the request context.
 
-Set `req.postgres` or `req.sqlite` (Express) / `request.postgres` or `request.sqlite` (Fastify) in your middleware to activate the extension:
+Set the connector in your middleware to activate the extension:
 
 ```ts
 import { PrismaClient } from '@prisma/client'
 import postgres from 'postgres'
+import { Hono } from 'hono'
 
 const prisma = new PrismaClient()
 const sql = postgres(process.env.DATABASE_URL!)
 
 // Express
+app.use(express.json())
 app.use((req, res, next) => {
   req.prisma = prisma
   req.postgres = sql
@@ -1321,9 +1983,27 @@ fastify.addHook('onRequest', async (request) => {
   request.prisma = prisma
   request.postgres = sql
 })
+
+// Hono
+type Env = {
+  Variables: {
+    prisma: PrismaClient
+    postgres: ReturnType<typeof postgres>
+  }
+}
+
+const app = new Hono<Env>()
+
+app.use('*', async (c, next) => {
+  c.set('prisma', prisma)
+  c.set('postgres', sql)
+  await next()
+})
 ```
 
-Without a connector on the request, the handlers use the standard PrismaClient. Set `DEBUG=true` in the environment to enable prisma-sql debug logging.
+Without a connector on the request context, the handlers use the standard PrismaClient. Set `DEBUG=true` in the environment to enable prisma-sql debug logging.
+
+For SQLite, use `c.set('sqlite', sqliteConnector)` (Hono) or the equivalent on Express/Fastify, and add `sqlite` to the `Variables` type.
 
 ## Query parameter parsing
 
@@ -1331,42 +2011,48 @@ GET query values are parsed server-side. Strings starting with `{`, `[`, or `"`
 
 POST read endpoints bypass this parsing entirely — the JSON body is used as-is with native types.
 
+On the Hono target, duplicate query keys collapse to the last value (`?a=1&a=2` → `a=2`). `encodeQueryParams` does not emit duplicate keys, so this only matters for hand-built query strings.
+
 ## Router schema
 
-| Operation           | Method | Path             | Notes                              |
-| ------------------- | ------ | ---------------- | ---------------------------------- |
-| findMany            | GET    | `/{modelName}/`              |                                    |
-| findMany            | POST   | `/{modelName}/read`          | POST read alternative              |
-| findFirst           | GET    | `/{modelName}/first`         |                                    |
-| findFirst           | POST   | `/{modelName}/first`         | POST read alternative              |
-| findFirstOrThrow    | GET    | `/{modelName}/first/strict`  |                                    |
-| findFirstOrThrow    | POST   | `/{modelName}/first/strict`  | POST read alternative              |
-| findUnique          | GET    | `/{modelName}/unique`        |                                    |
-| findUnique          | POST   | `/{modelName}/unique`        | POST read alternative              |
-| findUniqueOrThrow   | GET    | `/{modelName}/unique/strict` |                                    |
-| findUniqueOrThrow   | POST   | `/{modelName}/unique/strict` | POST read alternative              |
-| findManyPaginated   | GET    | `/{modelName}/paginated`     |                                    |
-| findManyPaginated   | POST   | `/{modelName}/paginated`     | POST read alternative              |
-| count               | GET    | `/{modelName}/count`         |                                    |
-| count               | POST   | `/{modelName}/count`         | POST read alternative              |
-| aggregate           | GET    | `/{modelName}/aggregate`     |                                    |
-| aggregate           | POST   | `/{modelName}/aggregate`     | POST read alternative              |
-| groupBy             | GET    | `/{modelName}/groupby`       |                                    |
-| groupBy             | POST   | `/{modelName}/groupby`       | POST read alternative              |
-| create              | POST   | `/{modelName}/`              |                                    |
-| createMany          | POST   | `/{modelName}/many`          |                                    |
-| createManyAndReturn | POST   | `/{modelName}/many/return`   |                                    |
-| update              | PUT    | `/{modelName}/`              |                                    |
-| updateMany          | PUT    | `/{modelName}/many`          |                                    |
-| updateManyAndReturn | PUT    | `/{modelName}/many/return`   |                                    |
-| upsert              | PATCH  | `/{modelName}/`              |                                    |
-| delete              | DELETE | `/{modelName}/`              |                                    |
-| deleteMany          | DELETE | `/{modelName}/many`          |                                    |
+`{modelname}` in the paths below is the lowercased model name. For a `User` model, `/{modelname}/first` becomes `/user/first`. For `BlogPost`, it becomes `/blogpost/first`. See [Path casing in generated endpoints](#path-casing-in-generated-endpoints).
+
+| Operation           | Method | Path                         | Notes                              |
+| ------------------- | ------ | ---------------------------- | ---------------------------------- |
+| findMany            | GET    | `/{modelname}/`              |                                    |
+| findMany            | POST   | `/{modelname}/read`          | POST read alternative              |
+| findFirst           | GET    | `/{modelname}/first`         |                                    |
+| findFirst           | POST   | `/{modelname}/first`         | POST read alternative              |
+| findFirstOrThrow    | GET    | `/{modelname}/first/strict`  |                                    |
+| findFirstOrThrow    | POST   | `/{modelname}/first/strict`  | POST read alternative              |
+| findUnique          | GET    | `/{modelname}/unique`        |                                    |
+| findUnique          | POST   | `/{modelname}/unique`        | POST read alternative              |
+| findUniqueOrThrow   | GET    | `/{modelname}/unique/strict` |                                    |
+| findUniqueOrThrow   | POST   | `/{modelname}/unique/strict` | POST read alternative              |
+| findManyPaginated   | GET    | `/{modelname}/paginated`     |                                    |
+| findManyPaginated   | POST   | `/{modelname}/paginated`     | POST read alternative              |
+| count               | GET    | `/{modelname}/count`         |                                    |
+| count               | POST   | `/{modelname}/count`         | POST read alternative              |
+| aggregate           | GET    | `/{modelname}/aggregate`     |                                    |
+| aggregate           | POST   | `/{modelname}/aggregate`     | POST read alternative              |
+| groupBy             | GET    | `/{modelname}/groupby`       |                                    |
+| groupBy             | POST   | `/{modelname}/groupby`       | POST read alternative              |
+| create              | POST   | `/{modelname}/`              |                                    |
+| createMany          | POST   | `/{modelname}/many`          |                                    |
+| createManyAndReturn | POST   | `/{modelname}/many/return`   |                                    |
+| update              | PUT    | `/{modelname}/`              |                                    |
+| updateMany          | PUT    | `/{modelname}/many`          |                                    |
+| updateManyAndReturn | PUT    | `/{modelname}/many/return`   |                                    |
+| upsert              | PATCH  | `/{modelname}/`              |                                    |
+| delete              | DELETE | `/{modelname}/`              |                                    |
+| deleteMany          | DELETE | `/{modelname}/many`          |                                    |
 
 Paths shown are relative suffixes. Actual paths include the model prefix (e.g., `/user/first`) unless `addModelPrefix: false`, and any `customUrlPrefix`.
 
 POST read endpoints are enabled by default. Set `disablePostReads: true` to remove them.
 
+For the Express target, GET read endpoints can also stream SSE events when the request sends `Accept: text/event-stream`. SSE uses the same GET paths shown above; no additional routes are generated. See [Progressive Endpoint Composition](#progressive-endpoint-composition-express-sse).
+
 ## Skipping models
 
 Add `/// generator off` to a model's documentation to skip generation:
@@ -1383,7 +2069,7 @@ model InternalLog {
 ### Express
 
 ```ts
-interface RouteConfig {
+interface RouteConfig<TCtx = unknown> {
   enableAll?: boolean
   addModelPrefix?: boolean           // default: true
   customUrlPrefix?: string
@@ -1404,6 +2090,8 @@ interface RouteConfig {
     variantHeader?: string           // default: 'x-api-variant'
   }
 
+  resolveContext?: (req: Request) => TCtx | Promise<TCtx>
+
   queryBuilder?: QueryBuilderConfig | false
 
   pagination?: {
@@ -1412,13 +2100,18 @@ interface RouteConfig {
     distinctCountLimit?: number      // default: 100000
   }
 
-  // per-operation config
-  findMany?: OperationConfig
-  findUnique?: OperationConfig
-  findUniqueOrThrow?: OperationConfig
-  findFirst?: OperationConfig
-  findFirstOrThrow?: OperationConfig
-  findManyPaginated?: OperationConfig
+  // read operation config
+  findMany?: ReadOperationConfig<TCtx>
+  findUnique?: ReadOperationConfig<TCtx>
+  findUniqueOrThrow?: ReadOperationConfig<TCtx>
+  findFirst?: ReadOperationConfig<TCtx>
+  findFirstOrThrow?: ReadOperationConfig<TCtx>
+  findManyPaginated?: ReadOperationConfig<TCtx>
+  aggregate?: ReadOperationConfig<TCtx>
+  count?: ReadOperationConfig<TCtx>
+  groupBy?: ReadOperationConfig<TCtx>
+
+  // write operation config
   create?: OperationConfig
   createMany?: OperationConfig
   createManyAndReturn?: OperationConfig
@@ -1428,9 +2121,6 @@ interface RouteConfig {
   upsert?: OperationConfig
   delete?: OperationConfig
   deleteMany?: OperationConfig
-  aggregate?: OperationConfig
-  count?: OperationConfig
-  groupBy?: OperationConfig
 }
 
 interface OperationConfig {
@@ -1439,6 +2129,46 @@ interface OperationConfig {
   shape?: Record<string, any>
 }
 
+interface ReadOperationConfig<TCtx = unknown> extends OperationConfig {
+  progressive?: Record<string, ProgressiveVariantConfig>
+  progressiveStages?: Record<string, ProgressiveStage<TCtx>>
+}
+
+type ProgressiveVariantConfig = {
+  enabled?: boolean
+  stages: string[]
+}
+
+type ProgressiveStageContext<TContext = unknown, TPrisma = any> = {
+  ctx: TContext
+  req: Request
+  res: Response
+  prisma: TPrisma
+  variant: string
+  accumulated: Record<string, unknown>
+  signal: AbortSignal
+}
+
+type ProgressivePatch = {
+  key: string
+  value: unknown
+}
+
+type ProgressiveStopResult<T = unknown> = {
+  stop: true
+  data: T
+}
+
+type ProgressiveStageResult<T = unknown> =
+  | void
+  | ProgressivePatch
+  | ProgressivePatch[]
+  | ProgressiveStopResult<T>
+
+type ProgressiveStage<TContext = unknown, TPrisma = any, T = unknown> = (
+  context: ProgressiveStageContext<TContext, TPrisma>,
+) => Promise<ProgressiveStageResult<T>>
+
 interface QueryBuilderConfig {
   enabled?: boolean
   port?: number
@@ -1467,6 +2197,27 @@ type FastifyHookHandler = (
 
 The `guard.resolveVariant` callback receives `FastifyRequest` instead of `Request`.
 
+### Hono
+
+The Hono config is identical except for hook and resolver types:
+
+```ts
+interface OperationConfig {
+  before?: HonoHookHandler[]
+  after?: HonoHookHandler[]
+  shape?: Record<string, any>
+}
+
+type HonoHookHandler<Env extends { Variables: any } = any> = (
+  c: Context<Env>,
+  next: Next,
+) => Promise<Response | void> | Response | void
+```
+
+The `guard.resolveVariant` callback receives Hono's `Context`. Hooks are native Hono middleware — call `await next()` to continue the chain, return a `Response` (or throw `HTTPException`) to short-circuit.
+
+The Hono router does not auto-start the Query Builder. Set `queryBuilder: false` to make the playground route return 404, or run `prisma-query-builder-ui` manually for development.
+
 ### Shared options
 
 `customUrlPrefix` is normalized to ensure a leading slash and strip trailing slashes.
@@ -1475,6 +2226,8 @@ The `guard.resolveVariant` callback receives `FastifyRequest` instead of `Reques
 
 `disablePostReads` removes all POST read endpoints when set to `true`. POST read endpoints are enabled by default. This is a global setting — there is no per-operation toggle.
 
+`resolveContext` is Express-only and is required for enabled progressive SSE variants. It is called before progressive stages run and its return value is passed to each stage as `ctx`.
+
 `openApiServers` sets the `servers` array in the OpenAPI spec:
 
 ```ts