@prisma-next/framework-components 0.5.0-dev.6 → 0.5.0-dev.61

package/src/{execution-descriptors.ts → execution/execution-descriptors.ts}

@@ -1,3 +1,10 @@
+import type {
+  AdapterDescriptor,
+  DriverDescriptor,
+  ExtensionDescriptor,
+  FamilyDescriptor,
+  TargetDescriptor,
+} from '../shared/framework-components';
 import type {
   RuntimeAdapterInstance,
   RuntimeDriverInstance,
@@ -6,13 +13,6 @@ import type {
   RuntimeTargetInstance,
 } from './execution-instances';
 import type { ExecutionStack } from './execution-stack';
-import type {
-  AdapterDescriptor,
-  DriverDescriptor,
-  ExtensionDescriptor,
-  FamilyDescriptor,
-  TargetDescriptor,
-} from './framework-components';
 
 export interface RuntimeFamilyDescriptor<
   TFamilyId extends string,

package/src/{execution-instances.ts → execution/execution-instances.ts}

@@ -4,7 +4,7 @@ import type {
   ExtensionInstance,
   FamilyInstance,
   TargetInstance,
-} from './framework-components';
+} from '../shared/framework-components';
 
 export interface RuntimeFamilyInstance<TFamilyId extends string>
   extends FamilyInstance<TFamilyId> {}

package/src/{execution-requirements.ts → execution/execution-requirements.ts}

@@ -1,10 +1,10 @@
+import { checkContractComponentRequirements } from '../shared/framework-components';
 import type {
   RuntimeAdapterDescriptor,
   RuntimeExtensionDescriptor,
   RuntimeFamilyDescriptor,
   RuntimeTargetDescriptor,
 } from './execution-descriptors';
-import { checkContractComponentRequirements } from './framework-components';
 
 export function assertRuntimeContractRequirementsSatisfied<
   TFamilyId extends string,

package/src/execution/query-plan.ts

@@ -0,0 +1,53 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+
+/**
+ * Family-agnostic plan marker.
+ *
+ * Carries only `meta` (the family-agnostic plan metadata) and the optional
+ * phantom `_row` parameter that lets type-level utilities recover the row
+ * type from a plan value. SQL and Mongo extend this marker with their own
+ * concrete shapes (`SqlQueryPlan`, `MongoQueryPlan`).
+ *
+ * `QueryPlan` is the *pre-lowering* marker — i.e. the surface a builder
+ * produces before family-specific lowering turns it into an executable
+ * plan (`ExecutionPlan`).
+ */
+export interface QueryPlan<Row = unknown> {
+  readonly meta: PlanMeta;
+  /**
+   * Phantom property to carry the Row generic for type-level utilities.
+   * Not set at runtime; used only for `ResultType` extraction.
+   */
+  readonly _row?: Row;
+}
+
+/**
+ * Family-agnostic execution-plan marker.
+ *
+ * Extends `QueryPlan` with no additional structural fields — the marker
+ * exists to nominally distinguish executable plans from pre-lowering plans
+ * in the type system. Family-specific execution plans (`SqlExecutionPlan`,
+ * `MongoExecutionPlan`) extend this marker with their concrete shapes
+ * (e.g. `sql + params` for SQL, `wireCommand` for Mongo).
+ */
+export interface ExecutionPlan<Row = unknown> extends QueryPlan<Row> {}
+
+/**
+ * Extracts the `Row` type from a plan via the phantom `_row` property.
+ *
+ * Works with any plan that extends `QueryPlan<Row>` — including
+ * `ExecutionPlan<Row>`, `SqlQueryPlan<Row>`, `SqlExecutionPlan<Row>`,
+ * `MongoQueryPlan<Row>`, and `MongoExecutionPlan<Row>`.
+ *
+ * The `_row` property must be present in the plan's static type for the
+ * conditional to bind `R`; objects whose type lacks `_row` resolve to
+ * `never`. Without the `keyof` guard, `extends { _row?: infer R }` would
+ * silently match any object and infer `unknown`.
+ *
+ * Example: `type Row = ResultType<typeof plan>`.
+ */
+export type ResultType<P> = '_row' extends keyof P
+  ? P extends { readonly _row?: infer R }
+    ? R
+    : never
+  : never;

package/src/execution/race-against-abort.ts

@@ -0,0 +1,85 @@
+import type { CodecCallContext } from '../shared/codec-types';
+import type { RuntimeAbortedPhase } from './runtime-error';
+import { runtimeAborted } from './runtime-error';
+
+/**
+ * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
+ * codec-call context is already aborted at the precheck site. Centralises
+ * the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
+ * every codec dispatch site repeats.
+ */
+export function checkAborted(ctx: CodecCallContext, phase: RuntimeAbortedPhase): void {
+  if (ctx.signal?.aborted) {
+    throw runtimeAborted(phase, ctx.signal.reason);
+  }
+}
+
+/**
+ * Race a per-cell `Promise.all` (or any other in-flight work promise) against
+ * the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly
+ * even when codec bodies ignore the signal. In-flight bodies that ignore the
+ * signal are abandoned and run to completion in the background — the
+ * cooperative-cancellation contract documented in ADR 204.
+ *
+ * Call sites still SHOULD pre-check `signal.aborted` and short-circuit with
+ * a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —
+ * that path is the canonical "aborted at entry" surface and avoids
+ * scheduling the work promise. As a defensive belt-and-braces, this helper
+ * also handles the already-aborted case internally: `AbortSignal` does not
+ * replay past abort events to listeners registered after the abort, so we
+ * inspect `signal.aborted` synchronously and reject with the sentinel
+ * before installing the listener. The rejection is still attributed to the
+ * abort path via the sentinel-identity check.
+ *
+ * Distinguishing the rejection source is load-bearing for AC-ERR4
+ * (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).
+ * The semantically equivalent `abortable(signal)` helper in
+ * `@prisma-next/utils` rejects with `signal.reason ?? new DOMException(...)`,
+ * which is not stably distinguishable from a codec-thrown error by identity
+ * alone (a fresh fallback DOMException is allocated per call). We instead
+ * track abort attribution with a unique sentinel: only the `onAbort` listener
+ * installed here ever rejects with the sentinel, so an `error === sentinel`
+ * identity check after the race is unambiguous.
+ *
+ * Lives in `framework-components` (rather than the SQL family, where it
+ * originated in m2) so every family runtime that needs cooperative
+ * cancellation around a codec-dispatch `Promise.all` (SQL encode + decode
+ * today, Mongo encode in m3) shares the same attribution logic.
+ */
+export async function raceAgainstAbort<T>(
+  work: Promise<T>,
+  signal: AbortSignal | undefined,
+  phase: RuntimeAbortedPhase,
+): Promise<T> {
+  if (signal === undefined) {
+    return await work;
+  }
+  const sentinel: { reason: unknown } = { reason: undefined };
+  let onAbort: (() => void) | undefined;
+
+  const abortPromise = new Promise<never>((_, reject) => {
+    if (signal.aborted) {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+      return;
+    }
+    onAbort = () => {
+      sentinel.reason = signal.reason;
+      reject(sentinel);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+
+  try {
+    return await Promise.race([work, abortPromise]);
+  } catch (error) {
+    if (error === sentinel) {
+      throw runtimeAborted(phase, sentinel.reason);
+    }
+    throw error;
+  } finally {
+    if (onAbort) {
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+}

package/src/execution/run-with-middleware.ts

@@ -0,0 +1,132 @@
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan } from './query-plan';
+import type { RuntimeMiddleware, RuntimeMiddlewareContext } from './runtime-middleware';
+
+/**
+ * Drives a single execution of `runDriver()` through the middleware lifecycle.
+ *
+ * Lifecycle, in order:
+ *  1. For each middleware in registration order: `intercept(exec, ctx)`. The
+ *     first non-`undefined` result wins; subsequent middleware's `intercept`
+ *     does not fire. On a hit, the runtime emits a `middleware.intercept`
+ *     debug event naming the winning middleware, switches the row source to
+ *     the intercepted rows, and proceeds with `source: 'middleware'`. On
+ *     all-passthrough (every `intercept` returns `undefined` or is omitted),
+ *     `source: 'driver'` is used and the row source is `runDriver()`.
+ *  2. If `source === 'driver'`: for each middleware in registration order,
+ *     `beforeExecute(exec, ctx)`. Skipped on the intercepted hit path —
+ *     `beforeExecute` semantically means "about to hit the driver".
+ *  3. Iterate the row source. On the driver path, for each row, for each
+ *     middleware in registration order: `onRow(row, exec, ctx)`; then yield
+ *     the row. On the intercepted hit path, `onRow` is skipped — intercepted
+ *     rows did not originate from a driver row stream — but rows are still
+ *     yielded to the consumer in order.
+ *  4. On successful completion: for each middleware in registration order:
+ *     `afterExecute(exec, { rowCount, latencyMs, completed: true, source },
+ *     ctx)`.
+ *  5. On any error thrown during steps 1–3: for each middleware in
+ *     registration order: `afterExecute(exec, { rowCount, latencyMs,
+ *     completed: false, source }, ctx)`. Errors thrown by `afterExecute`
+ *     during the error path are swallowed so they do not mask the original
+ *     error. The original error is then rethrown.
+ *
+ * The `source` field on `AfterExecuteResult` lets observers (telemetry,
+ * lints, budgets) distinguish driver-served from middleware-served
+ * executions without needing their own out-of-band signal.
+ *
+ * This helper is the single canonical implementation of the middleware
+ * orchestration loop; family runtimes should not reimplement it.
+ */
+export function runWithMiddleware<TExec extends ExecutionPlan, Row>(
+  exec: TExec,
+  middleware: ReadonlyArray<RuntimeMiddleware<TExec>>,
+  ctx: RuntimeMiddlewareContext,
+  runDriver: () => AsyncIterable<Row>,
+): AsyncIterableResult<Row> {
+  const iterator = async function* (): AsyncGenerator<Row, void, unknown> {
+    const startedAt = Date.now();
+    let rowCount = 0;
+    let completed = false;
+    let source: 'driver' | 'middleware' = 'driver';
+    // Deferred so a winning interceptor can skip `runDriver()` entirely.
+    // For factories that lazily produce async generators this is a no-op,
+    // but factories that do eager work (e.g. acquiring a connection,
+    // sending a query) must not run on the intercepted hit path.
+    let rowSource: AsyncIterable<Row> | Iterable<Row> | undefined;
+
+    try {
+      for (const mw of middleware) {
+        if (!mw.intercept) {
+          continue;
+        }
+        // Mark the lifecycle as middleware-driven *before* awaiting the
+        // hook. If `intercept` throws, the catch block reports the failure
+        // as `source: 'middleware'` — the failure originated in the
+        // intercept chain, not in the driver. If `intercept` returns
+        // `undefined` (passthrough), we revert to `'driver'` and continue.
+        source = 'middleware';
+        const result = await mw.intercept(exec, ctx);
+        if (result === undefined) {
+          source = 'driver';
+          continue;
+        }
+        ctx.log.debug?.({ event: 'middleware.intercept', middleware: mw.name });
+        // The intercepted rows are typed as `Record<string, unknown>` at
+        // the SPI level; the consumer's `Row` type parameter is enforced by
+        // the caller (via the plan's phantom `_row`) the same way driver
+        // rows are. Cast through unknown to bridge the SPI shape to the
+        // caller-supplied Row.
+        rowSource = result.rows as unknown as AsyncIterable<Row> | Iterable<Row>;
+        break;
+      }
+
+      if (source === 'driver') {
+        for (const mw of middleware) {
+          if (mw.beforeExecute) {
+            await mw.beforeExecute(exec, ctx);
+          }
+        }
+        rowSource = runDriver();
+      }
+
+      // `rowSource` is always assigned by this point: either the intercepted
+      // rows (on a hit) or `runDriver()` (on the driver path).
+      for await (const row of rowSource as AsyncIterable<Row> | Iterable<Row>) {
+        if (source === 'driver') {
+          for (const mw of middleware) {
+            if (mw.onRow) {
+              await mw.onRow(row as Record<string, unknown>, exec, ctx);
+            }
+          }
+        }
+        rowCount++;
+        yield row;
+      }
+
+      completed = true;
+    } catch (error) {
+      const latencyMs = Date.now() - startedAt;
+      for (const mw of middleware) {
+        if (mw.afterExecute) {
+          try {
+            await mw.afterExecute(exec, { rowCount, latencyMs, completed, source }, ctx);
+          } catch {
+            // Swallow afterExecute errors during the error path so they do not
+            // mask the original error.
+          }
+        }
+      }
+
+      throw error;
+    }
+
+    const latencyMs = Date.now() - startedAt;
+    for (const mw of middleware) {
+      if (mw.afterExecute) {
+        await mw.afterExecute(exec, { rowCount, latencyMs, completed, source }, ctx);
+      }
+    }
+  };
+
+  return new AsyncIterableResult(iterator());
+}

package/src/execution/runtime-core.ts

@@ -0,0 +1,133 @@
+import type { CodecCallContext } from '../shared/codec-types';
+import { AsyncIterableResult } from './async-iterable-result';
+import type { ExecutionPlan, QueryPlan } from './query-plan';
+import { checkAborted } from './race-against-abort';
+import { runWithMiddleware } from './run-with-middleware';
+import type {
+  RuntimeExecuteOptions,
+  RuntimeExecutor,
+  RuntimeMiddleware,
+  RuntimeMiddlewareContext,
+} from './runtime-middleware';
+
+/**
+ * Constructor options shared by every concrete `RuntimeCore` subclass.
+ *
+ * Family runtimes typically build the middleware list and the
+ * `RuntimeMiddlewareContext` themselves (running compatibility checks,
+ * narrowing the context's `contract` field, etc.) before calling `super`.
+ */
+export interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {
+  readonly middleware: ReadonlyArray<TMiddleware>;
+  readonly ctx: RuntimeMiddlewareContext;
+}
+
+/**
+ * Family-agnostic abstract runtime base.
+ *
+ * Defines the entire `execute(plan)` template in one place:
+ *
+ * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides
+ *    this to run its `beforeCompile` middleware-hook chain.
+ * 2. `lower(plan)` — abstract. Each family produces its `*ExecutionPlan`
+ *    (SQL via `lowerSqlPlan`, Mongo via `adapter.lower`).
+ * 3. `runWithMiddleware(exec, this.middleware, this.ctx,
+ *    () => runDriver(exec))` — concrete; lifts the middleware lifecycle
+ *    out of the family runtimes into the canonical helper.
+ *
+ * Concrete subclasses must implement `lower`, `runDriver`, and `close`.
+ *
+ * The class is generic over:
+ * - `TPlan` — the family's pre-lowering plan type.
+ * - `TExec` — the family's post-lowering (executable) plan type.
+ * - `TMiddleware` — the family's middleware type. Constrained to
+ *   `RuntimeMiddleware<TExec>` because `runWithMiddleware` invokes the
+ *   `beforeExecute` / `onRow` / `afterExecute` hooks with the lowered
+ *   `TExec`. (The spec/plan wording "RuntimeMiddleware<TPlan>" is
+ *   tightened to `<TExec>` here so the helper call typechecks; the
+ *   intent is unchanged — middleware sees the post-lowering plan.)
+ */
+export abstract class RuntimeCore<
+  TPlan extends QueryPlan,
+  TExec extends ExecutionPlan,
+  TMiddleware extends RuntimeMiddleware<TExec>,
+> implements RuntimeExecutor<TPlan>
+{
+  protected readonly middleware: ReadonlyArray<TMiddleware>;
+  protected readonly ctx: RuntimeMiddlewareContext;
+
+  constructor(options: RuntimeCoreOptions<TMiddleware>) {
+    this.middleware = options.middleware;
+    this.ctx = options.ctx;
+  }
+
+  /**
+   * Pre-lowering hook for plan rewriting. Defaults to identity. Subclasses
+   * may override to run a `beforeCompile` middleware chain (SQL does this
+   * to support typed AST rewrites — see `before-compile-chain.ts`).
+   */
+  protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan> {
+    return plan;
+  }
+
+  /**
+   * Lower a pre-lowering `TPlan` into the family's executable `TExec`.
+   * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo
+   * produces `{ command, ... }`.
+   *
+   * `ctx` carries per-query cancellation (and any future fields on
+   * `CodecCallContext`); concrete subclasses forward it to the
+   * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,
+   * Mongo's `resolveValue` in m3). The runtime allocates one ctx per
+   * `execute()` call and threads the same reference everywhere; the
+   * `signal` field inside may be `undefined`, but the ctx object itself
+   * is always present.
+   */
+  protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
+
+  /**
+   * Drive the underlying transport for a lowered `TExec`. Yields raw rows
+   * directly from the driver as `Record<string, unknown>`; codec decoding
+   * (if any) is the subclass's responsibility, applied by wrapping
+   * `execute()` rather than living inside this hook.
+   *
+   * The `Row` type parameter on `execute()` is satisfied by the caller via
+   * the plan's phantom `_row`; the runtime treats rows as opaque records
+   * here and trusts the caller's row typing.
+   */
+  protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;
+
+  abstract close(): Promise<void>;
+
+  execute<Row>(
+    plan: TPlan & { readonly _row?: Row },
+    options?: RuntimeExecuteOptions,
+  ): AsyncIterableResult<Row> {
+    const self = this;
+    const signal = options?.signal;
+    // One ctx per execute() call. The ctx object is always allocated; the
+    // `signal` field is only included when a signal was supplied (required
+    // under exactOptionalPropertyTypes — `{ signal: undefined }` would not
+    // satisfy `signal?: AbortSignal`).
+    const codecCtx: CodecCallContext = signal === undefined ? {} : { signal };
+
+    async function* generator(): AsyncGenerator<Row, void, unknown> {
+      // Pre-check the signal at entry so an already-aborted caller observes
+      // RUNTIME.ABORTED on the first `next()` without any work being done.
+      checkAborted(codecCtx, 'stream');
+
+      const compiled = await self.runBeforeCompile(plan);
+      const exec = await self.lower(compiled, codecCtx);
+      // The driver yields raw `Record<string, unknown>`; we cast to `Row` here.
+      // The Row contract is enforced by the caller via `plan._row`.
+      yield* runWithMiddleware<TExec, Row>(
+        exec,
+        self.middleware,
+        self.ctx,
+        () => self.runDriver(exec) as AsyncIterable<Row>,
+      );
+    }
+
+    return new AsyncIterableResult(generator());
+  }
+}

package/src/execution/runtime-error.ts

@@ -0,0 +1,83 @@
+export interface RuntimeErrorEnvelope extends Error {
+  readonly code: string;
+  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+
+/**
+ * Stable code emitted by the runtime when an in-flight `execute()`
+ * is cancelled via the per-query `AbortSignal`. The envelope's
+ * `details.phase` distinguishes where the abort was observed:
+ *
+ * - `'encode'` — abort fired during `encodeParams` (SQL) or
+ *   `resolveValue` (Mongo).
+ * - `'decode'` — abort fired during `decodeRow` / `decodeField`.
+ * - `'stream'` — abort fired between rows or before any codec call
+ *   (already-aborted at entry).
+ */
+export const RUNTIME_ABORTED = 'RUNTIME.ABORTED' as const;
+
+/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
+export type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';
+
+/**
+ * Type guard for the runtime-error envelope produced by `runtimeError`.
+ *
+ * Prefer this over duck-typing on `error.code` directly so consumers stay
+ * insulated from the envelope's internal shape.
+ */
+export function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof (error as { code?: unknown }).code === 'string' &&
+    'category' in error &&
+    'severity' in error
+  );
+}
+
+export function runtimeError(
+  code: string,
+  message: string,
+  details?: Record<string, unknown>,
+): RuntimeErrorEnvelope {
+  const error = new Error(message) as RuntimeErrorEnvelope;
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+
+  return Object.assign(error, {
+    code,
+    category: resolveCategory(code),
+    severity: 'error' as const,
+    message,
+    details,
+  });
+}
+
+function resolveCategory(code: string): RuntimeErrorEnvelope['category'] {
+  const prefix = code.split('.')[0] ?? 'RUNTIME';
+  switch (prefix) {
+    case 'PLAN':
+    case 'CONTRACT':
+    case 'LINT':
+    case 'BUDGET':
+      return prefix;
+    default:
+      return 'RUNTIME';
+  }
+}
+
+/**
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
+ * abort was observed (encode / decode / stream); cause carries `signal.reason`
+ * verbatim from the platform — native abort produces a `DOMException`,
+ * explicit `controller.abort(reason)` produces whatever the caller passed.
+ * No synthesis happens here.
+ */
+export function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope {
+  const envelope = runtimeError(RUNTIME_ABORTED, `Operation aborted during ${phase}`, { phase });
+  return Object.assign(envelope, { cause });
+}