@prisma-next/sql-runtime 0.13.0-dev.3 → 0.13.0-dev.31

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.13.0-dev.3",
+  "version": "0.13.0-dev.31",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.13.0-dev.3",
-    "@prisma-next/utils": "0.13.0-dev.3",
-    "@prisma-next/framework-components": "0.13.0-dev.3",
-    "@prisma-next/ids": "0.13.0-dev.3",
-    "@prisma-next/operations": "0.13.0-dev.3",
-    "@prisma-next/sql-contract": "0.13.0-dev.3",
-    "@prisma-next/sql-operations": "0.13.0-dev.3",
-    "@prisma-next/sql-relational-core": "0.13.0-dev.3",
+    "@prisma-next/contract": "0.13.0-dev.31",
+    "@prisma-next/utils": "0.13.0-dev.31",
+    "@prisma-next/framework-components": "0.13.0-dev.31",
+    "@prisma-next/ids": "0.13.0-dev.31",
+    "@prisma-next/operations": "0.13.0-dev.31",
+    "@prisma-next/sql-contract": "0.13.0-dev.31",
+    "@prisma-next/sql-operations": "0.13.0-dev.31",
+    "@prisma-next/sql-relational-core": "0.13.0-dev.31",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.13.0-dev.3",
-    "@prisma-next/tsconfig": "0.13.0-dev.3",
+    "@prisma-next/test-utils": "0.13.0-dev.31",
+    "@prisma-next/tsconfig": "0.13.0-dev.31",
     "@types/pg": "8.20.0",
     "pg": "8.21.0",
-    "@prisma-next/tsdown": "0.13.0-dev.3",
+    "@prisma-next/tsdown": "0.13.0-dev.31",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8"

package/src/codecs/ast-codec-resolver.ts

@@ -1,4 +1,5 @@
 import type { CodecRef } from '@prisma-next/framework-components/codec';
+import { materializeCodec } from '@prisma-next/framework-components/codec';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
 import { canonicalizeJson } from '@prisma-next/framework-components/utils';
 import type { Codec, SqlCodecInstanceContext } from '@prisma-next/sql-relational-core/ast';
@@ -46,54 +47,11 @@ export function createAstCodecResolver(
         );
       }
 
-      // Parameterized codecs whose paramsSchema accepts `{}` (every field
-      // optional, e.g. `pg/timestamptz@1` precision) tolerate refs that omit
-      // `typeParams` entirely. Normalize `undefined` to `{}` at the validation
-      // boundary; the integrity check upstream already rejected refs whose
-      // schemas reject the empty object.
-      const validated = validateTypeParams(
-        descriptor.paramsSchema,
-        descriptor.isParameterized && ref.typeParams === undefined
-          ? { ...ref, typeParams: {} }
-          : ref,
-      );
       const ctx = instanceContextFor(ref);
-      // The descriptor's `factory` is typed against its own `P`; the registry erases `P` to `unknown`, so callers narrow per codec id at the dispatch boundary. The descriptor's `paramsSchema` validates the input above before we forward it, so this narrow is safe by construction.
-      const codec = (
-        descriptor.factory as (params: unknown) => (ctx: SqlCodecInstanceContext) => Codec
-      )(validated)(ctx);
+      const codec = materializeCodec(descriptor, ref, ctx);
 
       cache.set(key, codec);
       return codec;
     },
   };
 }
-
-function validateTypeParams(
-  paramsSchema: { '~standard': { validate: (input: unknown) => unknown } },
-  ref: CodecRef,
-): unknown {
-  const result = paramsSchema['~standard'].validate(ref.typeParams) as
-    | { value: unknown }
-    | { issues: ReadonlyArray<{ message: string }> }
-    | Promise<unknown>;
-
-  if (result instanceof Promise) {
-    throw runtimeError(
-      'RUNTIME.TYPE_PARAMS_INVALID',
-      `paramsSchema for codec '${ref.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`,
-      { codecId: ref.codecId, typeParams: ref.typeParams },
-    );
-  }
-
-  if ('issues' in result && result.issues) {
-    const messages = result.issues.map((issue) => issue.message).join('; ');
-    throw runtimeError(
-      'RUNTIME.TYPE_PARAMS_INVALID',
-      `Invalid typeParams for codec '${ref.codecId}': ${messages}`,
-      { codecId: ref.codecId, typeParams: ref.typeParams },
-    );
-  }
-
-  return (result as { value: unknown }).value;
-}

package/src/codecs/validation.ts

@@ -1,21 +1,13 @@
 import type { Contract } from '@prisma-next/contract/types';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
-import type { SqlStorage, StorageTable } from '@prisma-next/sql-contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { CodecDescriptorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
 
-// Framework `Namespace.tables` is widened to `Record<string, object>` so
-// emitted `contract.d.ts` table literals (which omit the optional `kind`
-// discriminator) satisfy it structurally. At runtime, every `SqlStorage`
-// namespace holds `StorageTable` instances — the constructor enforces it.
-// Narrowing per-iteration via a single-step cast (not `as unknown as`)
-// keeps Pattern C walks readable without weakening the substrate type.
-type SqlNamespaceTables = Readonly<Record<string, StorageTable>>;
-
 export function extractCodecIds(contract: Contract<SqlStorage>): Set<string> {
   const codecIds = new Set<string>();
 
   for (const ns of Object.values(contract.storage.namespaces)) {
-    for (const table of Object.values(ns.entries.table as SqlNamespaceTables)) {
+    for (const table of Object.values(ns.entries.table ?? {})) {
       for (const column of Object.values(table.columns)) {
         const codecId = column.codecId;
         codecIds.add(codecId);
@@ -26,37 +18,34 @@ export function extractCodecIds(contract: Contract<SqlStorage>): Set<string> {
   return codecIds;
 }
 
-function extractCodecIdsFromColumns(contract: Contract<SqlStorage>): Map<string, string> {
-  const codecIds = new Map<string, string>();
+type ColumnCodecRef = {
+  readonly namespaceId: string;
+  readonly table: string;
+  readonly column: string;
+  readonly codecId: string;
+};
 
-  for (const ns of Object.values(contract.storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table as SqlNamespaceTables)) {
+function extractColumnCodecRefs(contract: Contract<SqlStorage>): ColumnCodecRef[] {
+  const refs: ColumnCodecRef[] = [];
+
+  for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const [columnName, column] of Object.entries(table.columns)) {
-        const codecId = column.codecId;
-        const key = `${tableName}.${columnName}`;
-        codecIds.set(key, codecId);
+        refs.push({ namespaceId, table: tableName, column: columnName, codecId: column.codecId });
       }
     }
   }
 
-  return codecIds;
+  return refs;
 }
 
 export function validateContractCodecMappings(
   registry: CodecDescriptorRegistry,
   contract: Contract<SqlStorage>,
 ): void {
-  const codecIds = extractCodecIdsFromColumns(contract);
-  const invalidCodecs: Array<{ table: string; column: string; codecId: string }> = [];
-
-  for (const [key, codecId] of codecIds.entries()) {
-    if (registry.descriptorFor(codecId) === undefined) {
-      const parts = key.split('.');
-      const table = parts[0] ?? '';
-      const column = parts[1] ?? '';
-      invalidCodecs.push({ table, column, codecId });
-    }
-  }
+  const invalidCodecs = extractColumnCodecRefs(contract).filter(
+    (ref) => registry.descriptorFor(ref.codecId) === undefined,
+  );
 
   if (invalidCodecs.length > 0) {
     const details: Record<string, unknown> = {
@@ -66,7 +55,7 @@ export function validateContractCodecMappings(
 
     throw runtimeError(
       'RUNTIME.CODEC_MISSING',
-      `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.table}.${c.column} (${c.codecId})`).join(', ')}`,
+      `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.namespaceId}.${c.table}.${c.column} (${c.codecId})`).join(', ')}`,
       details,
     );
   }

package/src/exports/index.ts

@@ -16,6 +16,10 @@ export { budgets } from '../middleware/budgets';
 export type { LintsOptions } from '../middleware/lints';
 export { lints } from '../middleware/lints';
 export type { SqlMiddleware, SqlMiddlewareContext } from '../middleware/sql-middleware';
+export {
+  PreparedStatementImpl,
+  type PreparedStatementInternals,
+} from '../prepared/prepared-statement';
 export type {
   BindSiteParams,
   Declaration,
@@ -54,11 +58,11 @@ export {
   createSqlExecutionStack,
 } from '../sql-context';
 export type {
-  CreateRuntimeOptions,
+  ConnectionProvider,
   Runtime,
   RuntimeConnection,
   RuntimeQueryable,
   RuntimeTransaction,
   TransactionContext,
 } from '../sql-runtime';
-export { createRuntime, withTransaction } from '../sql-runtime';
+export { SqlRuntimeBase, withTransaction } from '../sql-runtime';

package/src/runtime-spi.ts

@@ -9,7 +9,7 @@ export interface MarkerReader {
 }
 
 /**
- * SQL family adapter SPI consumed by `SqlRuntime`. Encapsulates the
+ * SQL family adapter SPI consumed by `SqlRuntimeBase`. Encapsulates the
  * runtime contract, marker reader, and plan validation logic so the
  * runtime can be unit-tested without a concrete SQL adapter profile.
  *

package/src/sql-context.ts

@@ -27,11 +27,7 @@ import {
 } from '@prisma-next/framework-components/execution';
 import { runtimeError } from '@prisma-next/framework-components/runtime';
 import { canonicalizeJson } from '@prisma-next/framework-components/utils';
-import {
-  isPostgresEnumStorageEntry,
-  type SqlStorage,
-  type StorageTypeInstance,
-} from '@prisma-next/sql-contract/types';
+import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
 import { blindCast } from '@prisma-next/utils/casts';
 
 function documentScopedCodecTypes(
@@ -241,30 +237,6 @@ export function assertExecutionStackContractRequirements(
   }
 }
 
-/**
- * Resolves codec id + typeParams for a `SqlStorage.types` entry that
- * represents an enum. The canonical contract path always pipes raw JSON
- * through the `SqlStorage` constructor, which rejects raw
- * `kind: 'postgres-enum'` envelopes that bypass the per-target
- * `ContractSerializer.deserializeContract` hydration. By the time this
- * function runs, the entry is a live IR-class instance that
- * structurally satisfies `PostgresEnumStorageEntry` — `codecId` and
- * `values` are enumerable own properties on the instance. Returns
- * `undefined` when the entry is not enum-shaped, so callers fall
- * through to the codec-typed path.
- */
-function readEnumViewIfApplicable(
-  typeInstance: unknown,
-): { readonly codecId: string; readonly typeParams: Record<string, unknown> } | undefined {
-  if (!isPostgresEnumStorageEntry(typeInstance)) {
-    return undefined;
-  }
-  return {
-    codecId: typeInstance.codecId,
-    typeParams: { values: typeInstance.values },
-  };
-}
-
 function validateTypeParams(
   typeParams: Record<string, unknown>,
   descriptor: RuntimeParameterizedCodecDescriptor,
@@ -335,7 +307,7 @@ function collectTypeRefSites(
 ): Map<string, Array<{ readonly table: string; readonly column: string }>> {
   const sites = new Map<string, Array<{ readonly table: string; readonly column: string }>>();
   for (const ns of Object.values(storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const [columnName, column] of Object.entries(table.columns)) {
         if (typeof column.typeRef !== 'string') continue;
         const list = sites.get(column.typeRef);
@@ -365,11 +337,8 @@ function initializeTypeHelpers(
   const typeRefSites = collectTypeRefSites(storage);
 
   for (const [typeName, typeInstance] of Object.entries(documentTypes)) {
-    const enumView = readEnumViewIfApplicable(typeInstance);
-    const codecId = enumView ? enumView.codecId : (typeInstance as StorageTypeInstance).codecId;
-    const typeParams = enumView
-      ? enumView.typeParams
-      : (typeInstance as StorageTypeInstance).typeParams;
+    const codecId = typeInstance.codecId;
+    const typeParams = typeInstance.typeParams;
     const descriptor = codecDescriptors.get(codecId);
 
     if (!descriptor) {
@@ -397,7 +366,7 @@ function validateColumnTypeParams(
   codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
 ): void {
   for (const ns of Object.values(storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const [columnName, column] of Object.entries(table.columns)) {
         if (column.typeParams) {
           const descriptor = codecDescriptors.get(column.codecId);
@@ -426,7 +395,7 @@ function assertColumnCodecIntegrity(
   codecDescriptors: CodecDescriptorRegistry,
 ): void {
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const columnName of Object.keys(table.columns)) {
         const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
         if (!ref) continue;
@@ -533,25 +502,15 @@ function buildContractCodecRegistry(
 
   const typeRefSites = collectTypeRefSites(contract.storage);
   for (const [typeName, typeInstance] of Object.entries(documentScopedCodecTypes(contract) ?? {})) {
-    const enumView = readEnumViewIfApplicable(typeInstance);
-    const instanceTypeParams = enumView
-      ? enumView.typeParams
-      : (typeInstance as StorageTypeInstance).typeParams;
+    const instanceTypeParams = typeInstance.typeParams;
     const hasParamKeys =
       instanceTypeParams !== undefined && Object.keys(instanceTypeParams).length > 0;
-    const ref: CodecRef = enumView
-      ? hasParamKeys
-        ? {
-            codecId: enumView.codecId,
-            typeParams: instanceTypeParams as unknown as JsonValue,
-          }
-        : { codecId: enumView.codecId }
-      : hasParamKeys
-        ? {
-            codecId: (typeInstance as StorageTypeInstance).codecId,
-            typeParams: instanceTypeParams as JsonValue,
-          }
-        : { codecId: (typeInstance as StorageTypeInstance).codecId };
+    const ref: CodecRef = hasParamKeys
+      ? {
+          codecId: typeInstance.codecId,
+          typeParams: instanceTypeParams as JsonValue,
+        }
+      : { codecId: typeInstance.codecId };
     const key = refKeyOf(ref);
     const sites = typeRefSites.get(typeName) ?? [];
     const existing = usedAtByKey.get(key);
@@ -565,7 +524,7 @@ function buildContractCodecRegistry(
   }
 
   for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const [columnName, column] of Object.entries(table.columns)) {
         if (column.typeRef !== undefined) continue;
         const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
@@ -597,7 +556,7 @@ function buildContractCodecRegistry(
   });
 
   for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) {
-    for (const [tableName, table] of Object.entries(ns.entries.table)) {
+    for (const [tableName, table] of Object.entries(ns.entries.table ?? {})) {
       for (const columnName of Object.keys(table.columns)) {
         const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
         if (!ref) continue;

package/src/sql-runtime.ts

@@ -1,8 +1,4 @@
 import type { Contract } from '@prisma-next/contract/types';
-import type {
-  ExecutionStackInstance,
-  RuntimeDriverInstance,
-} from '@prisma-next/framework-components/execution';
 import {
   AsyncIterableResult,
   checkAborted,
@@ -23,6 +19,7 @@ import type {
   LoweredStatement,
   PreparedExecuteRequest,
   SqlCodecCallContext,
+  SqlConnection,
   SqlDriver,
   SqlQueryable,
   SqlTransaction,
@@ -64,11 +61,7 @@ import type {
   TelemetryOutcome,
   VerifyMarkerOption,
 } from './runtime-spi';
-import type {
-  ExecutionContext,
-  SqlRuntimeAdapterInstance,
-  SqlRuntimeExtensionInstance,
-} from './sql-context';
+import type { ExecutionContext } from './sql-context';
 import { SqlFamilyAdapter } from './sql-family-adapter';
 
 export type Log = RuntimeLog;
@@ -83,25 +76,10 @@ export interface RuntimeOptions<TContract extends Contract<SqlStorage> = Contrac
   readonly log?: Log;
 }
 
-export interface CreateRuntimeOptions<
-  TContract extends Contract<SqlStorage> = Contract<SqlStorage>,
-  TTargetId extends string = string,
-> {
-  readonly stackInstance: ExecutionStackInstance<
-    'sql',
-    TTargetId,
-    SqlRuntimeAdapterInstance<TTargetId>,
-    RuntimeDriverInstance<'sql', TTargetId>,
-    SqlRuntimeExtensionInstance<TTargetId>
-  >;
-  readonly context: ExecutionContext<TContract>;
-  readonly driver: SqlDriver<unknown>;
-  readonly verifyMarker?: VerifyMarkerOption;
-  readonly middleware?: readonly SqlMiddleware[];
-  readonly mode?: 'strict' | 'permissive';
-  readonly log?: Log;
-}
-
+/**
+ * SQL-family runtime interface. Named `Runtime` (not `SqlRuntime`) by deliberate exception
+ * to avoid a repo-wide rename; see ADR 230 (runtime target layer) for the recorded decision.
+ */
 export interface Runtime extends RuntimeQueryable {
   connection(): Promise<RuntimeConnection>;
   telemetry(): RuntimeTelemetryEvent | null;
@@ -167,7 +145,12 @@ function isExecutionPlan(plan: SqlExecutionPlan | SqlQueryPlan): plan is SqlExec
 const noopLogSink = (): void => {};
 const noopLog: Log = { info: noopLogSink, warn: noopLogSink, error: noopLogSink };
 
-class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>
+/**
+ * Abstract family-layer base for SQL runtimes. Subclass to build a target runtime
+ * (e.g. `PostgresRuntimeImpl`); app code should consume the `Runtime` interface returned
+ * by the target factories, never this class directly.
+ */
+export abstract class SqlRuntimeBase<TContract extends Contract<SqlStorage> = Contract<SqlStorage>>
   extends RuntimeCore<SqlQueryPlan, SqlExecutionPlan, SqlMiddleware>
   implements Runtime
 {
@@ -325,6 +308,16 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     );
   }
 
+  /**
+   * Returns the raw driver connection. The connection is a `SqlQueryable` — SQL
+   * issued on it runs below the middleware/codec/telemetry pipeline. It carries
+   * its own lifecycle (`release`/`destroy`/`beginTransaction`); the caller owns
+   * disposal.
+   */
+  protected acquireRawConnection(): Promise<SqlConnection> {
+    return this.driver.acquireConnection();
+  }
+
   private async *streamRows<Row>(
     exec: SqlExecutionPlan,
     decodeContext: DecodeContext,
@@ -385,7 +378,12 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     }
   }
 
-  private executeAgainstQueryable<Row>(
+  /**
+   * Execute a plan against a caller-supplied queryable, running the full
+   * middleware/codec/telemetry pipeline. Use `acquireRawConnection` to obtain a
+   * queryable that subclasses can bind typed plans to.
+   */
+  protected executeAgainstQueryable<Row>(
     plan: SqlExecutionPlan<unknown> | SqlQueryPlan<unknown>,
     queryable: SqlQueryable,
     options?: RuntimeExecuteOptions,
@@ -526,7 +524,11 @@ class SqlRuntimeImpl<TContract extends Contract<SqlStorage> = Contract<SqlStorag
     return new PreparedStatementImpl<ParamsFromDeclaration<D, CT>, Row>(internals);
   }
 
-  private executePreparedAgainstQueryable<P, Row>(
+  /**
+   * Execute a prepared statement against a caller-supplied queryable, running
+   * the full middleware/codec/telemetry pipeline.
+   */
+  protected executePreparedAgainstQueryable<P, Row>(
     ps: PreparedStatementImpl<P, Row>,
     userParams: Record<string, unknown>,
     queryable: SqlQueryable,
@@ -753,8 +755,13 @@ function transactionClosedError(): Error {
   );
 }
 
+/** Minimal structural type `withTransaction` depends on — anything that can open a connection. */
+export interface ConnectionProvider {
+  connection(): Promise<RuntimeConnection>;
+}
+
 export async function withTransaction<R>(
-  runtime: Runtime,
+  runtime: ConnectionProvider,
   fn: (tx: TransactionContext) => PromiseLike<R>,
 ): Promise<R> {
   const connection = await runtime.connection();
@@ -859,19 +866,3 @@ export async function withTransaction<R>(
     }
   }
 }
-
-export function createRuntime<TContract extends Contract<SqlStorage>, TTargetId extends string>(
-  options: CreateRuntimeOptions<TContract, TTargetId>,
-): Runtime {
-  const { stackInstance, context, driver, verifyMarker, middleware, mode, log } = options;
-
-  return new SqlRuntimeImpl({
-    context,
-    adapter: stackInstance.adapter,
-    driver,
-    ...ifDefined('verifyMarker', verifyMarker),
-    ...ifDefined('middleware', middleware),
-    ...ifDefined('mode', mode),
-    ...ifDefined('log', log),
-  });
-}