joist-core 2.3.0-next.76 → 2.3.0-next.78

package/build/query.cjs

@@ -59,6 +59,46 @@ function query(q) {
 	else return newSubqueryProxy(handle);
 }
 /**
+* 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 === "") require_utils.fail("A recursive CTE needs a name");
+	if (opts.union !== void 0 && opts.union !== "all" && opts.union !== "distinct") require_utils.fail("A recursive CTE's union must be 'all' or 'distinct'");
+	const handle = new SubqueryHandle(toQuery(base), true);
+	if (handle.output().kind !== "pojo") require_utils.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`:
@@ -147,9 +187,23 @@ function projectionToSql(select, ctx) {
 }
 /** The runtime identity of a `query(...)` value; `Ctx.aliasFor` keys on it, like a table's `TableMgmt`. */
 var SubqueryHandle = class {
-	q;
-	constructor(q) {
-		this.q = q;
+	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) require_utils.fail("Only a recursive CTE replaces its body");
+		this.#q = q;
 	}
 	get name() {
 		return this.q.as;
@@ -313,6 +367,7 @@ const MUTATION_KEYS = [
 	"allowAll"
 ];
 const READ_KEYS = [
+	"with",
 	"from",
 	"join",
 	"where",
@@ -369,6 +424,7 @@ function setOperands(q) {
 	if (keys.length !== 1) require_utils.fail("A set query requires exactly one operation key");
 	validateQueryKeys(q, [
 		keys[0],
+		"with",
 		"orderBy",
 		"limit",
 		"offset",
@@ -492,10 +548,13 @@ var OutputExpr = class extends require_Expr.BaseExpr {
 * 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) {
+function parseSetQuery(q, parent, assigner, recursiveSelf) {
 	const [operation, operands] = setOperands(q);
 	const output = queryOutput(q);
-	const plans = operands.map((operand) => parseQuery(toQuery(operand), parent, assigner));
+	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;
@@ -516,10 +575,25 @@ function parseSetQuery(q, parent, assigner) {
 		sql += " OFFSET ?";
 		bindings.push(q.offset);
 	}
+	const referenced = new Set(plans.flatMap((plan) => plan.outerRefs));
+	const keptCtes = [];
+	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);
+		keptCtes.unshift(cte);
+	}
+	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(plans.flatMap((plan) => plan.outerRefs))],
+		outerRefs: [...new Set(outerRefs.filter((ref) => !cteAliases.has(ref)))],
 		output,
 		decodeRows: plans[0].decodeRows
 	};
@@ -550,14 +624,84 @@ 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)) require_utils.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) ?? require_utils.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)) require_utils.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;
@@ -587,11 +731,13 @@ function describeHandle(handle) {
 * 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) {
+function parseQuery(q, parent, assigner, recursiveSelf) {
 	validateReadQuery(q);
-	if (isSetQuery(q)) return parseSetQuery(q, parent, assigner);
+	if (isSetQuery(q)) return parseSetQuery(q, parent, assigner, recursiveSelf);
 	const ctx = new Ctx(assigner, parent);
+	if (recursiveSelf) ctx.setRecursiveSelf(recursiveSelf);
 	const joinEntries = [...q.join ?? []].filter(isDefined);
+	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";
@@ -636,7 +782,7 @@ function parseQuery(q, parent, assigner) {
 	const having = conditionToSql(q.having, ctx, true);
 	const groupBys = (q.groupBy ?? []).map((g) => asExpr(g, "groupBy").toSql(ctx));
 	const orderBys = orderBysToSql(q, ctx);
-	const kept = pruneJoins(q, from, joins, [
+	const { joins: kept, ctes: keptCtes } = pruneJoins(q, ctx, from, joins, ctes, [
 		...selects,
 		...groupBys,
 		...orderBys,
@@ -651,6 +797,7 @@ function parseQuery(q, parent, assigner) {
 		if (forward) require_utils.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: [],
@@ -714,6 +861,20 @@ function parseQuery(q, parent, assigner) {
 */
 function registerSource(source, ctx, assigner) {
 	const handle = handleOf(source);
+	const cteAlias = ctx.cteAliasFor(handle);
+	if (cteAlias) {
+		ctx.useCte(handle);
+		return () => ({
+			handle,
+			alias: cteAlias,
+			sql: require_keywords.safeKq(cteAlias),
+			bindings: [],
+			refs: [],
+			entitySelects: [],
+			meta: void 0
+		});
+	}
+	if (ctx.isPendingCte(handle)) require_utils.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);
@@ -1058,14 +1219,28 @@ function refsOf(parsed) {
 * 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, from, joins, used) {
-	if (q.pruneJoins === false) return joins;
+function pruneJoins(q, ctx, from, joins, ctes, used) {
+	if (q.pruneJoins === false) return {
+		joins,
+		ctes
+	};
 	const deps = /* @__PURE__ */ new Map();
-	for (const j of joins) {
-		const refs = [...j.userOn?.refs ?? [], ...j.source.refs].filter((r) => r !== j.source.alias);
-		deps.set(j.source.alias, refs);
+	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;
@@ -1075,7 +1250,53 @@ function pruneJoins(q, from, joins, used) {
 	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);
-	return joins.filter((j) => required.has(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)) require_utils.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);
+}
+/**
+* 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) => `${require_keywords.safeKq(c.alias)} AS (${c.plan.sql})`).join(", ")} `,
+		bindings: ctes.flatMap((c) => c.plan.bindings),
+		refs: []
+	};
 }
 function asExpr(value, where) {
 	if (value instanceof require_Expr.BaseExpr) return value;
@@ -1101,6 +1322,7 @@ exports.isReadQueryValue = isReadQueryValue;
 exports.parseUserQuery = parseUserQuery;
 exports.projectionToSql = projectionToSql;
 exports.query = query;
+exports.recursiveQuery = recursiveQuery;
 exports.scalarQueryBrand = scalarQueryBrand;
 exports.sql = sql;
 exports.subqueryBrand = subqueryBrand;