prisma-generator-express 1.66.0 → 1.68.0

package/src/copy/misc.ts

@@ -1,68 +1,88 @@
-export const isObject = (value: unknown): value is Record<string, unknown> => {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== 'object') return false
-  if (Array.isArray(value)) return false
-  const proto = Object.getPrototypeOf(value)
-  return proto === Object.prototype || proto === null
-}
-
-const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
-
-export function isSafeKey(key: string): boolean {
-  return !UNSAFE_KEYS.has(key)
-}
-
-export function sanitizeKeys<T>(value: T): T {
-  if (Array.isArray(value)) {
-    let mutated = false
-    const out: unknown[] = new Array(value.length)
-    for (let i = 0; i < value.length; i++) {
-      const sanitized = sanitizeKeys(value[i])
-      if (sanitized !== value[i]) mutated = true
-      out[i] = sanitized
-    }
-    return (mutated ? out : value) as T
-  }
-  if (isPlainObject(value)) {
-    const keys = Object.keys(value)
-    let hasUnsafe = false
-    let childrenMutated = false
-    const sanitizedChildren: Record<string, unknown> = {}
-    for (const key of keys) {
-      if (!isSafeKey(key)) {
-        hasUnsafe = true
-        continue
-      }
-      const original = (value as Record<string, unknown>)[key]
-      const sanitized = sanitizeKeys(original)
-      if (sanitized !== original) childrenMutated = true
-      sanitizedChildren[key] = sanitized
-    }
-    if (!hasUnsafe && !childrenMutated) return value
-    return sanitizedChildren as T
-  }
-  return value
-}
-
-export function normalizePrefix(p: string): string {
-  if (!p) return ''
-  let result = p
-  if (!result.startsWith('/')) result = '/' + result
-  while (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1)
-  if (result === '/') return ''
-  return result
-}
-
-export function removeTrailingSlash(path: string): string {
-  if (path === '/') return ''
-  return path.endsWith('/') ? path.slice(0, -1) : path
-}
-
-export function getEnv(): Record<string, string | undefined> {
-  return typeof process !== 'undefined' && process.env
-    ? process.env
-    : ({} as Record<string, string | undefined>)
-}
+export const isObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function isPlainObject(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  if (Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+export function isSafeKey(key: string): boolean {
+  return !UNSAFE_KEYS.has(key)
+}
+
+export function sanitizeKeys<T>(value: T): T {
+  if (Array.isArray(value)) {
+    let mutated = false
+    const out: unknown[] = new Array(value.length)
+    for (let i = 0; i < value.length; i++) {
+      const sanitized = sanitizeKeys(value[i])
+      if (sanitized !== value[i]) mutated = true
+      out[i] = sanitized
+    }
+    return (mutated ? out : value) as T
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value)
+    let hasUnsafe = false
+    let childrenMutated = false
+    const sanitizedChildren: Record<string, unknown> = {}
+    for (const key of keys) {
+      if (!isSafeKey(key)) {
+        hasUnsafe = true
+        continue
+      }
+      const original = (value as Record<string, unknown>)[key]
+      const sanitized = sanitizeKeys(original)
+      if (sanitized !== original) childrenMutated = true
+      sanitizedChildren[key] = sanitized
+    }
+    if (!hasUnsafe && !childrenMutated) return value
+    return sanitizedChildren as T
+  }
+  return value
+}
+
+export function normalizePrefix(p: string): string {
+  if (!p) return ''
+  let result = p
+  if (!result.startsWith('/')) result = '/' + result
+  while (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1)
+  if (result === '/') return ''
+  return result
+}
+
+export function removeTrailingSlash(path: string): string {
+  if (path === '/') return ''
+  return path.endsWith('/') ? path.slice(0, -1) : path
+}
+
+export function getEnv(): Record<string, string | undefined> {
+  return typeof process !== 'undefined' && process.env
+    ? process.env
+    : ({} as Record<string, string | undefined>)
+}
+
+let dropGuardDeprecationWarned = false
+
+export function resolveDropGuardEnv(
+  env: Record<string, string | undefined>,
+): boolean {
+  if (env.PGE_DROP_GUARD === 'true') return true
+  if (env.E2E === 'true') {
+    if (!dropGuardDeprecationWarned) {
+      dropGuardDeprecationWarned = true
+      console.warn(
+        '[prisma-generator-express] E2E=true guard bypass is deprecated. Use PGE_DROP_GUARD=true.',
+      )
+    }
+    return true
+  }
+  return false
+}

package/src/copy/ndjson.ts

@@ -0,0 +1,72 @@
+import type { SseWritable } from './sse'
+
+/**
+ * NDJSON chunked streaming for list reads.
+ *
+ * Contract: one JSON document per line; the final line is
+ * `{"done":true,"rows":N}`. Clients parse by splitting on newlines — there is
+ * no event vocabulary and no client-side merge algorithm. The same guard
+ * shapes, projection defaults, and pagination limits apply as on the JSON
+ * endpoint, because every page goes through the same generated core function.
+ */
+
+export function acceptsNdjson(accept: string | undefined): boolean {
+  if (!accept) return false
+  return accept
+    .toLowerCase()
+    .split(',')
+    .some((entry) => entry.split(';')[0].trim() === 'application/x-ndjson')
+}
+
+export function startNdjson(res: SseWritable): void {
+  res.setHeader('Content-Type', 'application/x-ndjson')
+  res.setHeader('Cache-Control', 'no-cache, no-transform')
+  res.setHeader('X-Stream-Protocol-Version', '1')
+  res.setHeader('X-Accel-Buffering', 'no')
+  res.statusCode = 200
+}
+
+export interface NdjsonStreamOptions {
+  res: SseWritable
+  isClosed: () => boolean
+  fetchPage: (skip: number, take: number) => Promise<unknown>
+  initialSkip: number
+  requestedTake?: number
+  defaultLimit?: number
+  maxLimit: number
+}
+
+export async function runNdjsonFindMany(
+  options: NdjsonStreamOptions,
+): Promise<void> {
+  startNdjson(options.res)
+  const take = Math.min(
+    options.requestedTake ?? options.defaultLimit ?? options.maxLimit,
+    options.maxLimit,
+  )
+  let skip = options.initialSkip
+  let written = 0
+
+  while (
+    written < options.maxLimit &&
+    !options.isClosed() &&
+    !options.res.writableEnded
+  ) {
+    const result = await options.fetchPage(skip, take)
+    if (!Array.isArray(result)) {
+      throw new Error(
+        'NDJSON streaming requires an array result from the core read',
+      )
+    }
+    for (const row of result) {
+      if (written >= options.maxLimit) break
+      options.res.write(JSON.stringify(row) + '\n')
+      written++
+    }
+    if (result.length < take) break
+    skip += result.length
+  }
+
+  options.res.write(JSON.stringify({ done: true, rows: written }) + '\n')
+  options.res.end()
+}

package/src/copy/operationDefinitions.ts

@@ -21,11 +21,25 @@ export interface OpMetadata {
   argsSchema: readonly string[]
   requiredArgs: readonly string[]
   notes: string
+  /**
+   * EXPLICIT behaviour annotations, never inferred from `kind`. Mapped to MCP
+   * tool hints (readOnlyHint / destructiveHint / idempotentHint) and available
+   * for any other transport that wants the same vocabulary. MCP semantics:
+   * `destructive: false` means ONLY additive updates — anything that can
+   * overwrite or remove existing data (update, upsert, delete families) is
+   * destructive.
+   */
+  readOnly: boolean
+  destructive: boolean
+  idempotent: boolean
 }
 
 export const OPERATION_METADATA: readonly OpMetadata[] = [
   {
     name: 'findMany',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '',
     configKey: 'findMany',
@@ -40,12 +54,25 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     errors: [400, 403, 500, 501, 503],
     responseDesc: 'Array of records',
     transport: 'GET query params',
-    argsSchema: ['where', 'select', 'include', 'omit', 'orderBy', 'cursor', 'take', 'skip', 'distinct'],
+    argsSchema: [
+      'where',
+      'select',
+      'include',
+      'omit',
+      'orderBy',
+      'cursor',
+      'take',
+      'skip',
+      'distinct',
+    ],
     requiredArgs: [],
     notes: 'Pagination limits may apply when configured.',
   },
   {
     name: 'findUnique',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/unique',
     configKey: 'findUnique',
@@ -66,6 +93,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findUniqueOrThrow',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/unique/strict',
     configKey: 'findUniqueOrThrow',
@@ -86,6 +116,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findFirst',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/first',
     configKey: 'findFirst',
@@ -100,12 +133,25 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     errors: [400, 403, 500, 501, 503],
     responseDesc: 'Single record or null',
     transport: 'GET query params',
-    argsSchema: ['where', 'select', 'include', 'omit', 'orderBy', 'cursor', 'take', 'skip', 'distinct'],
+    argsSchema: [
+      'where',
+      'select',
+      'include',
+      'omit',
+      'orderBy',
+      'cursor',
+      'take',
+      'skip',
+      'distinct',
+    ],
     requiredArgs: [],
     notes: 'Returns null (not 404) when no record matches.',
   },
   {
     name: 'findFirstOrThrow',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/first/strict',
     configKey: 'findFirstOrThrow',
@@ -120,12 +166,25 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     errors: [400, 403, 404, 500, 501, 503],
     responseDesc: 'Single record',
     transport: 'GET query params',
-    argsSchema: ['where', 'select', 'include', 'omit', 'orderBy', 'cursor', 'take', 'skip', 'distinct'],
+    argsSchema: [
+      'where',
+      'select',
+      'include',
+      'omit',
+      'orderBy',
+      'cursor',
+      'take',
+      'skip',
+      'distinct',
+    ],
     requiredArgs: [],
     notes: 'Returns 404 when no record matches.',
   },
   {
     name: 'findManyPaginated',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/paginated',
     configKey: 'findManyPaginated',
@@ -140,12 +199,26 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     errors: [400, 403, 409, 500, 501, 503],
     responseDesc: '{ data: Record[], total: number, hasMore: boolean }',
     transport: 'GET query params',
-    argsSchema: ['where', 'select', 'include', 'omit', 'orderBy', 'cursor', 'take', 'skip', 'distinct'],
+    argsSchema: [
+      'where',
+      'select',
+      'include',
+      'omit',
+      'orderBy',
+      'cursor',
+      'take',
+      'skip',
+      'distinct',
+    ],
     requiredArgs: [],
-    notes: 'Wraps findMany with total count. hasMore is reliable for forward offset pagination (skip + take) only. Distinct count over 100k falls back to approximate total. 409 possible on transaction conflict.',
+    notes:
+      'Wraps findMany with total count. hasMore is reliable for forward offset pagination (skip + take) only. Distinct count over 100k falls back to approximate total. 409 possible on transaction conflict.',
   },
   {
     name: 'count',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/count',
     configKey: 'count',
@@ -162,10 +235,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'GET query params',
     argsSchema: ['where', 'orderBy', 'cursor', 'take', 'skip', 'select'],
     requiredArgs: [],
-    notes: 'select here means count-specific field selection, not record field selection.',
+    notes:
+      'select here means count-specific field selection, not record field selection.',
   },
   {
     name: 'aggregate',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/aggregate',
     configKey: 'aggregate',
@@ -178,14 +255,29 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     excludeFromEnableAll: false,
     writeStrategyAffected: false,
     errors: [400, 403, 500, 501, 503],
-    responseDesc: 'Object with requested aggregate fields (_count, _avg, _sum, _min, _max)',
+    responseDesc:
+      'Object with requested aggregate fields (_count, _avg, _sum, _min, _max)',
     transport: 'GET query params',
-    argsSchema: ['where', 'orderBy', 'cursor', 'take', 'skip', '_count', '_avg', '_sum', '_min', '_max'],
+    argsSchema: [
+      'where',
+      'orderBy',
+      'cursor',
+      'take',
+      'skip',
+      '_count',
+      '_avg',
+      '_sum',
+      '_min',
+      '_max',
+    ],
     requiredArgs: [],
     notes: '_avg, _sum only apply to numeric fields.',
   },
   {
     name: 'groupBy',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/groupby',
     configKey: 'groupBy',
@@ -198,14 +290,31 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     excludeFromEnableAll: false,
     writeStrategyAffected: false,
     errors: [400, 403, 500, 501, 503],
-    responseDesc: 'Array of objects, each with grouped field values and requested aggregates',
+    responseDesc:
+      'Array of objects, each with grouped field values and requested aggregates',
     transport: 'GET query params',
-    argsSchema: ['by', 'where', 'orderBy', 'having', 'take', 'skip', '_count', '_avg', '_sum', '_min', '_max'],
+    argsSchema: [
+      'by',
+      'where',
+      'orderBy',
+      'having',
+      'take',
+      'skip',
+      '_count',
+      '_avg',
+      '_sum',
+      '_min',
+      '_max',
+    ],
     requiredArgs: ['by'],
-    notes: 'by is a JSON-encoded array of scalar field names. orderBy is required when using skip or take. Response contains only the by-fields plus requested aggregates.',
+    notes:
+      'by is a JSON-encoded array of scalar field names. orderBy is required when using skip or take. Response contains only the by-fields plus requested aggregates.',
   },
   {
     name: 'create',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '',
     configKey: 'create',
@@ -226,6 +335,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'createMany',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/many',
     configKey: 'createMany',
@@ -242,10 +354,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'POST JSON body',
     argsSchema: ['data', 'skipDuplicates'],
     requiredArgs: ['data'],
-    notes: 'data is an array of scalar-only inputs. Nested relation writes are not supported. skipDuplicates silently ignores conflicts (not supported on all providers).',
+    notes:
+      'data is an array of scalar-only inputs. Nested relation writes are not supported. skipDuplicates silently ignores conflicts (not supported on all providers).',
   },
   {
     name: 'createManyAndReturn',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/many/return',
     configKey: 'createManyAndReturn',
@@ -262,10 +378,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'POST JSON body',
     argsSchema: ['data', 'skipDuplicates', 'select', 'include', 'omit'],
     requiredArgs: ['data'],
-    notes: 'Like createMany but returns created records. data items are scalar-only. Requires Prisma 5.14.0+, PostgreSQL/CockroachDB/SQLite only. The order of returned records is not guaranteed.',
+    notes:
+      'Like createMany but returns created records. data items are scalar-only. Requires Prisma 5.14.0+, PostgreSQL/CockroachDB/SQLite only. The order of returned records is not guaranteed.',
   },
   {
     name: 'update',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '',
     configKey: 'update',
@@ -282,10 +402,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'PUT JSON body',
     argsSchema: ['where', 'data', 'select', 'include', 'omit'],
     requiredArgs: ['where', 'data'],
-    notes: '404 when the record to update is not found. 409 on unique constraint violation or transaction conflict.',
+    notes:
+      '404 when the record to update is not found. 409 on unique constraint violation or transaction conflict.',
   },
   {
     name: 'updateMany',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '/many',
     configKey: 'updateMany',
@@ -302,10 +426,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'PUT JSON body',
     argsSchema: ['where', 'data'],
     requiredArgs: ['where', 'data'],
-    notes: 'Updates all matching records with scalar-only data. Nested relation writes are not supported. Returns count, not records. 409 on unique constraint violation.',
+    notes:
+      'Updates all matching records with scalar-only data. Nested relation writes are not supported. Returns count, not records. 409 on unique constraint violation.',
   },
   {
     name: 'updateManyAndReturn',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '/many/return',
     configKey: 'updateManyAndReturn',
@@ -322,10 +450,14 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     transport: 'PUT JSON body',
     argsSchema: ['where', 'data', 'select', 'include', 'omit'],
     requiredArgs: ['where', 'data'],
-    notes: 'Like updateMany but returns updated records. data is scalar-only. Requires Prisma 6.2.0+, PostgreSQL/CockroachDB/SQLite only. 409 on unique constraint violation.',
+    notes:
+      'Like updateMany but returns updated records. data is scalar-only. Requires Prisma 6.2.0+, PostgreSQL/CockroachDB/SQLite only. 409 on unique constraint violation.',
   },
   {
     name: 'upsert',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'patch',
     pathSuffix: '',
     configKey: 'upsert',
@@ -346,6 +478,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'delete',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'delete',
     pathSuffix: '',
     configKey: 'delete',
@@ -366,6 +501,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'deleteMany',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'delete',
     pathSuffix: '/many',
     configKey: 'deleteMany',
@@ -386,6 +524,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'updateEach',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/each',
     configKey: 'updateEach',
@@ -398,11 +539,13 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
     excludeFromEnableAll: true,
     writeStrategyAffected: false,
     errors: [400, 403, 409, 500, 501, 503],
-    responseDesc: 'Non-atomic: per-row { status, data } / { status, error } array. Atomic: array of records.',
+    responseDesc:
+      'Non-atomic: per-row { status, data } / { status, error } array. Atomic: array of records.',
     transport: 'POST JSON body (array)',
     argsSchema: [],
     requiredArgs: ['array of { where, data }'],
-    notes: 'Internal batch endpoint. Bypasses guard shapes. Not enabled by enableAll. Non-atomic max 1000 items, atomic max 100 items. Header x-batch-atomic:true switches to transactional mode.',
+    notes:
+      'Internal batch endpoint. Bypasses guard shapes. Not enabled by enableAll. Non-atomic max 1000 items, atomic max 100 items. Header x-batch-atomic:true switches to transactional mode.',
   },
 ]
 
@@ -410,9 +553,12 @@ export const OPERATION_BY_NAME: Record<string, OpMetadata> = Object.fromEntries(
   OPERATION_METADATA.map((m) => [m.name, m]),
 )
 
-export const READ_OPERATIONS: readonly OpMetadata[] = OPERATION_METADATA.filter((m) => m.kind === 'read')
+export const READ_OPERATIONS: readonly OpMetadata[] = OPERATION_METADATA.filter(
+  (m) => m.kind === 'read',
+)
 
-export const WRITE_OPERATIONS: readonly OpMetadata[] = OPERATION_METADATA.filter((m) => m.kind === 'write' || m.kind === 'batch')
+export const WRITE_OPERATIONS: readonly OpMetadata[] =
+  OPERATION_METADATA.filter((m) => m.kind === 'write' || m.kind === 'batch')
 
 export const READ_OPERATION_NAMES = new Set(READ_OPERATIONS.map((m) => m.name))
 
@@ -439,10 +585,16 @@ export function getPostReadPathSuffix(opName: string): string {
 }
 
 export function isOperationEnabled(
-  config: Record<string, any>,
+  config: object,
   def: OperationDef | OpMetadata,
 ): boolean {
-  if (config[def.configKey] === false) return false
-  if (def.excludeFromEnableAll) return !!config[def.configKey]
-  return !!(config.enableAll || config[def.configKey])
-}
+  // Route configs are interfaces without index signatures, so the value is
+  // reached through one runtime narrowing here at the single point that reads it.
+  if (!config || typeof config !== 'object') {
+    return false
+  }
+  const cfg = config as Record<string, unknown>
+  if (cfg[def.configKey] === false) return false
+  if (def.excludeFromEnableAll) return !!cfg[def.configKey]
+  return !!(cfg.enableAll || cfg[def.configKey])
+}