prisma-generator-express 1.67.0 → 1.68.0

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',
@@ -56,6 +70,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findUnique',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/unique',
     configKey: 'findUnique',
@@ -76,6 +93,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findUniqueOrThrow',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/unique/strict',
     configKey: 'findUniqueOrThrow',
@@ -96,6 +116,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findFirst',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/first',
     configKey: 'findFirst',
@@ -126,6 +149,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findFirstOrThrow',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/first/strict',
     configKey: 'findFirstOrThrow',
@@ -156,6 +182,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'findManyPaginated',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/paginated',
     configKey: 'findManyPaginated',
@@ -187,6 +216,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'count',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/count',
     configKey: 'count',
@@ -208,6 +240,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'aggregate',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/aggregate',
     configKey: 'aggregate',
@@ -240,6 +275,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'groupBy',
+    readOnly: true,
+    destructive: false,
+    idempotent: true,
     method: 'get',
     pathSuffix: '/groupby',
     configKey: 'groupBy',
@@ -274,6 +312,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'create',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '',
     configKey: 'create',
@@ -294,6 +335,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'createMany',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/many',
     configKey: 'createMany',
@@ -315,6 +359,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'createManyAndReturn',
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/many/return',
     configKey: 'createManyAndReturn',
@@ -336,6 +383,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'update',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '',
     configKey: 'update',
@@ -357,6 +407,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'updateMany',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '/many',
     configKey: 'updateMany',
@@ -378,6 +431,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'updateManyAndReturn',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'put',
     pathSuffix: '/many/return',
     configKey: 'updateManyAndReturn',
@@ -399,6 +455,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'upsert',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'patch',
     pathSuffix: '',
     configKey: 'upsert',
@@ -419,6 +478,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'delete',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'delete',
     pathSuffix: '',
     configKey: 'delete',
@@ -439,6 +501,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'deleteMany',
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
     method: 'delete',
     pathSuffix: '/many',
     configKey: 'deleteMany',
@@ -459,6 +524,9 @@ export const OPERATION_METADATA: readonly OpMetadata[] = [
   },
   {
     name: 'updateEach',
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
     method: 'post',
     pathSuffix: '/each',
     configKey: 'updateEach',
@@ -517,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])
 }

package/src/copy/operationPipeline.ts

@@ -0,0 +1,267 @@
+import { HttpError, mapError } from './errorMapper'
+import { formatGuardVariantResolutionError } from './guardVariantError'
+import { isPlainObject } from './misc'
+import {
+  applyDroppedGuard,
+  type ContextResolver,
+  type OpKind,
+} from './projectionDefaults'
+import {
+  resolveOperationVariantKey,
+  resolveGuardShapeOnce,
+  type NormalizedGuardRouting,
+  type PaginationConfig,
+  type FindManyPaginatedMode,
+} from './routeConfig'
+import type { GuardVariantResolution } from './guardVariantRouting'
+import type {
+  OperationContext,
+  PrismaClientLike,
+  RuntimeOperationOverride,
+} from './operationRuntime'
+
+/**
+ * Transport-neutral orchestration shared by the Express, Fastify, Hono and MCP
+ * emitters. Five stages: route, prepareGuard, settle, execute, classifyError.
+ *
+ * The pipeline never reads a request, a header or an authentication. Adapters
+ * resolve the caller themselves and pass it in; `caller` is a routing key for
+ * variant selection only, never an identity.
+ */
+
+/** Resolves application context at most once per request. */
+export type GetContext<T = unknown> = () => Promise<T>
+
+export function memoizeContext<T>(): GetContext<T>
+export function memoizeContext<T>(resolver: () => T | undefined): GetContext<T>
+export function memoizeContext(resolver?: () => unknown): GetContext {
+  let cached: Promise<unknown> | undefined
+  return () => (cached ??= Promise.resolve(resolver?.()))
+}
+
+/**
+ * One request-scoped argument channel. Backed by adapter request storage
+ * (Express `res.locals.parsedQuery` / `req.body`, the Fastify request, Hono
+ * context vars). Dropped-guard transformations, framework hooks, overrides and
+ * execution all observe the same storage through it, so guard transforms
+ * cannot be dropped between stages.
+ *
+ * `read()` returns the STORED value — `undefined` when nothing was stored —
+ * exactly like the storage it fronts; mutation of a stored object is visible
+ * to every later stage.
+ */
+export type ArgsChannel = {
+  read(): Record<string, unknown> | undefined
+  write(next: Record<string, unknown>): void
+}
+
+/**
+ * Runtime narrowing for the adapter boundary: request bags store the client
+ * as `unknown` (Express `req.prisma`, the Fastify request, Hono vars), and
+ * this is the ONE place that narrows it to the structural client contract the
+ * pipeline types require. Missing client is the classic deployment fault —
+ * classified 500, same message the operation core raises later.
+ */
+export function requirePrisma(value: unknown): PrismaClientLike {
+  if (value === null || typeof value !== 'object') {
+    throw new HttpError(
+      500,
+      'PrismaClient not found on request. Set req.prisma in middleware.',
+    )
+  }
+  return value as PrismaClientLike
+}
+
+/** Ensure-style accessor over a channel: materialises and stores empties. */
+export function ensureArgs(channel: ArgsChannel): Record<string, unknown> {
+  const current = channel.read()
+  if (current) return current
+  const fresh: Record<string, unknown> = {}
+  channel.write(fresh)
+  return fresh
+}
+
+/** Minimal execution policy; `GuardPolicy` itself carries target defaults. */
+export type PipelinePolicy = {
+  dropGuard: boolean
+  validateResolvedShapes: boolean
+}
+
+export type RouteStageOk = {
+  ok: true
+  variantKey: string | undefined
+  caller: string | undefined
+}
+
+export type RouteStageResult = RouteStageOk | { ok: false; failure: HttpError }
+
+export type GuardStageOk = {
+  ok: true
+  guardShape: Record<string, unknown> | undefined
+}
+
+export type GuardStageResult = GuardStageOk | { ok: false; failure: HttpError }
+
+/**
+ * Variant routing. Synchronous; no application context, no Prisma. A variant
+ * failure is stored already classified as 400, so `settleStage` rethrows the
+ * same classified error wherever the adapter chooses to settle it.
+ */
+export function routeOperation(input: {
+  guardRouting: NormalizedGuardRouting
+  caller: string | undefined
+}): RouteStageResult {
+  const resolution: GuardVariantResolution = resolveOperationVariantKey(
+    input.guardRouting,
+    input.caller,
+  )
+  if (!resolution.ok) {
+    return {
+      ok: false,
+      failure: new HttpError(
+        400,
+        formatGuardVariantResolutionError(resolution),
+      ),
+    }
+  }
+  const variantKey =
+    input.guardRouting.kind === 'named' ? resolution.key : undefined
+  return {
+    ok: true,
+    variantKey,
+    caller: typeof input.caller === 'string' ? input.caller : undefined,
+  }
+}
+
+/**
+ * Guard-shape preparation. Accepts only a successful route result at the type
+ * level. Shape handling preserves upstream behaviour: default passes the raw
+ * shape through unresolved; resolution happens only when the policy asks for
+ * it (`validateResolvedShapes`, always on for MCP) or the guard is dropped
+ * (local apply, written through the argument channels).
+ *
+ * Resolved-shape failures are stored classified as 500; `settleStage`
+ * rethrows them unchanged.
+ */
+export async function prepareGuardOperation(
+  routed: RouteStageOk,
+  input: {
+    guardShape: Record<string, unknown> | undefined
+    opKind: OpKind
+    policy: PipelinePolicy
+    getContext: ContextResolver | undefined
+    args: ArgsChannel
+    writeArgs: ArgsChannel | undefined
+  },
+): Promise<GuardStageResult> {
+  const { guardShape } = input
+  if (!guardShape) return { ok: true, guardShape: undefined }
+
+  try {
+    if (input.policy.dropGuard) {
+      await applyDroppedGuard(
+        guardShape,
+        routed.variantKey,
+        input.getContext,
+        input.opKind,
+        {
+          readQuery: input.args.read(),
+          writeBody: input.writeArgs?.read(),
+        },
+        () => ensureArgs(input.args),
+        input.writeArgs
+          ? () => ensureArgs(input.writeArgs as ArgsChannel)
+          : () => {
+              throw new HttpError(
+                500,
+                'dropped guard requires a write argument channel for this operation',
+              )
+            },
+      )
+      return { ok: true, guardShape: undefined }
+    }
+
+    let effectiveShape: Record<string, unknown> = guardShape
+    if (input.policy.validateResolvedShapes) {
+      const resolution = await resolveGuardShapeOnce(
+        guardShape,
+        routed.variantKey,
+        input.getContext,
+      )
+      if (!resolution.ok) {
+        return {
+          ok: false,
+          failure: new HttpError(
+            500,
+            'guard shape could not be resolved: ' + resolution.problem,
+          ),
+        }
+      }
+      effectiveShape = isPlainObject(resolution.shape)
+        ? resolution.shape
+        : guardShape
+    }
+    return { ok: true, guardShape: effectiveShape }
+  } catch (error) {
+    return { ok: false, failure: mapError(error) }
+  }
+}
+
+/**
+ * Rethrows the stored classified failure without reclassification. Placement
+ * is the adapter's behavioural choice (default order, Hono `before-hooks`,
+ * MCP before authorize continuation).
+ */
+export function settleStage(
+  result: RouteStageResult | GuardStageResult,
+): asserts result is RouteStageOk | GuardStageOk {
+  if (!result.ok) throw result.failure
+}
+
+/** Shared error classification; encoding stays per transport. */
+export function classifyError(error: unknown): HttpError {
+  return mapError(error)
+}
+
+export type ExecuteDeps<TPrisma extends PrismaClientLike = PrismaClientLike> = {
+  core: (ctx: OperationContext) => Promise<unknown>
+  args: ArgsChannel
+  body?: unknown
+  /** The caller's client; typed so `TPrisma` flows through the shared stage. */
+  prisma: TPrisma
+  postgres?: unknown
+  sqlite?: unknown
+  pagination?: PaginationConfig
+  override?: RuntimeOperationOverride
+  getContext: (() => unknown | Promise<unknown>) | undefined
+  findManyPaginatedMode?: FindManyPaginatedMode
+}
+
+/**
+ * Execution. Reads the argument channel at call time, so every write the
+ * dropped-guard transformation made is what reaches the operation core — the
+ * same core, pagination, override and transformResult path REST uses.
+ */
+export async function executeOperation<
+  TPrisma extends PrismaClientLike = PrismaClientLike,
+>(
+  routed: { variantKey?: string; caller?: string },
+  guard: { guardShape?: Record<string, unknown> },
+  deps: ExecuteDeps<TPrisma>,
+): Promise<unknown> {
+  const ctx: OperationContext = {
+    prisma: deps.prisma,
+    postgres: deps.postgres,
+    sqlite: deps.sqlite,
+    parsedQuery: deps.args.read() ?? {},
+    body: deps.body,
+    guardShape: guard.guardShape,
+    guardCaller: routed.caller,
+    guardVariantKey: routed.variantKey,
+    paginationConfig: deps.pagination,
+    operationOverride: deps.override,
+    resolveOperationContext: deps.getContext,
+    findManyPaginatedMode: deps.findManyPaginatedMode,
+  }
+  return deps.core(ctx)
+}

package/src/copy/operationRuntime.ts

@@ -72,22 +72,32 @@ type SpeedExtensionFactory = (opts: {
 }) => unknown
 
 let _speedExtension: SpeedExtensionFactory | null = null
+let _prismasqlReady: Promise<void> | undefined
 
 const _prismasqlModule = 'prisma-' + 'sql'
-const _prismasqlReady = (async () => {
-  try {
-    const mod = (await import(_prismasqlModule)) as {
-      speedExtension?: SpeedExtensionFactory
-      default?: { speedExtension?: SpeedExtensionFactory }
-    }
-    _speedExtension = mod.speedExtension ?? mod.default?.speedExtension ?? null
-  } catch (err) {
-    const code = (err as { code?: string } | null)?.code
-    if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') {
-      console.warn(LOG_PREFIX, 'prisma-sql initialization failed:', err)
+
+/**
+ * Loaded on FIRST USE, not at module load: the copied runtime stays free of
+ * top-level side effects, so a bundler can evaluate the import graph without
+ * triggering the optional `prisma-sql` lookup.
+ */
+function ensurePrismaSqlReady(): Promise<void> {
+  return (_prismasqlReady ??= (async () => {
+    try {
+      const mod = (await import(_prismasqlModule)) as {
+        speedExtension?: SpeedExtensionFactory
+        default?: { speedExtension?: SpeedExtensionFactory }
+      }
+      _speedExtension =
+        mod.speedExtension ?? mod.default?.speedExtension ?? null
+    } catch (err) {
+      const code = (err as { code?: string } | null)?.code
+      if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') {
+        console.warn(LOG_PREFIX, 'prisma-sql initialization failed:', err)
+      }
     }
-  }
-})()
+  })())
+}
 
 const _extendedClients = new WeakMap<object, WeakMap<object, unknown>>()
 
@@ -101,7 +111,7 @@ export async function getExtendedClient(
       'PrismaClient not found on request. Set req.prisma in middleware.',
     )
   }
-  await _prismasqlReady
+  await ensurePrismaSqlReady()
   if (!_speedExtension) return base
   const connector = (ctx.postgres ?? ctx.sqlite) as object | undefined
   if (!connector) return base