joist-core 2.3.0-next.99 → 2.4.0

package/build/queries/sql/query.cjs

@@ -13,6 +13,7 @@ const require_queries_renderConditions = require("../renderConditions.cjs");
 const require_queries_sql_AliasAssigner = require("./AliasAssigner.cjs");
 const require_queries_sql_Tables = require("./Tables.cjs");
 const require_queries_sql_expressions_expression = require("./expressions/expression.cjs");
+const require_queries_sql_JoinTree = require("./JoinTree.cjs");
 //#region src/queries/sql/query.ts
 /**
 * `em.query`: SQL-shaped queries as plain object literals.
@@ -28,10 +29,10 @@ const require_queries_sql_expressions_expression = require("./expressions/expres
 *     select: { name: a.first_name, n: bookStats.n },
 *     orderBy: { n: "DESC" },
 *   });
-*   // rows: { name: string; n: number | null }[]   (null because of the LEFT join)
+*   // 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, a
-* `{ key: expr }` object returns typed POJOs, a bare subquery returns that subquery's rows.
+* `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)`:
@@ -51,24 +52,26 @@ const subqueryBrand = Symbol("joist.subquery");
 const entityQueryBrand = Symbol("joist.entityQuery");
 const scalarQueryBrand = Symbol("joist.scalarQuery");
 function query(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);
+	return createQueryValue(q);
 }
 /**
-* Builds a query value only when its user-supplied `where` survives pruning.
+* 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`.
-* Joins, HAVING, and implicit soft-delete/STI conditions do not keep the value alive.
+* 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) {
-	checkCondition(q.where);
-	return isPrunedQueryCondition(q.where) ? void 0 : query(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.
@@ -123,9 +126,9 @@ function recursiveQuery(name, base, step, opts = {}) {
 * // Selecting this expression keeps the join to Book b.
 * sql.number`${b.order} * ${2}`
 *
-* // Reference an unmodeled column; it is untracked at the type level.
-* sql.ref<string>(a, "ts_search")
-* sql.condition`${sql.ref(a, "ts_search")} @@ plainto_tsquery(${term})`
+* // 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) {
@@ -159,10 +162,6 @@ sql.booleanArrayOrNull = typedSql;
 sql.condition = function condition(strings, ...values) {
 	return require_queries_sql_Expr.deferredCondition((ctx) => new require_queries_sql_Expr.TemplateExpr(strings, values).toSql(ctx));
 };
-/** A column Joist does not model, on a source that is in the query. */
-sql.ref = function ref(source, column) {
-	return new require_queries_sql_Expr.RefExpr(handleOf(source), column);
-};
 /**
 * Parses `arg` (a `Query` POJO or `query(...)` value) into a runnable `Plan`.
 *
@@ -189,8 +188,8 @@ function isReadQueryValue(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) {
-	const output = projectionOutput(select);
+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);
@@ -199,7 +198,7 @@ function projectionToSql(select, ctx) {
 				...fragment,
 				sql: `${fragment.sql} AS value`
 			}],
-			decodeRows: (_, rows) => rows.map((row) => expr.decode(row.value)),
+			decodeRows: (_, rows) => rows.map((row) => decodeValue(expr, row.value)),
 			output
 		};
 	}
@@ -272,6 +271,9 @@ var SubqueryColumnExpr = class extends require_queries_sql_Expr.BaseExpr {
 		this.key = key;
 		this.inner = inner;
 	}
+	get [require_queries_sql_Expr.selectKeyBrand]() {
+		return this.key;
+	}
 	toSql(ctx) {
 		const alias = ctx.aliasFor(this.handle);
 		return {
@@ -501,6 +503,7 @@ function queryOutput(q) {
 			columns
 		};
 	}
+	q = normalizeQueryJoins(q);
 	const { select } = q;
 	if (require_queries_sql_Tables.isTable(select)) return {
 		kind: "entity",
@@ -515,6 +518,20 @@ function projectionOutput(select) {
 		kind: "scalar",
 		columns: [["value", asExpr(select, "select")]]
 	};
+	if (Array.isArray(select)) {
+		if (select.length === 0) require_utils.fail("A column array projection must not be empty");
+		const columns = select.map((value, index) => {
+			const expr = asExpr(value, `select[${index}]`);
+			const key = expr[require_queries_sql_Expr.selectKeyBrand];
+			if (typeof key !== "string") require_utils.fail(`select[${index}] must be a physical or subquery column`);
+			return [key, expr];
+		});
+		if (new Set(columns.map(([key]) => key)).size !== columns.length) require_utils.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)) {
@@ -530,7 +547,7 @@ function projectionOutput(select) {
 	return require_utils.fail("Expected a scalar expression or a nonempty named expression projection");
 }
 /**
-* Adds physical NULL from unmatched LEFT joins without mutating shared expressions or their codecs.
+* 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.
 */
@@ -638,7 +655,7 @@ function parseSetQuery(q, parent, assigner, recursiveSelf) {
 		bindings,
 		outerRefs: [...new Set(outerRefs.filter((ref) => !cteAliases.has(ref)))],
 		output,
-		decodeRows: plans[0].decodeRows
+		decodeRows: (_, rows) => rows.map((row) => decodeRow(row, output.columns))
 	};
 }
 /** Validate and quote only named set output sorts, including before a reusable value is parsed. */
@@ -777,6 +794,7 @@ function describeHandle(handle) {
 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);
@@ -824,7 +842,8 @@ function parseQuery(q, parent, assigner, recursiveSelf) {
 	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 where = conditionToSql(fromInjected.length > 0 ? { and: [q.where, ...fromInjected] } : q.where, ctx, true);
+	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);
@@ -937,15 +956,17 @@ function registerSource(source, ctx, assigner) {
 			};
 		};
 	} else {
-		const meta = require_queries_sql_Tables.getTableMetadata(source);
-		const alias = assigner.getAlias(meta.tableName);
+		const mgmt = require_queries_sql_Tables.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.hasLazyColumns ? require_queries_entityQueryUtils.lazyExcludedSelects(meta, alias) : [require_queries_sql_keywords.kqStar(alias)];
+			const entitySelects = !meta ? [] : meta.hasLazyColumns ? require_queries_entityQueryUtils.lazyExcludedSelects(meta, alias) : [require_queries_sql_keywords.kqStar(alias)];
 			return {
 				handle,
 				alias,
-				sql: `${require_queries_sql_keywords.kq(meta.tableName)} AS ${require_queries_sql_keywords.kq(alias)}`,
+				sql: `${require_queries_sql_Tables.tableSqlName(mgmt)} AS ${require_queries_sql_keywords.kq(alias)}`,
 				bindings: [],
 				refs: [],
 				entitySelects,
@@ -997,7 +1018,8 @@ function registerJoinTable(handle, ctx, assigner) {
 /** Generates the `select` clause SQL and returns how to decode the resulting rows. */
 function selectsToSql(q, ctx, from, entitySelects) {
 	const { select } = q;
-	if (require_queries_sql_Tables.isTable(select)) {
+	if (require_queries_sql_Tables.isTable(select) && !require_queries_sql_Tables.isEntityTable(select)) require_utils.fail("A custom table cannot be selected as an entity; select its columns individually");
+	if (require_queries_sql_Tables.isEntityTable(select)) {
 		if (from.handle !== require_queries_sql_Tables.getTableMgmt(select)) require_utils.fail("Selecting a joined table is not supported yet; select the from table, or select its columns individually");
 		const alias = ctx.aliasFor(require_queries_sql_Tables.getTableMgmt(select));
 		const meta = require_queries_sql_Tables.getTableMetadata(select);
@@ -1028,9 +1050,7 @@ function selectsToSql(q, ctx, from, entitySelects) {
 			output
 		};
 	}
-	const projection = projectionToSql(select, ctx);
-	projection.output = joinedOutput(projection.output, q.join);
-	return projection;
+	return projectionToSql(select, ctx, q.join);
 }
 /**
 * Builds the mandatory CTI joins and flat row projection needed by entity hydration.
@@ -1041,7 +1061,7 @@ function selectsToSql(q, ctx, from, entitySelects) {
 * `_sN` aliases can be made unique before their projection fragments are built.
 */
 function ctiEntityPlan(q, from, assigner) {
-	if (!require_queries_sql_Tables.isTable(q.select) || from.handle !== require_queries_sql_Tables.getTableMgmt(q.select)) return {
+	if (!require_queries_sql_Tables.isEntityTable(q.select) || from.handle !== require_queries_sql_Tables.getTableMgmt(q.select)) return {
 		joins: [],
 		selects: void 0
 	};
@@ -1103,7 +1123,7 @@ function ctiEntityPlan(q, from, assigner) {
 }
 /** Adds the discriminator projection and subtype filter required by STI entity hydration. */
 function stiEntityPlan(q, from) {
-	if (!require_queries_sql_Tables.isTable(q.select) || from.handle !== require_queries_sql_Tables.getTableMgmt(q.select)) return {
+	if (!require_queries_sql_Tables.isEntityTable(q.select) || from.handle !== require_queries_sql_Tables.getTableMgmt(q.select)) return {
 		selects: void 0,
 		conditions: []
 	};
@@ -1169,7 +1189,7 @@ function decodeRow(row, decoders) {
 	const result = {};
 	for (const [key, expr] of decoders) {
 		const value = row[key];
-		const decoded = value === null || value === void 0 ? null : expr.decode(value);
+		const decoded = decodeValue(expr, value);
 		if (key === "__proto__") Object.defineProperty(result, key, {
 			value: decoded,
 			enumerable: true,
@@ -1180,6 +1200,10 @@ function decodeRow(row, decoders) {
 	}
 	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",
@@ -1189,7 +1213,7 @@ const ORDER_BY_DIRECTIONS = [
 	"DESC NULLS LAST"
 ];
 /**
-* Generates ORDER BY SQL in entry order for keyed/expression arrays or a single keyed object.
+* 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.
@@ -1218,7 +1242,7 @@ function orderBysToSql(q, ctx) {
 				});
 			} else {
 				if (require_queries_sql_Expr.isExpr(select)) return require_utils.fail(`the keyed orderBy form needs a POJO or entity select`);
-				if (!(isSubqueryValue(select) ? select[subqueryBrand].columnKeys() : Object.keys(select)).includes(key)) return require_utils.fail(`orderBy key '${key}' is not a key of select`);
+				if (!(isSubqueryValue(select) ? select[subqueryBrand].columnKeys() : projectionOutput(select).columns.map(([key]) => key)).includes(key)) return require_utils.fail(`orderBy key '${key}' is not a key of select`);
 				result.push({
 					sql: `${require_queries_sql_keywords.safeKq(key)} ${dir}`,
 					bindings: [],
@@ -1261,6 +1285,10 @@ function conditionToSql(cond, ctx, topLevel) {
 function checkCondition(value) {
 	if (require_queries_find_DeferredAlias.isDeferredAliasCondition(value) || value && typeof value === "object" && require_queries_conditions.predicateBrand in value && value[require_queries_conditions.predicateBrand] === "domain") require_utils.fail("Domain alias conditions are only supported by em.find; use table(...) predicates in SQL queries and mutations.");
 	if (value === void 0 || value === require_queries_skipCondition.skipCondition) return;
+	if (isInQueryCondition(value)) {
+		checkCondition(normalizeWhere(normalizeQueryJoins(toQuery(value[require_queries_sql_Tables.inQueryCondition].query)).where));
+		return;
+	}
 	if (!value || typeof value !== "object" || Array.isArray(value) || require_queries_sql_Expr.isExpr(value)) require_utils.fail("Query predicate must be a condition or an and/or group");
 	const condition = value;
 	if ("and" in condition || "or" in condition) {
@@ -1346,6 +1374,13 @@ function checkConditionKeys(value, allowed, description) {
 */
 function resolveQueryCondition(cond, ctx) {
 	if (cond === void 0) return void 0;
+	if (isInQueryCondition(cond)) {
+		const { column, query } = cond[require_queries_sql_Tables.inQueryCondition];
+		const value = createMaybeQueryValue(query);
+		if (value === void 0) return void 0;
+		if (!require_queries_sql_Expr.isExpr(value)) return require_utils.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
@@ -1380,6 +1415,7 @@ function isFilter(cond) {
 */
 function isPrunedQueryCondition(cond) {
 	if (cond === void 0 || cond === require_queries_skipCondition.skipCondition) return true;
+	if (isInQueryCondition(cond)) return isPrunedQueryCondition(normalizeWhere(normalizeQueryJoins(cond[require_queries_sql_Tables.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);
@@ -1388,6 +1424,10 @@ function isPrunedQueryCondition(cond) {
 	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 && require_queries_sql_Tables.inQueryCondition in value;
+}
 /** The physical source aliases a parsed condition tree references. */
 function refsOf(parsed) {
 	return require_queries_parsedConditions.deepFindConditions(parsed, false).flatMap((c) => c.kind === "column" ? [c.alias] : c.kind === "raw" ? c.aliases : c.outerAliases);
@@ -1521,6 +1561,28 @@ function joinFragmentParts(parts, sep) {
 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 = require_queries_sql_JoinTree.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 require_queries_sql_Expr.TemplateExpr(strings, values);