joist-core 2.3.0 → 2.4.0-next.2

package/build/queries/sql/query.js

@@ -0,0 +1,1592 @@
+import { kq, kqStar, safeKq } from "./keywords.js";
+import { skipCondition } from "../skipCondition.js";
+import { predicateBrand } from "../conditions.js";
+import { isDeferredAliasCondition } from "../find/DeferredAlias.js";
+import { ConditionBuilder } from "../ConditionBuilder.js";
+import { filterSoftDeletes, lazyExcludedSelects, stiSubtypeFilter } from "../entityQueryUtils.js";
+import { deepFindConditions } from "../parsedConditions.js";
+import { BaseExpr, TemplateExpr, asNode, deferredCondition, deferredSym, isExpr, orderByToSql, resolveDeferredConditions, selectKeyBrand } from "./Expr.js";
+import { fail } from "../../utils.js";
+import { getBaseMeta } from "../../EntityMetadata.js";
+import { buildWhereClause } from "../renderConditions.js";
+import { AliasAssigner } from "./AliasAssigner.js";
+import { JoinTableHandle, collectionJoin, getTableMetadata, getTableMgmt, inQueryCondition, isEntityTable, isTable, m2mJoinTable, referenceJoinSource, tableSqlName } from "./Tables.js";
+import { buildExpr } from "./expressions/expression.js";
+import { compileJoinTree } from "./JoinTree.js";
+//#region src/queries/sql/query.ts
+/**
+* `em.query`: SQL-shaped queries as plain object literals.
+*
+* A query is data, a `Query<S, J>` POJO, `{ from, join, where, groupBy, having, select, orderBy, ... }`
+* in SQL evaluation order:
+*
+*   const [a, b] = tables(Author, Book);
+*   const bookStats = query({ from: b, groupBy: [b.author_id], select: { authorId: b.author_id, n: b.id.count() } });
+*   const rows = await em.query({
+*     from: a,
+*     join: [{ left: bookStats, on: bookStats.authorId.eq(a.id) }],
+*     select: { name: a.first_name, n: bookStats.n },
+*     orderBy: { n: "DESC" },
+*   });
+*   // rows: { name: string; n: number | undefined }[]   (undefined because of the LEFT join)
+*
+* `em.query(pojo)` runs it. `select` decides the row type: a bare table returns entities, an array of
+* columns or a `{ key: expr }` object returns typed POJOs, and a bare subquery returns its rows.
+*
+* `query(pojo)` turns the *same* POJO into a value: a derived table with typed columns, a scalar
+* expression, or an entity list. It is the one non-POJO step, and the subquery analog of `table(Author)`:
+* to reference a query's columns, the outer query needs *values* for them, and no POJO can manufacture
+* values keyed off its own `select` keys.
+*
+* `table()`/`tables()` and `query()` are the only free functions a query needs, plus the `sql` tagged
+* template as the escape hatch for SQL with no modeled shape. Everything else is in-DSL: join kinds are
+* keyword keys (`{ left: b, on }`), SQL functions are methods on
+* expressions (`b.id.count()`, `b.title.max()`, `x.coalesce(0)`), conditions are methods
+* (`a.age.gte(18)`), and pruning is `undefined`: an `undefined` condition drops out, and a join nothing
+* references anymore drops with it (see "Pruning" below).
+*
+* User documentation: `docs/src/content/docs/features/queries-raw.md`.
+*/
+const subqueryBrand = Symbol("joist.subquery");
+const entityQueryBrand = Symbol("joist.entityQuery");
+const scalarQueryBrand = Symbol("joist.scalarQuery");
+function query(q) {
+	return createQueryValue(q);
+}
+/**
+* Builds a query value only when its user-supplied `where` or join-tree filters survive pruning.
+*
+* Missing or empty conditions prune the value, including nested groups and `pruneIfUndefined`.
+* Alias-only joins, HAVING, and implicit soft-delete/STI conditions do not keep the value alive.
+*
+* I.e. `queryMaybe({ from: b, where: b.authorId.eq(enabled ? a.id : undefined), select: b.id })`
+* returns `undefined` when `enabled` is false, so an enclosing `notExists` also prunes.
+*/
+function queryMaybe(q) {
+	return createMaybeQueryValue(q);
+}
+/** Applies queryMaybe's structural pruning before creating any kind of read-query value. */
+function createMaybeQueryValue(q) {
+	const normalized = normalizeQueryJoins(q);
+	const where = normalizeWhere(normalized.where);
+	checkCondition(where);
+	return isPrunedQueryCondition(where) ? void 0 : createQueryValue(normalized);
+}
+/**
+* Declares a `WITH RECURSIVE` CTE from its two terms, and returns the CTE as a readable value.
+*
+* `base` is the non-recursive term, which seeds the rows and, as in PostgreSQL, supplies the CTE's
+* columns. `step` is the recursive term: it receives the CTE itself, so it can join back to the rows
+* found so far. The two terms are combined with UNION ALL, or UNION when `union: "distinct"` drops
+* duplicates, which is how a cyclic graph is kept from looping forever.
+*
+* ```ts
+* const [a] = tables(Author);
+* const tree = recursiveQuery(
+*   "tree",
+*   { from: a, where: a.mentor_id.isNull(), select: { id: a.id, mentorId: a.mentor_id } },
+*   (self) => ({
+*     from: a,
+*     join: [{ inner: self, on: a.mentor_id.eq(self.id) }],
+*     select: { id: a.id, mentorId: a.mentor_id },
+*   }),
+* );
+* const rows = await em.query({ with: tree, from: tree, select: tree });
+* ```
+*
+* Unlike `query()`, the name is required, because the step term must name it.
+*/
+function recursiveQuery(name, base, step, opts = {}) {
+	if (typeof name !== "string" || name === "") fail("A recursive CTE needs a name");
+	if (opts.union !== void 0 && opts.union !== "all" && opts.union !== "distinct") fail("A recursive CTE's union must be 'all' or 'distinct'");
+	const handle = new SubqueryHandle(toQuery(base), true);
+	if (handle.output().kind !== "pojo") fail("A recursive CTE's base term needs a named projection");
+	const self = newSubqueryProxy(handle);
+	const operands = [base, step(self)];
+	handle.setBody(opts.union === "distinct" ? {
+		union: operands,
+		as: name
+	} : {
+		unionAll: operands,
+		as: name
+	});
+	return self;
+}
+/**
+* Builds a SQL expression from a tagged template.
+*
+* For an Author alias `a` assigned the SQL alias `a1`:
+*
+* ```ts
+* sql`${a.age} * 2`     // Expression: a1.age * 2
+* sql`${a.age.gte(18)}` // Condition: (a1.age >= ?), bindings [18]
+* sql`${"Alice"}`      // Value: ?, bindings ["Alice"]
+*
+* // Selecting this expression keeps the join to Book b.
+* sql.number`${b.order} * ${2}`
+*
+* // Reference an unmodeled column; prefer the table's own `column`, which keeps its source key.
+* a.column<string>("ts_search")
+* sql.condition`${a.column("ts_search")} @@ plainto_tsquery(${term})`
+* ```
+*/
+function sql(strings, ...values) {
+	return typedSql(strings, ...values);
+}
+/** Shorthand for `sql<number>`; does not cast or convert the SQL result. */
+sql.number = typedSql;
+/** Shorthand for `sql<number | null>`; does not cast or convert the SQL result. */
+sql.numberOrNull = typedSql;
+/** Shorthand for `sql<number[]>`; does not cast or convert the SQL result. */
+sql.numberArray = typedSql;
+/** Shorthand for `sql<number[] | null>`; does not cast or convert the SQL result. */
+sql.numberArrayOrNull = typedSql;
+/** Shorthand for `sql<string>`; does not cast or convert the SQL result. */
+sql.string = typedSql;
+/** Shorthand for `sql<string | null>`; does not cast or convert the SQL result. */
+sql.stringOrNull = typedSql;
+/** Shorthand for `sql<string[]>`; does not cast or convert the SQL result. */
+sql.stringArray = typedSql;
+/** Shorthand for `sql<string[] | null>`; does not cast or convert the SQL result. */
+sql.stringArrayOrNull = typedSql;
+/** Shorthand for `sql<boolean>`; does not cast or convert the SQL result. */
+sql.boolean = typedSql;
+/** Shorthand for `sql<boolean | null>`; does not cast or convert the SQL result. */
+sql.booleanOrNull = typedSql;
+/** Shorthand for `sql<boolean[]>`; does not cast or convert the SQL result. */
+sql.booleanArray = typedSql;
+/** Shorthand for `sql<boolean[] | null>`; does not cast or convert the SQL result. */
+sql.booleanArrayOrNull = typedSql;
+/** A raw condition for `where`, `having`, or `on`. */
+sql.condition = function condition(strings, ...values) {
+	return deferredCondition((ctx) => new TemplateExpr(strings, values).toSql(ctx));
+};
+/**
+* Parses `arg` (a `Query` POJO or `query(...)` value) into a runnable `Plan`.
+*
+* `EntityManager.query` runs the plan; this module deliberately does not import `EntityManager` (see
+* `EntityHydrator`), so it parses and hands back `{ sql, bindings, decodeRows }` instead of executing.
+*/
+function parseUserQuery(arg) {
+	if (arg instanceof SubqueryExpr) fail("Scalar query values are expressions, not executable read inputs");
+	return parseQuery(toQuery(arg), void 0, new AliasAssigner());
+}
+/**
+* Parses a read that sits inside another statement, i.e. an INSERT's SELECT source, so it resolves that
+* statement's CTEs and shares its alias space instead of generating names that could collide with them.
+*/
+function parseNestedQuery(arg, parent, assigner) {
+	if (arg instanceof SubqueryExpr) fail("Scalar query values are expressions, not executable read inputs");
+	return parseQuery(toQuery(arg), parent, assigner);
+}
+/** Recognizes read brands, including malformed hybrids that must reach read validation rather than mutation execution. */
+function isReadQueryValue(arg) {
+	return isSubqueryValue(arg) || isEntityQueryValue(arg);
+}
+/**
+* Compiles scalar or nonempty named expression projections, shared by SELECT and mutation RETURNING.
+* Source-shaped values need read hydration/source rules and are deliberately excluded here.
+*/
+function projectionToSql(select, ctx, joins) {
+	const output = joinedOutput(projectionOutput(select), joins);
+	if (output.kind === "scalar") {
+		const expr = output.columns[0][1];
+		const fragment = expr.toSql(ctx);
+		return {
+			selects: [{
+				...fragment,
+				sql: `${fragment.sql} AS value`
+			}],
+			decodeRows: (_, rows) => rows.map((row) => decodeValue(expr, row.value)),
+			output
+		};
+	}
+	const entries = output.columns;
+	return {
+		selects: entries.map((entry) => {
+			const [key, expr] = entry;
+			const fragment = expr.toSql(ctx);
+			return {
+				...fragment,
+				sql: `${fragment.sql} AS ${safeKq(key)}`
+			};
+		}),
+		decodeRows: (_, rows) => rows.map((row) => decodeRow(row, entries)),
+		output
+	};
+}
+/** The runtime identity of a `query(...)` value; `Ctx.aliasFor` keys on it, like a table's `TableMgmt`. */
+var SubqueryHandle = class {
+	recursive;
+	#q;
+	constructor(q, recursive = false) {
+		this.recursive = recursive;
+		this.#q = q;
+	}
+	get q() {
+		return this.#q;
+	}
+	/**
+	* Gives a recursive CTE its finished body. `recursiveQuery` starts the handle on its base term, so
+	* the step term can read the CTE's columns while the body that will hold that step is still being
+	* built. The base term supplies the CTE's columns either way, PostgreSQL's rule for a recursive WITH.
+	*/
+	setBody(q) {
+		if (!this.recursive) fail("Only a recursive CTE replaces its body");
+		this.#q = q;
+	}
+	get name() {
+		return this.q.as;
+	}
+	/** The select keys, for `select: <subquery>` and for reporting unknown columns. */
+	columnKeys() {
+		const output = this.output();
+		if (output.kind === "pojo") return output.columns.map(([key]) => key);
+		return fail(`A subquery with an entity or scalar select has no columns`);
+	}
+	/** The inner expression behind `key`, for its decoder/encoder. */
+	columnExpr(key) {
+		return this.output().columns.find(([name]) => name === key)?.[1] ?? fail(`Subquery ${this.describe()} has no column ${key}`);
+	}
+	/** Resolve output metadata without parsing SQL or caching aliases from an enclosing query. */
+	output() {
+		return queryOutput(this.q);
+	}
+	column(key) {
+		return new SubqueryColumnExpr(this, key, this.columnExpr(key));
+	}
+	describe() {
+		return this.q.as ? `'${this.q.as}'` : "(anonymous)";
+	}
+};
+/** A column of a joined/from'd subquery, i.e. `bookStats.bookCount`, which becomes `book_stats."bookCount"`. */
+var SubqueryColumnExpr = class extends BaseExpr {
+	handle;
+	key;
+	inner;
+	constructor(handle, key, inner) {
+		super();
+		this.handle = handle;
+		this.key = key;
+		this.inner = inner;
+	}
+	get [selectKeyBrand]() {
+		return this.key;
+	}
+	toSql(ctx) {
+		const alias = ctx.aliasFor(this.handle);
+		return {
+			sql: `${safeKq(alias)}.${safeKq(this.key)}`,
+			bindings: [],
+			refs: [alias]
+		};
+	}
+	decode(value) {
+		return this.inner.decode(value);
+	}
+	encode(value) {
+		return this.inner.encode(value);
+	}
+	get outputType() {
+		return this.inner.outputType;
+	}
+	get sqlNullable() {
+		return this.inner.sqlNullable;
+	}
+	get sqlSource() {
+		return this.handle;
+	}
+};
+/**
+* A scalar (or IN-list) subquery, i.e. `query({ from: b, where: [...], select: b.id.count() })`.
+*
+* It closes over the outer aliases it references, so correlation is free; those references are the
+* subquery's "free" aliases and count toward the outer query's join pruning.
+*/
+var SubqueryExpr = class extends BaseExpr {
+	handle;
+	[scalarQueryBrand] = true;
+	constructor(handle) {
+		super();
+		this.handle = handle;
+	}
+	get subquerySelect() {
+		const expr = this.handle.output().columns[0][1];
+		return expr instanceof OutputExpr ? expr.inner : expr;
+	}
+	get outputType() {
+		return this.subquerySelect.outputType;
+	}
+	get sqlNullable() {
+		return true;
+	}
+	toSql(ctx) {
+		const bare = this.toSqlBare(ctx);
+		return {
+			...bare,
+			sql: `(${bare.sql})`
+		};
+	}
+	toSqlBare(ctx) {
+		const parent = ctx instanceof Ctx ? ctx : fail("Subqueries need the query parser's context");
+		const plan = parseQuery(this.handle.q, parent, parent.assigner);
+		return {
+			sql: plan.sql,
+			bindings: plan.bindings,
+			refs: plan.outerRefs
+		};
+	}
+	decode(value) {
+		return this.subquerySelect.decode(value);
+	}
+	encode(value) {
+		return this.subquerySelect.encode(value);
+	}
+};
+function newSubqueryProxy(handle) {
+	return new Proxy({}, {
+		get(_, key) {
+			if (key === subqueryBrand) return handle;
+			if (typeof key === "string") return handle.column(key);
+		},
+		has(_, key) {
+			return key === subqueryBrand || typeof key === "string" && handle.columnKeys().includes(key);
+		}
+	});
+}
+function isSubqueryValue(value) {
+	return typeof value === "object" && value !== null && subqueryBrand in value;
+}
+function isEntityQueryValue(value) {
+	return typeof value === "object" && value !== null && entityQueryBrand in value;
+}
+function isPlainSelect(select) {
+	return typeof select === "object" && select !== null && !isExpr(select) && !isSubqueryValue(select) && !isEntityQueryValue(select) && (Object.getPrototypeOf(select) === Object.prototype || Object.getPrototypeOf(select) === null);
+}
+/** Returns the runtime identity of a source: a table's `TableMgmt` or a subquery's handle. */
+function handleOf(source) {
+	if (isTable(source)) return getTableMgmt(source);
+	if (isSubqueryValue(source)) return readValueHandle(source);
+	return fail(`Expected a table or a query(...) value, got ${source}`);
+}
+function toQuery(arg) {
+	if (isReadQueryValue(arg)) return toQuery(readValueHandle(arg).q);
+	if (arg instanceof SubqueryExpr) return toQuery(arg.handle.q);
+	validateReadQuery(arg);
+	return arg;
+}
+/** Virtual subquery columns are not own clauses; attached properties on the value are always rejected. */
+function readValueHandle(arg) {
+	if (!isSubqueryValue(arg) && !isEntityQueryValue(arg)) return fail("Expected a branded read query value");
+	validateQueryKeys(arg, [isSubqueryValue(arg) ? subqueryBrand : entityQueryBrand], "Read query values");
+	const handle = isSubqueryValue(arg) ? arg[subqueryBrand] : arg[entityQueryBrand];
+	return handle instanceof SubqueryHandle ? handle : fail("Invalid read query value handle");
+}
+const SET_OPERATIONS = {
+	union: "UNION",
+	unionAll: "UNION ALL",
+	intersect: "INTERSECT",
+	intersectAll: "INTERSECT ALL",
+	except: "EXCEPT",
+	exceptAll: "EXCEPT ALL"
+};
+const MUTATION_KEYS = [
+	"insert",
+	"update",
+	"delete",
+	"values",
+	"set",
+	"returning",
+	"allowAll"
+];
+const READ_KEYS = [
+	"with",
+	"from",
+	"join",
+	"where",
+	"groupBy",
+	"having",
+	"select",
+	"orderBy",
+	"limit",
+	"offset",
+	"distinct",
+	"pruneJoins",
+	"softDeletes",
+	"as"
+];
+/**
+* Checks every ordinary or compound root before exposing output metadata or compiling SQL.
+* Validate options before applying defaults so wrong-type values, including null, cannot disappear.
+*/
+function validateReadQuery(arg) {
+	if (typeof arg !== "object" || arg === null || Array.isArray(arg)) fail("em.query expects a { from, select, ... } object or a query(...) value");
+	if (isSetQuery(arg)) setOperands(arg);
+	else {
+		validateQueryKeys(arg, READ_KEYS, "Read queries");
+		if (!("from" in arg && "select" in arg)) fail("em.query expects a { from, select, ... } object or a query(...) value");
+	}
+	const options = arg;
+	for (const key of ["limit", "offset"]) {
+		const value = options[key];
+		if (value !== void 0 && (typeof value !== "number" || !Number.isInteger(value) || value < 0)) fail(`Read query ${key} must be a nonnegative finite integer`);
+	}
+	if (options.softDeletes !== void 0 && options.softDeletes !== "include" && options.softDeletes !== "exclude") fail("Read query softDeletes must be 'include' or 'exclude'");
+	for (const key of ["distinct", "pruneJoins"]) if (options[key] !== void 0 && typeof options[key] !== "boolean") fail(`Read query ${key} must be a boolean`);
+	if (options.as !== void 0 && typeof options.as !== "string") fail("Read query as must be a string");
+}
+/** Includes undefined, symbol, non-enumerable, and inherited clauses rather than silently ignoring them. */
+function validateQueryKeys(arg, allowed, description) {
+	for (let object = arg; object && object !== Object.prototype; object = Object.getPrototypeOf(object)) for (const key of Reflect.ownKeys(object)) {
+		if (allowed.includes(key)) continue;
+		if (MUTATION_KEYS.includes(key)) fail(`Read queries do not support mutation clause '${String(key)}'; use em.execute`);
+		fail(`${description} do not support clause '${String(key)}'`);
+	}
+}
+/** Detect operation keys even when their values are invalid, so mixed roots cannot fall through to SELECT. */
+function isSetQuery(value) {
+	return typeof value === "object" && value !== null && Object.keys(SET_OPERATIONS).some((key) => key in value);
+}
+/** Validate each root independently; no operand, including the left side of EXCEPT, can be pruned. */
+function setOperands(q) {
+	const keys = Object.keys(SET_OPERATIONS).filter((key) => key in q);
+	if (keys.length !== 1) fail("A set query requires exactly one operation key");
+	validateQueryKeys(q, [
+		keys[0],
+		"with",
+		"orderBy",
+		"limit",
+		"offset",
+		"as"
+	], "Set queries");
+	const operands = q[keys[0]];
+	if (!Array.isArray(operands) || operands.length < 2) fail("Set operations require at least two operands");
+	return [keys[0], operands];
+}
+/**
+* Resolve ordered output columns without rendering SQL. Set compatibility is deliberately conservative:
+* every column needs the same known SQL representation, logical domain, and precise ID target.
+*
+* I.e. Author.id and Book.author share the Author key codec, but Book.id must never decode as Author.id.
+* The first branch supplies names and conversions only after every branch passes these checks.
+* UNION admits NULL from any branch; EXCEPT/INTERSECT retain the left branch's nullable facts.
+* Unknown nullability stays unknown unless another UNION branch is known nullable.
+*/
+function queryOutput(q) {
+	validateReadQuery(q);
+	if (isSetQuery(q)) {
+		const [operation, operands] = setOperands(q);
+		const first = queryOutput(toQuery(operands[0]));
+		const columns = [...first.columns];
+		for (const operand of operands) {
+			const output = operand === operands[0] ? first : queryOutput(toQuery(operand));
+			if (output.kind !== "pojo") fail(output.kind === "entity" ? "Set operations do not support entity-mode operands" : "Set operations require POJO operands; wrap scalar expressions in a named select projection");
+			if (output.columns.length !== first.columns.length) fail("Set operands must have the same POJO keys");
+			for (let i = 0; i < columns.length; i++) {
+				const [key, expr] = columns[i];
+				const other = output.columns.find(([name]) => name === key)?.[1];
+				if (!other) fail(`Set operands must have the same POJO keys; missing '${key}'`);
+				const left = expr.outputType;
+				const right = other.outputType;
+				if (!left || !right) fail(`Set column '${key}' has an unknown or unsupported output codec; sql<R> does not declare a SQL type or codec`);
+				if (left.dbType !== right.dbType || left.domain !== right.domain || left.idMeta !== right.idMeta) fail(`Set column '${key}' has incompatible output codecs (${left.dbType} and ${right.dbType}); use matching SQL representations and logical domains`);
+				if (operation === "union" || operation === "unionAll") {
+					const nullable = expr.sqlNullable === true || other.sqlNullable === true ? true : expr.sqlNullable === void 0 || other.sqlNullable === void 0 ? void 0 : false;
+					if (nullable !== expr.sqlNullable) columns[i] = [key, new OutputExpr(expr, nullable)];
+				}
+			}
+		}
+		setOrderBys(q, first);
+		return {
+			kind: first.kind,
+			columns
+		};
+	}
+	q = normalizeQueryJoins(q);
+	const { select } = q;
+	if (isTable(select)) return {
+		kind: "entity",
+		columns: []
+	};
+	if (isSubqueryValue(select)) return readValueHandle(select).output();
+	return joinedOutput(projectionOutput(select), q.join);
+}
+/** Validates the projection before compiling SQL or exposing reusable query columns. */
+function projectionOutput(select) {
+	if (isExpr(select)) return {
+		kind: "scalar",
+		columns: [["value", asExpr(select, "select")]]
+	};
+	if (Array.isArray(select)) {
+		if (select.length === 0) fail("A column array projection must not be empty");
+		const columns = select.map((value, index) => {
+			const expr = asExpr(value, `select[${index}]`);
+			const key = expr[selectKeyBrand];
+			if (typeof key !== "string") fail(`select[${index}] must be a physical or subquery column`);
+			return [key, expr];
+		});
+		if (new Set(columns.map(([key]) => key)).size !== columns.length) fail("A column array projection must not contain duplicate field names");
+		return {
+			kind: "pojo",
+			columns
+		};
+	}
+	if (isPlainSelect(select)) {
+		const columns = [];
+		for (const key of Reflect.ownKeys(select)) {
+			if (typeof key !== "string") fail("Projection keys must be strings");
+			if (Object.prototype.propertyIsEnumerable.call(select, key)) columns.push([key, asSelectExpr(select[key], `select.${key}`)]);
+		}
+		if (columns.length === 0) fail("A named expression projection must not be empty");
+		return {
+			kind: "pojo",
+			columns
+		};
+	}
+	return fail("Expected a scalar expression or a nonempty named expression projection");
+}
+/**
+* Adds SQL nullability from unmatched LEFT joins without mutating shared expressions or their codecs.
+* Only direct columns carry sqlSource; COUNT and COALESCE retain their own SQL nullability.
+* I.e. selecting Book.title from a LEFT-joined Book makes its output nullable, but COUNT(Book.id) stays NOT NULL.
+*/
+function joinedOutput(output, joins) {
+	if (!joins?.some((join) => join?.left)) return output;
+	const left = /* @__PURE__ */ new Set();
+	for (const join of resolveReferenceJoins(joins)) if (join.left) left.add(handleOf(join.left));
+	return {
+		kind: output.kind,
+		columns: output.columns.map((column) => {
+			const [key, expr] = column;
+			return expr.sqlSource && left.has(expr.sqlSource) && expr.sqlNullable !== true ? [key, new OutputExpr(expr, true)] : column;
+		})
+	};
+}
+/**
+* Resolves reference joins in declaration order without changing reusable join entries.
+* Only .as() carries a source handle; explicit INNER joins retain their filtering semantics.
+* I.e. LEFT Book followed by Book.author.as(a) adds Author to the set of nullable handles.
+*/
+function resolveReferenceJoins(joins) {
+	const left = /* @__PURE__ */ new Set();
+	return (joins ?? []).filter(isDefined).map((join) => {
+		const source = join[referenceJoinSource];
+		if (join.inner && source && left.has(source)) {
+			const { inner, ...rest } = join;
+			const resolved = {
+				...rest,
+				left: inner
+			};
+			left.add(handleOf(inner));
+			return resolved;
+		}
+		if (join.left) left.add(handleOf(join.left));
+		return join;
+	});
+}
+/** An output-only nullability adjustment that preserves the selected expression's SQL and conversions. */
+var OutputExpr = class extends BaseExpr {
+	inner;
+	nullable;
+	constructor(inner, nullable) {
+		super();
+		this.inner = inner;
+		this.nullable = nullable;
+	}
+	get outputType() {
+		return this.inner.outputType;
+	}
+	get sqlNullable() {
+		return this.nullable;
+	}
+	toSql(ctx) {
+		return this.inner.toSql(ctx);
+	}
+	decode(value) {
+		return this.inner.decode(value);
+	}
+	encode(value) {
+		return this.inner.encode(value);
+	}
+};
+/**
+* Compile siblings in separate local scopes with the same enclosing context. Projection wrappers align
+* output positions without moving DISTINCT/order/pagination or repeating volatile selected expressions.
+* Parenthesizing each accumulated left side preserves array association and explicit nested grouping.
+*/
+function parseSetQuery(q, parent, assigner, recursiveSelf) {
+	const [operation, operands] = setOperands(q);
+	const output = queryOutput(q);
+	const ctx = new Ctx(assigner, parent);
+	if (recursiveSelf) ctx.setRecursiveSelf(recursiveSelf);
+	const ctes = registerCtes(q, ctx, assigner);
+	const plans = operands.map((operand) => parseQuery(toQuery(operand), ctx, assigner));
+	let sql = "";
+	for (const plan of plans) {
+		let branch = plan.sql;
+		if (output.columns.some(([key], i) => plan.output.columns[i][0] !== key)) {
+			const alias = safeKq(assigner.getLiteralAlias("sq"));
+			branch = `SELECT ${output.columns.map(([key]) => `${alias}.${safeKq(key)} AS ${safeKq(key)}`).join(", ")} FROM (${branch}) AS ${alias}`;
+		}
+		sql = sql ? `(${sql}) ${SET_OPERATIONS[operation]} (${branch})` : branch;
+	}
+	const orderBys = setOrderBys(q, output);
+	if (orderBys.length > 0) sql += ` ORDER BY ${orderBys.join(", ")}`;
+	const bindings = plans.flatMap((plan) => plan.bindings);
+	if (q.limit !== void 0) {
+		sql += " LIMIT ?";
+		bindings.push(q.limit);
+	}
+	if (q.offset !== void 0) {
+		sql += " OFFSET ?";
+		bindings.push(q.offset);
+	}
+	const keptCtes = pruneCtes(ctes, new Set(plans.flatMap((plan) => plan.outerRefs)));
+	if (keptCtes.length > 0) {
+		const clause = withFragment(keptCtes);
+		sql = clause.sql + sql;
+		bindings.unshift(...clause.bindings);
+	}
+	const cteAliases = new Set(ctes.map((cte) => cte.alias));
+	const outerRefs = [...ctx.outerRefs, ...plans.flatMap((plan) => plan.outerRefs)];
+	return {
+		sql,
+		bindings,
+		outerRefs: [...new Set(outerRefs.filter((ref) => !cteAliases.has(ref)))],
+		output,
+		decodeRows: (_, rows) => rows.map((row) => decodeRow(row, output.columns))
+	};
+}
+/** Validate and quote only named set output sorts, including before a reusable value is parsed. */
+function setOrderBys(q, output) {
+	const orderBys = [];
+	for (const entry of Array.isArray(q.orderBy) ? q.orderBy : q.orderBy ? [q.orderBy] : []) {
+		if (entry === void 0) continue;
+		if (!entry || typeof entry !== "object" || isExpr(entry)) fail("Set orderBy requires output-key hashes; use an outer query for expressions");
+		for (const [key, direction] of Object.entries(entry)) {
+			if (direction === void 0) continue;
+			if (!output.columns.some(([name]) => name === key)) fail(`Set orderBy key '${key}' is not a named output column`);
+			if (!ORDER_BY_DIRECTIONS.includes(direction)) fail("Set orderBy requires output-key directions; use an outer query for expressions");
+			orderBys.push(`${safeKq(key)} ${direction}`);
+		}
+	}
+	return orderBys;
+}
+/**
+* What an expression needs from the query it is generating SQL for.
+*
+* Each (sub)query gets its own `Ctx`; a lookup that misses locally walks up to the enclosing query and
+* records the hit in `outerRefs`, which is how a correlated subquery reports the outer aliases it
+* depends on (the way `ExistsCondition.outerAliases` does), so join pruning keeps them.
+*/
+var Ctx = class {
+	assigner;
+	parent;
+	aliases = /* @__PURE__ */ new Map();
+	/**
+	* The subset of `aliases` that are CTE names. A `from`/`join` on one of these emits just the name,
+	* i.e. `FROM book_stats`, where an ordinary `query(...)` value emits its whole body inline, i.e.
+	* `FROM (SELECT ...) AS sq`.
+	*/
+	ctes = /* @__PURE__ */ new Map();
+	/**
+	* `with` entries named but not yet turned into SQL. `registerCtes` names every entry first, then
+	* generates the bodies one at a time, so while one body is being generated the entries after it sit
+	* here. Reading one of those is a forward reference.
+	*/
+	pendingCtes = /* @__PURE__ */ new Map();
+	/** CTEs already read by this query's `from`/`join`, so a second read fails instead of colliding. */
+	usedCtes = /* @__PURE__ */ new Set();
+	/** The recursive CTE whose body this query is part of, if any; see `recursiveSelf`. */
+	ownRecursiveSelf;
+	outerRefs = /* @__PURE__ */ new Set();
+	constructor(assigner, parent) {
+		this.assigner = assigner;
+		this.parent = parent;
+	}
+	/**
+	* One handle can hold only one alias per query, so a value used twice must be told apart, not
+	* silently collapsed into the second registration's alias.
+	*/
+	register(handle, alias) {
+		if (this.aliases.has(handle)) fail(`${describeHandle(handle)} is already in this query's \`with\`/\`from\`/\`join\`; use a separate table(...)/query(...) value for each use`);
+		this.aliases.set(handle, alias);
+	}
+	/** Names every `with` entry up front, so a CTE reading a later sibling is reported, not inlined. */
+	declareCte(handle, alias) {
+		this.pendingCtes.set(handle, alias);
+	}
+	/** Brings a pending CTE into scope, for the sources and columns that may now read it. */
+	promoteCte(handle) {
+		const alias = this.pendingCtes.get(handle) ?? fail("CTE was not declared");
+		this.pendingCtes.delete(handle);
+		this.ctes.set(handle, alias);
+		this.register(handle, alias);
+	}
+	/**
+	* The CTE name for `handle`, looking in the enclosing queries too, because a CTE is in scope for the
+	* whole statement.
+	*
+	* Unlike `aliasFor`, a hit in an enclosing query is not added to `outerRefs`: reading a CTE by name
+	* is not a correlated reference, so it must not keep an enclosing join alive.
+	*/
+	cteAliasFor(handle) {
+		return this.ctes.get(handle) ?? this.parent?.cteAliasFor(handle);
+	}
+	/**
+	* The recursive CTE this query's terms belong to, inherited from the enclosing query.
+	*
+	* PostgreSQL requires a recursive term to reference its own CTE, so that reference is not optional
+	* and must survive pruning, unlike an ordinary explicit join that nothing else reads.
+	*/
+	get recursiveSelf() {
+		return this.ownRecursiveSelf ?? this.parent?.recursiveSelf;
+	}
+	setRecursiveSelf(handle) {
+		this.ownRecursiveSelf = handle;
+	}
+	/** Whether `handle` is a CTE with no SQL yet, i.e. itself or a later `with` entry. */
+	isPendingCte(handle) {
+		return this.pendingCtes.has(handle) || (this.parent?.isPendingCte(handle) ?? false);
+	}
+	/**
+	* Fails if this query already reads `handle`. A `Ctx` maps each handle to a single alias, so two
+	* reads of one CTE value would render as the same name, i.e. `FROM tree JOIN tree`, and neither the
+	* SQL nor a column expression could say which one it meant. Each read needs its own `query(...)`.
+	*
+	* Only this query is checked, not the enclosing ones: a nested subquery has its own FROM, so reading
+	* the same CTE in there is fine.
+	*/
+	useCte(handle) {
+		if (this.usedCtes.has(handle)) fail(`${describeHandle(handle)} is already in this query's \`from\`/\`join\`; use a separate query(...) value for each use`);
+		this.usedCtes.add(handle);
+	}
+	aliasFor(handle) {
+		const local = this.aliases.get(handle);
+		if (local) return local;
+		if (this.parent) {
+			const outer = this.parent.aliasFor(handle);
+			this.outerRefs.add(outer);
+			return outer;
+		}
+		return fail(`${describeHandle(handle)} is not in this query's from/join`);
+	}
+	conditionToSql(cond) {
+		return conditionToSql(cond, this, false);
+	}
+};
+function describeHandle(handle) {
+	if (handle instanceof SubqueryHandle) return `Subquery ${handle.describe()}`;
+	if (handle instanceof JoinTableHandle) return `Join table ${handle.joinTableName}`;
+	if ("tableName" in handle) return `Table for ${handle.tableName}`;
+	return "Table";
+}
+/**
+* Parses one `Query` POJO into SQL, recursively for subqueries.
+*
+* 1. Register every source's runtime identity with its SQL alias in this parse's context.
+* 2. Generate SQL for sources, selects, conditions, group-bys, and order-bys against the context; every fragment
+*    reports the aliases it references.
+* 3. Prune: drop joins nothing references (see below), then reject a kept join whose ON collapsed.
+* 4. Assemble the SQL from the kept fragments, so pruned bindings disappear with their SQL.
+*/
+function parseQuery(q, parent, assigner, recursiveSelf) {
+	validateReadQuery(q);
+	if (isSetQuery(q)) return parseSetQuery(q, parent, assigner, recursiveSelf);
+	q = normalizeQueryJoins(q);
+	const ctx = new Ctx(assigner, parent);
+	if (recursiveSelf) ctx.setRecursiveSelf(recursiveSelf);
+	const joinEntries = resolveReferenceJoins(q.join);
+	const ctes = registerCtes(q, ctx, assigner);
+	const parseFrom = registerSource(q.from, ctx, assigner);
+	const pendingJoins = joinEntries.flatMap((j) => {
+		const kind = "inner" in j && j.inner ? "inner" : "left";
+		const alias = kind === "inner" ? j.inner : j.left;
+		const keep = j.keep ?? false;
+		const softDeletes = j[collectionJoin] === true;
+		const target = {
+			kind,
+			keep,
+			on: j.on,
+			softDeletes,
+			parseSource: registerSource(alias, ctx, assigner)
+		};
+		const m2m = j[m2mJoinTable];
+		if (!m2m) return [target];
+		return [{
+			kind,
+			keep,
+			on: m2m.on,
+			softDeletes: false,
+			parseSource: registerJoinTable(m2m.handle, ctx, assigner)
+		}, target];
+	});
+	const softDeletes = q.softDeletes ?? "exclude";
+	const from = parseFrom();
+	const userJoins = pendingJoins.map((j) => {
+		const source = j.parseSource();
+		const userOn = conditionToSql(j.on, ctx, true);
+		const injected = injectedConditions(source, j.softDeletes ? softDeletes : "include");
+		const fullOn = userOn && injected.length > 0 ? conditionToSql({ and: [j.on, ...injected] }, ctx, true) : userOn;
+		return {
+			kind: j.kind,
+			keep: j.keep,
+			source,
+			userOn,
+			fullOn
+		};
+	});
+	const cti = ctiEntityPlan(q, from, assigner);
+	const joins = [...cti.joins, ...userJoins];
+	const sti = stiEntityPlan(q, from);
+	const { selects, decodeRows, output } = selectsToSql(q, ctx, from, cti.selects ?? sti.selects);
+	const fromInjected = [...injectedConditions(from, softDeletes), ...sti.conditions];
+	const predicate = normalizeWhere(q.where);
+	const where = conditionToSql(fromInjected.length > 0 ? { and: [predicate, ...fromInjected] } : predicate, ctx, true);
+	const having = conditionToSql(q.having, ctx, true);
+	const groupBys = (q.groupBy ?? []).map((g) => asExpr(g, "groupBy").toSql(ctx));
+	const orderBys = orderBysToSql(q, ctx);
+	const { joins: kept, ctes: keptCtes } = pruneJoins(q, ctx, from, joins, ctes, [
+		...selects,
+		...groupBys,
+		...orderBys,
+		where,
+		having
+	].filter(isDefined));
+	const laterAliases = new Set(kept.map((j) => j.source.alias));
+	for (const j of kept) {
+		if (!j.userOn) fail(`Join ${describeHandle(j.source.handle)} has no ON condition left (they all pruned), but the query still references it`);
+		laterAliases.delete(j.source.alias);
+		const forward = j.fullOn.refs.find((r) => laterAliases.has(r));
+		if (forward) fail(`Join ${describeHandle(j.source.handle)} references '${forward}', which is joined later; move that join earlier in the join array`);
+	}
+	const out = [];
+	if (keptCtes.length > 0) out.push(withFragment(keptCtes));
+	out.push({
+		sql: `SELECT ${q.distinct ? "DISTINCT " : ""}`,
+		bindings: [],
+		refs: []
+	});
+	out.push(joinFragmentParts(selects, ", "));
+	out.push({
+		sql: ` FROM ${from.sql}`,
+		bindings: from.bindings,
+		refs: []
+	});
+	for (const j of kept) {
+		const keyword = j.kind === "inner" ? "JOIN" : "LEFT OUTER JOIN";
+		out.push({
+			sql: ` ${keyword} ${j.source.sql} ON ${j.fullOn.sql}`,
+			bindings: [...j.source.bindings, ...j.fullOn.bindings],
+			refs: []
+		});
+	}
+	if (where) out.push({
+		sql: ` WHERE ${where.sql}`,
+		bindings: where.bindings,
+		refs: []
+	});
+	if (groupBys.length > 0) out.push({
+		...joinFragmentParts(groupBys, ", "),
+		sql: ` GROUP BY ${groupBys.map((g) => g.sql).join(", ")}`
+	});
+	if (having) out.push({
+		sql: ` HAVING ${having.sql}`,
+		bindings: having.bindings,
+		refs: []
+	});
+	if (orderBys.length > 0) out.push({
+		...joinFragmentParts(orderBys, ", "),
+		sql: ` ORDER BY ${orderBys.map((o) => o.sql).join(", ")}`
+	});
+	if (q.limit !== void 0) out.push({
+		sql: ` LIMIT ?`,
+		bindings: [q.limit],
+		refs: []
+	});
+	if (q.offset !== void 0) out.push({
+		sql: ` OFFSET ?`,
+		bindings: [q.offset],
+		refs: []
+	});
+	return {
+		sql: out.map((o) => o.sql).join(""),
+		bindings: out.flatMap((o) => o.bindings),
+		outerRefs: [...ctx.outerRefs],
+		output,
+		decodeRows
+	};
+}
+/**
+* Assigns a SQL alias to a source and returns a function that parses it after all sources are registered.
+*
+* Conditions resolve source identities through the context when their SQL is generated.
+* Each entity source reads only its physical table, without inheritance joins or class tags.
+*/
+function registerSource(source, ctx, assigner) {
+	const handle = handleOf(source);
+	const cteAlias = ctx.cteAliasFor(handle);
+	if (cteAlias) {
+		ctx.useCte(handle);
+		return () => ({
+			handle,
+			alias: cteAlias,
+			sql: safeKq(cteAlias),
+			bindings: [],
+			refs: [],
+			entitySelects: [],
+			meta: void 0
+		});
+	}
+	if (ctx.isPendingCte(handle)) fail(`${describeHandle(handle)} is declared later in this query's \`with\`; a CTE can only read earlier ones, and cannot read itself`);
+	if (handle instanceof SubqueryHandle) {
+		const alias = handle.name ? assigner.getLiteralAlias(handle.name) : assigner.getLiteralAlias("sq");
+		ctx.register(handle, alias);
+		return () => {
+			const inner = parseQuery(handle.q, ctx, assigner);
+			return {
+				handle,
+				alias,
+				sql: `(${inner.sql}) AS ${safeKq(alias)}`,
+				bindings: inner.bindings,
+				refs: inner.outerRefs,
+				entitySelects: [],
+				meta: void 0
+			};
+		};
+	} else {
+		const mgmt = getTableMgmt(source);
+		const { tableName } = mgmt;
+		const meta = "meta" in mgmt ? mgmt.meta : void 0;
+		const alias = assigner.getAlias(tableName);
+		ctx.register(handle, alias);
+		return () => {
+			const entitySelects = !meta ? [] : meta.hasLazyColumns ? lazyExcludedSelects(meta, alias) : [kqStar(alias)];
+			return {
+				handle,
+				alias,
+				sql: `${tableSqlName(mgmt)} AS ${kq(alias)}`,
+				bindings: [],
+				refs: [],
+				entitySelects,
+				meta
+			};
+		};
+	}
+}
+/**
+* Per-source soft-delete injections: `alias.deleted_at IS NULL` for a soft-deletable entity.
+* CTI subtypes are skipped because their deleted-at column belongs to the base table (see
+* `filterSoftDeletes`). STI sources read all physical rows without discriminator predicates.
+*
+* The conditions go into the from's WHERE or the join's ON, and never keep an otherwise unreferenced
+* join alive, which is what `pruneable: true` means on em.find's side.
+*/
+function injectedConditions(source, softDeletes) {
+	const { meta } = source;
+	if (!meta) return [];
+	const conditions = [];
+	if (filterSoftDeletes(meta, softDeletes)) {
+		const field = meta.allFields[getBaseMeta(meta).timestampFields.deletedAt];
+		const column = field.serde.columns[0];
+		conditions.push({
+			kind: "column",
+			alias: `${source.alias}${field.aliasSuffix}`,
+			column: column.columnName,
+			dbType: column.dbType,
+			cond: { kind: "is-null" },
+			pruneable: true
+		});
+	}
+	return conditions;
+}
+/** Registers a sugar m2m join table, i.e. `authors_to_tags`: a raw table with no entity metadata. */
+function registerJoinTable(handle, ctx, assigner) {
+	const alias = assigner.getAlias(handle.joinTableName);
+	ctx.register(handle, alias);
+	return () => ({
+		handle,
+		alias,
+		sql: `${kq(handle.joinTableName)} AS ${kq(alias)}`,
+		bindings: [],
+		refs: [],
+		entitySelects: [],
+		meta: void 0
+	});
+}
+/** Generates the `select` clause SQL and returns how to decode the resulting rows. */
+function selectsToSql(q, ctx, from, entitySelects) {
+	const { select } = q;
+	if (isTable(select) && !isEntityTable(select)) fail("A custom table cannot be selected as an entity; select its columns individually");
+	if (isEntityTable(select)) {
+		if (from.handle !== getTableMgmt(select)) fail("Selecting a joined table is not supported yet; select the from table, or select its columns individually");
+		const alias = ctx.aliasFor(getTableMgmt(select));
+		const meta = getTableMetadata(select);
+		return {
+			selects: entitySelects ?? from.entitySelects.map((s) => ({
+				sql: s,
+				bindings: [],
+				refs: [alias]
+			})),
+			decodeRows: (em, rows) => em.hydrate(meta.cstr, rows),
+			output: {
+				kind: "entity",
+				columns: []
+			}
+		};
+	} else if (isSubqueryValue(select)) {
+		const handle = readValueHandle(select);
+		if (from.handle !== handle) fail("Selecting a joined subquery is not supported; select the from subquery, or select its columns individually");
+		const alias = ctx.aliasFor(handle);
+		const output = handle.output();
+		return {
+			selects: output.columns.map(([k]) => ({
+				sql: `${safeKq(alias)}.${safeKq(k)} AS ${safeKq(k)}`,
+				bindings: [],
+				refs: [alias]
+			})),
+			decodeRows: (_, rows) => rows.map((row) => decodeRow(row, output.columns)),
+			output
+		};
+	}
+	return projectionToSql(select, ctx, q.join);
+}
+/**
+* Builds the mandatory CTI joins and flat row projection needed by entity hydration.
+*
+* The joins use the same ParsedJoin path as user joins, but `keep: true` makes them survive pruning.
+* They are generated only for an entity selection of the from source; POJO and scalar reads keep their
+* physical-table behavior. User source aliases have already been allocated, so the preferred `_bN` and
+* `_sN` aliases can be made unique before their projection fragments are built.
+*/
+function ctiEntityPlan(q, from, assigner) {
+	if (!isEntityTable(q.select) || from.handle !== getTableMgmt(q.select)) return {
+		joins: [],
+		selects: void 0
+	};
+	const meta = getTableMetadata(q.select);
+	if (meta.inheritanceType !== "cti") return {
+		joins: [],
+		selects: void 0
+	};
+	const joins = [];
+	const selects = from.entitySelects.map((sql) => ({
+		sql,
+		bindings: [],
+		refs: [from.alias]
+	}));
+	for (const [i, baseMeta] of meta.baseTypes.entries()) {
+		const alias = assigner.getLiteralAlias(`${from.alias}_b${i}`);
+		joins.push(ctiJoin(from, baseMeta, alias));
+		selects.push(...entitySelectFragments(baseMeta, alias));
+	}
+	const subtypeColumns = /* @__PURE__ */ new Map();
+	for (const [i, subtypeMeta] of meta.subTypes.entries()) {
+		const alias = assigner.getLiteralAlias(`${from.alias}_s${i}`);
+		joins.push(ctiJoin(from, subtypeMeta, alias));
+		selects.push(...entitySelectFragments(subtypeMeta, alias));
+		for (const field of Object.values(subtypeMeta.fields)) {
+			if (field.fieldName === "id" || !field.serde || field.kind === "primitive" && field.lazy) continue;
+			for (const column of field.serde.columns) {
+				const aliases = subtypeColumns.get(column.columnName);
+				if (aliases) aliases.push(alias);
+				else subtypeColumns.set(column.columnName, [alias]);
+			}
+		}
+	}
+	selects.push({
+		sql: `${safeKq(from.alias)}.${kq("id")} AS ${kq("id")}`,
+		bindings: [],
+		refs: [from.alias]
+	});
+	for (const [column, aliases] of subtypeColumns) {
+		if (aliases.length < 2) continue;
+		selects.push({
+			sql: `COALESCE(${aliases.map((alias) => `${safeKq(alias)}.${kq(column)}`).join(", ")}) AS ${kq(column)}`,
+			bindings: [],
+			refs: aliases
+		});
+	}
+	if (meta.subTypes.length > 0) {
+		const subtypeAliases = joins.slice(meta.baseTypes.length).map((join) => join.source.alias);
+		selects.push({
+			sql: `CASE ${subtypeAliases.map((alias) => `WHEN ${safeKq(alias)}.${kq("id")} IS NOT NULL THEN ?`).join(" ")} ELSE '_' END AS ${kq("__class")}`,
+			bindings: meta.subTypes.map((subtype) => subtype.type),
+			refs: subtypeAliases
+		});
+	}
+	return {
+		joins,
+		selects
+	};
+}
+/** Adds the discriminator projection and subtype filter required by STI entity hydration. */
+function stiEntityPlan(q, from) {
+	if (!isEntityTable(q.select) || from.handle !== getTableMgmt(q.select)) return {
+		selects: void 0,
+		conditions: []
+	};
+	const meta = getTableMetadata(q.select);
+	if (meta.inheritanceType !== "sti") return {
+		selects: void 0,
+		conditions: []
+	};
+	const selects = from.entitySelects.map((sql) => ({
+		sql,
+		bindings: [],
+		refs: [from.alias]
+	}));
+	if (!(from.entitySelects.length === 1 && from.entitySelects[0] === kqStar(from.alias))) {
+		const discriminator = getBaseMeta(meta).stiDiscriminatorColumnName;
+		selects.push({
+			sql: `${safeKq(from.alias)}.${kq(discriminator)} AS ${kq(discriminator)}`,
+			bindings: [],
+			refs: [from.alias]
+		});
+	}
+	const condition = stiSubtypeFilter(meta, from.alias);
+	return {
+		selects,
+		conditions: condition ? [condition] : []
+	};
+}
+/** Creates one mandatory CTI join through the selected source's primary key. */
+function ctiJoin(from, meta, alias) {
+	const on = {
+		sql: `${safeKq(from.alias)}.${kq("id")} = ${safeKq(alias)}.${kq("id")}`,
+		bindings: [],
+		refs: [from.alias, alias]
+	};
+	return {
+		kind: "left",
+		source: {
+			handle: {
+				tableName: meta.tableName,
+				meta
+			},
+			alias,
+			sql: `${kq(meta.tableName)} AS ${safeKq(alias)}`,
+			bindings: [],
+			refs: [],
+			entitySelects: [],
+			meta
+		},
+		userOn: on,
+		fullOn: on,
+		keep: true
+	};
+}
+/** Selects one physical CTI table while preserving lazy-field exclusions. */
+function entitySelectFragments(meta, alias) {
+	return (meta.hasLazyColumns ? lazyExcludedSelects(meta, alias) : [kqStar(alias)]).map((sql) => ({
+		sql,
+		bindings: [],
+		refs: [alias]
+	}));
+}
+function decodeRow(row, decoders) {
+	const result = {};
+	for (const [key, expr] of decoders) {
+		const value = row[key];
+		const decoded = decodeValue(expr, value);
+		if (key === "__proto__") Object.defineProperty(result, key, {
+			value: decoded,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+		else result[key] = decoded;
+	}
+	return result;
+}
+/** Decodes a top-level projected SQL NULL using Joist's undefined convention. */
+function decodeValue(expr, value) {
+	return value === null ? void 0 : expr.decode(value);
+}
+const ORDER_BY_DIRECTIONS = [
+	"ASC",
+	"DESC",
+	"ASC NULLS FIRST",
+	"ASC NULLS LAST",
+	"DESC NULLS FIRST",
+	"DESC NULLS LAST"
+];
+/**
+* Generates ORDER BY SQL in entry order for keyed/expression arrays or a single entry.
+*
+* Expression entries retain bindings and alias references for join pruning. Undefined entries and
+* directions are omitted before expression references are collected.
+*/
+function orderBysToSql(q, ctx) {
+	const { orderBy, select } = q;
+	if (!orderBy) return [];
+	const result = [];
+	for (const entry of Array.isArray(orderBy) ? orderBy : [orderBy]) {
+		if (entry === void 0) continue;
+		if (isExpr(entry.sort)) {
+			const fragment = orderByToSql(entry, ctx);
+			if (fragment) result.push(fragment);
+			continue;
+		}
+		for (const [key, dir] of Object.entries(entry)) {
+			if (dir === void 0) continue;
+			if (!ORDER_BY_DIRECTIONS.includes(dir)) return fail(`Invalid orderBy direction '${dir}'`);
+			if (isTable(select)) {
+				const column = select[key];
+				if (!isExpr(column)) return fail(`orderBy key '${key}' is not a sortable column of the table`);
+				const fragment = asNode(column).toSql(ctx);
+				result.push({
+					...fragment,
+					sql: `${fragment.sql} ${dir}`
+				});
+			} else {
+				if (isExpr(select)) return fail(`the keyed orderBy form needs a POJO or entity select`);
+				if (!(isSubqueryValue(select) ? select[subqueryBrand].columnKeys() : projectionOutput(select).columns.map(([key]) => key)).includes(key)) return fail(`orderBy key '${key}' is not a key of select`);
+				result.push({
+					sql: `${safeKq(key)} ${dir}`,
+					bindings: [],
+					refs: []
+				});
+			}
+		}
+	}
+	return result;
+}
+/**
+* Parses a user-facing condition (a single condition or an `{ and }`/`{ or }` filter) with the same
+* `ConditionBuilder` `em.find` uses, so `undefined` members drop out, empty groups drop, and
+* `pruneIfUndefined` applies unchanged. Deferred SQL expression conditions are resolved
+* against the context first.
+*/
+function conditionToSql(cond, ctx, topLevel) {
+	checkCondition(cond);
+	if (cond === void 0) return void 0;
+	const resolved = resolveDeferredConditions(resolveQueryCondition(cond, ctx), ctx);
+	if (resolved === void 0) return void 0;
+	const filter = isFilter(resolved) ? resolved : { and: [resolved] };
+	const cb = new ConditionBuilder();
+	cb.maybeAddExpression(filter);
+	const parsed = cb.toExpressionFilter();
+	if (!parsed) return void 0;
+	const where = buildWhereClause(parsed, topLevel);
+	if (!where) return void 0;
+	return {
+		sql: where[0],
+		bindings: where[1],
+		refs: refsOf(parsed)
+	};
+}
+/**
+* Rejects malformed predicates throughout a condition tree before pruning can discard a restriction.
+* I.e. an invalid Author-name condition stays invalid even inside a group that would otherwise prune,
+* while an explicitly omitted query-valued condition is allowed to prune.
+*/
+function checkCondition(value) {
+	if (isDeferredAliasCondition(value) || value && typeof value === "object" && predicateBrand in value && value[predicateBrand] === "domain") fail("Domain alias conditions are only supported by em.find; use table(...) predicates in SQL queries and mutations.");
+	if (value === void 0 || value === skipCondition) return;
+	if (isInQueryCondition(value)) {
+		checkCondition(normalizeWhere(normalizeQueryJoins(toQuery(value[inQueryCondition].query)).where));
+		return;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value) || isExpr(value)) fail("Query predicate must be a condition or an and/or group");
+	const condition = value;
+	if ("and" in condition || "or" in condition) {
+		if ("and" in condition === "or" in condition) fail("Query conditions require exactly one and/or group");
+		const key = "and" in condition ? "and" : "or";
+		checkConditionKeys(condition, [key, "pruneIfUndefined"], "Query condition group");
+		if (!Array.isArray(condition[key])) fail("Query condition groups require an array");
+		if (condition.pruneIfUndefined !== void 0 && condition.pruneIfUndefined !== "any" && condition.pruneIfUndefined !== "all") fail("Invalid query pruneIfUndefined policy");
+		for (const child of condition[key]) checkCondition(child);
+	} else if ("exists" in condition || "notExists" in condition) {
+		const key = "exists" in condition ? "exists" : "notExists";
+		checkConditionKeys(condition, [key], "Query existence condition");
+		const query = condition[key];
+		if (query === void 0) return;
+		if (!(query instanceof SubqueryExpr) && !isReadQueryValue(query)) fail(`Query ${key} requires a query(...) value`);
+		toQuery(query);
+	} else if (condition.kind === "raw") {
+		checkConditionKeys(condition, [
+			"kind",
+			"aliases",
+			"condition",
+			"bindings",
+			"pruneable",
+			deferredSym,
+			predicateBrand
+		], "Query raw condition");
+		if (typeof condition.condition !== "string" || !Array.isArray(condition.aliases) || !condition.aliases.every((alias) => typeof alias === "string") || !Array.isArray(condition.bindings) || typeof condition.pruneable !== "boolean") fail("Malformed query raw condition");
+	} else if (condition.kind === "column") {
+		checkConditionKeys(condition, [
+			"kind",
+			"alias",
+			"column",
+			"dbType",
+			"cond",
+			"pruneable",
+			predicateBrand
+		], "Query column condition");
+		if (typeof condition.alias !== "string" || typeof condition.column !== "string" || typeof condition.dbType !== "string" || condition.pruneable !== void 0 && typeof condition.pruneable !== "boolean") fail("Malformed query column condition");
+		const filter = condition.cond;
+		if (!filter) fail("Malformed query column filter");
+		checkConditionKeys(filter, ["kind", "value"], "Query column filter");
+		const unary = filter.kind === "is-null" || filter.kind === "not-null";
+		if (!unary && (![
+			"eq",
+			"ne",
+			"in",
+			"nin",
+			"gt",
+			"gte",
+			"lt",
+			"lte",
+			"like",
+			"nlike",
+			"ilike",
+			"nilike",
+			"regex",
+			"nregex",
+			"iregex",
+			"niregex",
+			"contains",
+			"ncontains",
+			"overlaps",
+			"noverlaps",
+			"containedBy",
+			"between",
+			"jsonPathExists",
+			"jsonPathPredicate"
+		].includes(filter.kind) || !("value" in filter))) fail("Malformed query column filter");
+		if (unary && "value" in filter) fail("Unary query filters do not accept values");
+	} else fail("Unknown query condition");
+}
+/** Conditions use own enumerable POJO fields, with predicate-brand and SQL-resolver symbols allowed. */
+function checkConditionKeys(value, allowed, description) {
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) fail(`${description} must be a plain POJO`);
+	for (const key of Reflect.ownKeys(value)) {
+		if (!allowed.includes(key)) fail(`${description} does not support '${String(key)}'`);
+		if (typeof key === "string" && !Object.prototype.propertyIsEnumerable.call(value, key)) fail(`${description} requires enumerable fields`);
+	}
+}
+/**
+* Converts query-valued predicates to SQL conditions for the shared condition builder.
+* Keeps each subquery's projection and reports its outer aliases for join pruning.
+*/
+function resolveQueryCondition(cond, ctx) {
+	if (cond === void 0) return void 0;
+	if (isInQueryCondition(cond)) {
+		const { column, query } = cond[inQueryCondition];
+		const value = createMaybeQueryValue(query);
+		if (value === void 0) return void 0;
+		if (!isExpr(value)) return fail("An in query literal must select one expression");
+		return column.in(value);
+	}
+	if ("and" in cond && cond.and) return {
+		and: cond.and.map((child) => resolveQueryCondition(child, ctx)),
+		pruneIfUndefined: cond.pruneIfUndefined
+	};
+	if ("or" in cond && cond.or) return {
+		or: cond.or.map((child) => resolveQueryCondition(child, ctx)),
+		pruneIfUndefined: cond.pruneIfUndefined
+	};
+	if ("exists" in cond || "notExists" in cond) {
+		const positive = "exists" in cond;
+		const subquery = positive ? cond.exists : cond.notExists;
+		if (subquery === void 0) return void 0;
+		const plan = parseQuery(toQuery(subquery), ctx, ctx.assigner);
+		return {
+			kind: "raw",
+			condition: `${positive ? "EXISTS" : "NOT EXISTS"} (${plan.sql})`,
+			bindings: plan.bindings,
+			aliases: plan.outerRefs,
+			pruneable: false
+		};
+	}
+	return cond;
+}
+function isFilter(cond) {
+	return "and" in cond && cond.and !== void 0 || "or" in cond && cond.or !== void 0;
+}
+/**
+* Checks structural pruning without resolving SQL or correlated aliases.
+*
+* Keeps individual predicates and applies ConditionBuilder's pruning policy (i.e. pruneIfUndefined) to groups.
+* I.e. an Author condition AND an omitted Book condition survives unless the group uses `any`.
+*/
+function isPrunedQueryCondition(cond) {
+	if (cond === void 0 || cond === skipCondition) return true;
+	if (isInQueryCondition(cond)) return isPrunedQueryCondition(normalizeWhere(normalizeQueryJoins(cond[inQueryCondition].query).where));
+	if ("and" in cond || "or" in cond) {
+		const children = (cond.and ?? cond.or ?? []).map(isPrunedQueryCondition);
+		return children.every((pruned) => pruned) || "pruneIfUndefined" in cond && cond.pruneIfUndefined === "any" && children.some((pruned) => pruned);
+	}
+	if ("exists" in cond) return cond.exists === void 0;
+	if ("notExists" in cond) return cond.notExists === void 0;
+	return false;
+}
+/** Recognizes the direct query-literal condition created by EntityColumn.in. */
+function isInQueryCondition(value) {
+	return typeof value === "object" && value !== null && inQueryCondition in value;
+}
+/** The physical source aliases a parsed condition tree references. */
+function refsOf(parsed) {
+	return deepFindConditions(parsed, false).flatMap((c) => c.kind === "column" ? [c.alias] : c.kind === "raw" ? c.aliases : c.outerAliases);
+}
+/**
+* Pruning: em.find's paradigm, on a flat join list.
+*
+* A condition given `undefined` was already dropped by `ConditionBuilder`. Now a join that nothing
+* references anymore drops with it: a join is required if the source, a select, a surviving condition,
+* a group-by, an order-by, or another required join's ON references it, or if it is pinned with
+* `keep: true`. Marking follows ON dependencies transitively, exactly like `pruneUnusedJoins`'s
+* `DependencyTracker`.
+*
+* em.find's joins almost never filter rows by themselves, so pruning them is semantics-preserving. An
+* explicit `{ inner: b, on }` here does filter rows, so pruning it when unreferenced drops that filter;
+* that matches `{ books: { title: undefined } }` in em.find and is deliberate. `keep: true` pins it, and
+* a pure existence filter is better written as `a.id.in(query({ ... }))`, which is never `undefined`.
+*
+* CTEs prune on the same rule and through the same dependency map: a `with` entry nothing reads
+* anymore drops with the join that read it, and a CTE read only by another CTE survives with it.
+* A CTE joined into the query shares its alias with that join, so their dependencies are merged.
+*
+* The one join that never prunes is a recursive term's reference to its own CTE: PostgreSQL requires
+* it, so it is not the caller's optional filter (see `Ctx.recursiveSelf`).
+*/
+function pruneJoins(q, ctx, from, joins, ctes, used) {
+	if (q.pruneJoins === false) return {
+		joins,
+		ctes
+	};
+	const deps = /* @__PURE__ */ new Map();
+	function addDeps(alias, refs) {
+		const own = refs.filter((r) => r !== alias);
+		const existing = deps.get(alias);
+		if (existing) existing.push(...own);
+		else deps.set(alias, own);
+	}
+	for (const j of joins) addDeps(j.source.alias, [...j.userOn?.refs ?? [], ...j.source.refs]);
+	for (const c of ctes) addDeps(c.alias, c.plan.outerRefs);
+	const required = /* @__PURE__ */ new Set();
+	function markRequired(alias) {
+		if (required.has(alias)) return;
+		required.add(alias);
+		for (const dep of deps.get(alias) ?? []) markRequired(dep);
+	}
+	markRequired(from.alias);
+	for (const r of used.flatMap((u) => u.refs)) markRequired(r);
+	for (const j of joins) if (j.keep) markRequired(j.source.alias);
+	for (const j of joins) if (j.source.handle === ctx.recursiveSelf) markRequired(j.source.alias);
+	return {
+		joins: joins.filter((j) => required.has(j.source.alias)),
+		ctes: ctes.filter((c) => required.has(c.alias))
+	};
+}
+/**
+* Names and parses each `with` entry, in declaration order.
+*
+* Each entry is in scope before the next is parsed, so a CTE can read an *earlier* sibling by name,
+* PostgreSQL's rule for a non-recursive WITH. A forward reference, or a CTE reading the query's own
+* `from`, fails as "not in this query's from/join", the same error any out-of-scope source gets.
+*
+* I.e. `with: [totals, ranked]` parses `totals` first, so `ranked` can join it, but not the reverse.
+*/
+function registerCtes(q, ctx, assigner) {
+	const handles = (q.with === void 0 ? [] : Array.isArray(q.with) ? q.with : [q.with]).filter(isDefined).map(withEntryHandle);
+	const aliases = handles.map((handle) => assigner.getLiteralAlias(handle.name ?? "cte"));
+	handles.forEach((handle, i) => ctx.declareCte(handle, aliases[i]));
+	return handles.map((handle, i) => {
+		if (handle.recursive) ctx.promoteCte(handle);
+		const plan = parseQuery(handle.q, ctx, assigner, handle.recursive ? handle : void 0);
+		if (!handle.recursive) ctx.promoteCte(handle);
+		return {
+			alias: aliases[i],
+			plan,
+			recursive: handle.recursive
+		};
+	});
+}
+/** A CTE must be a table shape, so entity-mode and scalar values, which have no columns, are out. */
+function withEntryHandle(entry) {
+	if (!isSubqueryValue(entry)) fail(entry instanceof SubqueryExpr || isEntityQueryValue(entry) ? "A `with` entry needs named columns; entity and scalar query(...) values have none" : "A `with` entry must be a query(...) value");
+	return readValueHandle(entry);
+}
+/**
+* Drops the CTEs that nothing reads, given the aliases the rest of the statement referenced.
+*
+* A CTE can only read earlier siblings, so going last to first means every CTE that could read this one
+* was already visited, and its own reads are already in `referenced`. That makes one pass enough; first
+* to last would have to repeat until the set stopped growing. `unshift` restores WITH order.
+*/
+function pruneCtes(ctes, referenced) {
+	const kept = [];
+	for (let i = ctes.length - 1; i >= 0; i--) {
+		const cte = ctes[i];
+		if (!referenced.has(cte.alias)) continue;
+		for (const ref of cte.plan.outerRefs) referenced.add(ref);
+		kept.unshift(cte);
+	}
+	return kept;
+}
+/**
+* Renders `WITH a AS (...), b AS (...) `, whose bindings lead the statement, as their SQL does.
+*
+* One recursive CTE makes the whole clause `WITH RECURSIVE`, PostgreSQL's rule: the keyword is on the
+* clause, not on the entry that needs it, and it does not force the other entries to be recursive.
+*/
+function withFragment(ctes) {
+	return {
+		sql: `WITH${ctes.some((c) => c.recursive) ? " RECURSIVE" : ""} ${ctes.map((c) => `${safeKq(c.alias)} AS (${c.plan.sql})`).join(", ")} `,
+		bindings: ctes.flatMap((c) => c.plan.bindings),
+		refs: []
+	};
+}
+function asExpr(value, where) {
+	if (value instanceof BaseExpr) return value;
+	return fail(`${where} must be an expression, i.e. a table column, aggregate, sql\`...\`, or scalar query(...)`);
+}
+/** Builds inline select expressions while leaving existing expression instances intact. */
+function asSelectExpr(value, where) {
+	if (value instanceof BaseExpr) return value;
+	if (isPlainSelect(value)) return buildExpr(value);
+	return fail(`${where} must be a column, an expression, or an expression literal`);
+}
+function joinFragmentParts(parts, sep) {
+	return {
+		sql: parts.map((p) => p.sql).join(sep),
+		bindings: parts.flatMap((p) => p.bindings),
+		refs: []
+	};
+}
+function isDefined(value) {
+	return value !== void 0;
+}
+/** Lowers a relationship tree before SQL rendering or output nullability is calculated. */
+function normalizeQueryJoins(q) {
+	if (q.join === void 0 || Array.isArray(q.join)) return q;
+	const tree = compileJoinTree(q.from, q.join);
+	return {
+		...q,
+		join: tree.joins,
+		where: { and: [tree.condition, normalizeWhere(q.where)] }
+	};
+}
+/** Gives WHERE arrays the same pruning and validation as explicit AND groups. */
+function normalizeWhere(where) {
+	return Array.isArray(where) ? { and: where } : where;
+}
+/** Creates the runtime query value after the public signature has checked its input. */
+function createQueryValue(q) {
+	const handle = new SubqueryHandle(toQuery(q));
+	const output = handle.output();
+	if (output.kind === "entity") return { [entityQueryBrand]: handle };
+	else if (output.kind === "scalar") return new SubqueryExpr(handle);
+	else return newSubqueryProxy(handle);
+}
+/** Keeps shorthand declarations callable-only, without recursively copying sql's own shorthand properties. */
+function typedSql(strings, ...values) {
+	return new TemplateExpr(strings, values);
+}
+//#endregion
+export { Ctx, SubqueryHandle, conditionToSql, entityQueryBrand, injectedConditions, isReadQueryValue, parseNestedQuery, parseUserQuery, projectionToSql, pruneCtes, query, queryMaybe, recursiveQuery, registerCtes, scalarQueryBrand, sql, subqueryBrand, withFragment };
+
+//# sourceMappingURL=query.js.map