prisma-generator-express 1.54.0 → 1.56.0

package/src/copy/docsRenderer.ts

@@ -1,4 +1,4 @@
-import type { RouteConfig } from './routeConfig'
+import type { RouteConfig, WriteStrategy } from './routeConfig'
 import { OPERATION_DEFS, isOperationEnabled, READ_OPERATION_NAMES } from './operationDefinitions'
 import { getEnv, normalizePrefix } from './misc'
 
@@ -256,6 +256,41 @@ const OP_DETAIL_MAP: Record<string, OpDetail> = {
   },
 }
 
+function detailForOp(opName: string, writeStrategy?: WriteStrategy): OpDetail {
+  const base = OP_DETAIL_MAP[opName]
+  if (!base) return base
+  if (writeStrategy === 'forceReturn') {
+    if (opName === 'createMany') {
+      return {
+        ...base,
+        optional: ['skipDuplicates', 'select', 'include', 'omit'],
+        responseDesc: 'Array of created records (201)',
+        supportsSelect: true,
+        supportsInclude: true,
+        supportsOmit: true,
+        notes: 'writeStrategy="forceReturn": silently invokes createManyAndReturn and returns the created records instead of { count }.',
+      }
+    }
+    if (opName === 'updateMany') {
+      return {
+        ...base,
+        optional: ['select', 'include', 'omit'],
+        responseDesc: 'Array of updated records',
+        supportsSelect: true,
+        supportsInclude: true,
+        supportsOmit: true,
+        notes: 'writeStrategy="forceReturn": silently invokes updateManyAndReturn and returns the updated records instead of { count }.',
+      }
+    }
+  }
+  return base
+}
+
+function isOpHiddenByStrategy(opName: string, writeStrategy?: WriteStrategy): boolean {
+  if (writeStrategy !== 'throwOnNonReturning') return false
+  return opName === 'createMany' || opName === 'updateMany'
+}
+
 function exampleValue(ctx: DocsModelContext, fieldName: string): unknown {
   return ctx.exampleValues[fieldName] ?? 'example'
 }
@@ -409,46 +444,17 @@ function isEnumField(f: FieldMeta): boolean {
 function scalarFilterOperators(scalarType: string): string[] {
   if (scalarType === 'String') {
     return [
-      'equals',
-      'in',
-      'notIn',
-      'lt',
-      'lte',
-      'gt',
-      'gte',
-      'contains',
-      'startsWith',
-      'endsWith',
-      'mode',
-      'not',
+      'equals', 'in', 'notIn', 'lt', 'lte', 'gt', 'gte',
+      'contains', 'startsWith', 'endsWith', 'mode', 'not',
     ]
   }
-
-  if (
-    scalarType === 'Int' ||
-    scalarType === 'BigInt' ||
-    scalarType === 'Float' ||
-    scalarType === 'Decimal'
-  ) {
+  if (scalarType === 'Int' || scalarType === 'BigInt' || scalarType === 'Float' || scalarType === 'Decimal') {
     return ['equals', 'in', 'notIn', 'lt', 'lte', 'gt', 'gte', 'not']
   }
-
-  if (scalarType === 'DateTime') {
-    return ['equals', 'in', 'notIn', 'lt', 'lte', 'gt', 'gte', 'not']
-  }
-
-  if (scalarType === 'Boolean') {
-    return ['equals', 'not']
-  }
-
-  if (scalarType === 'Json') {
-    return ['equals', 'path', 'string_contains', 'array_contains', 'not']
-  }
-
-  if (scalarType === 'Bytes') {
-    return ['equals', 'in', 'notIn', 'not']
-  }
-
+  if (scalarType === 'DateTime') return ['equals', 'in', 'notIn', 'lt', 'lte', 'gt', 'gte', 'not']
+  if (scalarType === 'Boolean') return ['equals', 'not']
+  if (scalarType === 'Json') return ['equals', 'path', 'string_contains', 'array_contains', 'not']
+  if (scalarType === 'Bytes') return ['equals', 'in', 'notIn', 'not']
   return ['equals', 'in', 'notIn', 'not']
 }
 
@@ -465,27 +471,11 @@ function whereFieldKind(f: FieldMeta): string {
 
 function whereFieldShape(f: FieldMeta): string {
   const kind = whereFieldKind(f)
-
-  if (kind === 'relation-list') {
-    return '{ some?: RelatedWhere, every?: RelatedWhere, none?: RelatedWhere }'
-  }
-
-  if (kind === 'relation-single') {
-    return '{ is?: RelatedWhere, isNot?: RelatedWhere }'
-  }
-
-  if (kind === 'scalar-list') {
-    return '{ has?, hasEvery?, hasSome?, isEmpty? }'
-  }
-
-  if (kind === 'scalar') {
-    return 'scalar value OR filter object'
-  }
-
-  if (kind === 'enum') {
-    return 'enum value OR enum filter'
-  }
-
+  if (kind === 'relation-list') return '{ some?: RelatedWhere, every?: RelatedWhere, none?: RelatedWhere }'
+  if (kind === 'relation-single') return '{ is?: RelatedWhere, isNot?: RelatedWhere }'
+  if (kind === 'scalar-list') return '{ has?, hasEvery?, hasSome?, isEmpty? }'
+  if (kind === 'scalar') return 'scalar value OR filter object'
+  if (kind === 'enum') return 'enum value OR enum filter'
   return 'n/a'
 }
 
@@ -540,7 +530,12 @@ function buildFullPath(basePath: string, suffix: string): string {
   return basePath ? basePath + suffix : suffix
 }
 
-export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModelContext): string {
+export function renderDocs(
+  modelName: string,
+  config: DocsConfig,
+  ctx: DocsModelContext,
+  writeStrategy?: WriteStrategy,
+): string {
   const title = config.docsTitle || modelName + ' API'
   const generatedAt = new Date().toISOString()
 
@@ -559,8 +554,9 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
 
   const getOps = OPERATION_DEFS
     .filter((d) => isOperationEnabled(config as Record<string, any>, d))
+    .filter((d) => !isOpHiddenByStrategy(d.name, writeStrategy))
     .map((d) => {
-      const detail = OP_DETAIL_MAP[d.name]
+      const detail = detailForOp(d.name, writeStrategy)
       return {
         op: d.name,
         method: d.method.toUpperCase(),
@@ -627,12 +623,8 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
   if (firstStringField) {
     andClauses.push({ [firstStringField.name]: { contains: 'example', mode: 'insensitive' } })
   }
-  if (andClauses.length > 0) {
-    whereExample.AND = andClauses
-  }
-  if (firstBooleanField) {
-    whereExample.OR = [{ [firstBooleanField.name]: { equals: true } }]
-  }
+  if (andClauses.length > 0) whereExample.AND = andClauses
+  if (firstBooleanField) whereExample.OR = [{ [firstBooleanField.name]: { equals: true } }]
 
   const selectExample: any = {}
   for (const f of scalarFields.slice(0, 10)) selectExample[f.name] = true
@@ -644,9 +636,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
   const omitCandidates = scalarFields.filter((f) => !f.isId && !f.isUnique)
   for (const f of omitCandidates.slice(0, 3)) omitExample[f.name] = true
 
-  const orderByField = firstUnique
-    ? firstUnique.name
-    : firstFilterFieldName
+  const orderByField = firstUnique ? firstUnique.name : firstFilterFieldName
 
   const findManyQueryArgs: any = {
     where: whereExample,
@@ -698,9 +688,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     : null
   if (updateBodyExample) {
     const firstEditableString = scalarFields.find((sf) => sf.type === 'String' && !sf.isId)
-    if (firstEditableString) {
-      updateBodyExample.data[firstEditableString.name] = 'updated'
-    }
+    if (firstEditableString) updateBodyExample.data[firstEditableString.name] = 'updated'
   }
 
   const updateFetchExample = updateBodyExample
@@ -746,11 +734,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     } else {
       writeContract = 'Optional (nullable)'
     }
-    return {
-      name: f.name,
-      type: describeFieldType(f),
-      writeContract,
-    }
+    return { name: f.name, type: describeFieldType(f), writeContract }
   })
 
   const argsReferenceRead = {
@@ -817,7 +801,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     },
   }
 
-  const argsReferenceWrite = {
+  const argsReferenceWriteBase: Record<string, Record<string, string>> = {
     create: {
       data: modelName + 'CreateInput (required)',
       select: 'Select',
@@ -867,19 +851,51 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
       include: 'Include',
       omit: 'Omit',
     },
-    deleteMany: {
-      where: 'WhereInput (required)',
-    },
+    deleteMany: { where: 'WhereInput (required)' },
   }
 
+  const argsReferenceWrite: Record<string, Record<string, string>> = (() => {
+    if (writeStrategy === 'throwOnNonReturning') {
+      const { createMany, updateMany, ...rest } = argsReferenceWriteBase
+      return rest
+    }
+    if (writeStrategy === 'forceReturn') {
+      return {
+        ...argsReferenceWriteBase,
+        createMany: {
+          data: modelName + 'CreateManyInput[] (required, scalar-only)',
+          skipDuplicates: 'boolean',
+          select: 'Select',
+          include: 'Include',
+          omit: 'Omit',
+        },
+        updateMany: {
+          where: 'WhereInput (required)',
+          data: modelName + 'UpdateManyMutationInput (required, scalar-only)',
+          select: 'Select',
+          include: 'Include',
+          omit: 'Omit',
+        },
+      }
+    }
+    return argsReferenceWriteBase
+  })()
+
+  const batchMutationNote =
+    writeStrategy === 'forceReturn'
+      ? 'Batch mutations: deleteMany returns { count }. createMany and updateMany silently invoke their returning counterparts and return arrays of records. Batch data inputs are scalar-only — nested relation writes are not supported.'
+      : writeStrategy === 'throwOnNonReturning'
+        ? 'Batch mutations: deleteMany returns { count }. createMany and updateMany are disabled and return 501 if called directly; use the /many/return variants. Batch data inputs are scalar-only — nested relation writes are not supported.'
+        : 'Batch mutations (createMany, updateMany, deleteMany) return { count }. Batch data inputs are scalar-only — nested relation writes are not supported.'
+
   const transportNotes = [
     'GET endpoints: Prisma args as JSON-encoded query parameter strings via encodeQueryParams.',
     'POST/PUT/DELETE/PATCH endpoints: Prisma args as JSON request body. Body must be a JSON object.',
     'POST read endpoints: All read operations also accept POST with the same args as JSON body instead of query params. Use when query parameters exceed URL length limits. findMany uses POST /read, all others use the same path as GET.',
     'findManyPaginated returns { data, total, hasMore }. hasMore is reliable for forward offset pagination only.',
-    'Batch mutations (createMany, updateMany, deleteMany) return { count }. Batch data inputs are scalar-only — nested relation writes are not supported.',
+    batchMutationNote,
     'findUnique and findFirst return null (not 404) when no record matches. Use the OrThrow variants for 404 behavior.',
-    'createManyAndReturn requires Prisma 5.14.0+, updateManyAndReturn requires Prisma 6.2.0+. Both are limited to PostgreSQL, CockroachDB, and SQLite.',
+    'createManyAndReturn requires Prisma 5.14.0+, updateManyAndReturn requires Prisma 6.2.0+. Both are limited to PostgreSQL/CockroachDB/SQLite.',
   ]
 
   const errorRows = [
@@ -887,8 +903,8 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     { status: '403', description: 'Forbidden', causes: 'Guard policy rejected the operation.' },
     { status: '404', description: 'Not found', causes: 'Record not found. Only from OrThrow operations, update, and delete.' },
     { status: '409', description: 'Conflict', causes: 'Unique constraint violation on create/update/upsert, or transaction conflict (e.g. in findManyPaginated).' },
-    { status: '500', description: 'Internal server error', causes: 'Database error, table/column missing, raw query failure, or unhandled error.' },
-    { status: '501', description: 'Not implemented', causes: 'Database provider does not support the requested feature.' },
+    { status: '500', description: 'Internal server error', causes: 'Database error, table/column missing, raw query failure, unhandled error, or findManyPaginatedMode="transaction" without transaction support on the Prisma client.' },
+    { status: '501', description: 'Not implemented', causes: 'Database provider does not support the requested feature, or writeStrategy disabled the endpoint.' },
     { status: '503', description: 'Service unavailable', causes: 'Database connection pool timeout.' },
   ]
 
@@ -903,6 +919,15 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     '<a class="' + chipClass + '" href="?ui=yaml">YAML</a>' +
     (hasPlayground ? '<a class="' + chipClass + '" href="?ui=playground">Playground</a>' : '')
 
+  const writeStrategyBanner = !writeStrategy || writeStrategy === 'regular'
+    ? ''
+    : '<div class="mt-3 p-3 rounded-xl border border-amber-300 bg-amber-50 text-xs">' +
+      '<strong>writeStrategy = ' + escapeHtml(writeStrategy) + '.</strong> ' +
+      (writeStrategy === 'throwOnNonReturning'
+        ? 'POST /many (createMany) and PUT /many (updateMany) are disabled and respond with 501. Use the /many/return variants.'
+        : 'POST /many silently invokes createManyAndReturn; PUT /many silently invokes updateManyAndReturn. Both return arrays of records instead of { count } and accept select/include/omit.') +
+      '</div>'
+
   const tocHtml = '<ol class="m-0 pl-[18px]">' + anchors().map((a) => '<li class="my-1.5"><a href="#' + escapeHtml(a.id) + '" class="text-inherit">' + escapeHtml(a.label) + '</a></li>').join('') + '</ol>'
 
   const whereRows = ctx.fields.map((f) => {
@@ -997,12 +1022,19 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     'Forced values (literals instead of true) are injected server-side and cannot be overridden by the client.',
   ]
 
+  const writeStrategyNotes = !writeStrategy || writeStrategy === 'regular'
+    ? []
+    : writeStrategy === 'throwOnNonReturning'
+      ? ['<strong>writeStrategy="throwOnNonReturning":</strong> the createMany (POST /many) and updateMany (PUT /many) endpoints are disabled and return 501. Use the corresponding <span class="font-mono">/many/return</span> endpoints instead.']
+      : ['<strong>writeStrategy="forceReturn":</strong> the createMany (POST /many) and updateMany (PUT /many) endpoints silently invoke createManyAndReturn and updateManyAndReturn respectively. They return arrays of records instead of <span class="font-mono">{ count }</span>, and their request bodies accept <span class="font-mono">select</span>, <span class="font-mono">include</span>, and <span class="font-mono">omit</span>.']
+
   const runtimeNotes = [
     '<strong>Query parameter parsing:</strong> GET query values are parsed server-side. Strings starting with <span class="font-mono">{</span>, <span class="font-mono">[</span>, or <span class="font-mono">"</span> are JSON-parsed. The strings <span class="font-mono">true</span>, <span class="font-mono">false</span>, <span class="font-mono">null</span> are converted to their JS equivalents. Numeric conversion only applies to <span class="font-mono">take</span> and <span class="font-mono">skip</span>. Use <span class="font-mono">encodeQueryParams</span> to avoid encoding issues.',
     '<strong>POST read endpoints:</strong> All read operations accept POST as an alternative transport. The request body is a plain JSON object with the same argument structure as the GET query params — no JSON-string encoding needed. POST reads use native JSON types (numbers, booleans, objects) directly. findMany POST read is at <span class="font-mono">/read</span>; all other read operations use the same path as their GET counterpart. Disable with <span class="font-mono">disablePostReads: true</span> in route config.',
     '<strong>Request body validation:</strong> All write endpoints require a JSON object body. Sending <span class="font-mono">null</span>, arrays, or non-object JSON values returns 400.',
     '<strong>Documentation in production:</strong> Docs endpoints are disabled by default when <span class="font-mono">NODE_ENV=production</span> or <span class="font-mono">DISABLE_OPENAPI=true</span>. To enable in production, set <span class="font-mono">disableOpenApi: false</span> in the route config.',
-    '<strong>Paginated query atomicity:</strong> findManyPaginated wraps data + count in a database transaction when available. If interactive transactions are not supported (e.g. some edge adapters), the queries run separately and data/total may be slightly inconsistent under concurrent writes. When a guard shape is configured, the data and count queries run in parallel without a transaction to keep the guard wrapper in scope, so atomicity is not guaranteed in that mode.',
+    '<strong>Paginated query execution:</strong> findManyPaginated execution is controlled by the generator option <span class="font-mono">findManyPaginatedMode</span>. The default <span class="font-mono">"promiseAll"</span> runs data and count with <span class="font-mono">Promise.all</span> — faster, but not atomic under concurrent writes (data and total may be slightly inconsistent). <span class="font-mono">"transaction"</span> runs data and count inside an interactive transaction and throws <span class="font-mono">500</span> if the Prisma client does not support transactions. There is no implicit fallback in transaction mode.',
+    '<strong>Materialized count source:</strong> findManyPaginated supports endpoint-level <span class="font-mono">pagination.countSource.type="materializedView"</span> for counts driven by a materialized view. The view query is used only when the request has no dynamic <span class="font-mono">where</span>, no <span class="font-mono">distinct</span>, and no guard shape — any of those falls back to the delegate count to keep the total consistent with the filtered data. The generated SQL uses PostgreSQL-style <span class="font-mono">$N</span> placeholders (PostgreSQL and CockroachDB). The optional <span class="font-mono">countSource.where</span> field supports flat equality and <span class="font-mono">null</span> only — no operators, no nested objects.',
     '<strong>Distinct count approximation:</strong> When findManyPaginated is used with distinct and the number of unique values exceeds 100,000, the total falls back to a non-distinct count which may overcount. When a guard shape is configured alongside distinct, the total also falls back to a non-distinct count to avoid imposing the public read shape on the internal counting query. The hasMore value is affected accordingly.',
     '<strong>Serialization:</strong> BigInt values are serialized as strings. Bytes/Buffer values are serialized as base64 strings. Decimal values are serialized as strings. DateTime values are serialized as ISO 8601 strings.',
     '<strong>Playground:</strong> The query playground embeds an iframe to a local prisma-query-builder-ui instance. It connects to your real database using the configured DATABASE_URL. It is disabled in production and when queryBuilder is set to false or queryBuilder.enabled is set to false.',
@@ -1011,6 +1043,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
     '<strong>Bulk write constraints:</strong> createMany, createManyAndReturn, updateMany, and updateManyAndReturn accept scalar-only data inputs. Nested relation writes are not supported in these operations.',
     '<strong>Provider compatibility:</strong> createManyAndReturn requires Prisma 5.14.0+ and is limited to PostgreSQL, CockroachDB, and SQLite. updateManyAndReturn requires Prisma 6.2.0+ with the same provider restrictions. skipDuplicates is not supported on all database providers.',
     '<strong>omit compatibility:</strong> The omit parameter requires Prisma 6.2.0+. On versions 6.0.x–6.1.x, requests using omit return 400.',
+    ...writeStrategyNotes,
   ]
 
   const noUniqueFieldNote = '<div class="bg-gray-50 border border-gray-200 rounded-xl p-3 text-xs text-gray-500">This model has no unique or id fields suitable for a generated example. Use the unique constraint from your schema.</div>'
@@ -1048,6 +1081,8 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
       <div class="flex gap-2 flex-wrap items-center pt-0.5">${openApiLinks}</div>
     </div>
 
+    ${writeStrategyBanner}
+
     <div class="${calloutClass}">${tocHtml}</div>
 
     <h2 class="mt-[18px] mb-2 text-base border-t border-gray-200 pt-3.5" id="ops">1. Operations</h2>
@@ -1274,9 +1309,7 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
       </div>
       <div>
         <h3 class="mt-3.5 mb-2 text-sm">11.3 GET — findUnique</h3>
-        ${findUniqueFetchExample
-          ? codeBlock(findUniqueFetchExample)
-          : noUniqueFieldNote}
+        ${findUniqueFetchExample ? codeBlock(findUniqueFetchExample) : noUniqueFieldNote}
       </div>
       <div>
         <h3 class="mt-3.5 mb-2 text-sm">11.4 POST — create</h3>
@@ -1284,21 +1317,15 @@ export function renderDocs(modelName: string, config: DocsConfig, ctx: DocsModel
       </div>
       <div>
         <h3 class="mt-3.5 mb-2 text-sm">11.5 PUT — update</h3>
-        ${updateFetchExample
-          ? codeBlock(updateFetchExample)
-          : noUniqueFieldNote}
+        ${updateFetchExample ? codeBlock(updateFetchExample) : noUniqueFieldNote}
       </div>
       <div>
         <h3 class="mt-3.5 mb-2 text-sm">11.6 DELETE — delete</h3>
-        ${deleteFetchExample
-          ? codeBlock(deleteFetchExample)
-          : noUniqueFieldNote}
+        ${deleteFetchExample ? codeBlock(deleteFetchExample) : noUniqueFieldNote}
       </div>
       <div>
         <h3 class="mt-3.5 mb-2 text-sm">11.7 Guard variant header</h3>
-        ${guardFetchExample
-          ? codeBlock(guardFetchExample)
-          : noUniqueFieldNote}
+        ${guardFetchExample ? codeBlock(guardFetchExample) : noUniqueFieldNote}
       </div>
     </div>
 

package/src/copy/operationRuntime.ts

@@ -5,6 +5,9 @@ import type {
   ProgressiveStageResult,
   ProgressiveStageContext,
   ProgressiveStage,
+  PaginationConfig,
+  PaginationCountSource,
+  FindManyPaginatedMode,
 } from './routeConfig'
 
 export type {
@@ -13,12 +16,9 @@ export type {
   ProgressiveStageResult,
   ProgressiveStageContext,
   ProgressiveStage,
-}
-
-export interface PaginationConfig {
-  defaultLimit?: number
-  maxLimit?: number
-  distinctCountLimit?: number
+  PaginationConfig,
+  PaginationCountSource,
+  FindManyPaginatedMode,
 }
 
 export interface OperationContext {
@@ -30,6 +30,7 @@ export interface OperationContext {
   guardShape?: Record<string, unknown>
   guardCaller?: string
   paginationConfig?: PaginationConfig
+  findManyPaginatedMode?: FindManyPaginatedMode
 }
 
 export type PrismaDelegate = {
@@ -58,8 +59,14 @@ export type PrismaClientLike = {
   $transaction?: <T>(fn: (tx: PrismaClientLike) => Promise<T>) => Promise<T>
 }
 
+type PrismaRawClient = {
+  $queryRawUnsafe?: <T = unknown>(sql: string, ...values: unknown[]) => Promise<T>
+}
+
 export const DISTINCT_COUNT_LIMIT = 100000
 
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+
 export class HttpError extends Error {
   status: number
   constructor(status: number, message: string) {
@@ -254,6 +261,14 @@ export function applyPaginationLimits(
   return result
 }
 
+export function mergePaginationConfig(
+  base: PaginationConfig | undefined,
+  override: Partial<PaginationConfig> | undefined,
+): PaginationConfig | undefined {
+  if (!base && !override) return undefined
+  return { ...(base ?? {}), ...(override ?? {}) }
+}
+
 export function normalizeDistinct(value: unknown): string[] {
   if (typeof value === 'string') return [value]
   if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string')
@@ -309,13 +324,85 @@ export function buildCountShape(
   return result
 }
 
+function quoteIdent(name: string): string {
+  if (!IDENT_RE.test(name)) {
+    throw new HttpError(400, 'invalid identifier: ' + name)
+  }
+  return '"' + name.replace(/"/g, '""') + '"'
+}
+
+function buildMaterializedCountFqn(
+  source: Extract<PaginationCountSource, { type: 'materializedView' }>,
+): string {
+  return source.schema
+    ? quoteIdent(source.schema) + '.' + quoteIdent(source.relation)
+    : quoteIdent(source.relation)
+}
+
+function buildMaterializedCountWhere(
+  where: Record<string, unknown> | undefined,
+): { sql: string; values: unknown[] } {
+  if (!where || Object.keys(where).length === 0) {
+    return { sql: '', values: [] }
+  }
+  const values: unknown[] = []
+  const clauses: string[] = []
+  for (const [key, value] of Object.entries(where)) {
+    if (value === null) {
+      clauses.push(quoteIdent(key) + ' IS NULL')
+      continue
+    }
+    values.push(value)
+    clauses.push(quoteIdent(key) + ' = $' + values.length)
+  }
+  return { sql: ' WHERE ' + clauses.join(' AND '), values }
+}
+
+export async function countFromMaterializedView(
+  client: unknown,
+  source: Extract<PaginationCountSource, { type: 'materializedView' }>,
+): Promise<number> {
+  const raw = client as PrismaRawClient
+  if (typeof raw.$queryRawUnsafe !== 'function') {
+    throw new HttpError(500, 'Materialized count source requires $queryRawUnsafe on the Prisma client')
+  }
+  const column = source.column ?? 'total'
+  const where = buildMaterializedCountWhere(source.where)
+  const sql =
+    'SELECT ' +
+    quoteIdent(column) +
+    ' AS "total" FROM ' +
+    buildMaterializedCountFqn(source) +
+    where.sql +
+    ' LIMIT 1'
+  const rows = await raw.$queryRawUnsafe<Array<{ total: unknown }>>(sql, ...where.values)
+  const value = rows[0]?.total
+  const total = Number(value)
+  if (!Number.isFinite(total)) {
+    throw new HttpError(500, 'Materialized count source did not return a numeric total')
+  }
+  return Math.trunc(total)
+}
+
 export async function countForPagination(
   delegate: PrismaDelegate,
   query: Record<string, unknown>,
   shape: Record<string, unknown> | undefined,
   caller: string | undefined,
   distinctCountLimit?: number,
+  countSource?: PaginationCountSource,
+  rawClient?: unknown,
 ): Promise<number> {
+  if (
+    countSource &&
+    countSource.type === 'materializedView' &&
+    !shape &&
+    !query.where &&
+    !query.distinct
+  ) {
+    return countFromMaterializedView(rawClient ?? delegate, countSource)
+  }
+
   const distinctFields = normalizeDistinct(query.distinct)
   const hasDistinct = distinctFields.length > 0
   const effectiveLimit = distinctCountLimit ?? DISTINCT_COUNT_LIMIT
@@ -333,9 +420,7 @@ export async function countForPagination(
     return (await delegate.count(countArgs)) as number
   }
 
-  if (hasDistinct && shape) {
-    return runCount()
-  }
+  if (hasDistinct && shape) return runCount()
 
   if (hasDistinct) {
     const selectField = distinctFields[0]

package/src/copy/routeConfig.express.ts

@@ -7,12 +7,20 @@ import type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 } from './routeConfig'
 
 export type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 }
 
 export type {

package/src/copy/routeConfig.fastify.ts

@@ -5,12 +5,20 @@ import type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 } from './routeConfig'
 
 export type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 }
 
 export type FastifyHookHandler = (

package/src/copy/routeConfig.hono.ts

@@ -5,12 +5,20 @@ import type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 } from './routeConfig'
 
 export type {
   QueryBuilderConfig,
   OpenApiServerConfig,
   OpenApiSecuritySchemeConfig,
+  WriteStrategy,
+  FindManyPaginatedMode,
+  PaginationConfig,
+  PaginationCountSource,
 }
 
 export type HonoEnvBase = {
@@ -24,7 +32,7 @@ export type HonoInternalVariables = {
   sqlite?: unknown
   parsedQuery?: Record<string, unknown>
   body?: unknown
-  routeConfig?: { pagination?: unknown }
+  routeConfig?: { pagination?: PaginationConfig }
   guardShape?: Record<string, unknown>
   guardCaller?: string
   resultData?: unknown

package/src/copy/routeConfig.ts

@@ -20,6 +20,27 @@ export interface OpenApiSecuritySchemeConfig {
   description?: string
 }
 
+export type WriteStrategy = 'regular' | 'throwOnNonReturning' | 'forceReturn'
+
+export type FindManyPaginatedMode = 'transaction' | 'promiseAll'
+
+export type PaginationCountSource =
+  | { type?: 'delegate' }
+  | {
+      type: 'materializedView'
+      relation: string
+      schema?: string
+      column?: string
+      where?: Record<string, unknown>
+    }
+
+export interface PaginationConfig {
+  defaultLimit?: number
+  maxLimit?: number
+  distinctCountLimit?: number
+  countSource?: PaginationCountSource
+}
+
 export type ProgressivePatch = {
   key: string
   value: unknown
@@ -70,6 +91,7 @@ export interface BaseOperationConfig<HookHandler, TShape = Record<string, unknow
   before?: HookHandler[]
   after?: HookHandler[]
   shape?: TShape
+  pagination?: Partial<PaginationConfig>
 }
 
 export interface BaseRouteConfig<
@@ -97,11 +119,7 @@ export interface BaseRouteConfig<
   }
   resolveContext?: (request: RequestType) => TCtx | Promise<TCtx>
   queryBuilder?: QueryBuilderConfig | false
-  pagination?: {
-    defaultLimit?: number
-    maxLimit?: number
-    distinctCountLimit?: number
-  }
+  pagination?: PaginationConfig
   findUnique?: BaseOperationConfig<HookHandler, TShape>
   findUniqueOrThrow?: BaseOperationConfig<HookHandler, TShape>
   findFirst?: BaseOperationConfig<HookHandler, TShape>