@prisma-next/runtime-executor 0.3.0-dev.34 → 0.3.0-dev.35

package/dist/index.mjs

@@ -0,0 +1,599 @@
+import { createHash } from "node:crypto";
+import { type } from "arktype";
+
+//#region src/errors.ts
+function runtimeError(code, message, details) {
+	const error = new Error(message);
+	Object.defineProperty(error, "name", {
+		value: "RuntimeError",
+		configurable: true
+	});
+	return Object.assign(error, {
+		code,
+		category: resolveCategory(code),
+		severity: "error",
+		message,
+		details
+	});
+}
+function resolveCategory(code) {
+	const prefix = code.split(".")[0] ?? "RUNTIME";
+	switch (prefix) {
+		case "PLAN":
+		case "CONTRACT":
+		case "LINT":
+		case "BUDGET": return prefix;
+		default: return "RUNTIME";
+	}
+}
+
+//#endregion
+//#region src/async-iterable-result.ts
+/**
+* Custom async iterable result that extends AsyncIterable with a toArray() method.
+* This provides a convenient way to collect all results from an async iterator.
+*/
+var AsyncIterableResult = class {
+	generator;
+	consumed = false;
+	consumedBy;
+	bufferedArrayPromise;
+	constructor(generator) {
+		this.generator = generator;
+	}
+	[Symbol.asyncIterator]() {
+		if (this.consumed) throw runtimeError("RUNTIME.ITERATOR_CONSUMED", `AsyncIterableResult iterator has already been consumed via ${this.consumedBy === "bufferedArray" ? "toArray()/then()" : "for-await loop"}. Each AsyncIterableResult can only be iterated once.`, {
+			consumedBy: this.consumedBy,
+			suggestion: this.consumedBy === "bufferedArray" ? "If you need to iterate multiple times, store the results from toArray() in a variable and reuse that." : "If you need to iterate multiple times, use toArray() to collect all results first."
+		});
+		this.consumed = true;
+		this.consumedBy = "iterator";
+		return this.generator;
+	}
+	/**
+	* Collects all values from the async iterator into an array.
+	* Once called, the iterator is consumed and cannot be reused.
+	*/
+	toArray() {
+		if (this.consumedBy === "iterator") return Promise.reject(runtimeError("RUNTIME.ITERATOR_CONSUMED", "AsyncIterableResult iterator has already been consumed via for-await loop. Each AsyncIterableResult can only be iterated once.", {
+			consumedBy: this.consumedBy,
+			suggestion: "The iterator was already consumed by a for-await loop. Use toArray() or await the result before iterating."
+		}));
+		if (this.bufferedArrayPromise) return this.bufferedArrayPromise;
+		this.consumed = true;
+		this.consumedBy = "bufferedArray";
+		this.bufferedArrayPromise = (async () => {
+			const out = [];
+			for await (const item of this.generator) out.push(item);
+			return out;
+		})();
+		return this.bufferedArrayPromise;
+	}
+	then(onfulfilled, onrejected) {
+		return this.toArray().then(onfulfilled, onrejected);
+	}
+};
+
+//#endregion
+//#region src/fingerprint.ts
+const STRING_LITERAL_REGEX = /'(?:''|[^'])*'/g;
+const NUMERIC_LITERAL_REGEX = /\b\d+(?:\.\d+)?\b/g;
+const WHITESPACE_REGEX = /\s+/g;
+function computeSqlFingerprint(sql) {
+	const normalized = sql.replace(STRING_LITERAL_REGEX, "?").replace(NUMERIC_LITERAL_REGEX, "?").replace(WHITESPACE_REGEX, " ").trim().toLowerCase();
+	return `sha256:${createHash("sha256").update(normalized).digest("hex")}`;
+}
+
+//#endregion
+//#region src/guardrails/raw.ts
+const SELECT_STAR_REGEX = /select\s+\*/i;
+const LIMIT_REGEX = /\blimit\b/i;
+const MUTATION_PREFIX_REGEX = /^(insert|update|delete|create|alter|drop|truncate)\b/i;
+const READ_ONLY_INTENTS = new Set([
+	"read",
+	"report",
+	"readonly"
+]);
+function evaluateRawGuardrails(plan, config) {
+	const lints$1 = [];
+	const budgets$1 = [];
+	const normalized = normalizeWhitespace(plan.sql);
+	const statementType = classifyStatement(normalized);
+	if (statementType === "select") {
+		if (SELECT_STAR_REGEX.test(normalized)) lints$1.push(createLint("LINT.SELECT_STAR", "error", "Raw SQL plan selects all columns via *", { sql: snippet(plan.sql) }));
+		if (!LIMIT_REGEX.test(normalized)) {
+			const severity = config?.budgets?.unboundedSelectSeverity ?? "error";
+			lints$1.push(createLint("LINT.NO_LIMIT", "warn", "Raw SQL plan omits LIMIT clause", { sql: snippet(plan.sql) }));
+			budgets$1.push(createBudget("BUDGET.ROWS_EXCEEDED", severity, "Raw SQL plan is unbounded and may exceed row budget", {
+				sql: snippet(plan.sql),
+				...config?.budgets?.estimatedRows !== void 0 ? { estimatedRows: config.budgets.estimatedRows } : {}
+			}));
+		}
+	}
+	if (isMutationStatement(statementType) && isReadOnlyIntent(plan.meta)) lints$1.push(createLint("LINT.READ_ONLY_MUTATION", "error", "Raw SQL plan mutates data despite read-only intent", {
+		sql: snippet(plan.sql),
+		intent: plan.meta.annotations?.["intent"]
+	}));
+	const refs = plan.meta.refs;
+	if (refs) evaluateIndexCoverage(refs, lints$1);
+	return {
+		lints: lints$1,
+		budgets: budgets$1,
+		statement: statementType
+	};
+}
+function evaluateIndexCoverage(refs, lints$1) {
+	const predicateColumns = refs.columns ?? [];
+	if (predicateColumns.length === 0) return;
+	const indexes = refs.indexes ?? [];
+	if (indexes.length === 0) {
+		lints$1.push(createLint("LINT.UNINDEXED_PREDICATE", "warn", "Raw SQL plan predicates lack supporting indexes", { predicates: predicateColumns }));
+		return;
+	}
+	if (!predicateColumns.every((column) => indexes.some((index) => index.table === column.table && index.columns.some((col) => col.toLowerCase() === column.column.toLowerCase())))) lints$1.push(createLint("LINT.UNINDEXED_PREDICATE", "warn", "Raw SQL plan predicates lack supporting indexes", { predicates: predicateColumns }));
+}
+function classifyStatement(sql) {
+	const trimmed = sql.trim();
+	const lower = trimmed.toLowerCase();
+	if (lower.startsWith("with")) {
+		if (lower.includes("select")) return "select";
+	}
+	if (lower.startsWith("select")) return "select";
+	if (MUTATION_PREFIX_REGEX.test(trimmed)) return "mutation";
+	return "other";
+}
+function isMutationStatement(statement) {
+	return statement === "mutation";
+}
+function isReadOnlyIntent(meta) {
+	const annotations = meta.annotations;
+	const intent = typeof annotations?.intent === "string" ? annotations.intent.toLowerCase() : void 0;
+	return intent !== void 0 && READ_ONLY_INTENTS.has(intent);
+}
+function normalizeWhitespace(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function snippet(sql) {
+	return normalizeWhitespace(sql).slice(0, 200);
+}
+function createLint(code, severity, message, details) {
+	return {
+		code,
+		severity,
+		message,
+		...details ? { details } : {}
+	};
+}
+function createBudget(code, severity, message, details) {
+	return {
+		code,
+		severity,
+		message,
+		...details ? { details } : {}
+	};
+}
+
+//#endregion
+//#region src/marker.ts
+const MetaSchema = type({ "[string]": "unknown" });
+function parseMeta(meta) {
+	if (meta === null || meta === void 0) return {};
+	let parsed;
+	if (typeof meta === "string") try {
+		parsed = JSON.parse(meta);
+	} catch {
+		return {};
+	}
+	else parsed = meta;
+	const result = MetaSchema(parsed);
+	if (result instanceof type.errors) return {};
+	return result;
+}
+const ContractMarkerRowSchema = type({
+	core_hash: "string",
+	profile_hash: "string",
+	"contract_json?": "unknown | null",
+	"canonical_version?": "number | null",
+	"updated_at?": "Date | string",
+	"app_tag?": "string | null",
+	"meta?": "unknown | null"
+});
+function parseContractMarkerRow(row) {
+	const result = ContractMarkerRowSchema(row);
+	if (result instanceof type.errors) {
+		const messages = result.map((p) => p.message).join("; ");
+		throw new Error(`Invalid contract marker row: ${messages}`);
+	}
+	const validatedRow = result;
+	const updatedAt = validatedRow.updated_at ? validatedRow.updated_at instanceof Date ? validatedRow.updated_at : new Date(validatedRow.updated_at) : /* @__PURE__ */ new Date();
+	return {
+		storageHash: validatedRow.core_hash,
+		profileHash: validatedRow.profile_hash,
+		contractJson: validatedRow.contract_json ?? null,
+		canonicalVersion: validatedRow.canonical_version ?? null,
+		updatedAt,
+		appTag: validatedRow.app_tag ?? null,
+		meta: parseMeta(validatedRow.meta)
+	};
+}
+
+//#endregion
+//#region src/plugins/budgets.ts
+async function computeEstimatedRows(plan, driver) {
+	if (typeof driver.explain !== "function") return;
+	try {
+		return extractEstimatedRows((await driver.explain(plan.sql, [...plan.params])).rows);
+	} catch {
+		return;
+	}
+}
+function extractEstimatedRows(rows) {
+	for (const row of rows) {
+		const estimate = findPlanRows(row);
+		if (estimate !== void 0) return estimate;
+	}
+}
+function findPlanRows(node) {
+	if (!node || typeof node !== "object") return;
+	const explainNode = node;
+	const planRows = explainNode["Plan Rows"];
+	if (typeof planRows === "number") return planRows;
+	if ("Plan" in explainNode && explainNode.Plan !== void 0) {
+		const nested = findPlanRows(explainNode.Plan);
+		if (nested !== void 0) return nested;
+	}
+	if (Array.isArray(explainNode.Plans)) for (const child of explainNode.Plans) {
+		const nested = findPlanRows(child);
+		if (nested !== void 0) return nested;
+	}
+	for (const value of Object.values(node)) if (typeof value === "object" && value !== null) {
+		const nested = findPlanRows(value);
+		if (nested !== void 0) return nested;
+	}
+}
+function budgetError(code, message, details) {
+	const error = new Error(message);
+	Object.defineProperty(error, "name", {
+		value: "RuntimeError",
+		configurable: true
+	});
+	return Object.assign(error, {
+		code,
+		category: "BUDGET",
+		severity: "error",
+		details
+	});
+}
+function estimateRows(plan, tableRows, defaultTableRows) {
+	if (!plan.ast) return null;
+	const table = plan.meta.refs?.tables?.[0];
+	if (!table) return null;
+	const tableEstimate = tableRows[table] ?? defaultTableRows;
+	if (plan.ast && typeof plan.ast === "object" && "kind" in plan.ast && plan.ast.kind === "select" && "limit" in plan.ast && typeof plan.ast.limit === "number") return Math.min(plan.ast.limit, tableEstimate);
+	return tableEstimate;
+}
+function hasDetectableLimit(plan) {
+	if (plan.ast && typeof plan.ast === "object" && "kind" in plan.ast && plan.ast.kind === "select" && "limit" in plan.ast && typeof plan.ast.limit === "number") return true;
+	const annotations = plan.meta.annotations;
+	return typeof annotations?.limit === "number" || typeof annotations?.LIMIT === "number";
+}
+function budgets(options) {
+	const maxRows = options?.maxRows ?? 1e4;
+	const defaultTableRows = options?.defaultTableRows ?? 1e4;
+	const tableRows = options?.tableRows ?? {};
+	const maxLatencyMs = options?.maxLatencyMs ?? 1e3;
+	const rowSeverity = options?.severities?.rowCount ?? "error";
+	const latencySeverity = options?.severities?.latency ?? "warn";
+	let observedRows = 0;
+	return Object.freeze({
+		name: "budgets",
+		async beforeExecute(plan, ctx) {
+			observedRows = 0;
+			ctx.now();
+			const estimated = estimateRows(plan, tableRows, defaultTableRows);
+			const isUnbounded = !hasDetectableLimit(plan);
+			const isSelect = plan.sql.trimStart().toUpperCase().startsWith("SELECT");
+			if (isSelect && isUnbounded) {
+				if (estimated !== null && estimated >= maxRows) {
+					const error$1 = budgetError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", {
+						source: "heuristic",
+						estimatedRows: estimated,
+						maxRows
+					});
+					if (rowSeverity === "error" || ctx.mode === "strict") throw error$1;
+					ctx.log.warn({
+						code: error$1.code,
+						message: error$1.message,
+						details: error$1.details
+					});
+					return;
+				}
+				const error = budgetError("BUDGET.ROWS_EXCEEDED", "Unbounded SELECT query exceeds budget", {
+					source: "heuristic",
+					maxRows
+				});
+				if (rowSeverity === "error" || ctx.mode === "strict") throw error;
+				ctx.log.warn({
+					code: error.code,
+					message: error.message,
+					details: error.details
+				});
+				return;
+			}
+			if (estimated !== null) {
+				if (estimated > maxRows) {
+					const error = budgetError("BUDGET.ROWS_EXCEEDED", "Estimated row count exceeds budget", {
+						source: "heuristic",
+						estimatedRows: estimated,
+						maxRows
+					});
+					if (rowSeverity === "error" || ctx.mode === "strict") throw error;
+					ctx.log.warn({
+						code: error.code,
+						message: error.message,
+						details: error.details
+					});
+				}
+				return;
+			}
+			if (!plan.ast) {
+				if (options?.explain?.enabled === true && isSelect && typeof ctx.driver === "object" && ctx.driver !== null) {
+					const estimatedRows = await computeEstimatedRows(plan, ctx.driver);
+					if (estimatedRows !== void 0) {
+						if (estimatedRows > maxRows) {
+							const error = budgetError("BUDGET.ROWS_EXCEEDED", "Estimated row count exceeds budget", {
+								source: "explain",
+								estimatedRows,
+								maxRows
+							});
+							if (rowSeverity === "error" || ctx.mode === "strict") throw error;
+							ctx.log.warn({
+								code: error.code,
+								message: error.message,
+								details: error.details
+							});
+						}
+						return;
+					}
+				}
+			}
+		},
+		async onRow(_row, _plan, _ctx) {
+			observedRows += 1;
+			if (observedRows > maxRows) throw budgetError("BUDGET.ROWS_EXCEEDED", "Observed row count exceeds budget", {
+				source: "observed",
+				observedRows,
+				maxRows
+			});
+		},
+		async afterExecute(_plan, result, ctx) {
+			const latencyMs = result.latencyMs;
+			if (latencyMs > maxLatencyMs) {
+				const error = budgetError("BUDGET.TIME_EXCEEDED", "Query latency exceeds budget", {
+					latencyMs,
+					maxLatencyMs
+				});
+				if (latencySeverity === "error" && ctx.mode === "strict") throw error;
+				ctx.log.warn({
+					code: error.code,
+					message: error.message,
+					details: error.details
+				});
+			}
+		}
+	});
+}
+
+//#endregion
+//#region src/plugins/lints.ts
+function lintError(code, message, details) {
+	const error = new Error(message);
+	Object.defineProperty(error, "name", {
+		value: "RuntimeError",
+		configurable: true
+	});
+	return Object.assign(error, {
+		code,
+		category: "LINT",
+		severity: "error",
+		details
+	});
+}
+function lints(options) {
+	return Object.freeze({
+		name: "lints",
+		async beforeExecute(plan, ctx) {
+			if (plan.ast) return;
+			const evaluation = evaluateRawGuardrails(plan);
+			for (const lint of evaluation.lints) {
+				const effectiveSeverity = getConfiguredSeverity(lint.code, options) ?? lint.severity;
+				if (effectiveSeverity === "error") throw lintError(lint.code, lint.message, lint.details);
+				if (effectiveSeverity === "warn") ctx.log.warn({
+					code: lint.code,
+					message: lint.message,
+					details: lint.details
+				});
+			}
+		}
+	});
+}
+function getConfiguredSeverity(code, options) {
+	const severities = options?.severities;
+	if (!severities) return;
+	if (code === "LINT.SELECT_STAR") return severities.selectStar;
+	if (code === "LINT.NO_LIMIT") return severities.noLimit;
+	if (code === "LINT.READ_ONLY_MUTATION") return severities.readOnlyMutation;
+	if (code === "LINT.UNINDEXED_PREDICATE") return severities.unindexedPredicate;
+}
+
+//#endregion
+//#region src/runtime-core.ts
+var RuntimeCoreImpl = class {
+	_typeContract;
+	_typeAdapter;
+	_typeDriver;
+	contract;
+	familyAdapter;
+	driver;
+	plugins;
+	mode;
+	verify;
+	operationRegistry;
+	pluginContext;
+	verified;
+	startupVerified;
+	_telemetry;
+	constructor(options) {
+		const { familyAdapter, driver } = options;
+		this.contract = familyAdapter.contract;
+		this.familyAdapter = familyAdapter;
+		this.driver = driver;
+		this.plugins = options.plugins ?? [];
+		this.mode = options.mode ?? "strict";
+		this.verify = options.verify;
+		this.operationRegistry = options.operationRegistry;
+		this.verified = options.verify.mode === "startup" ? false : options.verify.mode === "always";
+		this.startupVerified = false;
+		this._telemetry = null;
+		this.pluginContext = {
+			contract: this.contract,
+			adapter: options.familyAdapter,
+			driver: this.driver,
+			mode: this.mode,
+			now: () => Date.now(),
+			log: options.log ?? {
+				info: () => {},
+				warn: () => {},
+				error: () => {}
+			}
+		};
+	}
+	async verifyPlanIfNeeded(_plan) {
+		if (this.verify.mode === "always") this.verified = false;
+		if (this.verified) return;
+		const readStatement = this.familyAdapter.markerReader.readMarkerStatement();
+		const result = await this.driver.query(readStatement.sql, readStatement.params);
+		if (result.rows.length === 0) {
+			if (this.verify.requireMarker) throw runtimeError("CONTRACT.MARKER_MISSING", "Contract marker not found in database");
+			this.verified = true;
+			return;
+		}
+		const marker = parseContractMarkerRow(result.rows[0]);
+		const contract = this.contract;
+		if (marker.storageHash !== contract.storageHash) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database storage hash does not match contract", {
+			expected: contract.storageHash,
+			actual: marker.storageHash
+		});
+		const expectedProfile = contract.profileHash ?? null;
+		if (expectedProfile !== null && marker.profileHash !== expectedProfile) throw runtimeError("CONTRACT.MARKER_MISMATCH", "Database profile hash does not match contract", {
+			expectedProfile,
+			actualProfile: marker.profileHash
+		});
+		this.verified = true;
+		this.startupVerified = true;
+	}
+	validatePlan(plan) {
+		this.familyAdapter.validatePlan(plan, this.contract);
+	}
+	recordTelemetry(plan, outcome, durationMs) {
+		const contract = this.contract;
+		this._telemetry = Object.freeze({
+			lane: plan.meta.lane,
+			target: contract.target,
+			fingerprint: computeSqlFingerprint(plan.sql),
+			outcome,
+			...durationMs !== void 0 ? { durationMs } : {}
+		});
+	}
+	execute(plan) {
+		return this.#executeWith(plan, this.driver);
+	}
+	async connection() {
+		const driverConn = await this.driver.acquireConnection();
+		const self = this;
+		return {
+			async transaction() {
+				const driverTx = await driverConn.beginTransaction();
+				return {
+					async commit() {
+						await driverTx.commit();
+					},
+					async rollback() {
+						await driverTx.rollback();
+					},
+					execute(plan) {
+						return self.#executeWith(plan, driverTx);
+					}
+				};
+			},
+			execute(plan) {
+				return self.#executeWith(plan, driverConn);
+			},
+			async release() {
+				await driverConn.release();
+			}
+		};
+	}
+	telemetry() {
+		return this._telemetry;
+	}
+	operations() {
+		return this.operationRegistry;
+	}
+	close() {
+		const driver = this.driver;
+		if (typeof driver.close === "function") return driver.close();
+		return Promise.resolve();
+	}
+	#executeWith(plan, queryable) {
+		this.validatePlan(plan);
+		this._telemetry = null;
+		const iterator = async function* (self) {
+			const startedAt = Date.now();
+			let rowCount = 0;
+			let completed = false;
+			if (!self.startupVerified && self.verify.mode === "startup") await self.verifyPlanIfNeeded(plan);
+			if (self.verify.mode === "onFirstUse") await self.verifyPlanIfNeeded(plan);
+			try {
+				if (self.verify.mode === "always") await self.verifyPlanIfNeeded(plan);
+				for (const plugin of self.plugins) if (plugin.beforeExecute) await plugin.beforeExecute(plan, self.pluginContext);
+				const encodedParams = plan.params;
+				for await (const row of queryable.execute({
+					sql: plan.sql,
+					params: encodedParams
+				})) {
+					for (const plugin of self.plugins) if (plugin.onRow) await plugin.onRow(row, plan, self.pluginContext);
+					rowCount++;
+					yield row;
+				}
+				completed = true;
+				self.recordTelemetry(plan, "success", Date.now() - startedAt);
+			} catch (error) {
+				if (self._telemetry === null) self.recordTelemetry(plan, "runtime-error", Date.now() - startedAt);
+				const latencyMs$1 = Date.now() - startedAt;
+				for (const plugin of self.plugins) if (plugin.afterExecute) try {
+					await plugin.afterExecute(plan, {
+						rowCount,
+						latencyMs: latencyMs$1,
+						completed
+					}, self.pluginContext);
+				} catch {}
+				throw error;
+			}
+			const latencyMs = Date.now() - startedAt;
+			for (const plugin of self.plugins) if (plugin.afterExecute) await plugin.afterExecute(plan, {
+				rowCount,
+				latencyMs,
+				completed
+			}, self.pluginContext);
+		};
+		return new AsyncIterableResult(iterator(this));
+	}
+};
+function createRuntimeCore(options) {
+	return new RuntimeCoreImpl(options);
+}
+
+//#endregion
+export { AsyncIterableResult, budgets, computeSqlFingerprint, createRuntimeCore, evaluateRawGuardrails, lints, parseContractMarkerRow, runtimeError };
+//# sourceMappingURL=index.mjs.map