@prisma-next/sql-runtime 0.9.0-dev.1 → 0.9.0-dev.3

package/dist/{exports-C2zFVOFS.mjs → exports-DHQOSWty.mjs}

@@ -1,6 +1,6 @@
 import { AsyncIterableResult, RuntimeCore, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runBeforeExecuteChain, runWithMiddleware, runtimeError } from "@prisma-next/framework-components/runtime";
 import { type } from "arktype";
-import { collectOrderedParamRefs, isQueryAst } from "@prisma-next/sql-relational-core/ast";
+import { PreparedParamRef, collectOrderedParamRefs, isQueryAst } from "@prisma-next/sql-relational-core/ast";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { checkContractComponentRequirements } from "@prisma-next/framework-components/components";
 import { createExecutionStack } from "@prisma-next/framework-components/execution";
@@ -60,19 +60,24 @@ function validateCodecRegistryCompleteness(registry, contract) {
 /**
 * Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
 *
-* @param adapter - Adapter to lower AST to SQL
-* @param contract - Contract for lowering context
-* @param queryPlan - SQL query plan from a lane (contains AST, params, meta, but no SQL)
-* @returns Fully executable Plan with SQL string
+* Ad-hoc lowerings produce only `{kind: 'literal'}` slots; this helper
+* unwraps them into the bare-value array `SqlExecutionPlan` exposes.
+* Encountering a `{kind: 'bind'}` slot here means the caller passed an
+* AST containing `PreparedParamRef` to the ad-hoc execute path — that's a
+* caller error, surfaced as `RUNTIME.PREPARE_BIND_ON_ADHOC`.
 */
 function lowerSqlPlan(adapter, contract, queryPlan) {
 	const lowered = adapter.lower(queryPlan.ast, {
 		contract,
 		params: queryPlan.params
 	});
+	const params = lowered.params.map((slot) => {
+		if (slot.kind === "literal") return slot.value;
+		throw runtimeError("RUNTIME.PREPARE_BIND_ON_ADHOC", `Ad-hoc execute received a bind-site slot for '${slot.name}' — bind-site references are only valid inside runtime.prepare(...).`, { name: slot.name });
+	});
 	return Object.freeze({
 		sql: lowered.sql,
-		params: lowered.params ?? queryPlan.params,
+		params,
 		ast: queryPlan.ast,
 		meta: queryPlan.meta
 	});
@@ -138,7 +143,7 @@ function primaryTableFromAst(ast) {
 function estimateRowsFromAst(ast, tableRows, defaultTableRows, hasAggregateWithoutGroup) {
 	if (hasAggregateWithoutGroup) return 1;
 	const tableEstimate = tableRows[primaryTableFromAst(ast)] ?? defaultTableRows;
-	if (ast.limit !== void 0) return Math.min(ast.limit, tableEstimate);
+	if (typeof ast.limit === "number") return Math.min(ast.limit, tableEstimate);
 	return tableEstimate;
 }
 function emitBudgetViolation(error, shouldBlock, ctx) {
@@ -920,9 +925,6 @@ function writeContractMarker(input) {
 //#region src/codecs/decoding.ts
 const WIRE_PREVIEW_LIMIT = 100;
 const EMPTY_INCLUDE_ALIASES = /* @__PURE__ */ new Set();
-function isAstBackedPlan(plan) {
-	return plan.ast !== void 0;
-}
 function projectionListFromAst(ast) {
 	if (ast.kind === "select") return ast.projection;
 	if (ast.kind === "raw-sql") return;
@@ -931,15 +933,9 @@ function projectionListFromAst(ast) {
 function resolveProjectionCodec(item, contractCodecs) {
 	if (item.codec && contractCodecs) return contractCodecs.forCodecRef(item.codec);
 }
-function buildDecodeContext(plan, contractCodecs) {
-	if (!isAstBackedPlan(plan)) return {
-		aliases: void 0,
-		codecs: /* @__PURE__ */ new Map(),
-		columnRefs: /* @__PURE__ */ new Map(),
-		includeAliases: EMPTY_INCLUDE_ALIASES
-	};
-	const projection = projectionListFromAst(plan.ast);
-	if (!projection) return {
+function buildDecodeContext(ast, contractCodecs) {
+	const projection = projectionListFromAst(ast);
+	if (!projection || projection.length === 0) return {
 		aliases: void 0,
 		codecs: /* @__PURE__ */ new Map(),
 		columnRefs: /* @__PURE__ */ new Map(),
@@ -1044,10 +1040,9 @@ async function decodeField(alias, wireValue, decodeCtx, rowCtx) {
 * - **Mid-flight aborts** race the per-cell `Promise.all` against the signal so the runtime returns promptly even when codec bodies ignore it. In-flight bodies that ignore the signal complete in the background (cooperative cancellation).
 * - Existing `RUNTIME.DECODE_FAILED` envelopes from codec bodies pass through unchanged (no double wrap).
 */
-async function decodeRow(row, plan, rowCtx, contractCodecs) {
+async function decodeRow(row, decodeCtx, rowCtx) {
 	checkAborted(rowCtx, "decode");
 	const signal = rowCtx.signal;
-	const decodeCtx = buildDecodeContext(plan, contractCodecs);
 	const aliases = decodeCtx.aliases ?? Object.keys(row);
 	if (decodeCtx.aliases !== void 0) {
 		for (const alias of decodeCtx.aliases) if (!Object.hasOwn(row, alias)) throw runtimeError("RUNTIME.DECODE_FAILED", `Row missing projection alias "${alias}"`, {
@@ -1084,6 +1079,14 @@ const NO_METADATA = Object.freeze({
 	codec: void 0,
 	name: void 0
 });
+function deriveParamMetadata(ast) {
+	return collectOrderedParamRefs(ast).map((ref) => {
+		return {
+			codec: ref.codec,
+			name: ref.name
+		};
+	});
+}
 function resolveParamCodec(metadata, contractCodecs) {
 	if (metadata.codec && contractCodecs) return contractCodecs.forCodecRef(metadata.codec);
 }
@@ -1121,23 +1124,13 @@ async function encodeParamValue(value, metadata, paramIndex, ctx, contractCodecs
 * - Existing `RUNTIME.ENCODE_FAILED` envelopes that surface from a codec body before the runtime observes the abort pass through unchanged (no double wrap).
 */
 async function encodeParams(plan, ctx, contractCodecs) {
+	return encodeParamsWithMetadata(plan.params, deriveParamMetadata(plan.ast), ctx, contractCodecs);
+}
+async function encodeParamsWithMetadata(values, metadata, ctx, contractCodecs) {
 	checkAborted(ctx, "encode");
 	const signal = ctx.signal;
-	if (plan.params.length === 0) return plan.params;
-	const paramCount = plan.params.length;
-	const metadata = new Array(paramCount).fill(NO_METADATA);
-	if (plan.ast) {
-		const refs = collectOrderedParamRefs(plan.ast);
-		for (let i = 0; i < paramCount && i < refs.length; i++) {
-			const ref = refs[i];
-			if (ref) metadata[i] = {
-				codec: ref.codec,
-				name: ref.name
-			};
-		}
-	}
-	const tasks = new Array(paramCount);
-	for (let i = 0; i < paramCount; i++) tasks[i] = encodeParamValue(plan.params[i], metadata[i] ?? NO_METADATA, i, ctx, contractCodecs);
+	if (values.length === 0) return values;
+	const tasks = values.map((value, i) => encodeParamValue(value, metadata[i] ?? NO_METADATA, i, ctx, contractCodecs));
 	const settled = await raceAgainstAbort(Promise.all(tasks), signal, "encode");
 	return Object.freeze(settled);
 }
@@ -1217,6 +1210,81 @@ async function runBeforeCompileChain(middleware, initial, ctx) {
 	return current;
 }
 //#endregion
+//#region src/prepared/bind-site-params.ts
+function normalizeSpec(spec) {
+	if (typeof spec === "string") return {
+		codec: { codecId: spec },
+		nullable: false
+	};
+	return {
+		codec: spec.typeParams !== void 0 ? {
+			codecId: spec.codecId,
+			typeParams: spec.typeParams
+		} : { codecId: spec.codecId },
+		nullable: spec.nullable === true
+	};
+}
+var BindSiteExpression = class {
+	returnType;
+	#ast;
+	constructor(ref, returnType) {
+		this.#ast = ref;
+		this.returnType = returnType;
+	}
+	buildAst() {
+		return this.#ast;
+	}
+};
+function buildBindSiteParams(declaration) {
+	const params = {};
+	for (const [name, spec] of Object.entries(declaration)) {
+		const { codec, nullable } = normalizeSpec(spec);
+		params[name] = new BindSiteExpression(PreparedParamRef.of(name, codec), {
+			codecId: codec.codecId,
+			nullable
+		});
+	}
+	return Object.freeze(params);
+}
+//#endregion
+//#region src/prepared/encode-prepared.ts
+/**
+* Resolve a PreparedStatement's slot order to the unencoded values it
+* will carry into encode. Literal slots come from the lowered AST;
+* bind slots are looked up by name on `userParams`. Missing user params
+* surface `RUNTIME.PREPARE_MISSING_PARAM` so the caller cannot silently
+* bind `undefined`.
+*/
+function resolvePreparedSlotValues(ps, userParams) {
+	return ps.slots.map((slot) => {
+		if (slot.kind === "literal") return slot.value;
+		if (!Object.hasOwn(userParams, slot.name)) throw runtimeError("RUNTIME.PREPARE_MISSING_PARAM", `Prepared statement execute is missing parameter '${slot.name}'`, { name: slot.name });
+		return userParams[slot.name];
+	});
+}
+//#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;
@@ -1257,6 +1325,7 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	codecDescriptors;
 	sqlCtx;
 	verify;
+	#preparedStatementHandles = /* @__PURE__ */ new WeakMap();
 	codecRegistryValidated;
 	verified;
 	startupVerified;
@@ -1367,6 +1436,37 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 	execute(plan, options) {
 		return this.executeAgainstQueryable(plan, this.driver, options);
 	}
+	executePrepared(ps, params, options) {
+		return this.executePreparedAgainstQueryable(ps, params, this.driver, options);
+	}
+	async *streamRows(exec, decodeContext, driverCall, codecCtx, execMiddlewareCtx) {
+		this.familyAdapter.validatePlan(exec, this.contract);
+		this._telemetry = null;
+		if (!this.startupVerified && this.verify.mode === "startup") await this.verifyMarker();
+		if (!this.verified && this.verify.mode === "onFirstUse") await this.verifyMarker();
+		const startedAt = Date.now();
+		let outcome = null;
+		try {
+			if (this.verify.mode === "always") await this.verifyMarker();
+			const iterator = runWithMiddleware(exec, this.middleware, execMiddlewareCtx, driverCall)[Symbol.asyncIterator]();
+			try {
+				while (true) {
+					checkAborted(codecCtx, "stream");
+					const next = await iterator.next();
+					if (next.done) break;
+					yield await decodeRow(next.value, decodeContext, codecCtx);
+				}
+			} finally {
+				await iterator.return?.();
+			}
+			outcome = "success";
+		} catch (error) {
+			outcome = "runtime-error";
+			throw error;
+		} finally {
+			if (outcome !== null) this.recordTelemetry(exec, outcome, Date.now() - startedAt);
+		}
+	}
 	executeAgainstQueryable(plan, queryable, options) {
 		this.ensureCodecRegistryValidated();
 		const self = this;
@@ -1402,35 +1502,79 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 				});
 				exec = await self.encodeDraftParams(draftWithMutations, codecCtx);
 			}
-			self.familyAdapter.validatePlan(exec, self.contract);
-			self._telemetry = null;
-			if (!self.startupVerified && self.verify.mode === "startup") await self.verifyMarker();
-			if (!self.verified && self.verify.mode === "onFirstUse") await self.verifyMarker();
-			const startedAt = Date.now();
-			let outcome = null;
-			try {
-				if (self.verify.mode === "always") await self.verifyMarker();
-				const iterator = runWithMiddleware(exec, self.middleware, execMiddlewareCtx, () => queryable.execute({
-					sql: exec.sql,
-					params: exec.params
-				}))[Symbol.asyncIterator]();
-				try {
-					while (true) {
-						checkAborted(codecCtx, "stream");
-						const next = await iterator.next();
-						if (next.done) break;
-						yield await decodeRow(next.value, exec, codecCtx, self.contractCodecs);
+			const decodeContext = buildDecodeContext(exec.ast, self.contractCodecs);
+			yield* self.streamRows(exec, decodeContext, () => queryable.execute({
+				sql: exec.sql,
+				params: exec.params
+			}), codecCtx, execMiddlewareCtx);
+		};
+		return new AsyncIterableResult(generator());
+	}
+	async prepare(declaration, callback) {
+		this.ensureCodecRegistryValidated();
+		const userPlan = callback(buildBindSiteParams(declaration));
+		const finalPlan = await this.runBeforeCompile(userPlan);
+		const orderedRefs = collectOrderedParamRefs(finalPlan.ast);
+		const referencedNames = /* @__PURE__ */ new Set();
+		for (const ref of orderedRefs) if (ref.kind === "prepared-param-ref") referencedNames.add(ref.name);
+		const missing = Object.keys(declaration).filter((name) => !referencedNames.has(name));
+		if (missing.length > 0) throw runtimeError("RUNTIME.PREPARE_UNUSED_PARAM", `Prepared statement declaration includes parameter${missing.length === 1 ? "" : "s"} not referenced by the callback's plan: ${missing.join(", ")}`, { unused: missing });
+		const lowered = this.adapter.lower(finalPlan.ast, {
+			contract: this.contract,
+			params: orderedRefs.map((r) => r.kind === "param-ref" ? r.value : void 0)
+		});
+		const decodeContext = buildDecodeContext(finalPlan.ast, this.contractCodecs);
+		const paramMetadata = deriveParamMetadata(finalPlan.ast);
+		return new PreparedStatementImpl(Object.freeze({
+			sql: lowered.sql,
+			ast: finalPlan.ast,
+			meta: finalPlan.meta,
+			slots: lowered.params,
+			decodeContext,
+			paramMetadata
+		}));
+	}
+	executePreparedAgainstQueryable(ps, userParams, queryable, options) {
+		this.ensureCodecRegistryValidated();
+		const self = this;
+		const signal = options?.signal;
+		const scope = options?.scope ?? "runtime";
+		const codecCtx = signal === void 0 ? {} : { signal };
+		const execMiddlewareCtx = {
+			...self.ctx,
+			...ifDefined("signal", signal),
+			...scope !== "runtime" ? { scope } : {}
+		};
+		const generator = async function* () {
+			checkAborted(codecCtx, "stream");
+			const preEncodeValues = resolvePreparedSlotValues(ps, userParams);
+			const preEncodeExec = {
+				sql: ps.sql,
+				params: preEncodeValues,
+				ast: ps.ast,
+				meta: ps.meta
+			};
+			const mutator = createSqlParamRefMutator(preEncodeExec);
+			await runBeforeExecuteChain(preEncodeExec, self.middleware, execMiddlewareCtx, mutator);
+			const encodedParams = await encodeParamsWithMetadata(mutator.currentParams(), ps.paramMetadata, codecCtx, self.contractCodecs);
+			const exec = {
+				sql: ps.sql,
+				params: encodedParams,
+				ast: ps.ast,
+				meta: ps.meta
+			};
+			const handles = self.#preparedStatementHandles;
+			const request = {
+				sql: exec.sql,
+				params: exec.params,
+				handle: {
+					get: () => handles.get(ps),
+					set: (value) => {
+						handles.set(ps, value);
 					}
-				} finally {
-					await iterator.return?.();
 				}
-				outcome = "success";
-			} catch (error) {
-				outcome = "runtime-error";
-				throw error;
-			} finally {
-				if (outcome !== null) self.recordTelemetry(exec, outcome, Date.now() - startedAt);
-			}
+			};
+			yield* self.streamRows(exec, ps.decodeContext, () => queryable.executePrepared(request), codecCtx, execMiddlewareCtx);
 		};
 		return new AsyncIterableResult(generator());
 	}
@@ -1453,6 +1597,12 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 					...options,
 					scope: "connection"
 				});
+			},
+			executePrepared(ps, params, options) {
+				return self.executePreparedAgainstQueryable(ps, params, driverConn, {
+					...options,
+					scope: "connection"
+				});
 			}
 		};
 	}
@@ -1470,6 +1620,12 @@ var SqlRuntimeImpl = class extends RuntimeCore {
 					...options,
 					scope: "transaction"
 				});
+			},
+			executePrepared(ps, params, options) {
+				return self.executePreparedAgainstQueryable(ps, params, driverTx, {
+					...options,
+					scope: "transaction"
+				});
 			}
 		};
 	}
@@ -1538,6 +1694,17 @@ async function withTransaction(runtime, fn) {
 				}
 			};
 			return new AsyncIterableResult(guarded());
+		},
+		executePrepared(ps, params, options) {
+			if (invalidated) throw transactionClosedError();
+			const inner = transaction.executePrepared(ps, params, options);
+			const guarded = async function* () {
+				for await (const row of inner) {
+					if (invalidated) throw transactionClosedError();
+					yield row;
+				}
+			};
+			return new AsyncIterableResult(guarded());
 		}
 	};
 	let connectionDisposed = false;
@@ -1595,4 +1762,4 @@ function createRuntime(options) {
 //#endregion
 export { ensureTableStatement as a, createExecutionContext as c, budgets as d, parseContractMarkerRow as f, validateContractCodecMappings as g, validateCodecRegistryCompleteness as h, ensureSchemaStatement as i, createSqlExecutionStack as l, extractCodecIds as m, withTransaction as n, readContractMarker as o, lowerSqlPlan as p, APP_SPACE_ID as r, writeContractMarker as s, createRuntime as t, lints as u };
 
-//# sourceMappingURL=exports-C2zFVOFS.mjs.map
+//# sourceMappingURL=exports-DHQOSWty.mjs.map