@prisma-next/sql-runtime 0.13.0-dev.2 → 0.13.0-dev.21

package/package.json

@@ -1,27 +1,27 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.13.0-dev.2",
+  "version": "0.13.0-dev.21",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.13.0-dev.2",
-    "@prisma-next/utils": "0.13.0-dev.2",
-    "@prisma-next/framework-components": "0.13.0-dev.2",
-    "@prisma-next/ids": "0.13.0-dev.2",
-    "@prisma-next/operations": "0.13.0-dev.2",
-    "@prisma-next/sql-contract": "0.13.0-dev.2",
-    "@prisma-next/sql-operations": "0.13.0-dev.2",
-    "@prisma-next/sql-relational-core": "0.13.0-dev.2",
+    "@prisma-next/contract": "0.13.0-dev.21",
+    "@prisma-next/utils": "0.13.0-dev.21",
+    "@prisma-next/framework-components": "0.13.0-dev.21",
+    "@prisma-next/ids": "0.13.0-dev.21",
+    "@prisma-next/operations": "0.13.0-dev.21",
+    "@prisma-next/sql-contract": "0.13.0-dev.21",
+    "@prisma-next/sql-operations": "0.13.0-dev.21",
+    "@prisma-next/sql-relational-core": "0.13.0-dev.21",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.13.0-dev.2",
-    "@prisma-next/tsconfig": "0.13.0-dev.2",
+    "@prisma-next/test-utils": "0.13.0-dev.21",
+    "@prisma-next/tsconfig": "0.13.0-dev.21",
     "@types/pg": "8.20.0",
     "pg": "8.21.0",
-    "@prisma-next/tsdown": "0.13.0-dev.2",
+    "@prisma-next/tsdown": "0.13.0-dev.21",
     "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/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-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),
-  });
-}