prisma-generator-express 1.66.0 → 1.68.0

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

@@ -1,3 +1,5 @@
+import { resolveGuardShapeOnce } from './routeConfig'
+import { assertGuard } from './guardHelpers'
 import { HttpError, LOG_PREFIX } from './errorMapper'
 import { sanitizeKeys, isPlainObject } from './misc'
 import type {
@@ -24,12 +26,15 @@ export type {
 
 export interface OperationContext {
   prisma: unknown
+  operationOverride?: RuntimeOperationOverride
+  resolveOperationContext?: () => unknown | Promise<unknown>
   postgres?: unknown
   sqlite?: unknown
   parsedQuery?: Record<string, unknown>
   body?: unknown
   guardShape?: Record<string, unknown>
   guardCaller?: string
+  guardVariantKey?: string
   paginationConfig?: PaginationConfig
   findManyPaginatedMode?: FindManyPaginatedMode
 }
@@ -60,34 +65,53 @@ export type PrismaClientLike = {
   $transaction?: <T>(fn: (tx: PrismaClientLike) => Promise<T>) => Promise<T>
 }
 
-type SpeedExtensionFactory = (opts: { postgres?: unknown; sqlite?: unknown; debug?: boolean }) => unknown
+type SpeedExtensionFactory = (opts: {
+  postgres?: unknown
+  sqlite?: unknown
+  debug?: boolean
+}) => 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>>()
 
-export async function getExtendedClient(ctx: OperationContext): Promise<unknown> {
+export async function getExtendedClient(
+  ctx: OperationContext,
+): Promise<unknown> {
   const base = ctx.prisma as PrismaClientLike | null | undefined
   if (!base) {
-    throw new HttpError(500, 'PrismaClient not found on request. Set req.prisma in middleware.')
+    throw new HttpError(
+      500,
+      '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
@@ -98,11 +122,13 @@ export async function getExtendedClient(ctx: OperationContext): Promise<unknown>
   }
   try {
     if (typeof base.$extends !== 'function') return base
-    const extended = base.$extends(_speedExtension({
-      postgres: ctx.postgres,
-      sqlite: ctx.sqlite,
-      debug: process.env.DEBUG === 'true',
-    }))
+    const extended = base.$extends(
+      _speedExtension({
+        postgres: ctx.postgres,
+        sqlite: ctx.sqlite,
+        debug: process.env.DEBUG === 'true',
+      }),
+    )
     let map = _extendedClients.get(connector)
     if (!map) {
       map = new WeakMap<object, unknown>()
@@ -111,7 +137,10 @@ export async function getExtendedClient(ctx: OperationContext): Promise<unknown>
     map.set(base as unknown as object, extended)
     return extended
   } catch (error) {
-    console.warn('[speedExtension] Failed to initialize, using base client:', error)
+    console.warn(
+      '[speedExtension] Failed to initialize, using base client:',
+      error,
+    )
     return base
   }
 }
@@ -134,7 +163,10 @@ export function validateBody(body: unknown): Record<string, unknown> {
   return sanitizeKeys(body as Record<string, unknown>)
 }
 
-export function requireBodyField(body: Record<string, unknown>, field: string): void {
+export function requireBodyField(
+  body: Record<string, unknown>,
+  field: string,
+): void {
   if (!(field in body) || body[field] === undefined) {
     throw new HttpError(400, 'Missing required field: ' + field)
   }
@@ -143,7 +175,8 @@ export function requireBodyField(body: Record<string, unknown>, field: string):
 export function transformResult(value: unknown): unknown {
   if (value === null || value === undefined) return value
   if (typeof value === 'bigint') return value.toString()
-  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) return value.toString('base64')
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+    return value.toString('base64')
   if (typeof Buffer !== 'undefined' && value instanceof Uint8Array) {
     return Buffer.from(value).toString('base64')
   }
@@ -169,4 +202,69 @@ export function transformResult(value: unknown): unknown {
     return changed ? out : value
   }
   return value
-}
+}
+
+export const OPERATION_OVERRIDE_VERSION = 1
+
+export type OperationOverride<TInput, TResult, TContext, TPrisma> = {
+  invoke(options: {
+    input: TInput
+    args: TInput
+    context: TContext
+    prisma: TPrisma
+    core: () => Promise<TResult>
+  }): TResult | Promise<TResult>
+}['invoke']
+
+export type RuntimeOperationOverride = OperationOverride<
+  Record<string, unknown>,
+  unknown,
+  unknown,
+  Readonly<
+    Record<
+      string,
+      Readonly<Record<string, (...args: never[]) => Promise<unknown>>>
+    >
+  >
+>
+
+export async function executeOperationOverride<TResult>(
+  ctx: OperationContext,
+  model: string,
+  operation: keyof Omit<PrismaDelegate, 'guard'> | 'findManyPaginated',
+  input: Record<string, unknown>,
+  core: () => Promise<TResult>,
+): Promise<TResult> {
+  if (!ctx.operationOverride) return core()
+  if (!ctx.guardShape)
+    throw new HttpError(500, 'An operation override requires a guard shape')
+  const context = await ctx.resolveOperationContext?.()
+  const resolved = await resolveGuardShapeOnce(
+    ctx.guardShape,
+    ctx.guardVariantKey ?? ctx.guardCaller,
+    () => context,
+  )
+  if (!resolved.ok || !isPlainObject(resolved.shape)) {
+    throw new HttpError(
+      500,
+      'An operation override requires a resolved guard shape',
+    )
+  }
+  ctx.guardShape = resolved.shape
+  const delegate = getDelegate(await getExtendedClient(ctx), model)
+  assertGuard(delegate)
+  const guarded = delegate.guard(resolved.shape, ctx.guardCaller)
+  const methods =
+    operation === 'findManyPaginated'
+      ? (['findMany', 'count'] as const)
+      : [operation]
+  const exposed: Record<string, (...args: never[]) => Promise<unknown>> = {}
+  for (const method of methods) exposed[method] = guarded[method].bind(guarded)
+  return (await ctx.operationOverride({
+    input,
+    args: input,
+    context,
+    prisma: Object.freeze({ [model]: Object.freeze(exposed) }),
+    core,
+  })) as TResult
+}