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

package/README.md

@@ -41,52 +41,31 @@ Execute SQL query Plans with deterministic verification, guardrails, and feedbac
 
 ## Usage
 
-```typescript
-import postgresAdapter from '@prisma-next/adapter-postgres/runtime';
-import postgresDriver from '@prisma-next/driver-postgres/runtime';
-import pgvector from '@prisma-next/extension-pgvector/runtime';
-import postgresTarget from '@prisma-next/target-postgres/runtime';
-import { instantiateExecutionStack } from '@prisma-next/framework-components/execution';
-import {
-  budgets,
-  createExecutionContext,
-  createRuntime,
-  createSqlExecutionStack,
-} from '@prisma-next/sql-runtime';
-
-const contract = postgresTarget.contractSerializer.deserializeContract(contractJson);
-const stack = createSqlExecutionStack({
-  target: postgresTarget,
-  adapter: postgresAdapter,
-  driver: postgresDriver,
-  extensionPacks: [pgvector],
-});
+`SqlRuntime` is an abstract base class. Construct a runtime via the target factory — `postgres()` from `@prisma-next/postgres` or `sqlite()` from `@prisma-next/sqlite`. You do not call `new SqlRuntime()` directly.
 
-// Static context (no instantiation needed)
-const context = createExecutionContext({ contract, stack });
-
-// Dynamic runtime
-const stackInstance = instantiateExecutionStack(stack);
-const driver = stack.driver.create({ connect: { connectionString: process.env.DATABASE_URL } });
-const runtime = createRuntime({
-  stackInstance,
-  context,
-  driver,
+```typescript
+import postgres from '@prisma-next/postgres';
+import { budgets } from '@prisma-next/sql-runtime';
+import type { Contract } from './src/contract';
+import contractJson from './src/contract.json' with { type: 'json' };
+
+const db = postgres<Contract>({
+  contractJson,
+  url: process.env.DATABASE_URL,
   middleware: [budgets()],
 });
 
-for await (const row of runtime.execute(plan)) {
+for await (const row of db.runtime().execute(plan)) {
   console.log(row);
 }
 ```
 
-Use `verifyMarker: false` to skip the marker read entirely — e.g. during a known-skewed deploy window where contract drift is expected and tolerated.
+Pass `verifyMarker: false` to skip the marker read entirely — e.g. during a known-skewed deploy window where contract drift is expected and tolerated.
 
 ```typescript
-const runtime = createRuntime({
-  stackInstance,
-  context,
-  driver,
+const db = postgres<Contract>({
+  contractJson,
+  url: process.env.DATABASE_URL,
   verifyMarker: false,
   middleware: [budgets()],
 });
@@ -96,9 +75,9 @@ const runtime = createRuntime({
 
 ### Runtime
 
-- `createRuntime` - Create a SQL runtime instance
-- `Runtime` - Runtime instance type
-- `CreateRuntimeOptions` - Options for `createRuntime`
+- `SqlRuntime` - Abstract family-layer base class; subclass to build a target runtime (construction happens via target factories — `postgres()` from `@prisma-next/postgres`, `sqlite()` from `@prisma-next/sqlite`)
+- `Runtime` - Runtime instance interface
+- `withTransaction` - Helper to run a callback inside a transaction against any `Runtime`
 - `VerifyMarkerOption` - Marker-verification option (`'onFirstUse'` default; `false` to skip)
 - `RuntimeTelemetryEvent`, `TelemetryOutcome` - Telemetry event types
 
@@ -159,10 +138,12 @@ The `lints` middleware operates on `plan.ast` when it is a SQL `QueryAst`:
 When `plan.ast` is missing, the middleware falls back to raw heuristic guardrails (`fallbackWhenAstMissing: 'raw'`) or skips linting (`fallbackWhenAstMissing: 'skip'`). Default is `'raw'`.
 
 ```typescript
-import { createRuntime, lints } from '@prisma-next/sql-runtime';
+import postgres from '@prisma-next/postgres';
+import { lints } from '@prisma-next/sql-runtime';
 
-const runtime = createRuntime({
-  // ...
+const db = postgres<Contract>({
+  contractJson,
+  url: process.env.DATABASE_URL,
   middleware: [lints({ severities: { noLimit: 'error' } })],
 });
 ```
@@ -175,7 +156,7 @@ The SQL runtime extends the abstract `RuntimeCore` base class from `@prisma-next
 2. **SqlStaticContributions**: Codecs, operation signatures, parameterized codecs, and mutation default generators contributed by each descriptor
 3. **ExecutionContext**: Built from contract + stack descriptors (no instantiation)
 4. **ExecutionStackInstance**: Instantiated components used at runtime for execution
-5. **SqlRuntime**: `class SqlRuntimeImpl extends RuntimeCore<SqlQueryPlan, SqlExecutionPlan, SqlMiddleware>` — overrides `lower` (with codec param-encoding), `runDriver`, `runBeforeCompile` (delegates to the SQL `beforeCompile` chain), and `close`. The execution path also wraps the `runWithMiddleware` helper from `framework-components/runtime` with codec row-decoding, marker verification (via the `RuntimeFamilyAdapter` defined in `runtime-spi.ts`), and telemetry fingerprinting (via `computeSqlFingerprint` from `fingerprint.ts`).
+5. **SqlRuntime**: `class SqlRuntime extends RuntimeCore<SqlQueryPlan, SqlExecutionPlan, SqlMiddleware>` — overrides `lower` (with codec param-encoding), `runDriver`, `runBeforeCompile` (delegates to the SQL `beforeCompile` chain), and `close`. The execution path also wraps the `runWithMiddleware` helper from `framework-components/runtime` with codec row-decoding, marker verification (via the `RuntimeFamilyAdapter` defined in `runtime-spi.ts`), and telemetry fingerprinting (via `computeSqlFingerprint` from `fingerprint.ts`).
 6. **SqlMarker**: Provides SQL statements for marker management
 
 ```mermaid

package/dist/{exports-DDqF-xmg.mjs → exports-DJWGwqMq.mjs}

@@ -1,10 +1,10 @@
+import { materializeCodec } from "@prisma-next/framework-components/codec";
 import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
 import { canonicalizeJson } from "@prisma-next/framework-components/utils";
 import { PreparedParamRef, collectOrderedParamRefs, isQueryAst } from "@prisma-next/sql-relational-core/ast";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { checkContractComponentRequirements, mergeCapabilityMatrices } from "@prisma-next/framework-components/components";
 import { createExecutionStack } from "@prisma-next/framework-components/execution";
-import { isPostgresEnumStorageEntry } from "@prisma-next/sql-contract/types";
 import { blindCast } from "@prisma-next/utils/casts";
 import { createSqlOperationRegistry } from "@prisma-next/sql-operations";
 import { buildCodecDescriptorRegistry } from "@prisma-next/sql-relational-core/codec-descriptor-registry";
@@ -26,31 +26,11 @@ function createAstCodecResolver(descriptors, instanceContextFor) {
 		if (cached) return cached;
 		const descriptor = descriptors.descriptorFor(ref.codecId);
 		if (!descriptor) throw runtimeError("RUNTIME.CODEC_DESCRIPTOR_MISSING", `No codec descriptor registered for codecId '${ref.codecId}'.`, { codecId: ref.codecId });
-		const validated = validateTypeParams$1(descriptor.paramsSchema, descriptor.isParameterized && ref.typeParams === void 0 ? {
-			...ref,
-			typeParams: {}
-		} : ref);
-		const ctx = instanceContextFor(ref);
-		const codec = descriptor.factory(validated)(ctx);
+		const codec = materializeCodec(descriptor, ref, instanceContextFor(ref));
 		cache.set(key, codec);
 		return codec;
 	} };
 }
-function validateTypeParams$1(paramsSchema, ref) {
-	const result = paramsSchema["~standard"].validate(ref.typeParams);
-	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.value;
-}
 //#endregion
 //#region src/codecs/ast-codec-registry.ts
 /**
@@ -137,40 +117,30 @@ async function encodeParamsWithMetadata(values, metadata, ctx, contractCodecs) {
 //#region src/codecs/validation.ts
 function extractCodecIds(contract) {
 	const codecIds = /* @__PURE__ */ new Set();
-	for (const ns of Object.values(contract.storage.namespaces)) for (const table of Object.values(ns.entries.table)) for (const column of Object.values(table.columns)) {
+	for (const ns of Object.values(contract.storage.namespaces)) for (const table of Object.values(ns.entries.table ?? {})) for (const column of Object.values(table.columns)) {
 		const codecId = column.codecId;
 		codecIds.add(codecId);
 	}
 	return codecIds;
 }
-function extractCodecIdsFromColumns(contract) {
-	const codecIds = /* @__PURE__ */ new Map();
-	for (const ns of Object.values(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);
-	}
-	return codecIds;
+function extractColumnCodecRefs(contract) {
+	const refs = [];
+	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)) refs.push({
+		namespaceId,
+		table: tableName,
+		column: columnName,
+		codecId: column.codecId
+	});
+	return refs;
 }
 function validateContractCodecMappings(registry, contract) {
-	const codecIds = extractCodecIdsFromColumns(contract);
-	const invalidCodecs = [];
-	for (const [key, codecId] of codecIds.entries()) if (registry.descriptorFor(codecId) === void 0) {
-		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) === void 0);
 	if (invalidCodecs.length > 0) {
 		const details = {
 			contractTarget: contract.target,
 			invalidCodecs
 		};
-		throw runtimeError("RUNTIME.CODEC_MISSING", `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.table}.${c.column} (${c.codecId})`).join(", ")}`, details);
+		throw runtimeError("RUNTIME.CODEC_MISSING", `Missing codec implementations for column codecIds: ${invalidCodecs.map((c) => `${c.namespaceId}.${c.table}.${c.column} (${c.codecId})`).join(", ")}`, details);
 	}
 }
 function validateCodecRegistryCompleteness(registry, contract) {
@@ -472,6 +442,28 @@ function lints(options) {
 	});
 }
 //#endregion
+//#region src/prepared/prepared-statement.ts
+var PreparedStatementImpl = class {
+	sql;
+	ast;
+	meta;
+	slots;
+	decodeContext;
+	paramMetadata;
+	constructor(internals) {
+		this.sql = internals.sql;
+		this.ast = internals.ast;
+		this.meta = internals.meta;
+		this.slots = internals.slots;
+		this.decodeContext = internals.decodeContext;
+		this.paramMetadata = internals.paramMetadata;
+		Object.freeze(this);
+	}
+	execute(target, params, options) {
+		return target.executePrepared(this, params, options);
+	}
+};
+//#endregion
 //#region src/sql-context.ts
 function documentScopedCodecTypes(contract) {
 	return blindCast(contract.storage.types);
@@ -509,25 +501,6 @@ function assertExecutionStackContractRequirements(contract, stack) {
 		throw runtimeError("RUNTIME.MISSING_EXTENSION_PACK", `Contract requires extension pack(s) ${packIds.map((id) => `'${id}'`).join(", ")}, but runtime descriptors do not provide matching component(s).`, { packIds });
 	}
 }
-/**
-* 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) {
-	if (!isPostgresEnumStorageEntry(typeInstance)) return;
-	return {
-		codecId: typeInstance.codecId,
-		typeParams: { values: typeInstance.values }
-	};
-}
 function validateTypeParams(typeParams, descriptor, context) {
 	const result = descriptor.paramsSchema["~standard"].validate(typeParams);
 	if (result instanceof Promise) throw runtimeError("RUNTIME.TYPE_PARAMS_INVALID", `paramsSchema for codec '${descriptor.codecId}' returned a Promise; runtime validation requires a synchronous Standard Schema validator.`, {
@@ -567,7 +540,7 @@ function collectCodecDescriptors(contributors) {
 }
 function collectTypeRefSites(storage) {
 	const sites = /* @__PURE__ */ new Map();
-	for (const ns of Object.values(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table)) for (const [columnName, column] of Object.entries(table.columns)) {
+	for (const ns of Object.values(storage.namespaces)) 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);
 		const entry = {
@@ -584,9 +557,8 @@ function initializeTypeHelpers(storage, documentTypes, codecDescriptors) {
 	if (!documentTypes) return helpers;
 	const typeRefSites = collectTypeRefSites(storage);
 	for (const [typeName, typeInstance] of Object.entries(documentTypes)) {
-		const enumView = readEnumViewIfApplicable(typeInstance);
-		const codecId = enumView ? enumView.codecId : typeInstance.codecId;
-		const typeParams = enumView ? enumView.typeParams : typeInstance.typeParams;
+		const codecId = typeInstance.codecId;
+		const typeParams = typeInstance.typeParams;
 		const descriptor = codecDescriptors.get(codecId);
 		if (!descriptor) {
 			helpers[typeName] = typeInstance;
@@ -602,7 +574,7 @@ function initializeTypeHelpers(storage, documentTypes, codecDescriptors) {
 	return helpers;
 }
 function validateColumnTypeParams(storage, codecDescriptors) {
-	for (const ns of Object.values(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table)) for (const [columnName, column] of Object.entries(table.columns)) if (column.typeParams) {
+	for (const ns of Object.values(storage.namespaces)) 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);
 		if (descriptor) validateTypeParams(column.typeParams, descriptor, {
 			tableName,
@@ -622,7 +594,7 @@ function validateColumnTypeParams(storage, codecDescriptors) {
 * Runs unconditionally from `createExecutionContext` so contract bugs fail fast at construction time instead of silently skipping affected columns in the codec registry's pre-population walk.
 */
 function assertColumnCodecIntegrity(storage, codecDescriptors) {
-	for (const [namespaceId, ns] of Object.entries(storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table)) for (const columnName of Object.keys(table.columns)) {
+	for (const [namespaceId, ns] of Object.entries(storage.namespaces)) 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;
 		const descriptor = codecDescriptors.descriptorFor(ref.codecId);
@@ -682,13 +654,8 @@ function buildContractCodecRegistry(contract, codecDescriptors) {
 	const nameByKey = /* @__PURE__ */ new Map();
 	const typeRefSites = collectTypeRefSites(contract.storage);
 	for (const [typeName, typeInstance] of Object.entries(documentScopedCodecTypes(contract) ?? {})) {
-		const enumView = readEnumViewIfApplicable(typeInstance);
-		const instanceTypeParams = enumView ? enumView.typeParams : typeInstance.typeParams;
-		const hasParamKeys = instanceTypeParams !== void 0 && Object.keys(instanceTypeParams).length > 0;
-		const key = refKeyOf(enumView ? hasParamKeys ? {
-			codecId: enumView.codecId,
-			typeParams: instanceTypeParams
-		} : { codecId: enumView.codecId } : hasParamKeys ? {
+		const instanceTypeParams = typeInstance.typeParams;
+		const key = refKeyOf(instanceTypeParams !== void 0 && Object.keys(instanceTypeParams).length > 0 ? {
 			codecId: typeInstance.codecId,
 			typeParams: instanceTypeParams
 		} : { codecId: typeInstance.codecId });
@@ -700,7 +667,7 @@ function buildContractCodecRegistry(contract, codecDescriptors) {
 			nameByKey.set(key, typeName);
 		}
 	}
-	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)) {
+	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)) {
 		if (column.typeRef !== void 0) continue;
 		const ref = codecDescriptors.codecRefForColumn(namespaceId, tableName, columnName);
 		if (!ref) continue;
@@ -724,7 +691,7 @@ function buildContractCodecRegistry(contract, codecDescriptors) {
 			usedAt: usedAtByKey.get(key) ?? []
 		};
 	});
-	for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) for (const [tableName, table] of Object.entries(ns.entries.table)) for (const columnName of Object.keys(table.columns)) {
+	for (const [namespaceId, ns] of Object.entries(contract.storage.namespaces)) 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;
 		resolver.forCodecRef(ref);
@@ -1134,28 +1101,6 @@ function resolvePreparedSlotValues(ps, userParams) {
 	});
 }
 //#endregion
-//#region src/prepared/prepared-statement.ts
-var PreparedStatementImpl = class {
-	sql;
-	ast;
-	meta;
-	slots;
-	decodeContext;
-	paramMetadata;
-	constructor(internals) {
-		this.sql = internals.sql;
-		this.ast = internals.ast;
-		this.meta = internals.meta;
-		this.slots = internals.slots;
-		this.decodeContext = internals.decodeContext;
-		this.paramMetadata = internals.paramMetadata;
-		Object.freeze(this);
-	}
-	execute(target, params, options) {
-		return target.executePrepared(this, params, options);
-	}
-};
-//#endregion
 //#region src/sql-family-adapter.ts
 var SqlFamilyAdapter = class {
 	contract;
@@ -1187,7 +1132,12 @@ const noopLog = {
 	warn: noopLogSink,
 	error: noopLogSink
 };
-var SqlRuntimeImpl = class extends RuntimeCore {
+/**
+* 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.
+*/
+var SqlRuntimeBase = class extends RuntimeCore {
 	contract;
 	adapter;
 	driver;
@@ -1305,6 +1255,15 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	executePrepared(ps, params, options) {
 		return this.executePreparedAgainstQueryable(ps, params, this.driver, options);
 	}
+	/**
+	* 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.
+	*/
+	acquireRawConnection() {
+		return this.driver.acquireConnection();
+	}
 	async *streamRows(exec, decodeContext, driverCall, codecCtx, execMiddlewareCtx) {
 		this.familyAdapter.validatePlan(exec, this.contract);
 		this._telemetry = null;
@@ -1332,6 +1291,11 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 			if (outcome !== null) this.recordTelemetry(exec, outcome, Date.now() - startedAt);
 		}
 	}
+	/**
+	* 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.
+	*/
 	executeAgainstQueryable(plan, queryable, options) {
 		this.ensureCodecRegistryValidated();
 		const self = this;
@@ -1400,6 +1364,10 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 			paramMetadata
 		}));
 	}
+	/**
+	* Execute a prepared statement against a caller-supplied queryable, running
+	* the full middleware/codec/telemetry pipeline.
+	*/
 	executePreparedAgainstQueryable(ps, userParams, queryable, options) {
 		this.ensureCodecRegistryValidated();
 		const self = this;
@@ -1618,19 +1586,7 @@ async function withTransaction(runtime, fn) {
 		if (!connectionDisposed) await connection.release();
 	}
 }
-function createRuntime(options) {
-	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)
-	});
-}
 //#endregion
-export { lints as a, extractCodecIds as c, deriveParamMetadata as d, encodeParamsWithMetadata as f, createSqlExecutionStack as i, validateCodecRegistryCompleteness as l, withTransaction as n, budgets as o, createAstCodecRegistry as p, createExecutionContext as r, lowerSqlPlan as s, createRuntime as t, validateContractCodecMappings as u };
+export { PreparedStatementImpl as a, lowerSqlPlan as c, validateContractCodecMappings as d, deriveParamMetadata as f, createSqlExecutionStack as i, extractCodecIds as l, createAstCodecRegistry as m, withTransaction as n, lints as o, encodeParamsWithMetadata as p, createExecutionContext as r, budgets as s, SqlRuntimeBase as t, validateCodecRegistryCompleteness as u };
 
-//# sourceMappingURL=exports-DDqF-xmg.mjs.map
+//# sourceMappingURL=exports-DJWGwqMq.mjs.map