prisma-generator-express 1.52.0 → 1.54.0

package/README.md

@@ -12,7 +12,7 @@ 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), using manual stages or auto-include splitting for supported relation reads
+- Express-only progressive read streaming over Server-Sent Events (SSE), using manual stages or auto-include splitting for supported relation reads, including deep `findMany` / `findManyPaginated` auto-include paths
 - Express-only standalone materialized view router for read-only access to registered PostgreSQL materialized views
 - OpenAPI 3.1 spec (JSON and YAML endpoints registered automatically per router)
 - Documentation helpers for contract view and Scalar UI (require manual mounting)
@@ -74,7 +74,7 @@ Some operations require newer versions:
 
 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. Express supports both manual staged streaming and auto-include streaming for supported relation reads, including single-record reads and limited `findMany` reads. Fastify and Hono continue to support normal JSON read and write routes.
+Progressive Endpoint Composition over Server-Sent Events is currently supported by the Express target only. Express supports both manual staged streaming and auto-include streaming for supported relation reads, including single-record reads and deep `findMany` / `findManyPaginated` reads within the configured planner limits. Fastify and Hono continue to support normal JSON read and write routes.
 
 ### Database provider support
 
@@ -1562,7 +1562,7 @@ Progressive SSE has two modes:
 
 Manual mode is explicit staged data loading. You define stages yourself and each stage decides what query to run and which field path to patch.
 
-Auto-include mode is generated relation loading. The router keeps the normal GET endpoint, runs the root query first, then loads supported included relations as separate follow-up queries. For single-record reads, relation paths are streamed as field patches. For `findMany`, direct root relations are loaded in batches and streamed as index-aligned relation batches.
+Auto-include mode is generated relation loading. The router keeps the normal GET endpoint, runs the root query first, then loads supported included relations as separate follow-up queries. For single-record reads, relation paths are streamed as field patches. For `findMany` and `findManyPaginated`, root rows are streamed first, direct root relation stages are streamed as index-aligned relation batches, and deeper nested relation stages are streamed as locator-based nested relation batches. The terminal `result` event still contains the fully assembled payload.
 
 ### Request format
 
@@ -1601,8 +1601,9 @@ Auto-include progressive SSE supports these Express GET read operations:
 - `findFirst`
 - `findFirstOrThrow`
 - `findMany`
+- `findManyPaginated`
 
-`findMany` support is intentionally narrower than single-record support. It supports direct root relation loading only, with additional fallback cases listed in [Auto-include behavior and limits](#auto-include-behavior-and-limits).
+`findMany` and `findManyPaginated` support deep relation loading by flattening parent rows at each relation path, with fallback cases listed in [Auto-include behavior and limits](#auto-include-behavior-and-limits).
 
 If auto-include is configured on an unsupported operation, the router either falls back to single-result SSE or sends an SSE error depending on `fallback`.
 
@@ -1630,18 +1631,33 @@ Nested field event:
 { "type": "field", "key": "profile.appliedTo", "value": [] }
 ```
 
-Root array event for `findMany` auto-include:
+Root array event for `findMany` / `findManyPaginated` auto-include:
 
 ```json
 { "type": "rootArray", "data": [{ "id": "user-1" }, { "id": "user-2" }] }
 ```
 
-Relation batch event for `findMany` auto-include:
+Relation batch event for a direct root relation in `findMany` / `findManyPaginated` auto-include:
 
 ```json
 { "type": "relationBatch", "relationPath": "profile", "values": [{ "id": "profile-1" }, null] }
 ```
 
+Nested relation batch event for a depth-2-or-deeper relation in `findMany` / `findManyPaginated` auto-include:
+
+```json
+{
+  "type": "nestedRelationBatch",
+  "relationPath": "companies.users",
+  "depth": 2,
+  "attachments": [
+    { "locator": [0, "companies", 0], "value": [{ "id": "user-1" }] }
+  ]
+}
+```
+
+Each `attachments[].locator` is walked from `rootArray.data` to the parent object. The leaf field to assign is the last segment of `relationPath`. For example, `relationPath: "companies.users"` and `locator: [0, "companies", 0]` means `rootArray.data[0].companies[0].users = value`.
+
 Final result event:
 
 ```json
@@ -1656,7 +1672,9 @@ Error event:
 
 For single-record progressive responses, the final `result.data` is the accumulated object built from all applied patches, unless a manual stage returns a stop result.
 
-For `findMany` auto-include responses, `rootArray.data` is the source of truth for root row identity and order. Each `relationBatch.values` array is index-aligned with `rootArray.data`, so `values[i]` belongs to `rootArray.data[i]`. The terminal `result.data` is the fully merged array.
+For `findMany` auto-include responses, `rootArray.data` is the source of truth for root row identity and order. Each depth-1 `relationBatch.values` array is index-aligned with `rootArray.data`, so `values[i]` belongs to `rootArray.data[i]`. Each depth-2-or-deeper `nestedRelationBatch.attachments` array carries locator/value pairs that can be applied to the accumulated root rows immediately. The terminal `result.data` is the fully merged array and can be used as a final reconcile.
+
+For `findManyPaginated` auto-include responses, `pageMeta` is sent before `rootArray`. The terminal `result.data` has the normal paginated shape: `{ data, total, hasMore }`.
 
 ### Manual staged mode
 
@@ -1923,7 +1941,7 @@ On single-record reads, auto-include sends root scalar fields first, then sends
 
 The final `result` event contains the assembled object.
 
-For `findMany`, auto-include sends the root rows first, then sends one relation batch event per supported relation stage:
+For `findMany`, auto-include sends the root rows first, then sends one relation batch event for each supported direct root relation stage. Depth-2-or-deeper stages send `nestedRelationBatch` events with locators pointing to the parent object inside the accumulated root rows:
 
 ```ts
 const listConfig = {
@@ -1963,7 +1981,7 @@ const response = await fetch(`/user?${params}`, {
 })
 ```
 
-Example `findMany` auto-include event sequence:
+Example shallow `findMany` auto-include event sequence:
 
 ```json
 { "type": "rootArray", "data": [{ "id": "user-1" }, { "id": "user-2" }] }
@@ -1977,6 +1995,78 @@ Example `findMany` auto-include event sequence:
 { "type": "result", "data": [{ "id": "user-1", "profile": { "id": "profile-1", "displayName": "Alice" } }, { "id": "user-2", "profile": null }] }
 ```
 
+Deep `findMany` and `findManyPaginated` requests use the same planner. Nested stages are loaded by flattening the parent rows at each path, then emitted as locator-based attachment batches:
+
+```ts
+const params = encodeQueryParams({
+  take: 20,
+  include: {
+    companies: {
+      include: {
+        users: {
+          include: {
+            profile: {
+              select: {
+                id: true,
+                displayName: true,
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+})
+
+const response = await fetch(`/organization/paginated?${params}`, {
+  headers: {
+    Accept: 'text/event-stream',
+    'x-api-variant': 'list',
+  },
+})
+```
+
+Example deep event sequence:
+
+```json
+{ "type": "pageMeta", "total": 120, "hasMore": true }
+```
+
+```json
+{ "type": "rootArray", "data": [{ "id": "org-1" }, { "id": "org-2" }] }
+```
+
+```json
+{ "type": "relationBatch", "relationPath": "companies", "values": [[{ "id": "company-1" }], []] }
+```
+
+```json
+{
+  "type": "nestedRelationBatch",
+  "relationPath": "companies.users",
+  "depth": 2,
+  "attachments": [
+    { "locator": [0, "companies", 0], "value": [{ "id": "user-1" }] }
+  ]
+}
+```
+
+```json
+{
+  "type": "nestedRelationBatch",
+  "relationPath": "companies.users.profile",
+  "depth": 3,
+  "attachments": [
+    { "locator": [0, "companies", 0, "users", 0], "value": { "id": "profile-1", "displayName": "Alice" } }
+  ]
+}
+```
+
+```json
+{ "type": "result", "data": { "data": [{ "id": "org-1", "companies": [{ "id": "company-1", "users": [{ "id": "user-1", "profile": { "id": "profile-1", "displayName": "Alice" } }] }] }, { "id": "org-2", "companies": [] }], "total": 120, "hasMore": true } }
+```
+
+
 ### Auto-include behavior and limits
 
 Auto-include is designed for supported Prisma `include` and relation `select` trees on reads.
@@ -1988,22 +2078,28 @@ Supported root operations:
 - `findFirst`
 - `findFirstOrThrow`
 - `findMany`
+- `findManyPaginated`
 
 Supported single-record relation shapes:
 
 - direct to-one relation includes/selects
 - direct to-many relation includes/selects
 - to-many relation args such as `where`, `orderBy`, `take`, `skip`, `cursor`, and `distinct`
-- nested to-one relation loading through to-one parents
+- nested relation loading through to-one parents
+
+Single-record auto-include falls back when a nested stage crosses a to-many parent. Direct to-many loading is still supported, but nested loading under that array is not handled by the single-record progressive runtime.
 
-Supported `findMany` relation shapes:
+Supported `findMany` and `findManyPaginated` relation shapes:
 
-- direct root to-one relation includes/selects
-- direct root to-many relation includes/selects
+- direct and nested to-one relation includes/selects
+- direct and nested to-many relation includes/selects
 - relation-level `where` and `orderBy`
 - single-column link fields only
+- nested depth up to the configured planner limit
 
-`findMany` auto-include applies configured pagination limits to the root query before loading relation batches. If the client omits `take`, `pagination.defaultLimit` is applied when configured. If the client sends a large `take`, `pagination.maxLimit` is enforced before the root query runs.
+For `findMany` and `findManyPaginated`, each stage loads children with a batched query over the flattened parent rows at that stage's `parentPath`. Direct root stages stream `relationBatch` events. Depth-2-or-deeper stages stream `nestedRelationBatch` events with locator/value attachments, then also appear in the terminal `result` event.
+
+`findMany` and `findManyPaginated` auto-include apply configured pagination limits to the root query before loading relation batches. If the client omits `take`, `pagination.defaultLimit` is applied when configured. If the client sends a large `take`, `pagination.maxLimit` is enforced before the root query runs.
 
 Current MVP fallback cases include:
 
@@ -2013,13 +2109,12 @@ Current MVP fallback cases include:
 - `select` and `omit` at the same level
 - relation filters/order/cursor in the root query
 - relation filters/order/cursor inside staged relation queries when unsupported
-- nested relation loading through a to-many parent
 - omitted required link fields needed to stitch parent and child records
 - planner limits for maximum depth or stage count
-- `findMany` relation stages with composite link fields
-- `findMany` nested relation stages deeper than direct root relations
-- `findMany` to-many relation stages using `take`, `skip`, `cursor`, or `distinct`
-- `findManyPaginated`, `createManyAndReturn`, and `updateManyAndReturn`
+- single-record nested relation loading through a to-many parent
+- `findMany` / `findManyPaginated` relation stages with composite link fields
+- `findMany` / `findManyPaginated` to-many relation stages using `take`, `skip`, `cursor`, or `distinct`
+- `createManyAndReturn` and `updateManyAndReturn`
 
 When fallback happens:
 
@@ -2028,7 +2123,7 @@ When fallback happens:
 
 If `fallback` is omitted, the default behavior is equivalent to `'singleResult'`.
 
-`findMany` auto-include uses a batched relation loading strategy. It does not preserve Prisma's per-parent semantics for to-many `take`, `skip`, `cursor`, or `distinct`, so those cases fall back instead of returning silently different data.
+`findMany` and `findManyPaginated` auto-include use a batched relation loading strategy. They do not preserve Prisma's per-parent semantics for to-many `take`, `skip`, `cursor`, or `distinct`, so those cases fall back instead of returning silently different data.
 
 Auto-include does not require `resolveContext` or `progressiveStages`.
 
@@ -2071,6 +2166,20 @@ let rows: Array<Record<string, unknown>> = []
 let fields: Record<string, unknown> = {}
 let data: unknown = undefined
 
+const lastSegment = (path: string) => {
+  const parts = path.split('.')
+  return parts[parts.length - 1] ?? path
+}
+
+const walk = (source: Array<Record<string, unknown>>, locator: Array<number | string>) => {
+  let cursor: unknown = source[locator[0] as number]
+  for (let i = 1; i < locator.length; i++) {
+    if (cursor == null) return null
+    cursor = (cursor as Record<string | number, unknown>)[locator[i]]
+  }
+  return cursor
+}
+
 while (true) {
   const { value, done } = await reader.read()
   if (done) break
@@ -2097,12 +2206,24 @@ while (true) {
     }
 
     if (event.type === 'relationBatch') {
+      const field = lastSegment(event.relationPath)
       rows = rows.map((row, index) => ({
         ...row,
-        [event.relationPath]: event.values[index],
+        [field]: event.values[index],
       }))
     }
 
+    if (event.type === 'nestedRelationBatch') {
+      const field = lastSegment(event.relationPath)
+      for (const attachment of event.attachments) {
+        const parent = walk(rows, attachment.locator)
+        if (parent && typeof parent === 'object' && !Array.isArray(parent)) {
+          const record = parent as Record<string, unknown>
+          record[field] = attachment.value
+        }
+      }
+    }
+
     if (event.type === 'result') {
       data = event.data
     }
@@ -2118,6 +2239,8 @@ For React Query, include the variant and mode in the query key:
 
 Do not reuse the same query key as the JSON endpoint because the same URL can return different shapes depending on `x-api-variant`.
 
+For deep `findMany` / `findManyPaginated` auto-include, apply `nestedRelationBatch` events for progressive rendering and still treat the final `result` event as the authoritative nested payload for reconciliation. Direct root relation stages emit `relationBatch`; depth-2-or-deeper relation stages emit `nestedRelationBatch`.
+
 ### Runtime notes
 
 The SSE response sets:

package/dist/generators/generateRouter.js

@@ -237,7 +237,7 @@ export function ${routerFunctionName}<TCtx = unknown, TPrisma = any>(config: ${m
           const isAutoIncludeReadable =
             baseOp === 'findUnique' || baseOp === 'findUniqueOrThrow' ||
             baseOp === 'findFirst' || baseOp === 'findFirstOrThrow' ||
-            baseOp === 'findMany'
+            baseOp === 'findMany' || baseOp === 'findManyPaginated'
 
           if (!isAutoIncludeReadable) {
             if (progressiveConfig.fallback === 'error') {
@@ -263,7 +263,7 @@ export function ${routerFunctionName}<TCtx = unknown, TPrisma = any>(config: ${m
               res,
               ctx,
               args,
-              baseOp: baseOp as 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany',
+              baseOp: baseOp as 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'findManyPaginated',
               modelName: '${modelName}',
               delegateKey: '${delegateKey}',
               models: relationModels,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "prisma-generator-express",
   "description": "Prisma generator for Express, Fastify, and Hono CRUD APIs with OpenAPI documentation",
-  "version": "1.52.0",
+  "version": "1.54.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",

package/src/copy/autoIncludePlanner.ts

@@ -269,15 +269,9 @@ function walk(
       isPlainObject(relationArgs.omit)
 
     if (hasNestedProjection) {
-      const stagesBeforeRecursion = ctx.stages.length
-
       const nested = walk(ctx, relation.type, relationPath, relationArgs, depth + 1)
       if (nested.unsupportedReason) return nested
 
-      if (relation.isList && ctx.stages.length > stagesBeforeRecursion) {
-        return { unsupportedReason: 'nested relation through to-many parent not supported in MVP' }
-      }
-
       if (nested.projectionAfterStrip) {
         ctx.stages[stageIndex].stageArgs.select = nested.projectionAfterStrip
       }

package/src/copy/autoIncludeRuntime.ts

@@ -9,12 +9,15 @@ import {
   sendSSEProgress,
   sendSSERootArray,
   sendSSERelationBatch,
+  sendSSENestedRelationBatch,
+  sendSSEPageMeta,
   runSingleResultSSE,
   emitTerminalSSEError,
   setByPath,
   getDelegate,
   getExtendedClient,
   applyPaginationLimits,
+  countForPagination,
   mapError,
   type OperationContext,
   type PrismaDelegate,
@@ -39,6 +42,7 @@ export type AutoIncludeBaseOp =
   | 'findFirst'
   | 'findFirstOrThrow'
   | 'findMany'
+  | 'findManyPaginated'
 
 export type RunAutoIncludeOptions = {
   req: Request
@@ -54,6 +58,15 @@ export type RunAutoIncludeOptions = {
   signal?: AbortSignal
 }
 
+type RowPair = {
+  internal: Record<string, unknown>
+  public: Record<string, unknown>
+}
+
+type ParentEntry = RowPair & {
+  locator: Array<number | string>
+}
+
 function readPath(source: Record<string, unknown>, path: string): unknown {
   if (path === '') return source
   const parts = path.split('.')
@@ -196,9 +209,6 @@ function findManyUnsupportedReason(plan: AutoIncludePlan): string | null {
     if (rel.parentLinkFields.length !== 1 || rel.childLinkFields.length !== 1) {
       return 'auto-progressive fallback: composite link fields not supported for findMany batched auto-include'
     }
-    if (stage.depth > 1) {
-      return 'auto-progressive fallback: nested relations not supported for findMany batched auto-include'
-    }
     if (rel.isList) {
       const sa = stage.stageArgs
       if (
@@ -214,6 +224,67 @@ function findManyUnsupportedReason(plan: AutoIncludePlan): string | null {
   return null
 }
 
+function singleUnsupportedReason(plan: AutoIncludePlan): string | null {
+  const stagesByPath = new Map(plan.stages.map((s) => [s.relationPath, s]))
+  for (const stage of plan.stages) {
+    let parentPath = stage.parentPath
+    while (parentPath) {
+      const parentStage = stagesByPath.get(parentPath)
+      if (parentStage?.relationField.isList) {
+        return 'auto-progressive fallback: nested relation through to-many parent is not supported for single-result auto-include'
+      }
+      const dot = parentPath.lastIndexOf('.')
+      parentPath = dot === -1 ? '' : parentPath.slice(0, dot)
+    }
+  }
+  return null
+}
+
+function collectParentEntries(
+  rootPairs: RowPair[],
+  parentPath: string,
+): ParentEntry[] {
+  const initial: ParentEntry[] = rootPairs.map((p, i) => ({
+    internal: p.internal,
+    public: p.public,
+    locator: [i],
+  }))
+  if (parentPath === '') return initial
+
+  let entries = initial
+  for (const segment of parentPath.split('.')) {
+    const next: ParentEntry[] = []
+    for (const entry of entries) {
+      const internalValue = entry.internal[segment]
+      const publicValue = entry.public[segment]
+      if (Array.isArray(internalValue) && Array.isArray(publicValue)) {
+        const length = Math.min(internalValue.length, publicValue.length)
+        for (let i = 0; i < length; i++) {
+          const internalItem = internalValue[i]
+          const publicItem = publicValue[i]
+          if (isPlainObject(internalItem) && isPlainObject(publicItem)) {
+            next.push({
+              internal: internalItem,
+              public: publicItem,
+              locator: [...entry.locator, segment, i],
+            })
+          }
+        }
+        continue
+      }
+      if (isPlainObject(internalValue) && isPlainObject(publicValue)) {
+        next.push({
+          internal: internalValue,
+          public: publicValue,
+          locator: [...entry.locator, segment],
+        })
+      }
+    }
+    entries = next
+  }
+  return entries
+}
+
 async function runOneStageSingle(options: {
   extended: unknown
   models: Record<string, ModelRelationMap>
@@ -300,7 +371,7 @@ async function runAutoIncludeSingle(
 
     let rootResult: unknown
     try {
-      rootResult = await rootDelegate[baseOp as Exclude<AutoIncludeBaseOp, 'findMany'>](plan.rootArgs)
+      rootResult = await rootDelegate[baseOp as Exclude<AutoIncludeBaseOp, 'findMany' | 'findManyPaginated'>](plan.rootArgs)
     } catch (err) {
       if (isClientGone()) return
       console.error('[auto-progressive] root query failed:', err)
@@ -470,16 +541,12 @@ async function runOneStageMany(options: {
   extended: unknown
   models: Record<string, ModelRelationMap>
   stage: AutoIncludeStage
-  internalRows: Record<string, unknown>[]
-  publicRows: Record<string, unknown>[]
+  parentEntries: ParentEntry[]
   internalFieldPaths: string[]
   res: Response
   isAborted: () => boolean
 }): Promise<void> {
-  const {
-    extended, models, stage, internalRows, publicRows,
-    internalFieldPaths, res, isAborted,
-  } = options
+  const { extended, models, stage, parentEntries, internalFieldPaths, res, isAborted } = options
 
   if (isAborted()) return
 
@@ -492,7 +559,17 @@ async function runOneStageMany(options: {
     throw new Error('Target model not in relation metadata: ' + rel.type)
   }
 
-  const distinctValues = collectDistinctParentValues(internalRows, parentKey)
+  if (parentEntries.length === 0) {
+    if (stage.depth === 1) {
+      sendSSERelationBatch(res, stage.relationPath, [])
+    } else {
+      sendSSENestedRelationBatch(res, stage.relationPath, stage.depth, [])
+    }
+    return
+  }
+
+  const internalParents = parentEntries.map((p) => p.internal)
+  const distinctValues = collectDistinctParentValues(internalParents, parentKey)
   const delegate: PrismaDelegate = getDelegate(extended, targetModel.delegateKey)
 
   const children: unknown[] = []
@@ -515,11 +592,11 @@ async function runOneStageMany(options: {
     : internalFieldPaths
 
   const grouped = groupRelatedRows(children, childKey)
-  const publicValues: unknown[] = new Array(internalRows.length)
+  const publicValues: unknown[] = new Array(parentEntries.length)
 
-  for (let i = 0; i < internalRows.length; i++) {
-    const row = internalRows[i]
-    const fkVal = row[parentKey]
+  for (let i = 0; i < parentEntries.length; i++) {
+    const entry = parentEntries[i]
+    const fkVal = entry.internal[parentKey]
     let internalVal: unknown
 
     if (fkVal === undefined || fkVal === null) {
@@ -535,13 +612,131 @@ async function runOneStageMany(options: {
 
     const publicVal = buildPublicForStage(internalVal, effectivePaths, stage.relationPath)
 
-    internalRows[i][stage.relationName] = internalVal
-    publicRows[i][stage.relationName] = publicVal
+    entry.internal[stage.relationName] = internalVal
+    entry.public[stage.relationName] = publicVal
     publicValues[i] = publicVal
   }
 
   if (isAborted()) return
-  sendSSERelationBatch(res, stage.relationPath, publicValues)
+
+  if (stage.depth === 1) {
+    sendSSERelationBatch(res, stage.relationPath, publicValues)
+    return
+  }
+
+  const attachments = parentEntries.map((entry, i) => ({
+    locator: entry.locator,
+    value: publicValues[i],
+  }))
+  sendSSENestedRelationBatch(res, stage.relationPath, stage.depth, attachments)
+}
+
+function buildRootPairs(
+  rootRows: unknown[],
+  internalFieldPaths: string[],
+): { publicRows: Record<string, unknown>[]; rootPairs: RowPair[] } {
+  const n = rootRows.length
+  const publicRows: Record<string, unknown>[] = new Array(n)
+  const rootPairs: RowPair[] = new Array(n)
+  for (let i = 0; i < n; i++) {
+    const row = rootRows[i]
+    if (!isPlainObject(row)) {
+      const internalEmpty: Record<string, unknown> = {}
+      const publicEmpty: Record<string, unknown> = {}
+      publicRows[i] = publicEmpty
+      rootPairs[i] = { internal: internalEmpty, public: publicEmpty }
+      continue
+    }
+    const internalCopy: Record<string, unknown> = { ...row }
+    const publicCopy: Record<string, unknown> = { ...row }
+    stripInternalAtScope(publicCopy, internalFieldPaths, '')
+    publicRows[i] = publicCopy
+    rootPairs[i] = { internal: internalCopy, public: publicCopy }
+  }
+  return { publicRows, rootPairs }
+}
+
+async function processFindManyStages(args: {
+  extended: unknown
+  models: Record<string, ModelRelationMap>
+  plan: AutoIncludePlan
+  rootPairs: RowPair[]
+  res: Response
+  signal?: AbortSignal
+}): Promise<string | null> {
+  const { extended, models, plan, rootPairs, res, signal } = args
+  const groups = groupStagesByDepth(plan.stages)
+  let completed = 0
+  let stageErrorMessage: string | null = null
+  const isAborted = () =>
+    stageErrorMessage !== null ||
+    signal?.aborted === true ||
+    res.writableEnded ||
+    res.destroyed
+
+  for (const group of groups) {
+    if (signal?.aborted === true || res.writableEnded || res.destroyed) return stageErrorMessage
+    if (stageErrorMessage) break
+
+    await runConcurrent(group, STAGE_CONCURRENCY, async (stage) => {
+      if (isAborted()) return
+      const parentEntries = collectParentEntries(rootPairs, stage.parentPath)
+      try {
+        await runOneStageMany({
+          extended,
+          models,
+          stage,
+          parentEntries,
+          internalFieldPaths: plan.internalFieldPaths,
+          res,
+          isAborted,
+        })
+      } catch (err) {
+        if (isAborted()) return
+        console.error('[auto-progressive] stage failed:', stage.relationPath, err)
+        stageErrorMessage = mapError(err).message
+        return
+      }
+      if (isAborted()) return
+      completed++
+      sendSSEProgress(res, stage.relationPath, completed, plan.stages.length)
+    })
+  }
+  return stageErrorMessage
+}
+
+async function runPaginatedRoot(
+  extended: unknown,
+  rootDelegate: PrismaDelegate,
+  delegateKey: string,
+  rootArgs: Record<string, unknown>,
+  distinctCountLimit: number | undefined,
+): Promise<{ data: unknown[]; count: number }> {
+  const txClient = extended as {
+    $transaction?: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>
+  }
+
+  if (typeof txClient.$transaction === 'function') {
+    try {
+      const result = await txClient.$transaction(async (tx: unknown) => {
+        const txDelegate = getDelegate(tx, delegateKey)
+        const d = await txDelegate.findMany(rootArgs)
+        const t = await countForPagination(txDelegate, rootArgs, undefined, undefined, distinctCountLimit)
+        return { d, t }
+      })
+      return { data: result.d as unknown[], count: result.t }
+    } catch (err) {
+      const e = err as { code?: string }
+      if (e?.code !== 'P2028') throw err
+      console.warn('[auto-progressive] Interactive transactions not available, paginated queries are non-atomic')
+    }
+  }
+
+  const [data, count] = await Promise.all([
+    rootDelegate.findMany(rootArgs),
+    countForPagination(rootDelegate, rootArgs, undefined, undefined, distinctCountLimit),
+  ])
+  return { data: data as unknown[], count }
 }
 
 async function runAutoIncludeMany(
@@ -582,78 +777,105 @@ async function runAutoIncludeMany(
       return
     }
 
-    const internalRows: Record<string, unknown>[] = new Array(rootResult.length)
-    const publicRows: Record<string, unknown>[] = new Array(rootResult.length)
+    const { publicRows, rootPairs } = buildRootPairs(rootResult, plan.internalFieldPaths)
 
-    for (let i = 0; i < rootResult.length; i++) {
-      const row = rootResult[i]
-      if (!isPlainObject(row)) {
-        internalRows[i] = {}
-        publicRows[i] = {}
-        continue
+    sendSSERootArray(res, publicRows)
+    sendSSEProgress(res, 'root', 0, plan.stages.length)
+
+    const stageError = await processFindManyStages({
+      extended, models, plan, rootPairs, res, signal,
+    })
+
+    if (isClientGone()) return
+
+    if (stageError) {
+      if (!res.writableEnded && !res.destroyed) {
+        sendSSEError(res, stageError)
       }
-      const internalCopy: Record<string, unknown> = { ...row }
-      const publicCopy: Record<string, unknown> = { ...row }
-      stripInternalAtScope(publicCopy, plan.internalFieldPaths, '')
-      internalRows[i] = internalCopy
-      publicRows[i] = publicCopy
+      return
     }
 
-    sendSSERootArray(res, publicRows)
-    sendSSEProgress(res, 'root', 0, plan.stages.length)
+    if (res.writableEnded || res.destroyed) return
+    sendSSEResult(res, publicRows)
+  } catch (err) {
+    if (isClientGone()) return
+    console.error('[auto-progressive] many dispatch error:', err)
+    if (!res.writableEnded && !res.destroyed) {
+      sendSSEError(res, mapError(err).message)
+    }
+  } finally {
+    endSSE(res, keepalive)
+  }
+}
 
-    const groups = groupStagesByDepth(plan.stages)
-    let completed = 0
-    let stageErrorMessage: string | null = null
-    const isAborted = () =>
-      stageErrorMessage !== null ||
-      signal?.aborted === true ||
-      res.writableEnded ||
-      res.destroyed
+async function runAutoIncludePaginated(
+  options: RunAutoIncludeOptions,
+  plan: AutoIncludePlan,
+): Promise<void> {
+  const { res, ctx, delegateKey, models, signal } = options
 
-    for (const group of groups) {
-      if (isClientGone()) return
-      if (stageErrorMessage) break
+  const isClientGone = () =>
+    signal?.aborted === true || res.writableEnded || res.destroyed
 
-      await runConcurrent(group, STAGE_CONCURRENCY, async (stage) => {
-        if (isAborted()) return
-        try {
-          await runOneStageMany({
-            extended,
-            models,
-            stage,
-            internalRows,
-            publicRows,
-            internalFieldPaths: plan.internalFieldPaths,
-            res,
-            isAborted,
-          })
-        } catch (err) {
-          if (isAborted()) return
-          console.error('[auto-progressive] stage failed:', stage.relationPath, err)
-          stageErrorMessage = mapError(err).message
-          return
-        }
-        if (isAborted()) return
-        completed++
-        sendSSEProgress(res, stage.relationPath, completed, plan.stages.length)
-      })
+  let keepalive: IntervalHandle | null = null
+  try {
+    initSSE(res)
+    keepalive = startSSEKeepalive(res)
+    if (isClientGone()) return
+
+    const extended = await getExtendedClient(ctx)
+    if (isClientGone()) return
+
+    const rootDelegate = getDelegate(extended, delegateKey)
+    const rootArgs = applyPaginationLimits(plan.rootArgs, ctx.paginationConfig)
+    const distinctCountLimit = ctx.paginationConfig?.distinctCountLimit
+
+    let rootRows: unknown[]
+    let total: number
+    try {
+      const { data, count } = await runPaginatedRoot(
+        extended, rootDelegate, delegateKey, rootArgs, distinctCountLimit,
+      )
+      rootRows = data
+      total = count
+    } catch (err) {
+      if (isClientGone()) return
+      console.error('[auto-progressive] root findManyPaginated failed:', err)
+      sendSSEError(res, mapError(err).message)
+      return
     }
 
     if (isClientGone()) return
 
-    if (stageErrorMessage) {
+    const skip = typeof rootArgs.skip === 'number' ? rootArgs.skip : 0
+    const takeRaw = typeof rootArgs.take === 'number' ? rootArgs.take : rootRows.length
+    const absTake = Math.abs(takeRaw)
+    const hasMore = rootRows.length >= absTake && skip + rootRows.length < total
+
+    const { publicRows, rootPairs } = buildRootPairs(rootRows, plan.internalFieldPaths)
+
+    sendSSEPageMeta(res, total, hasMore)
+    sendSSERootArray(res, publicRows)
+    sendSSEProgress(res, 'root', 0, plan.stages.length)
+
+    const stageError = await processFindManyStages({
+      extended, models, plan, rootPairs, res, signal,
+    })
+
+    if (isClientGone()) return
+
+    if (stageError) {
       if (!res.writableEnded && !res.destroyed) {
-        sendSSEError(res, stageErrorMessage)
+        sendSSEError(res, stageError)
       }
       return
     }
 
     if (res.writableEnded || res.destroyed) return
-    sendSSEResult(res, publicRows)
+    sendSSEResult(res, { data: publicRows, total, hasMore })
   } catch (err) {
     if (isClientGone()) return
-    console.error('[auto-progressive] many dispatch error:', err)
+    console.error('[auto-progressive] paginated dispatch error:', err)
     if (!res.writableEnded && !res.destroyed) {
       sendSSEError(res, mapError(err).message)
     }
@@ -682,9 +904,12 @@ export async function runAutoIncludeProgressive(
     return handleAutoIncludeFallback(options, plan.unsupportedReason)
   }
 
-  if (options.baseOp === 'findMany') {
+  if (options.baseOp === 'findMany' || options.baseOp === 'findManyPaginated') {
     const reason = findManyUnsupportedReason(plan)
     if (reason) return handleAutoIncludeFallback(options, reason)
+  } else {
+    const reason = singleUnsupportedReason(plan)
+    if (reason) return handleAutoIncludeFallback(options, reason)
   }
 
   if (plan.stages.length === 0) {
@@ -698,5 +923,8 @@ export async function runAutoIncludeProgressive(
   if (options.baseOp === 'findMany') {
     return runAutoIncludeMany(options, plan)
   }
+  if (options.baseOp === 'findManyPaginated') {
+    return runAutoIncludePaginated(options, plan)
+  }
   return runAutoIncludeSingle(options, plan)
 }

package/src/copy/operationRuntime.ts

@@ -503,6 +503,23 @@ export function sendSSERelationBatch(
   return sendSSE(res, { type: 'relationBatch', relationPath, values })
 }
 
+export function sendSSENestedRelationBatch(
+  res: SseWritable,
+  relationPath: string,
+  depth: number,
+  attachments: Array<{ locator: Array<number | string>; value: unknown }>,
+): boolean {
+  return sendSSE(res, { type: 'nestedRelationBatch', relationPath, depth, attachments })
+}
+
+export function sendSSEPageMeta(
+  res: SseWritable,
+  total: number,
+  hasMore: boolean,
+): boolean {
+  return sendSSE(res, { type: 'pageMeta', total, hasMore })
+}
+
 export function sendSSEError(res: SseWritable, message: string): boolean {
   if (res.writableEnded || res.destroyed) return false
   try {

package/src/generators/generateRouter.ts

@@ -253,7 +253,7 @@ export function ${routerFunctionName}<TCtx = unknown, TPrisma = any>(config: ${m
           const isAutoIncludeReadable =
             baseOp === 'findUnique' || baseOp === 'findUniqueOrThrow' ||
             baseOp === 'findFirst' || baseOp === 'findFirstOrThrow' ||
-            baseOp === 'findMany'
+            baseOp === 'findMany' || baseOp === 'findManyPaginated'
 
           if (!isAutoIncludeReadable) {
             if (progressiveConfig.fallback === 'error') {
@@ -279,7 +279,7 @@ export function ${routerFunctionName}<TCtx = unknown, TPrisma = any>(config: ${m
               res,
               ctx,
               args,
-              baseOp: baseOp as 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany',
+              baseOp: baseOp as 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'findManyPaginated',
               modelName: '${modelName}',
               delegateKey: '${delegateKey}',
               models: relationModels,