qubu 0.0.0 → 0.3.3

package/dist/index.mjs

@@ -0,0 +1,1276 @@
+import { a as assertDialectCapability } from "./json-CUZlv4HT.mjs";
+import { c as render, n as call, o as cast, r as schemaCall, t as createClause } from "./types-Cec0xzo4.mjs";
+import { n as queryValidationError, t as QueryValidationError } from "./errors-Dxv73YJu.mjs";
+import { c as makeExpression, h as parenthesize, i as identifier, l as makeSchemaExpression, m as isFragment, o as isExpression, p as fragment, t as createColumnReference, u as markExpressionCategory } from "./column-CXMxx8Hq.mjs";
+import { i as value, t as asValue } from "./value-BvilP0oz.mjs";
+import { a as isDistinctFrom, c as lt, d as notLike, f as expressionOperand, i as gte, l as lte, m as renderOperands, n as eq, o as isNotDistinctFrom, p as isNullOperand, r as gt, s as like, u as ne } from "./relational-DCZrrNia.mjs";
+import { t as omit } from "./omit-OxV58AwX.mjs";
+import { n as snakeCaseIdentifier, t as resolveSqlNames } from "./naming-QVCOnSj2.mjs";
+import { r as exposeColumns, t as createSource } from "./source-DUoJVXmL.mjs";
+import { S as identityColumn, T as lateral, a as column, b as externalGeneratedColumn, c as json, d as nullable, f as numeric, g as uuid, h as timestamp, i as boolean, l as nativeColumn, m as text, n as bigint, o as date, p as portableStorage, r as binary, s as integer, t as table, u as nativeStorage, w as alias, x as generatedColumn, y as externalDefault } from "./table-llv9tsZ8.mjs";
+import { C as index, S as unsafeSchemaSql, c as check, d as references, f as unique, i as schema, l as foreignKey, o as catalogCheck, p as uniqueConstraint, s as catalogForeignKey, u as primaryKey } from "./registry-BufIskVN.mjs";
+//#region src/execution.ts
+function qubu(adapter) {
+	const client = createClient(adapter);
+	if (!isTransactionalQueryAdapter(adapter)) return client;
+	return Object.freeze({
+		...client,
+		transaction(callback, options) {
+			return adapter.transaction(async (transactionAdapter) => callback(createClient(transactionAdapter)), options);
+		}
+	});
+}
+function createClient(adapter) {
+	const client = {
+		adapter,
+		execute(query, options) {
+			return execute(query, adapter, options);
+		},
+		rows(query, options) {
+			return executeRows(query, adapter, options);
+		}
+	};
+	const streaming = isStreamingQueryAdapter(adapter);
+	const explainable = isExplainableQueryAdapter(adapter);
+	if (!streaming && !explainable) return Object.freeze(client);
+	return Object.freeze({
+		...client,
+		...streaming ? { stream(query, options) {
+			return stream(query, adapter, options);
+		} } : {},
+		...explainable ? { explain(query, options) {
+			return explain(query, adapter, options);
+		} } : {}
+	});
+}
+function isTransactionalQueryAdapter(adapter) {
+	return typeof adapter.transaction === "function";
+}
+function isStreamingQueryAdapter(adapter) {
+	return typeof adapter.stream === "function";
+}
+function isExplainableQueryAdapter(adapter) {
+	return typeof adapter.explain === "function";
+}
+function execute(first, second, options = {}) {
+	return executeInternal(first, second, options);
+}
+async function executeRows(first, second, options = {}) {
+	return (await executeInternal(first, second, options)).rows;
+}
+async function explain(first, second, options = {}) {
+	const query = isQuery(first) ? first : second;
+	const adapter = isQuery(first) ? second : first;
+	return adapter.explain(createExplainRequest(query, adapter, options));
+}
+function stream(first, second, options = {}) {
+	const query = isQuery(first) ? first : second;
+	const adapter = isQuery(first) ? second : first;
+	assertStreamableQuery(query);
+	return adapter.stream(createExecutionRequest(query, adapter, options));
+}
+async function executeInternal(first, second, options) {
+	const query = isQuery(first) ? first : second;
+	const adapter = isQuery(first) ? second : first;
+	const request = createExecutionRequest(query, adapter, options);
+	return adapter.execute(request);
+}
+function createExecutionRequest(query, adapter, options) {
+	const statement = render(query, { dialect: options.dialect ?? adapter.dialect });
+	return Object.freeze({
+		statement,
+		queryKind: query.queryKind,
+		...options.signal === void 0 ? {} : { signal: options.signal }
+	});
+}
+function createExplainRequest(query, adapter, options) {
+	const request = createExecutionRequest(query, adapter, options);
+	if (options.analyze === true && query.queryKind !== "select" && query.queryKind !== "set") throw queryValidationError({
+		code: "invalid-explain-query",
+		context: "execution.explain",
+		path: ["analyze"],
+		message: `EXPLAIN ANALYZE is only available for read queries; received ${query.queryKind}`,
+		hint: "Remove analyze for a plan-only mutation EXPLAIN."
+	});
+	const dialect = options.dialect ?? adapter.dialect;
+	if (dialect.explain === void 0) throw queryValidationError({
+		code: "unsupported-explain-dialect",
+		context: "execution.explain",
+		path: ["dialect"],
+		message: `Dialect "${dialect.name}" does not provide an EXPLAIN rendering policy`,
+		hint: "Use PostgreSQL, SQLite, MySQL, or a custom dialect with an explain policy."
+	});
+	const statement = Object.freeze({
+		text: dialect.explain.render(request.statement.text, query.queryKind, options),
+		parameters: request.statement.parameters
+	});
+	return Object.freeze({
+		...request,
+		statement
+	});
+}
+function assertStreamableQuery(query) {
+	if (query.queryKind === "select" || query.queryKind === "set") return;
+	throw queryValidationError({
+		code: "invalid-stream-query",
+		context: "execution.stream",
+		path: ["queryKind"],
+		message: `Only SELECT and set-operation queries can be streamed; received ${query.queryKind}`,
+		hint: "Use execute() or executeRows() for mutation queries."
+	});
+}
+function isQuery(value) {
+	return "render" in value && typeof value.render === "function";
+}
+//#endregion
+//#region src/expressions/case.ts
+function caseWhen(condition, thenValue, elseValue) {
+	const thenExpression = asValue(thenValue);
+	const elseExpression = asValue(elseValue);
+	return makeSchemaExpression("operator", (context) => {
+		context.append("CASE WHEN ");
+		context.render(condition);
+		context.append(" THEN ");
+		context.render(thenExpression);
+		context.append(" ELSE ");
+		context.render(elseExpression);
+		context.append(" END");
+	});
+}
+//#endregion
+//#region src/expressions/sql.ts
+function sqlTemplate(strings, values) {
+	return makeExpression("sql", (context) => {
+		strings.forEach((text, index) => {
+			context.append(text);
+			if (index >= values.length) return;
+			const value = values[index];
+			if (!isFragment(value)) {
+				context.parameter(value);
+				return;
+			}
+			if (isQueryFragment(value)) context.renderRelation(value);
+			else context.render(value);
+		});
+	});
+}
+function createSqlTag() {
+	return (strings, ...values) => sqlTemplate(strings, values);
+}
+const sqlTag = createSqlTag();
+sqlTag.type = createSqlTag;
+/**
+* Build trusted SQL syntax while binding every ordinary substitution as a
+* parameter. Qubu fragments remain composable substitutions.
+*
+* @remarks Template text is trusted and is not parsed. Use `identifier()` from
+* `qubu/core` for runtime identifiers and `unsafeExpression()` for deliberately
+* dynamic syntax. Use `sql.type<Output, SqlType>()` when the fragment's result
+* is known.
+*/
+const sql = Object.freeze(sqlTag);
+function isQueryFragment(value) {
+	return "queryKind" in value && "row" in value;
+}
+//#endregion
+//#region src/expressions/functions/aggregate.ts
+function count(expression) {
+	return makeExpression("function", (context) => {
+		context.append("COUNT(");
+		if (expression) context.render(expression);
+		else context.append("*");
+		context.append(")");
+	}, "aggregate");
+}
+function countDistinct(expression) {
+	return makeExpression("function", (context) => {
+		context.append("COUNT(DISTINCT ");
+		context.render(expression);
+		context.append(")");
+	}, "aggregate");
+}
+function sum(expression) {
+	return markExpressionCategory(call("SUM", expression), "aggregate");
+}
+function avg(expression) {
+	return markExpressionCategory(call("AVG", expression), "aggregate");
+}
+function min(expression) {
+	return markExpressionCategory(call("MIN", expression), "aggregate");
+}
+function max(expression) {
+	return markExpressionCategory(call("MAX", expression), "aggregate");
+}
+//#endregion
+//#region src/expressions/functions/string.ts
+function lower(expression) {
+	return schemaCall("LOWER", expression);
+}
+function upper(expression) {
+	return schemaCall("UPPER", expression);
+}
+function coalesce(...expressions) {
+	return schemaCall("COALESCE", ...expressions);
+}
+function concat(...argumentsToConcat) {
+	return schemaCall("CONCAT", ...argumentsToConcat);
+}
+//#endregion
+//#region src/expressions/functions/window.ts
+function over(expression, window) {
+	return makeExpression("function", (context) => {
+		context.render(expression);
+		context.append(" OVER (");
+		let hasPart = false;
+		if (window?.partitionBy && window.partitionBy.length > 0) {
+			context.append("PARTITION BY ");
+			window.partitionBy.forEach((part, index) => {
+				if (index > 0) context.append(", ");
+				context.render(part);
+			});
+			hasPart = true;
+		}
+		if (window?.orderBy && window.orderBy.length > 0) {
+			if (hasPart) context.append(" ");
+			context.append("ORDER BY ");
+			window.orderBy.forEach((part, index) => {
+				if (index > 0) context.append(", ");
+				context.render(part);
+			});
+		}
+		context.append(")");
+	}, "window");
+}
+function rowNumber() {
+	return markExpressionCategory(call("ROW_NUMBER"), "window");
+}
+function rank() {
+	return markExpressionCategory(call("RANK"), "window");
+}
+function denseRank() {
+	return markExpressionCategory(call("DENSE_RANK"), "window");
+}
+//#endregion
+//#region src/expressions/subquery.ts
+function scalar(query) {
+	if (Object.keys(query.row).length !== 1) throw queryValidationError({
+		code: "invalid-subquery",
+		context: "expression.scalar.query",
+		path: [
+			"scalar",
+			"query",
+			"row"
+		],
+		message: "scalar() requires a query with exactly one selected column",
+		hint: "Select exactly one named field before wrapping the query in scalar()."
+	});
+	return makeExpression("subquery", (context) => context.renderRelation(parenthesize(query)));
+}
+//#endregion
+//#region src/expressions/json.ts
+const jsonPathBrand = Symbol("json-path");
+/**
+* Build a root-relative JSON path from object keys and array indexes.
+*
+* @throws {TypeError} When an index is negative, fractional, or unsafe.
+*/
+function jsonPath(...segments) {
+	for (const [index, segment] of segments.entries()) if (typeof segment === "number" && (!Number.isSafeInteger(segment) || segment < 0)) throw queryValidationError({
+		code: "invalid-json-path",
+		context: "expression.json-path",
+		path: ["jsonPath", index],
+		message: "JSON path indexes must be non-negative safe integers",
+		hint: "Use a non-negative safe integer for each JSON array index."
+	});
+	return Object.freeze({
+		[jsonPathBrand]: true,
+		pathKind: "json",
+		segments: Object.freeze([...segments])
+	});
+}
+function jsonScalar(document, path, kind) {
+	return makeSchemaExpression("function", (context) => {
+		assertDialectCapability(context.dialect, "json");
+		if (!context.dialect.json) throw new Error(`Dialect "${context.dialect.name}" advertises JSON support without a JSON renderer`);
+		context.dialect.json.renderScalar(context, document, path.segments, kind);
+	});
+}
+/** Extract a JSON string, returning SQL NULL for missing, null, or non-string values. */
+function jsonText(document, path) {
+	return jsonScalar(document, path, "text");
+}
+/** Extract a JSON number, returning SQL NULL for missing, null, or non-number values. */
+function jsonNumber(document, path) {
+	return jsonScalar(document, path, "number");
+}
+/** Extract a JSON boolean, returning SQL NULL for missing, null, or non-boolean values. */
+function jsonBoolean(document, path) {
+	return jsonScalar(document, path, "boolean");
+}
+/** Test whether a path exists, including when its value is JSON null. */
+function jsonExists(document, path) {
+	return makeSchemaExpression("function", (context) => {
+		assertDialectCapability(context.dialect, "json");
+		if (!context.dialect.json) throw new Error(`Dialect "${context.dialect.name}" advertises JSON support without a JSON renderer`);
+		context.dialect.json.renderExists(context, document, path.segments);
+	});
+}
+//#endregion
+//#region src/expressions/operators/arithmetic.ts
+function arithmetic(operator, left, right) {
+	const rightExpression = expressionOperand(right);
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(");
+		context.render(left);
+		context.append(` ${operator} `);
+		context.render(rightExpression);
+		context.append(")");
+	});
+}
+const add = (left, right) => arithmetic("+", left, right);
+const subtract = (left, right) => arithmetic("-", left, right);
+const multiply = (left, right) => arithmetic("*", left, right);
+const divide = (left, right) => arithmetic("/", left, right);
+const modulo = (left, right) => arithmetic("%", left, right);
+//#endregion
+//#region src/expressions/operators/logic.ts
+function composeConditions(conditions, separator, name) {
+	if (conditions.length === 0) throw queryValidationError({
+		code: "invalid-boolean-expression",
+		context: `expression.${name}`,
+		path: [name],
+		message: `${name}() requires at least one condition`,
+		hint: `Pass at least one condition to ${name}(), or use omit for a conditional predicate.`
+	});
+	const presentConditions = conditions.filter((condition) => condition !== omit);
+	if (presentConditions.length === 0) return omit;
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(");
+		renderOperands(context, presentConditions, separator);
+		context.append(")");
+	});
+}
+function and(...conditions) {
+	return composeConditions(conditions, " AND ", "and");
+}
+function or(...conditions) {
+	return composeConditions(conditions, " OR ", "or");
+}
+function not(condition) {
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(NOT ");
+		context.render(condition);
+		context.append(")");
+	});
+}
+//#endregion
+//#region src/expressions/operators/comparison/range.ts
+function between(expression, lower, upper) {
+	if (isNullOperand(lower) || isNullOperand(upper)) throw new TypeError("between() does not accept NULL bounds; use an explicit NULL predicate");
+	const lowerExpression = expressionOperand(lower);
+	const upperExpression = expressionOperand(upper);
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(");
+		context.render(expression);
+		context.append(" BETWEEN ");
+		context.render(lowerExpression);
+		context.append(" AND ");
+		context.render(upperExpression);
+		context.append(")");
+	});
+}
+function inList(expression, values) {
+	const valueExpressions = values.map(expressionOperand);
+	return makeSchemaExpression("operator", (context) => {
+		if (values.length === 0) {
+			context.append("(1 = 0)");
+			return;
+		}
+		context.append("(");
+		context.render(expression);
+		context.append(" IN (");
+		valueExpressions.forEach((value, index) => {
+			if (index > 0) context.append(", ");
+			context.render(value);
+		});
+		context.append("))");
+	});
+}
+function notIn(expression, values) {
+	const valueExpressions = values.map(expressionOperand);
+	return makeSchemaExpression("operator", (context) => {
+		if (values.length === 0) {
+			context.append("(1 = 1)");
+			return;
+		}
+		context.append("(");
+		context.render(expression);
+		context.append(" NOT IN (");
+		valueExpressions.forEach((value, index) => {
+			if (index > 0) context.append(", ");
+			context.render(value);
+		});
+		context.append("))");
+	});
+}
+//#endregion
+//#region src/expressions/operators/comparison/subquery.ts
+function inQuery(expression, query) {
+	return makeExpression("subquery", (context) => {
+		context.append("(");
+		context.render(expression);
+		context.append(" IN ");
+		context.renderRelation(parenthesize(query));
+		context.append(")");
+	});
+}
+function exists(query) {
+	return makeExpression("subquery", (context) => {
+		context.append("EXISTS ");
+		context.renderRelation(parenthesize(query));
+	});
+}
+function notExists(query) {
+	return makeExpression("subquery", (context) => {
+		context.append("NOT EXISTS ");
+		context.renderRelation(parenthesize(query));
+	});
+}
+//#endregion
+//#region src/expressions/operators/comparison/null.ts
+function isNull(expression) {
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(");
+		context.render(expression);
+		context.append(" IS NULL)");
+	});
+}
+function isNotNull(expression) {
+	return makeSchemaExpression("operator", (context) => {
+		context.append("(");
+		context.render(expression);
+		context.append(" IS NOT NULL)");
+	});
+}
+function isTrue(expression) {
+	return makeSchemaExpression("operator", (context) => {
+		context.render(expression);
+		context.append(" IS TRUE");
+	});
+}
+//#endregion
+//#region src/query/selection.ts
+/**
+* Return every known source column as a named projection object.
+*
+* The result can be passed directly to `select()` or spread into a larger
+* projection, such as `{ ...all(users), displayName: upper(users.name) }`.
+*/
+function all(source) {
+	return Object.freeze({ ...source.columns });
+}
+//#endregion
+//#region src/query/types.ts
+function createQuery(queryKind, row, render) {
+	return Object.freeze({
+		queryKind,
+		row,
+		...fragment(render)
+	});
+}
+//#endregion
+//#region src/query/select/render.ts
+function renderSelection(selection, context) {
+	assertNamedSelection(selection);
+	const entries = Object.entries(selection).filter(([, expression]) => expression !== omit);
+	if (entries.length === 0) throw queryValidationError({
+		code: "invalid-selection",
+		context: "select.projection",
+		path: ["selection"],
+		message: "select() requires at least one field",
+		hint: "Pass a named projection object with at least one expression."
+	});
+	entries.forEach(([name, expression], index) => {
+		if (index > 0) context.append(", ");
+		if (!isExpression(expression)) throw queryValidationError({
+			code: "invalid-selection",
+			context: "select.projection",
+			path: ["selection", name],
+			message: `Selection field "${name}" must be an expression`,
+			hint: "Use a Qubu expression such as table.column, value(), or a function."
+		});
+		const outputName = context.projectionMode === "result" ? name : snakeCaseIdentifier(name);
+		context.render(expression);
+		context.append(" AS ");
+		context.render(identifier(outputName));
+	});
+}
+function selectionRow(selection) {
+	assertNamedSelection(selection);
+	return Object.fromEntries(Object.entries(selection).filter(([, expression]) => expression !== omit).map(([name]) => [name, void 0]));
+}
+function assertNamedSelection(selection) {
+	if (Array.isArray(selection)) throw queryValidationError({
+		code: "invalid-selection",
+		context: "select.projection",
+		path: ["selection"],
+		message: "Selection must be a named object projection",
+		hint: "Pass { fieldName: expression } to select()."
+	});
+}
+//#endregion
+//#region src/query/select/validate.ts
+function validateClauses(clauses) {
+	const singletonKinds = /* @__PURE__ */ new Set([
+		"distinct",
+		"from",
+		"where",
+		"group-by",
+		"having",
+		"order-by",
+		"offset",
+		"fetch",
+		"row-lock"
+	]);
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, clause] of clauses.entries()) {
+		if (!singletonKinds.has(clause.clauseKind)) continue;
+		if (seen.has(clause.clauseKind)) {
+			const hint = clause.clauseKind === "where" || clause.clauseKind === "having" ? "Compose repeated conditions with and() or or()." : clause.clauseKind === "order-by" ? "Combine terms in one orderBy() call." : clause.clauseKind === "row-lock" ? "Combine the mode and wait policy in one rowLock() call." : "Keep one clause of this kind.";
+			throw queryValidationError({
+				code: "duplicate-clause",
+				context: "select.clauses",
+				path: ["clauses", index],
+				message: `Only one ${clause.clauseKind} clause is allowed`,
+				hint
+			});
+		}
+		seen.add(clause.clauseKind);
+	}
+}
+//#endregion
+//#region src/query/clauses/pagination.ts
+function toPaginationPart(clause) {
+	return clause.clauseKind === "offset" ? {
+		kind: "offset",
+		rows: clause.rows
+	} : {
+		kind: "fetch",
+		rows: clause.rows,
+		direction: clause.direction
+	};
+}
+function renderPagination(context, clauses) {
+	const parts = clauses.map(toPaginationPart);
+	if (context.dialect.pagination) {
+		context.dialect.pagination.render(context, parts);
+		return;
+	}
+	parts.forEach((part, index) => {
+		if (index > 0) context.append(" ");
+		if (part.kind === "offset") {
+			context.append("OFFSET ");
+			context.parameter(part.rows);
+			context.append(" ROWS");
+		} else {
+			context.append(`FETCH ${part.direction} `);
+			context.parameter(part.rows);
+			context.append(" ROWS ONLY");
+		}
+	});
+}
+function offset(rows) {
+	if (!Number.isInteger(rows) || rows < 0) throw queryValidationError({
+		code: "invalid-pagination",
+		context: "select.pagination.offset",
+		path: ["offset"],
+		message: "offset() requires a non-negative integer",
+		hint: "Pass a non-negative integer row count."
+	});
+	return Object.assign(createClause("offset", "after-select", 90, (context) => renderPagination(context, [{
+		clauseKind: "offset",
+		rows
+	}])), {
+		clauseKind: "offset",
+		rows
+	});
+}
+function fetchRows(direction, rows) {
+	if (!Number.isInteger(rows) || rows < 0) throw queryValidationError({
+		code: "invalid-pagination",
+		context: `select.pagination.fetch${direction === "FIRST" ? "First" : "Next"}`,
+		path: ["fetch", direction],
+		message: "fetch rows require a non-negative integer",
+		hint: "Pass a non-negative integer row count."
+	});
+	return Object.assign(createClause("fetch", "after-select", 100, (context) => renderPagination(context, [{
+		clauseKind: "fetch",
+		direction,
+		rows
+	}])), {
+		clauseKind: "fetch",
+		direction,
+		rows
+	});
+}
+function fetchFirst(rows) {
+	return fetchRows("FIRST", rows);
+}
+function fetchNext(rows) {
+	return fetchRows("NEXT", rows);
+}
+//#endregion
+//#region src/query/select.ts
+function select(selection, ...parts) {
+	const normalizedClauses = parts.filter((part) => part !== omit);
+	validateClauses(normalizedClauses);
+	const orderedClauses = normalizedClauses.map((clause, index) => ({
+		clause,
+		index
+	})).sort((left, right) => left.clause.order - right.clause.order || left.index - right.index).map(({ clause }) => clause);
+	return createQuery("select", selectionRow(selection), (context) => {
+		const beforeSelect = orderedClauses.filter((clause) => clause.placement === "before-select");
+		const afterSelect = orderedClauses.filter((clause) => clause.placement === "after-select");
+		const paginationClauses = afterSelect.filter((clause) => clause.clauseKind === "offset" || clause.clauseKind === "fetch");
+		let renderedPagination = false;
+		for (const clause of beforeSelect) {
+			if (clause.clauseKind === "correlate") continue;
+			context.render(clause);
+			context.append(" ");
+		}
+		context.append("SELECT ");
+		const distinctClause = afterSelect.find((clause) => clause.clauseKind === "distinct");
+		if (distinctClause) {
+			context.render(distinctClause);
+			context.append(" ");
+		}
+		renderSelection(selection, context);
+		for (const clause of afterSelect) {
+			if (clause.clauseKind === "correlate") continue;
+			if (clause === distinctClause) continue;
+			if (clause.clauseKind === "offset" || clause.clauseKind === "fetch") {
+				if (renderedPagination) continue;
+				renderedPagination = true;
+				context.append(" ");
+				renderPagination(context, paginationClauses);
+				continue;
+			}
+			context.append(" ");
+			context.render(clause);
+		}
+	});
+}
+//#endregion
+//#region src/query/set.ts
+function setOperation(operator, left, right) {
+	return {
+		queryKind: "set",
+		row: left.row,
+		render: (context) => {
+			context.render(parenthesize(left));
+			context.append(` ${operator} `);
+			context.render(parenthesize(right));
+		}
+	};
+}
+function union(left, right) {
+	return setOperation("UNION", left, right);
+}
+function unionAll(left, right) {
+	return setOperation("UNION ALL", left, right);
+}
+function intersect(left, right) {
+	return setOperation("INTERSECT", left, right);
+}
+function except(left, right) {
+	return setOperation("EXCEPT", left, right);
+}
+//#endregion
+//#region src/query/clauses/correlate.ts
+function correlate(...sources) {
+	return Object.assign(createClause("correlate", "before-select", 0, (_context) => {}), {
+		clauseKind: "correlate",
+		sources
+	});
+}
+//#endregion
+//#region src/query/clauses/distinct.ts
+function distinct() {
+	return Object.assign(createClause("distinct", "after-select", 20, (context) => {
+		context.append("DISTINCT");
+	}), { clauseKind: "distinct" });
+}
+//#endregion
+//#region src/query/clauses/from.ts
+function from(...sources) {
+	return Object.assign(createClause("from", "after-select", 30, (context) => {
+		context.append("FROM ");
+		sources.forEach((source, index) => {
+			if (index > 0) context.append(", ");
+			context.render(source);
+		});
+	}), {
+		clauseKind: "from",
+		sources
+	});
+}
+//#endregion
+//#region src/query/clauses/group-by.ts
+function groupBy(...expressions) {
+	return Object.assign(createClause("group-by", "after-select", 60, (context) => {
+		context.append("GROUP BY ");
+		expressions.forEach((expression, index) => {
+			if (index > 0) context.append(", ");
+			context.render(expression);
+		});
+	}), {
+		clauseKind: "group-by",
+		expressions
+	});
+}
+//#endregion
+//#region src/query/clauses/having.ts
+function having(condition) {
+	if (condition === omit) return omit;
+	return Object.assign(createClause("having", "after-select", 70, (context) => {
+		context.append("HAVING ");
+		context.render(condition);
+	}), {
+		clauseKind: "having",
+		condition
+	});
+}
+//#endregion
+//#region src/query/clauses/joins.ts
+function join(joinType, source, condition) {
+	return Object.assign(createClause("join", "after-select", 40, (context) => {
+		context.append(`${joinType} JOIN `);
+		context.render(source);
+		if (condition) {
+			context.append(" ON ");
+			context.render(condition);
+		}
+	}), {
+		clauseKind: "join",
+		joinType,
+		source,
+		condition
+	});
+}
+function innerJoin(source, condition) {
+	return join("INNER", source, condition);
+}
+function leftJoin(source, condition) {
+	return join("LEFT", source, condition);
+}
+function rightJoin(source, condition) {
+	return join("RIGHT", source, condition);
+}
+function fullJoin(source, condition) {
+	return join("FULL", source, condition);
+}
+function crossJoin(source) {
+	return join("CROSS", source);
+}
+function naturalJoin(source) {
+	return join("NATURAL", source);
+}
+//#endregion
+//#region src/query/clauses/order-by.ts
+function orderTerm(expression, direction, nulls) {
+	const base = makeExpression("operator", (context) => {
+		context.render(expression);
+		if (direction) context.append(` ${direction}`);
+		if (nulls) context.append(` NULLS ${nulls}`);
+	});
+	return Object.freeze({
+		...base,
+		orderKind: "term",
+		expression,
+		direction,
+		nulls
+	});
+}
+function order(expression, direction, nulls) {
+	return orderTerm(expression, direction, nulls);
+}
+function asc(expression, nulls) {
+	return orderTerm(expression, "ASC", nulls);
+}
+function desc(expression, nulls) {
+	return orderTerm(expression, "DESC", nulls);
+}
+function nullsFirst(expression) {
+	return orderTerm(expression, void 0, "FIRST");
+}
+function nullsLast(expression) {
+	return orderTerm(expression, void 0, "LAST");
+}
+function orderBy(...parts) {
+	const presentParts = parts.filter((part) => part !== omit);
+	if (presentParts.length === 0) return omit;
+	const terms = presentParts.map((part) => "orderKind" in part ? part : orderTerm(part));
+	return Object.assign(createClause("order-by", "after-select", 80, (context) => {
+		context.append("ORDER BY ");
+		terms.forEach((term, index) => {
+			if (index > 0) context.append(", ");
+			context.render(term);
+		});
+	}), {
+		clauseKind: "order-by",
+		terms
+	});
+}
+//#endregion
+//#region src/query/clauses/row-lock.ts
+const rowLockModes = [
+	"update",
+	"no-key-update",
+	"share",
+	"key-share"
+];
+const rowLockWaitPolicies = [
+	"default",
+	"nowait",
+	"skip-locked"
+];
+function rowLock(modeOrOptions = "update", wait = "default") {
+	const mode = typeof modeOrOptions === "string" ? modeOrOptions : modeOrOptions.mode ?? "update";
+	const waitPolicy = typeof modeOrOptions === "string" ? wait : modeOrOptions.wait ?? modeOrOptions.waitPolicy ?? "default";
+	validateRowLockMode(mode);
+	validateRowLockWaitPolicy(waitPolicy);
+	return Object.assign(createClause("row-lock", "after-select", 110, (context) => {
+		assertDialectCapability(context.dialect, "row-locking");
+		const policy = context.dialect.rowLocking;
+		if (!policy) throw new Error(`Dialect "${context.dialect.name}" advertises the "row-locking" capability without a row-locking policy`);
+		policy.render(context, mode, waitPolicy);
+	}), {
+		clauseKind: "row-lock",
+		mode,
+		wait: waitPolicy
+	});
+}
+function validateRowLockMode(mode) {
+	if (rowLockModes.includes(mode)) return;
+	throw queryValidationError({
+		code: "invalid-row-lock",
+		context: "select.row-lock",
+		path: ["rowLock", "mode"],
+		message: `rowLock() does not support the "${String(mode)}" lock mode`,
+		hint: "Use update, no-key-update, share, or key-share."
+	});
+}
+function validateRowLockWaitPolicy(wait) {
+	if (rowLockWaitPolicies.includes(wait)) return;
+	throw queryValidationError({
+		code: "invalid-row-lock",
+		context: "select.row-lock",
+		path: ["rowLock", "wait"],
+		message: `rowLock() does not support the "${String(wait)}" wait policy`,
+		hint: "Use default, nowait, or skip-locked."
+	});
+}
+//#endregion
+//#region src/query/clauses/where.ts
+function where(condition) {
+	if (condition === omit) return omit;
+	return Object.assign(createClause("where", "after-select", 50, (context) => {
+		context.append("WHERE ");
+		context.render(condition);
+	}), {
+		clauseKind: "where",
+		condition
+	});
+}
+//#endregion
+//#region src/query/clauses/with.ts
+function cte(name, query) {
+	const reference = identifier(name);
+	const source = createSource("cte", (context) => context.render(reference), reference);
+	const sqlNames = resolveSqlNames(Object.keys(query.row).map((fieldName) => ({ fieldName })));
+	const columns = Object.fromEntries(Object.keys(query.row).map((fieldName) => [fieldName, createColumnReference(sqlNames[fieldName], reference, fieldName)]));
+	Object.assign(source, {
+		cteName: name,
+		query,
+		columns
+	});
+	exposeColumns(source, columns);
+	return source;
+}
+/**
+* Define a typed recursive `WITH` source from an anchor and one recursive
+* member. The callback receives a forward reference that must be introduced
+* through the member query's normal FROM or JOIN scope.
+*/
+function recursiveCte(name, anchor, member) {
+	const reference = identifier(name);
+	const source = createSource("cte", (context) => context.render(reference), reference);
+	const sqlNames = resolveSqlNames(Object.keys(anchor.row).map((fieldName) => ({ fieldName })));
+	const columns = Object.fromEntries(Object.keys(anchor.row).map((fieldName) => [fieldName, createColumnReference(sqlNames[fieldName], reference, fieldName)]));
+	Object.assign(source, {
+		cteName: name,
+		query: anchor,
+		columns
+	});
+	exposeColumns(source, columns);
+	const memberQuery = member(source);
+	const query = Object.freeze({
+		...createQuery("set", anchor.row, (context) => {
+			context.render(anchor);
+			context.append(" UNION ALL ");
+			context.render(memberQuery);
+		}),
+		recursive: true
+	});
+	Object.assign(source, { query });
+	return source;
+}
+function withCte(...ctes) {
+	return Object.assign(createClause("with", "before-select", 10, (context) => {
+		context.append(ctes.some((entry) => entry.query.recursive) ? "WITH RECURSIVE " : "WITH ");
+		ctes.forEach((entry, index) => {
+			if (index > 0) context.append(", ");
+			context.render(identifier(entry.cteName));
+			if (entry.query.recursive) {
+				const sqlNames = resolveSqlNames(Object.keys(entry.query.row).map((fieldName) => ({ fieldName })));
+				context.append(" (");
+				Object.keys(entry.query.row).forEach((fieldName, columnIndex) => {
+					if (columnIndex > 0) context.append(", ");
+					context.render(identifier(sqlNames[fieldName]));
+				});
+				context.append(")");
+			}
+			context.append(" AS ");
+			context.renderRelation(parenthesize(entry.query));
+		});
+	}), {
+		clauseKind: "with",
+		ctes
+	});
+}
+//#endregion
+//#region src/query/mutation/types.ts
+function createMutation(queryKind, row, render) {
+	return {
+		queryKind,
+		row,
+		render
+	};
+}
+function allowAll() {
+	return Object.freeze({
+		clauseKind: "allow-all",
+		render: () => void 0
+	});
+}
+function validateMutationClauses(kind, clauses) {
+	let whereSeen = false;
+	let returningSeen = false;
+	let allowAllSeen = false;
+	for (const clause of clauses) if (clause.clauseKind === "where") {
+		if (whereSeen) throw queryValidationError({
+			code: "duplicate-clause",
+			context: `mutation.${kind.toLowerCase()}.clauses`,
+			path: ["clauses", "where"],
+			message: `${kind} accepts only one WHERE clause`,
+			hint: "Compose repeated conditions with and() or or()."
+		});
+		whereSeen = true;
+	} else if (clause.clauseKind === "returning") {
+		if (returningSeen) throw queryValidationError({
+			code: "duplicate-clause",
+			context: `mutation.${kind.toLowerCase()}.clauses`,
+			path: ["clauses", "returning"],
+			message: `${kind} accepts only one RETURNING clause`,
+			hint: "Use one returning() clause containing the complete projection."
+		});
+		returningSeen = true;
+	} else if (clause.clauseKind === "allow-all") {
+		if (allowAllSeen) throw queryValidationError({
+			code: "duplicate-clause",
+			context: `mutation.${kind.toLowerCase()}.clauses`,
+			path: ["clauses", "allowAll"],
+			message: `${kind} accepts only one allowAll() marker`,
+			hint: "Keep one allowAll() marker when the mutation is intentionally unrestricted."
+		});
+		allowAllSeen = true;
+	}
+	if (!whereSeen && !allowAllSeen) throw queryValidationError({
+		code: "unsafe-mutation",
+		context: `mutation.${kind.toLowerCase()}.safety`,
+		path: ["clauses"],
+		message: `${kind} requires a WHERE clause; use allowAll() to opt into an unrestricted mutation`,
+		hint: "Add where(...) to target rows, or add allowAll() to make the unrestricted intent explicit."
+	});
+}
+//#endregion
+//#region src/query/mutation/insert.ts
+function values(...rows) {
+	return Object.freeze({
+		insertKind: "values",
+		rows
+	});
+}
+function defaultValues() {
+	return Object.freeze({ insertKind: "default-values" });
+}
+function insertSelect(query, columns) {
+	return Object.freeze({
+		insertKind: "select",
+		query,
+		columns
+	});
+}
+function insertInto(table, source, ...clauses) {
+	validateInsert(table, source);
+	const insertClauses = clauses;
+	return createMutation("insert", insertClauses.find((clause) => clause.clauseKind === "returning")?.row ?? {}, (context) => {
+		context.append("INSERT INTO ");
+		context.render(table.reference);
+		if (source.insertKind === "values") {
+			const rows = source.rows;
+			const columns = Object.keys(rows[0] ?? {});
+			if (columns.length === 0) context.append(" DEFAULT VALUES");
+			else {
+				renderTargetColumns(context, table, columns);
+				context.append(" VALUES ");
+				rows.forEach((row, rowIndex) => {
+					if (rowIndex > 0) context.append(", ");
+					context.append("(");
+					columns.forEach((columnName, columnIndex) => {
+						if (columnIndex > 0) context.append(", ");
+						renderInsertValue(context, row[columnName]);
+					});
+					context.append(")");
+				});
+			}
+		} else if (source.insertKind === "default-values") context.append(" DEFAULT VALUES");
+		else {
+			renderTargetColumns(context, table, source.columns);
+			context.append(" ");
+			context.renderRelation(source.query);
+		}
+		for (const clause of insertClauses) {
+			context.append(" ");
+			context.render(clause);
+		}
+	});
+}
+function renderTargetColumns(context, table, columns) {
+	context.append(" (");
+	columns.forEach((columnName, index) => {
+		if (index > 0) context.append(", ");
+		context.render(identifier(table.sqlNames[columnName] ?? columnName));
+	});
+	context.append(")");
+}
+function renderInsertValue(context, input) {
+	if (isExpression(input)) context.render(input);
+	else context.parameter(input);
+}
+function validateInsert(table, source) {
+	const definitions = table.definitions;
+	if (source.insertKind === "values") {
+		const firstColumns = Object.keys(source.rows[0] ?? {});
+		const firstSet = new Set(firstColumns);
+		for (const columnName of firstColumns) {
+			if (!definitions[columnName]) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.values.columns",
+				path: ["values", columnName],
+				message: `Unknown insert column "${columnName}"`,
+				hint: "Use only columns declared by the insert table."
+			});
+			if (definitions[columnName].generated) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.values.columns",
+				path: ["values", columnName],
+				message: `Generated column "${columnName}" cannot be inserted`,
+				hint: "Omit generated columns from the insert values."
+			});
+		}
+		for (const row of source.rows) {
+			const columns = Object.keys(row);
+			if (columns.length !== firstColumns.length || columns.some((columnName) => !firstSet.has(columnName))) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.values.rows",
+				path: ["values", "rows"],
+				message: "All INSERT values rows must use the same columns",
+				hint: "Use one identical column set for every values row."
+			});
+		}
+		for (const [columnName, definition] of Object.entries(definitions)) {
+			if (definition.generated || definition.hasDefault) continue;
+			if (!firstSet.has(columnName)) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.values.columns",
+				path: ["values", columnName],
+				message: `Required insert column "${columnName}" is missing`,
+				hint: "Provide the column value or define a default for it."
+			});
+		}
+	} else if (source.insertKind === "default-values") {
+		for (const [columnName, definition] of Object.entries(definitions)) if (!definition.generated && !definition.hasDefault) throw queryValidationError({
+			code: "invalid-insert",
+			context: "insert.default-values",
+			path: ["defaultValues", columnName],
+			message: `DEFAULT VALUES requires column "${columnName}" to have a default`,
+			hint: "Provide values for required columns or define defaults for them."
+		});
+	} else {
+		if (source.columns.length === 0) throw queryValidationError({
+			code: "invalid-insert",
+			context: "insert.select.columns",
+			path: ["insertSelect", "columns"],
+			message: "INSERT ... SELECT requires at least one target column",
+			hint: "List the target columns receiving the SELECT result."
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const columnName of source.columns) {
+			if (seen.has(columnName)) throw queryValidationError({
+				code: "duplicate-clause",
+				context: "insert.select.columns",
+				path: [
+					"insertSelect",
+					"columns",
+					columnName
+				],
+				message: `Duplicate insert column "${columnName}"`,
+				hint: "List each insert target column once."
+			});
+			seen.add(columnName);
+			if (!definitions[columnName]) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.select.columns",
+				path: [
+					"insertSelect",
+					"columns",
+					columnName
+				],
+				message: `Unknown insert column "${columnName}"`,
+				hint: "Use only columns declared by the insert table."
+			});
+			if (definitions[columnName].generated) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.select.columns",
+				path: [
+					"insertSelect",
+					"columns",
+					columnName
+				],
+				message: `Generated column "${columnName}" cannot be inserted`,
+				hint: "Omit generated columns from the insert target list."
+			});
+		}
+		for (const [columnName, definition] of Object.entries(definitions)) {
+			if (definition.generated || definition.hasDefault) continue;
+			if (!seen.has(columnName)) throw queryValidationError({
+				code: "invalid-insert",
+				context: "insert.select.columns",
+				path: [
+					"insertSelect",
+					"columns",
+					columnName
+				],
+				message: `Required insert column "${columnName}" is missing`,
+				hint: "Include every required insert column in the target list."
+			});
+		}
+	}
+}
+//#endregion
+//#region src/query/mutation/update.ts
+function update(table, assignments, ...clauses) {
+	const normalizedClauses = clauses;
+	validateMutationClauses("UPDATE", normalizedClauses);
+	const entries = validateUpdate(table, assignments);
+	const whereClause = normalizedClauses.find((clause) => clause.clauseKind === "where");
+	const returningClause = normalizedClauses.find((clause) => clause.clauseKind === "returning");
+	return createMutation("update", returningClause?.row ?? {}, (context) => {
+		context.append("UPDATE ");
+		context.render(table.reference);
+		context.append(" SET ");
+		entries.forEach(([columnName, value], index) => {
+			if (index > 0) context.append(", ");
+			context.render(identifier(table.sqlNames[columnName] ?? columnName));
+			context.append(" = ");
+			renderAssignmentValue(context, value);
+		});
+		if (whereClause) {
+			context.append(" ");
+			context.render(whereClause);
+		}
+		if (returningClause) {
+			context.append(" ");
+			context.render(returningClause);
+		}
+	});
+}
+function renderAssignmentValue(context, value) {
+	if (isExpression(value)) context.render(value);
+	else context.parameter(value);
+}
+function validateUpdate(table, assignments) {
+	const definitions = table.definitions;
+	const entries = Object.entries(assignments).filter(([, value]) => value !== omit);
+	if (entries.length === 0) throw queryValidationError({
+		code: "invalid-update",
+		context: "update.assignments",
+		path: ["assignments"],
+		message: "UPDATE requires at least one assignment",
+		hint: "Provide at least one writable column, or remove the update."
+	});
+	for (const [columnName] of entries) {
+		const definition = definitions[columnName];
+		if (!definition) throw queryValidationError({
+			code: "invalid-update",
+			context: "update.assignments",
+			path: ["assignments", columnName],
+			message: `Unknown update column "${columnName}"`,
+			hint: "Use a column declared by the update table."
+		});
+		if (definition.generated) throw queryValidationError({
+			code: "invalid-update",
+			context: "update.assignments",
+			path: ["assignments", columnName],
+			message: `Generated column "${columnName}" cannot be updated`,
+			hint: "Remove the generated column from the assignments."
+		});
+	}
+	return entries;
+}
+//#endregion
+//#region src/query/mutation/delete.ts
+function deleteFrom(table, ...clauses) {
+	const normalizedClauses = clauses;
+	validateMutationClauses("DELETE", normalizedClauses);
+	const whereClause = normalizedClauses.find((clause) => clause.clauseKind === "where");
+	const returningClause = normalizedClauses.find((clause) => clause.clauseKind === "returning");
+	return createMutation("delete", returningClause?.row ?? {}, (context) => {
+		context.append("DELETE FROM ");
+		context.render(table.reference);
+		if (whereClause) {
+			context.append(" ");
+			context.render(whereClause);
+		}
+		if (returningClause) {
+			context.append(" ");
+			context.render(returningClause);
+		}
+	});
+}
+//#endregion
+//#region src/query/mutation/returning.ts
+function returning(selection) {
+	return Object.freeze({
+		clauseKind: "returning",
+		selection,
+		row: selectionRow(selection),
+		render(context) {
+			context.append("RETURNING ");
+			renderSelection(selection, context);
+		}
+	});
+}
+//#endregion
+export { QueryValidationError, add, alias, all, allowAll, and, asValue, asc, avg, between, bigint, binary, boolean, call, caseWhen, cast, catalogCheck, catalogForeignKey, check, coalesce, column, concat, correlate, count, countDistinct, crossJoin, cte, date, defaultValues, deleteFrom, denseRank, desc, distinct, divide, eq, except, execute, executeRows, exists, explain, externalDefault, externalGeneratedColumn, fetchFirst, fetchNext, foreignKey, from, fullJoin, generatedColumn, groupBy, gt, gte, having, identityColumn, inList, inQuery, index, innerJoin, insertInto, insertSelect, integer, intersect, isDistinctFrom, isNotDistinctFrom, isNotNull, isNull, isTrue, json, jsonBoolean, jsonExists, jsonNumber, jsonPath, jsonText, lateral, leftJoin, like, lower, lt, lte, max, min, modulo, multiply, nativeColumn, nativeStorage, naturalJoin, ne, not, notExists, notIn, notLike, nullable, nullsFirst, nullsLast, numeric, offset, omit, or, order, orderBy, over, portableStorage, primaryKey, qubu, rank, recursiveCte, references, render, returning, rightJoin, rowLock, rowNumber, scalar, schema, schemaCall, select, sql, stream, subtract, sum, table, text, timestamp, union, unionAll, unique, uniqueConstraint, unsafeSchemaSql, update, upper, uuid, value, values, where, withCte };