@prisma-next/framework-components 0.7.0 → 0.8.0

package/src/execution/runtime-middleware.ts

@@ -58,6 +58,27 @@ export interface RuntimeMiddlewareContext {
    * cancels.
    */
   readonly signal?: AbortSignal;
+  /**
+   * Identifies the queryable scope this execution is running under.
+   *
+   * - `'runtime'` — top-level `runtime.execute(plan)`. The default scope
+   *   used by the standard read/write paths.
+   * - `'connection'` — `connection.execute(plan)` after
+   *   `runtime.connection()` checked out a connection from the pool.
+   * - `'transaction'` — `transaction.execute(plan)` inside an explicit
+   *   transaction, or a query routed through `withTransaction`.
+   *
+   * Middleware that should only act at the top level read this field to
+   * bypass non-runtime scopes. The cache middleware uses it to skip
+   * caching inside transactions (where read-after-write coherence is the
+   * caller's expectation) and dedicated connections (where the user has
+   * explicitly stepped outside the shared cache surface). Observers that
+   * don't care about the scope can ignore the field.
+   *
+   * Family runtimes populate this at context-construction time per
+   * scope. Existing middleware that ignore the field are unaffected.
+   */
+  readonly scope: 'runtime' | 'connection' | 'transaction';
 }
 
 export interface AfterExecuteResult {
@@ -201,6 +222,33 @@ export interface RuntimeMiddleware<
   ): Promise<void>;
 }
 
+/**
+ * Cross-family middleware — one that doesn't constrain `familyId` or
+ * `targetId` and is therefore compatible with any family runtime's
+ * middleware array (`SqlMiddleware[]`, `MongoMiddleware[]`, etc.).
+ *
+ * The intersection `RuntimeMiddleware & { familyId?: undefined; targetId?: undefined }`
+ * pins both optional properties to exactly `undefined` (intersecting
+ * `string | undefined` with `undefined` collapses to `undefined`). Under
+ * `exactOptionalPropertyTypes: true`, the plain `RuntimeMiddleware` shape
+ * — with `familyId?: string` — is *not* assignable to `SqlMiddleware`
+ * (which narrows `familyId?: 'sql'`) because `string` is wider than
+ * `'sql'`. Pinning the property to `undefined` makes the value a subtype
+ * of every narrowed variant: `undefined` extends both `'sql' | undefined`
+ * and `'mongo' | undefined`, so a `CrossFamilyMiddleware` value drops
+ * into a SQL or Mongo middleware slot without a cast.
+ *
+ * Cross-family middleware factories (`createCacheMiddleware`, future
+ * `audit` / OTel middleware) declare this as their return type so the
+ * cross-family typing is named once rather than re-spelled at every call
+ * site.
+ */
+export type CrossFamilyMiddleware<TPlan extends QueryPlan = QueryPlan> =
+  RuntimeMiddleware<TPlan> & {
+    readonly familyId?: undefined;
+    readonly targetId?: undefined;
+  };
+
 /**
  * Optional per-`execute` options accepted by every family runtime.
  *
@@ -212,6 +260,7 @@ export interface RuntimeMiddleware<
  */
 export interface RuntimeExecuteOptions {
   readonly signal?: AbortSignal;
+  readonly scope?: 'runtime' | 'connection' | 'transaction';
 }
 
 /**

package/src/exports/runtime.ts

@@ -1,3 +1,11 @@
+export type {
+  AnnotationHandle,
+  AnnotationValue,
+  DefineAnnotationOptions,
+  OperationKind,
+  ValidAnnotations,
+} from '../annotations';
+export { assertAnnotationsApplicable, defineAnnotation } from '../annotations';
 export { AsyncIterableResult } from '../execution/async-iterable-result';
 export { runBeforeExecuteChain } from '../execution/before-execute-chain';
 export type { ExecutionPlan, QueryPlan, ResultType } from '../execution/query-plan';
@@ -14,6 +22,7 @@ export {
 } from '../execution/runtime-error';
 export type {
   AfterExecuteResult,
+  CrossFamilyMiddleware,
   InterceptResult,
   ParamRefMutator,
   RuntimeExecuteOptions,
@@ -23,3 +32,5 @@ export type {
   RuntimeMiddlewareContext,
 } from '../execution/runtime-middleware';
 export { checkMiddlewareCompatibility } from '../execution/runtime-middleware';
+export type { LaneMetaBuilder, MetaBuilder } from '../meta-builder';
+export { createMetaBuilder } from '../meta-builder';

package/src/meta-builder.ts

@@ -0,0 +1,101 @@
+import {
+  type AnnotationValue,
+  assertAnnotationsApplicable,
+  type OperationKind,
+} from './annotations';
+
+/**
+ * Per-terminal meta configurator handed to user callbacks. The terminal's
+ * operation kind `K` is fixed by the terminal that constructed the builder;
+ * `annotate(...)` accepts only annotations whose declared `Kinds` include
+ * `K`.
+ *
+ * The conditional parameter type
+ * `K extends Kinds ? AnnotationValue<P, Kinds> : never` collapses to `never`
+ * for inapplicable annotations, surfacing the mismatch as a type error at
+ * the call site of `meta.annotate(...)`. No variadic-tuple inference is
+ * involved — TypeScript infers `Kinds` from the annotation argument and
+ * checks the conditional directly.
+ *
+ * The runtime gate inside `annotate` (via
+ * `assertAnnotationsApplicable`) catches cast / `any` / dynamic bypasses
+ * and throws `RUNTIME.ANNOTATION_INAPPLICABLE`.
+ *
+ * `annotate` returns the builder for chaining; the return value of the
+ * configurator callback is unused, so both block-body and expression-body
+ * callbacks compile.
+ *
+ * @example
+ * ```typescript
+ * await db.User.find({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+ * await db.User.create(input, (meta) => {
+ *   meta.annotate(auditAnnotation({ actor: 'system' }));
+ *   meta.annotate(otelAnnotation({ traceId }));
+ * });
+ * ```
+ */
+export interface MetaBuilder<K extends OperationKind> {
+  annotate<P, Kinds extends OperationKind>(
+    annotation: K extends Kinds ? AnnotationValue<P, Kinds> : never,
+  ): this;
+}
+
+/**
+ * Lane-side view of a meta builder. Extends the public `MetaBuilder<K>`
+ * surface with `annotations` so lane terminals can read the recorded map
+ * after invoking the user configurator.
+ *
+ * Lane terminals construct one of these via `createMetaBuilder(kind, terminalName)`,
+ * pass it to the user callback as `MetaBuilder<K>` (the narrower public
+ * view), then read `meta.annotations` to thread the recorded values into
+ * `plan.meta.annotations`.
+ */
+export interface LaneMetaBuilder<K extends OperationKind> extends MetaBuilder<K> {
+  readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
+}
+
+class MetaBuilderImpl<K extends OperationKind> implements LaneMetaBuilder<K> {
+  readonly #kind: K;
+  readonly #terminalName: string;
+  readonly #annotations = new Map<string, AnnotationValue<unknown, OperationKind>>();
+
+  constructor(kind: K, terminalName: string) {
+    this.#kind = kind;
+    this.#terminalName = terminalName;
+  }
+
+  get annotations(): ReadonlyMap<string, AnnotationValue<unknown, OperationKind>> {
+    return this.#annotations;
+  }
+
+  annotate<P, Kinds extends OperationKind>(
+    annotation: K extends Kinds ? AnnotationValue<P, Kinds> : never,
+  ): this {
+    // Inside the body, the conditional `K extends Kinds ? AnnotationValue<P, Kinds> : never`
+    // is opaque to TypeScript — it can't pick a branch without a concrete
+    // K. Widen to the structural shape so we can call into the runtime
+    // gate. The runtime gate (assertAnnotationsApplicable) is what
+    // catches cast bypasses where the conditional would have resolved to
+    // `never` had the type checker been allowed to specialise.
+    const value = annotation as AnnotationValue<unknown, OperationKind>;
+    assertAnnotationsApplicable([value], this.#kind, this.#terminalName);
+    this.#annotations.set(value.namespace, value);
+    return this;
+  }
+}
+
+/**
+ * Construct a lane-side meta builder for a terminal of operation kind `K`.
+ *
+ * Lane terminals call this with their `kind` (`'read'` or `'write'`) and a
+ * `terminalName` for error messages, hand the resulting builder to the
+ * user-supplied configurator callback (typed as `MetaBuilder<K>`, the
+ * narrower public view), and read `meta.annotations` afterwards to thread
+ * the recorded values into `plan.meta.annotations`.
+ */
+export function createMetaBuilder<K extends OperationKind>(
+  kind: K,
+  terminalName: string,
+): LaneMetaBuilder<K> {
+  return new MetaBuilderImpl(kind, terminalName);
+}