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

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-QqFFY55a.mjs}

@@ -1,3 +1,4 @@
+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";
@@ -26,31 +27,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
 /**
@@ -472,6 +453,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);
@@ -1134,28 +1137,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 +1168,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 +1291,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 +1327,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 +1400,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 +1622,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-QqFFY55a.mjs.map