@prisma-next/sql-relational-core 0.5.0-dev.75 → 0.5.0-dev.77

package/src/middleware/param-ref-mutator.ts

@@ -0,0 +1,230 @@
+import type { ParamRefMutator } from '@prisma-next/framework-components/runtime';
+import type { SqlColumnRef } from '../ast/codec-types';
+import type { ParamRef } from '../ast/types';
+import { collectOrderedParamRefs } from '../ast/util';
+import type { SqlExecutionPlan } from '../sql-execution-plan';
+
+/**
+ * Brand applied to {@link ParamRefHandle} so user-constructed handles
+ * are rejected by the type system. The mutator only accepts handles it
+ * produced from `entries()`.
+ *
+ * The brand is a phantom type — there is no runtime token. At runtime
+ * the handle is the underlying `ParamRef` instance from the plan's
+ * `ast`; the brand only narrows the type-level surface so callers
+ * cannot fabricate a handle from a fresh `ParamRef.of(...)`.
+ */
+declare const paramRefHandleBrand: unique symbol;
+
+/**
+ * Opaque token identifying a single `ParamRef` in the plan. Produced by
+ * {@link SqlParamRefMutator.entries}; consumed by `replaceValue` /
+ * `replaceValues`.
+ *
+ * The phantom `TCodecId` parameter records the codec id of the
+ * referenced `ParamRef` so type-level inference can route replacement
+ * values through `TCodecMap` to the codec's declared `TInput`.
+ */
+export interface ParamRefHandle<TCodecId extends string | undefined = string | undefined> {
+  readonly [paramRefHandleBrand]: TCodecId;
+}
+
+/**
+ * One outbound `ParamRef` slot in the plan exposed to middleware.
+ * `value` is the current value (post any prior middleware mutations);
+ * `codecId` is the codec id declared on the underlying `ParamRef`;
+ * `column` is populated for `ParamRef`s the lowering site could resolve
+ * to a single `(table, column)` via `ParamRef.refs` (encode-side column
+ * metadata is the middleware's domain — encode itself currently leaves
+ * `ctx.column` unset).
+ */
+export interface ParamRefEntry<TCodecId extends string | undefined = string | undefined> {
+  readonly ref: ParamRefHandle<TCodecId>;
+  readonly value: unknown;
+  readonly codecId: TCodecId;
+  readonly column?: SqlColumnRef;
+}
+
+/**
+ * Discriminated entry union over a codec map. For each `K` in
+ * `TCodecMap`, `entries()` may yield a `ParamRefEntry<K>`; ParamRefs
+ * with no codec id (or a codec id outside the map) yield a
+ * `ParamRefEntry<undefined>`. Pattern-matching on `entry.codecId`
+ * narrows `entry.ref` to a `ParamRefHandle<K>`, which routes through
+ * the typed `replaceValue` overload.
+ */
+export type ParamRefEntryUnion<TCodecMap extends Record<string, unknown>> =
+  | { [K in keyof TCodecMap & string]: ParamRefEntry<K> }[keyof TCodecMap & string]
+  | ParamRefEntry<undefined>;
+
+/**
+ * SQL-family mutator threaded into `SqlMiddleware.beforeExecute` as
+ * `params`. Scope is `ParamRef.value` slots only — middleware cannot
+ * insert / remove `ParamRef`s, rewrite SQL, or modify projection. The
+ * type-level `ParamRefHandle` brand and the `replaceValue(ref,
+ * newValue)` shape enforce this at compile time.
+ *
+ * Allocation discipline: the mutator is constructed lazily from the
+ * plan. `entries()` walks the plan's existing AST without allocating
+ * an intermediate array; the working params buffer is only allocated
+ * on the first `replaceValue` / `replaceValues` call. If no middleware
+ * mutates, `currentParams()` returns the plan's original `params` by
+ * reference identity.
+ *
+ * The `TCodecMap` parameter is a record keyed by codec id; `replaceValue`
+ * infers `newValue` from `TCodecMap[H['codecId']]` for handles whose
+ * codec id is statically resolvable. For codec ids the type system
+ * cannot resolve, `newValue` falls back to `unknown` and the middleware
+ * is on the hook for runtime correctness.
+ */
+export interface SqlParamRefMutator<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+> extends ParamRefMutator {
+  /** Iterate every outbound `ParamRef` the plan currently carries, in canonical order. */
+  entries(): IterableIterator<ParamRefEntryUnion<TCodecMap>>;
+
+  /**
+   * Replace one `ParamRef`'s value with the result of bulk processing.
+   * `newValue` is constrained to the codec's declared `TInput` for codec
+   * ids the type system can resolve via `TCodecMap`; for unresolvable
+   * codec ids `newValue` is `unknown` (the second overload).
+   */
+  replaceValue<TCodecId extends keyof TCodecMap & string>(
+    ref: ParamRefHandle<TCodecId>,
+    newValue: TCodecMap[TCodecId],
+  ): void;
+  replaceValue(ref: ParamRefHandle<undefined>, newValue: unknown): void;
+
+  /** Replace many at once (typical for bulk-pattern middleware). */
+  replaceValues(
+    updates: Iterable<{
+      readonly ref: ParamRefHandle<(keyof TCodecMap & string) | undefined>;
+      readonly newValue: unknown;
+    }>,
+  ): void;
+}
+
+/**
+ * Internal-only view of the mutator that exposes the post-mutation params
+ * array to the SQL runtime. The runtime calls `currentParams()` after the
+ * `beforeExecute` chain has run; the result is the plan's original
+ * `params` by reference identity if no middleware mutated, otherwise a
+ * frozen new array carrying the mutations applied in chain order.
+ *
+ * Family-internal contract — `SqlMiddleware` consumers never see this
+ * shape; they receive the public `SqlParamRefMutator` view above.
+ */
+export interface SqlParamRefMutatorInternal<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+> extends SqlParamRefMutator<TCodecMap> {
+  currentParams(): readonly unknown[];
+}
+
+type AnyHandle = ParamRefHandle<string | undefined>;
+
+/**
+ * Build a {@link SqlParamRefMutatorInternal} for the given lowered plan.
+ *
+ * The mutator captures `plan.params` by reference and walks
+ * `plan.ast` (via `collectOrderedParamRefs`) on demand to build
+ * entries. Mutations write to a lazily-allocated working copy so the
+ * fast path (no mutation) preserves bit-for-bit reference identity to
+ * the original `plan.params`.
+ *
+ * Threading: `plan.ast` carries the canonical `ParamRef` ordering used
+ * by every consumer (renderer's `$N` index map, encode-side metadata
+ * walk, etc.). The mutator's `entries()` yields the same order so
+ * middleware that filters by codec id sees ParamRefs in the order the
+ * runtime will encode them.
+ */
+export function createSqlParamRefMutator<
+  TCodecMap extends Record<string, unknown> = Record<string, unknown>,
+>(plan: SqlExecutionPlan): SqlParamRefMutatorInternal<TCodecMap> {
+  const originalParams = plan.params;
+  const refs: ReadonlyArray<ParamRef> = plan.ast ? collectOrderedParamRefs(plan.ast) : [];
+  let workingParams: unknown[] | undefined;
+
+  const indexOfRef = (handle: AnyHandle): number => {
+    // The handle is the underlying ParamRef instance the mutator yielded
+    // from entries(); equality is identity equality on the ParamRef. The
+    // brand on ParamRefHandle is unforgeable from outside, so the only
+    // legal handles came from this mutator's entries().
+    return refs.indexOf(handle as unknown as ParamRef);
+  };
+
+  const ensureWorkingParams = (): unknown[] => {
+    if (!workingParams) {
+      workingParams = [...originalParams];
+    }
+    return workingParams;
+  };
+
+  const writeAt = (index: number, value: unknown): void => {
+    const buffer = ensureWorkingParams();
+    buffer[index] = value;
+  };
+
+  function* entries(): IterableIterator<ParamRefEntryUnion<TCodecMap>> {
+    const view = workingParams ?? originalParams;
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (!ref) continue;
+      const handle = ref as unknown as ParamRefHandle<string | undefined>;
+      const value = i < view.length ? view[i] : ref.value;
+      const codecId = ref.codecId;
+      // Surface the column binding the lowering site resolved onto
+      // `ParamRef.refs` so column-aware middleware (e.g. cipherstash
+      // routing-key resolution) can address the cell without
+      // re-walking the AST. ParamRefs without a column binding stay
+      // `column: undefined`.
+      const column = ref.refs
+        ? ({ table: ref.refs.table, name: ref.refs.column } as const)
+        : undefined;
+      // The runtime erases the discriminated union to a single shape; the
+      // public type pins each entry's `ref` to the matching `codecId`
+      // arm at compile time.
+      const entry: ParamRefEntry<string | undefined> = column
+        ? { ref: handle, value, codecId, column }
+        : { ref: handle, value, codecId };
+      yield entry as ParamRefEntryUnion<TCodecMap>;
+    }
+  }
+
+  function replaceValue(handle: AnyHandle, newValue: unknown): void {
+    const index = indexOfRef(handle);
+    if (index < 0) {
+      // Handle does not belong to this plan. The type system pins this
+      // at the brand level; this runtime check guards against handles
+      // smuggled across plans.
+      return;
+    }
+    writeAt(index, newValue);
+  }
+
+  function replaceValues(
+    updates: Iterable<{ readonly ref: AnyHandle; readonly newValue: unknown }>,
+  ): void {
+    for (const { ref, newValue } of updates) {
+      const index = indexOfRef(ref);
+      if (index < 0) continue;
+      writeAt(index, newValue);
+    }
+  }
+
+  // The public `SqlParamRefMutator` declares overloaded `replaceValue`
+  // signatures (typed-by-codec / unresolvable-codec). The implementation
+  // is one function with a permissive runtime signature; the cast is the
+  // single point at which the runtime function meets the typed overload
+  // surface, matching the overload-implementation pattern.
+  return {
+    entries,
+    replaceValue: replaceValue as SqlParamRefMutator<TCodecMap>['replaceValue'],
+    replaceValues,
+    currentParams(): readonly unknown[] {
+      if (!workingParams) {
+        return originalParams;
+      }
+      return Object.freeze([...workingParams]);
+    },
+  };
+}

package/src/plan.ts

@@ -1,4 +1,6 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type { QueryPlan } from '@prisma-next/framework-components/runtime';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { AnyQueryAst } from './ast/types';
 
 /**
@@ -18,3 +20,37 @@ export interface SqlQueryPlan<Row = unknown> extends QueryPlan<Row> {
   readonly ast: AnyQueryAst;
   readonly params: readonly unknown[];
 }
+
+/**
+ * Wraps an `AnyQueryAst` (typically a `RawSqlExpr` constructed package-internally
+ * by an extension's migration factory) in a fully-populated `SqlQueryPlan`
+ * whose `meta` is sourced from the supplied contract.
+ *
+ * Centralising the envelope here means consumers (cipherstash migration
+ * factories today; future raw-sql callers) cannot drift on `storageHash` /
+ * `target` / `targetFamily`, which would otherwise surface as a subtle
+ * `assertContractMatches` failure inside `dataTransform`. `params` defaults
+ * to `[]` because parameters embedded in the AST as `ParamRef`s are resolved
+ * at lowering time (`encodeParams` walks `plan.ast.collectParamRefs()`),
+ * not at plan-construction time.
+ *
+ * The default `laneId` of `'raw'` reflects raw-SQL plans' standard lane tag;
+ * callers (e.g. a future `sql-raw-factory`) may override to differentiate
+ * the plan's provenance.
+ */
+export function planFromAst<Row = unknown>(
+  ast: AnyQueryAst,
+  contract: Contract<SqlStorage>,
+  laneId = 'raw',
+): SqlQueryPlan<Row> {
+  return {
+    ast,
+    params: [],
+    meta: {
+      target: contract.target,
+      targetFamily: contract.targetFamily,
+      storageHash: contract.storage.storageHash,
+      lane: laneId,
+    },
+  };
+}

package/dist/plan-CZ6CFuSX.d.mts

@@ -1,24 +0,0 @@
-import { d as AnyQueryAst } from "./types-hwPoFZX2.mjs";
-import { QueryPlan } from "@prisma-next/framework-components/runtime";
-
-//#region src/plan.d.ts
-/**
- * SQL query plan produced by lanes before lowering.
- *
- * Lanes build ASTs and metadata but do not perform SQL lowering. The `sql`
- * field is absent — `RuntimeCore` (the runtime base class in
- * `@prisma-next/framework-components/runtime`) drives lowering via the
- * SQL adapter and produces a `SqlExecutionPlan`.
- *
- * Extends the framework-level `QueryPlan<Row>` marker (`meta + _row`) and
- * adds SQL-specific fields (`ast`, `params`). The phantom `_row` property
- * (inherited from `QueryPlan`) is what `ResultType<P>` inspects to recover
- * the row type.
- */
-interface SqlQueryPlan<Row = unknown> extends QueryPlan<Row> {
-  readonly ast: AnyQueryAst;
-  readonly params: readonly unknown[];
-}
-//#endregion
-export { SqlQueryPlan as t };
-//# sourceMappingURL=plan-CZ6CFuSX.d.mts.map

package/dist/plan-CZ6CFuSX.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plan-CZ6CFuSX.d.mts","names":[],"sources":["../src/plan.ts"],"mappings":";;;;;;AAgBA;;;;;;;;;;;UAAiB,YAAA,wBAAoC,SAAA,CAAU,GAAA;EAAA,SACpD,GAAA,EAAK,WAAA;EAAA,SACL,MAAA;AAAA"}

package/dist/query-lane-context-DaimN0zf.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"query-lane-context-DaimN0zf.d.mts","names":[],"sources":["../src/ast/codec-types.ts","../src/query-lane-context.ts"],"mappings":";;;;;;;;;;AAmBA;UAAiB,YAAA;EAAA,SACN,KAAA;EAAA,SACA,IAAA;AAAA;AAQX;;;;;AAAA,UAAiB,mBAAA,SAA4B,gBAAA;EAAA,SAClC,MAAA,GAAS,YAAA;AAAA;;AAYpB;;;;;;;;UAAiB,uBAAA,SAAgC,oBAAA;EAAA,SACtC,MAAA,EAAQ,aAAA;IAAA,SAAyB,KAAA;IAAA,SAAwB,MAAA;EAAA;AAAA;;;;UAMnD,SAAA;EAAA,SACN,EAAA;IAAA,SACE,GAAA;MAAA,SACE,QAAA;QAAA,SACE,UAAA;MAAA;IAAA;EAAA;AAAA;;;;;;;;UAaA,OAAA,sDAEU,UAAA,cAAwB,UAAA,+CAGzC,KAAA,CAAU,EAAA,EAAI,OAAA,EAAS,KAAA,EAAO,MAAA;EACtC,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,GAAA,EAAK,mBAAA,GAAsB,OAAA,CAAQ,KAAA;EACzD,MAAA,CAAO,IAAA,EAAM,KAAA,EAAO,GAAA,EAAK,mBAAA,GAAsB,OAAA,CAAQ,MAAA;AAAA;;;;;;;;;UAWxC,qBAAA;EAdf;;;EAkBA,SAAA,CAAU,KAAA,UAAe,MAAA,WAAiB,OAAA;EAjBX;;;;EAuB/B,UAAA,CAAW,OAAA,WAAkB,OAAA;AAAA;;;;;KAQnB,kBAAA,GAAqB,eAAA;AAAA,KAE5B,uBAAA,MACH,CAAA,SAAU,eAAA,aAA4B,UAAA,CAAW,UAAA,CAAW,CAAA;AAAA,KAElD,iBAAA,MAAuB,CAAA,SAAU,kBAAA,GAAqB,CAAA;AAAA,KAEtD,oBAAA,MACV,uBAAA,CAAwB,CAAA,UAAW,KAAA,kBAA2B,UAAA,yBAC1D,EAAA;;;;;AA3BN;;KAoCY,qBAAA,MAA2B,CAAA;EAAA,SAC5B,MAAA,iCAAuC,UAAA;AAAA,IAE9C,OAAA,WAAkB,UAAA;;;;;;KAQV,iBAAA,4CAEa,WAAA,GAAc,kBAAA,KACjC,MAAA,yCAEiB,WAAA,IAAe,iBAAA,CAAkB,WAAA,CAAY,CAAA;EAAA,SACvD,KAAA,EAAO,oBAAA,CAAqB,WAAA,CAAY,CAAA;EAAA,SACxC,MAAA,EAAQ,oBAAA,CAAqB,WAAA,CAAY,CAAA;EAAA,SACzC,MAAA,EAAQ,qBAAA,CAAsB,WAAA,CAAY,CAAA;AAAA;;;;AAxHvD;;UCViB,uBAAA;EDWN;;AASX;EChBE,aAAA,CAAc,OAAA,WAAkB,eAAA;;;;EAIhC,MAAA,IAAU,gBAAA,CAAiB,eAAA;EDaT;;;ECTlB,YAAA,CAAa,UAAA,oBAA8B,eAAA;AAAA;;;;KAMjC,kBAAA,GAAqB,MAAA;AAAA,KAErB,kBAAA;AAAA,KAEA,sBAAA;EAAA,SACD,MAAA;EAAA,SACA,KAAA;AAAA;AAAA,KAGC,uBAAA;EAAA,SACD,EAAA,EAAI,kBAAA;EAAA,SACJ,KAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EDWR;;;;EAAA,SCNA,iBAAA,GAAoB,GAAA;AAAA;ADsB/B;;;;;AAAA,UCdiB,gBAAA,mBAAmC,QAAA,CAAS,UAAA,IAAc,QAAA,CAAS,UAAA;EAAA,SACzE,QAAA,EAAU,SAAA;EDkBY;;;;EAAA,SCbtB,cAAA,EAAgB,qBAAA;EDcwB;;;EAAA,SCVxC,gBAAA,EAAkB,uBAAA;EAAA,SAClB,eAAA,EAAiB,oBAAA;EDQlB;;;EAAA,SCJC,KAAA,EAAO,kBAAA;EDChB;;;ECGA,qBAAA,CAAsB,OAAA,EAAS,uBAAA,GAA0B,aAAA,CAAc,sBAAA;AAAA"}