joist-core 2.3.0 → 2.4.0-next.2

package/build/queries/sql/Tables.cjs

@@ -0,0 +1,803 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keys = require("../../keys.cjs");
+const require_queries_sql_keywords = require("./keywords.cjs");
+const require_queries_skipCondition = require("../skipCondition.cjs");
+const require_queries_valueFilters = require("../valueFilters.cjs");
+const require_queries_sql_Expr = require("./Expr.cjs");
+const require_utils = require("../../utils.cjs");
+const require_configure = require("../../configure.cjs");
+const require_EntityMetadata = require("../../EntityMetadata.cjs");
+const require_queries_renderConditions = require("../renderConditions.cjs");
+const require_queries_sql_custom = require("./custom.cjs");
+const require_Entity = require("../../Entity.cjs");
+let joist_utils = require("joist-utils");
+//#region src/queries/sql/Tables.ts
+function table(cstr, _name) {
+	return require_queries_sql_custom.isCustomTableDefinition(cstr) ? newCustomTableProxy(cstr) : newTableProxy(cstr);
+}
+/** Creates multiple physical table handles. */
+function tables(...type) {
+	return type.map((t) => newTableProxy(t));
+}
+/** The source of a default reference join, used to inherit optional paths within each query. */
+const referenceJoinSource = Symbol("joist.referenceJoinSource");
+const tableMgmt = Symbol("tableMgmt");
+const inQueryCondition = Symbol("joist.inQueryCondition");
+function getTableMgmt(table) {
+	return table[tableMgmt];
+}
+/** Qualifies custom tables without changing SQL for tables on the default search path. */
+function tableSqlName(table) {
+	return table.schema ? `${require_queries_sql_keywords.safeKq(table.schema)}.${require_queries_sql_keywords.kq(table.tableName)}` : require_queries_sql_keywords.kq(table.tableName);
+}
+/** Returns the metadata for the entity that `table` is bound to. */
+function getTableMetadata(table) {
+	return table[tableMgmt].meta;
+}
+function newTableProxy(cstr) {
+	const meta = require_EntityMetadata.getMetadata(cstr);
+	const mgmt = {
+		tableName: meta.tableName,
+		meta
+	};
+	const subtypes = new Map(meta.subTypes.map((m) => [m.type[0].toLowerCase() + m.type.slice(1), m]));
+	const proxy = new Proxy(cstr, {
+		/** Create a physical column expression or a relation join factory. */
+		get(_, key) {
+			if (key === tableMgmt) return mgmt;
+			if (typeof key !== "string") return void 0;
+			const descriptor = Object.hasOwn(meta.columns, key) ? meta.columns[key] : void 0;
+			if (descriptor) return descriptor.idMetadata ? new EntityColumnImpl(meta, descriptor, mgmt, key) : new PrimitiveColumnImpl(meta, descriptor, mgmt, key);
+			const subtype = subtypes.get(key);
+			if (subtype) {
+				const join = new SubtypeJoinImpl(proxy, subtype);
+				return Object.assign(join.as.bind(join), {
+					as: join.as.bind(join),
+					inner: join.inner.bind(join),
+					left: join.left.bind(join)
+				});
+			}
+			const relation = physicalRelation(meta, key);
+			if (key === "where" && !isRelation(meta.allFields[key])) return (filter) => tableWhere(mgmt, filter);
+			if (key === "column" && !isRelation(meta.allFields[key])) return (column) => new require_queries_sql_Expr.RefExpr(mgmt, column);
+			const field = relation ?? require_utils.fail(`No physical field ${key} on ${cstr.name}; join its base table explicitly`);
+			switch (field.kind) {
+				case "m2o": return new ReferenceJoinImpl(new EntityColumnImpl(meta, field.serde.columns[0].column, mgmt));
+				case "poly": return new PolyReferenceImpl(meta, mgmt, field);
+				case "o2m":
+				case "o2o":
+				case "lo2m": return new OneToManyJoinImpl(proxy, field);
+				case "m2m": return new ManyToManyJoinImpl(proxy, field);
+				default: throw new Error(`Unsupported table field kind ${field.kind}`);
+			}
+		},
+		has(_, key) {
+			return key === tableMgmt || typeof key === "string" && (key === "where" || key === "column" || Object.hasOwn(meta.columns, key) || !!physicalRelation(meta, key) || subtypes.has(key));
+		}
+	});
+	return proxy;
+}
+/** Creates a typed handle for primitive columns declared outside Joist codegen. */
+function newCustomTableProxy(definition) {
+	const { tableName, schema, columns } = require_queries_sql_custom.getCustomTableDefinition(definition);
+	const mgmt = {
+		tableName,
+		schema,
+		columns
+	};
+	return new Proxy({}, {
+		get(_, key) {
+			if (key === tableMgmt) return mgmt;
+			if (typeof key !== "string") return void 0;
+			const descriptor = Object.hasOwn(columns, key) ? columns[key] : void 0;
+			if (descriptor) return new PrimitiveColumnImpl(void 0, descriptor, mgmt, key);
+			if (key === "column") return (column) => new require_queries_sql_Expr.RefExpr(mgmt, column);
+			return require_utils.fail(`Custom table ${tableName} has no declared column ${key}; use .column("${key}")`);
+		},
+		has(_, key) {
+			return key === tableMgmt || key === "column" || typeof key === "string" && Object.hasOwn(columns, key);
+		}
+	});
+}
+function isTable(obj) {
+	return (typeof obj === "function" || typeof obj === "object" && obj !== null) && tableMgmt in obj;
+}
+/** Whether a physical table has generated entity metadata. */
+function isEntityTable(obj) {
+	return isTable(obj) && "meta" in obj[tableMgmt];
+}
+/** Whether a physical table has columns declared through `declareTable`. */
+function isCustomTable(obj) {
+	return isTable(obj) && "columns" in obj[tableMgmt];
+}
+/**
+* A physical table column implements `Expr`: it renders as `alias."column"`, decodes result
+* values through the column's shared scalar codec, and inherits aggregate methods from `BaseExpr`.
+*/
+var TableColumn = class extends require_queries_sql_Expr.BaseExpr {
+	meta;
+	column;
+	mgmt;
+	selectKey;
+	constructor(meta, column, mgmt, selectKey = column.columnName) {
+		super();
+		this.meta = meta;
+		this.column = column;
+		this.mgmt = mgmt;
+		this.selectKey = selectKey;
+	}
+	get [require_queries_sql_Expr.selectKeyBrand]() {
+		return this.selectKey;
+	}
+	/** Author.id, Book.authorId, and Comment.parentAuthorId use the same Author ID domain. */
+	get outputType() {
+		return this.column.outputType;
+	}
+	get sqlNullable() {
+		return this.column.sqlNullable;
+	}
+	get sqlSource() {
+		return this.mgmt;
+	}
+	toSql(ctx) {
+		const alias = ctx.aliasFor(this.mgmt);
+		return {
+			sql: require_queries_sql_keywords.kqDot(alias, this.column.columnName),
+			bindings: [],
+			refs: [alias]
+		};
+	}
+	/** Decodes result-set values with public PK/FK ids, while hydration keeps internal tagged ids. */
+	decode(value) {
+		if (value === null || value === void 0) return value;
+		const idMeta = this.idMetadata;
+		if (idMeta) return require_keys.toIdOf(idMeta, this.column.mapFromDb(value));
+		return this.column.mapFromDb(value);
+	}
+	encode(value) {
+		return this.column.mapToDb(value);
+	}
+	/** Identifies the ID domain of a primary key, FK, or physical polymorphic component. */
+	get idMetadata() {
+		return this.column.idMetadata?.();
+	}
+	/** Encodes literals when the condition is created and renders with each query's aliases. */
+	addCondition(value) {
+		const encoded = require_queries_valueFilters.mapToDb(this.column, value);
+		return require_queries_sql_Expr.deferredCondition((ctx) => {
+			const left = this.toSql(ctx);
+			const [sql, bindings] = require_queries_renderConditions.buildValueCondition(left.sql, encoded);
+			return {
+				sql,
+				bindings: [...left.bindings, ...bindings],
+				refs: left.refs
+			};
+		});
+	}
+	/** Renders raw operators against the same quoted column SQL as other expressions. */
+	addRawCondition(exp, bindings) {
+		return require_queries_sql_Expr.deferredCondition((ctx) => {
+			const left = this.toSql(ctx);
+			return {
+				sql: `${left.sql} ${exp}`,
+				bindings: [...left.bindings, ...bindings],
+				refs: left.refs
+			};
+		});
+	}
+	/** Uses column filter conversions for literals and shared comparisons for expressions and null equality. */
+	compare(op, value) {
+		if (value === void 0 || require_queries_sql_Expr.isExpr(value) || value === null && (op === "=" || op === "!=")) return super.compare(op, value);
+		const kind = {
+			"=": "eq",
+			"!=": "ne",
+			">": "gt",
+			">=": "gte",
+			"<": "lt",
+			"<=": "lte"
+		}[op];
+		if (!kind) return require_utils.fail(`Invalid operator ${op}`);
+		return this.addCondition({
+			kind,
+			value
+		});
+	}
+	/**
+	* Compares this column to another expression.
+	*
+	* Table columns, aggregates, subquery columns, and `sql` templates use the expression context
+	* to render their complete SQL.
+	* Negated array operators wrap the complete comparison in NOT.
+	*/
+	compareToExpr(op, value, negate = false) {
+		if (negate) return require_queries_sql_Expr.deferredCondition((ctx) => {
+			const comparison = ctx.conditionToSql(this.compareToExpr(op, value));
+			return {
+				...comparison,
+				sql: `NOT (${comparison.sql})`
+			};
+		});
+		return super.compare(op, value);
+	}
+};
+var PrimitiveColumnImpl = class extends TableColumn {
+	between(v1, v2) {
+		if (v1 === void 0 || v2 === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "between",
+			value: [v1, v2]
+		});
+	}
+	like(value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "like",
+			value
+		});
+	}
+	ilike(value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "ilike",
+			value
+		});
+	}
+	search(value) {
+		if (!value) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "ilike",
+			value: require_queries_valueFilters.makeLike(value)
+		});
+	}
+	in(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(values)) return this.inList("IN", values);
+		if (values.includes(null)) return { or: [this.addCondition({ kind: "is-null" }), this.addCondition({
+			kind: "in",
+			value: values.filter((v) => v !== null)
+		})] };
+		else return this.addCondition({
+			kind: "in",
+			value: values
+		});
+	}
+	/** Applies an IN condition unless the list is empty or undefined. */
+	inNonEmpty(values) {
+		return values === void 0 || values.length === 0 ? require_queries_skipCondition.skipCondition : this.in(values);
+	}
+	nin(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(values)) return this.inList("NOT IN", values);
+		return this.addCondition({
+			kind: "nin",
+			value: values.filter((v) => v !== null)
+		});
+	}
+	contains(v1) {
+		if (v1 === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(v1)) return this.compareToExpr("@>", v1);
+		return this.addCondition({
+			kind: "contains",
+			value: v1
+		});
+	}
+	ncontains(v1) {
+		if (v1 === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(v1)) return this.compareToExpr("@>", v1, true);
+		return this.addCondition({
+			kind: "ncontains",
+			value: v1
+		});
+	}
+	overlaps(v1) {
+		if (v1 === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(v1)) return this.compareToExpr("&&", v1);
+		return this.addCondition({
+			kind: "overlaps",
+			value: v1
+		});
+	}
+	noverlaps(v1) {
+		if (v1 === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(v1)) return this.compareToExpr("&&", v1, true);
+		return this.addCondition({
+			kind: "noverlaps",
+			value: v1
+		});
+	}
+	pathExists(jsonPath) {
+		if (jsonPath === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "jsonPathExists",
+			value: jsonPath
+		});
+	}
+	pathIsTrue(jsonPath) {
+		if (jsonPath === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addCondition({
+			kind: "jsonPathPredicate",
+			value: jsonPath
+		});
+	}
+	raw(exp, bindings) {
+		if (bindings === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addRawCondition(exp, bindings);
+	}
+};
+var EntityColumnImpl = class extends TableColumn {
+	/** Uses the ID target's tag, including for foreign keys and polymorphic components. */
+	taggedId() {
+		return new TaggedIdExpr(this);
+	}
+	in(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		else if (values === null) throw new Error("Unsupported");
+		else if (require_queries_sql_Expr.isExpr(values)) return this.inList("IN", values);
+		else if (!Array.isArray(values)) return { [inQueryCondition]: {
+			column: this,
+			query: values
+		} };
+		else if (values.includes(null)) return { or: [this.addCondition({ kind: "is-null" }), this.addCondition({
+			kind: "in",
+			value: values.filter((v) => v !== null)
+		})] };
+		else return this.addCondition({
+			kind: "in",
+			value: values
+		});
+	}
+	/** Applies an IN condition unless the list is empty, null, or undefined. */
+	inNonEmpty(values) {
+		return values === null || values === void 0 || values.length === 0 ? require_queries_skipCondition.skipCondition : this.in(values);
+	}
+	nin(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		else if (values === null) throw new Error("Unsupported");
+		else if (require_queries_sql_Expr.isExpr(values)) return this.inList("NOT IN", values);
+		else return this.addCondition({
+			kind: "nin",
+			value: values.filter((v) => v !== null)
+		});
+	}
+	gt(value) {
+		return this.compareId(">", "gt", value);
+	}
+	gte(value) {
+		return this.compareId(">=", "gte", value);
+	}
+	lt(value) {
+		return this.compareId("<", "lt", value);
+	}
+	lte(value) {
+		return this.compareId("<=", "lte", value);
+	}
+	raw(exp, bindings) {
+		if (bindings === void 0) return require_queries_skipCondition.skipCondition;
+		return this.addRawCondition(exp, bindings);
+	}
+	/** Joins via this FK, inheriting the source's LEFT join for otherwise required references. */
+	as(other) {
+		return {
+			...this.joinEntry(this.sqlNullable === false ? "inner" : "left", other),
+			[referenceJoinSource]: this.mgmt
+		};
+	}
+	inner(other) {
+		return this.joinEntry("inner", other);
+	}
+	left(other) {
+		return this.joinEntry("left", other);
+	}
+	joinEntry(kind, other) {
+		return {
+			[kind]: requireTable(other),
+			on: this.eq(idColumnOf(other))
+		};
+	}
+	compareId(op, kind, value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		if (value === null) throw new Error("Unsupported");
+		if (require_queries_sql_Expr.isExpr(value)) return this.compareToExpr(op, value);
+		return this.addCondition({
+			kind,
+			value
+		});
+	}
+};
+/** Converts a physical ID to SQL text so nested SQL expressions also receive the tag. */
+var TaggedIdExpr = class extends require_queries_sql_Expr.BaseExpr {
+	column;
+	constructor(column) {
+		super();
+		this.column = column;
+	}
+	toSql(ctx) {
+		const fragment = this.column.toSql(ctx);
+		const meta = this.column.idMetadata ?? require_utils.fail("Tagged IDs require an ID column");
+		return {
+			...fragment,
+			sql: `(? || ${fragment.sql}::text)`,
+			bindings: [require_keys.taggedIdPrefix(meta), ...fragment.bindings]
+		};
+	}
+	get outputType() {
+		return {
+			dbType: "text",
+			domain: String,
+			arrayElementSafe: true
+		};
+	}
+	get sqlNullable() {
+		return this.column.sqlNullable;
+	}
+	get sqlSource() {
+		return this.column.sqlSource;
+	}
+};
+var PolyReferenceImpl = class {
+	meta;
+	mgmt;
+	field;
+	constructor(meta, mgmt, field) {
+		this.meta = meta;
+		this.mgmt = mgmt;
+		this.field = field;
+	}
+	/** Compares to a tagged id, an entity, or another table's id column, which picks the component (`c.parent.eq(a.id)`). */
+	eq(value) {
+		return this.addEqOrNe("eq", value);
+	}
+	ne(value) {
+		return this.addEqOrNe("ne", value);
+	}
+	in(values) {
+		if (values === void 0) return require_queries_skipCondition.skipCondition;
+		if (require_queries_sql_Expr.isExpr(values)) return this.inSubquery(values);
+		const idsByConstructor = (0, joist_utils.groupBy)(values, (id) => require_configure.getConstructorFromTaggedId(require_keys.maybeResolveReferenceToId(id)).name);
+		return { or: Object.entries(idsByConstructor).map(([cstrName, ids]) => {
+			const comp = this.field.components.find((p) => p.otherMetadata().cstr.name === cstrName) ?? require_utils.fail(`No component for ${cstrName}`);
+			return this.componentColumn(comp).addCondition({
+				kind: "in",
+				value: ids
+			});
+		}) };
+	}
+	/** Applies an IN condition unless the list is empty or undefined. */
+	inNonEmpty(values) {
+		return values === void 0 || values.length === 0 ? require_queries_skipCondition.skipCondition : this.in(values);
+	}
+	/** Joins via this poly's component, inheriting the source's LEFT join when the poly is required. */
+	as(other) {
+		return {
+			...this.joinEntry(this.field.required ? "inner" : "left", other),
+			[referenceJoinSource]: this.mgmt
+		};
+	}
+	inner(other) {
+		return this.joinEntry("inner", other);
+	}
+	left(other) {
+		return this.joinEntry("left", other);
+	}
+	joinEntry(kind, other) {
+		return {
+			[kind]: requireTable(other),
+			on: this.eq(idColumnOf(other))
+		};
+	}
+	/**
+	* i.e. `c.parent.in(query({ from: a, ..., select: a.id }))`: like `eq` against a table column, the
+	* subquery's agreed ID domain picks the component, i.e. authors pick `parent_author_id`.
+	*/
+	inSubquery(values) {
+		const selected = require_queries_sql_Expr.asNode(values).subquerySelect;
+		const outputType = selected?.outputType;
+		let otherMeta = outputType?.idMeta;
+		if (!otherMeta) {
+			if (!outputType && selected instanceof TableColumn) otherMeta = selected.idMetadata;
+			if (!otherMeta) return require_utils.fail(selected instanceof TableColumn ? `${this.field.fieldName} \`in\` needs an id or FK column, got ${selected.column.columnName}` : `${this.field.fieldName} is polymorphic, so \`in\` needs a subquery selecting an id or FK column`);
+		}
+		const comp = this.field.components.find((p) => require_EntityMetadata.getBaseAndSelfMetas(otherMeta).includes(p.otherMetadata())) ?? require_utils.fail(`${this.field.fieldName} has no component for ${otherMeta.type}`);
+		return this.componentColumn(comp).in(values);
+	}
+	addEqOrNe(kind, value) {
+		if (value === void 0) return require_queries_skipCondition.skipCondition;
+		else if (value instanceof TableColumn) {
+			const otherMeta = value.idMetadata ?? require_utils.fail(`${this.field.fieldName} needs an id or FK column`);
+			const comp = this.field.components.find((p) => require_EntityMetadata.getBaseAndSelfMetas(otherMeta).includes(p.otherMetadata())) ?? require_utils.fail(`${this.field.fieldName} has no component for ${otherMeta.type}`);
+			return this.componentColumn(comp)[kind](value);
+		} else if (require_queries_sql_Expr.isExpr(value)) return require_utils.fail(`${this.field.fieldName} is polymorphic, so it can only be compared to tagged ids or entity table columns`);
+		else if (value === null) {
+			const value = kind === "eq" ? { kind: "is-null" } : { kind: "not-null" };
+			return { and: this.field.components.map((p) => this.componentColumn(p).addCondition(value)) };
+		} else {
+			const comp = this.field.components.find((p) => p.otherMetadata().cstr === require_configure.getConstructorFromTaggedId(require_keys.maybeResolveReferenceToId(value))) || require_utils.fail(`Could not find component for ${value}`);
+			return this.componentColumn(comp)[kind](value);
+		}
+	}
+	/** Returns the physical FK expression for one polymorphic target. */
+	componentColumn(comp) {
+		const descriptor = comp.column;
+		return new EntityColumnImpl(this.meta, descriptor, this.mgmt);
+	}
+};
+/**
+* Marks a sugar join entry whose target is a *collection* (o2m/m2m), which filter soft-deletes like
+* em.find's "collections filter out soft-deletes, but m2o/o2o references still return them"; see
+* `QueryParser.addSoftDeleteCondition`'s call site. Reference joins and explicit joins are unmarked.
+*/
+const collectionJoin = Symbol("joist.collectionJoin");
+/** Marks a sugar m2m join entry (`a.tags.as(t)`) with its hidden join-table join; `parseQuery` expands it. */
+const m2mJoinTable = Symbol("joist.m2mJoinTable");
+/** The runtime identity of an m2m join table in a query, i.e. `authors_to_tags`; it has no entity. */
+var JoinTableHandle = class {
+	joinTableName;
+	constructor(joinTableName) {
+		this.joinTableName = joinTableName;
+	}
+};
+/**
+* The `as`/`inner`/`left` join factory for collection relations, i.e. `a.books.as(b)` joins with the
+* relation's default kind (LEFT: a collection may be empty) and `.inner`/`.left` override. m2o/poly
+* relations implement the same three methods on their join factories. Physical FKs such as
+* `b.author_id` are expressions that also expose a join factory.
+*/
+var CollectionJoinImpl = class {
+	as(other) {
+		return this.joinEntry("left", requireTable(other));
+	}
+	inner(other) {
+		return this.joinEntry("inner", requireTable(other));
+	}
+	left(other) {
+		return this.joinEntry("left", requireTable(other));
+	}
+};
+/** Joins a named subtype explicitly; only STI subtype sugar adds a discriminator to its ON. */
+var SubtypeJoinImpl = class extends CollectionJoinImpl {
+	proxy;
+	subtype;
+	constructor(proxy, subtype) {
+		super();
+		this.proxy = proxy;
+		this.subtype = subtype;
+	}
+	joinEntry(kind, other) {
+		if (getTableMetadata(other) !== this.subtype) return require_utils.fail(`Expected table(${this.subtype.type}) for the explicit subtype join`);
+		const on = idColumnOf(this.proxy).eq(idColumnOf(other));
+		if (this.subtype.inheritanceType !== "sti" || this.subtype.stiDiscriminatorValue === void 0) return {
+			[kind]: other,
+			on
+		};
+		const base = this.subtype.baseTypes.find((m) => m.stiDiscriminatorField !== void 0);
+		const columnName = base.fields[base.stiDiscriminatorField].serde.columns[0].columnName;
+		const discriminator = require_queries_sql_Expr.deferredCondition((ctx) => {
+			const alias = ctx.aliasFor(other[tableMgmt]);
+			return {
+				sql: `${require_queries_sql_keywords.kqDot(alias, columnName)} = ?`,
+				bindings: [this.subtype.stiDiscriminatorValue],
+				refs: [alias]
+			};
+		});
+		return {
+			[kind]: other,
+			on: { and: [on, discriminator] }
+		};
+	}
+};
+/** An o2m/lo2m/o2o relation: the ON is the other side's FK (an m2o or a poly component) back to our id. */
+var OneToManyJoinImpl = class extends CollectionJoinImpl {
+	proxy;
+	field;
+	constructor(proxy, field) {
+		super();
+		this.proxy = proxy;
+		this.field = field;
+	}
+	joinEntry(kind, other) {
+		const { field } = this;
+		const otherMeta = getTableMetadata(other);
+		const descriptor = Object.values(otherMeta.columns).find((column) => column.columnName === field.otherColumnName);
+		if (!descriptor) return require_utils.fail(`Cannot join ${getTableMetadata(this.proxy).type}.${field.fieldName} to ${otherMeta.type}: ${field.otherColumnName} is not physically present on ${otherMeta.tableName}; join the base table explicitly`);
+		const on = new EntityColumnImpl(otherMeta, descriptor, other[tableMgmt]).eq(this.proxy.id);
+		const filtered = field.kind === "o2m" ? field.softDeletes !== "include" : field.kind === "lo2m";
+		return {
+			[kind]: other,
+			on,
+			[collectionJoin]: filtered
+		};
+	}
+};
+/**
+* An m2m relation, i.e. `a.tags.as(t)`.
+*
+* The entry's own ON is `t.id = att.tag_id`, and the hidden `[m2mJoinTable]` half is
+* `att.author_id = a.id`; only the target's ON references the join table, so reference pruning keeps
+* or drops the pair together. Both are deferred conditions: the join table has no entity metadata, so
+* its alias only exists once the parser registers it.
+*/
+var ManyToManyJoinImpl = class extends CollectionJoinImpl {
+	proxy;
+	field;
+	constructor(proxy, field) {
+		super();
+		this.proxy = proxy;
+		this.field = field;
+	}
+	joinEntry(kind, other) {
+		const { joinTableName, columnNames } = this.field;
+		const [ourColumn, otherColumn] = columnNames;
+		const jt = new JoinTableHandle(joinTableName);
+		const ourId = idColumnOf(this.proxy);
+		const otherId = idColumnOf(other);
+		const jtOn = require_queries_sql_Expr.deferredCondition((ctx) => {
+			const jtAlias = ctx.aliasFor(jt);
+			const id = ourId.toSql(ctx);
+			return {
+				sql: `${require_queries_sql_keywords.kqDot(jtAlias, ourColumn)} = ${id.sql}`,
+				bindings: id.bindings,
+				refs: id.refs
+			};
+		});
+		const on = require_queries_sql_Expr.deferredCondition((ctx) => {
+			const jtAlias = ctx.aliasFor(jt);
+			const id = otherId.toSql(ctx);
+			return {
+				sql: `${id.sql} = ${require_queries_sql_keywords.kqDot(jtAlias, otherColumn)}`,
+				bindings: id.bindings,
+				refs: [...id.refs, jtAlias]
+			};
+		});
+		const filtered = this.field.softDeletes !== "include";
+		return {
+			[kind]: other,
+			on,
+			[collectionJoin]: filtered,
+			[m2mJoinTable]: {
+				handle: jt,
+				on: jtOn
+			}
+		};
+	}
+};
+/** Fails fast when a join factory is passed something other than a table. */
+function requireTable(other) {
+	if (!isEntityTable(other)) return require_utils.fail(`Expected an entity table to join, got ${other}`);
+	return other;
+}
+/** The id column of a joined table, for building sugar ON conditions. */
+function idColumnOf(other) {
+	return other.id;
+}
+/** Keeps relation names join-only; physical FK columns retain expression methods. */
+var ReferenceJoinImpl = class {
+	column;
+	constructor(column) {
+		this.column = column;
+	}
+	as(other) {
+		return this.column.as(other);
+	}
+	inner(other) {
+		return this.column.inner(other);
+	}
+	left(other) {
+		return this.column.left(other);
+	}
+};
+/** Identifies domain relationship keys exposed alongside physical columns. */
+function isRelation(field) {
+	return field !== void 0 && [
+		"m2o",
+		"poly",
+		"o2m",
+		"lo2m",
+		"m2m",
+		"o2o"
+	].includes(field.kind);
+}
+/** Resolves relationship sugar only from domain fields owned by this physical table. */
+function physicalRelation(meta, key) {
+	const field = [meta, ...require_EntityMetadata.getBaseSelfAndSubMetas(require_EntityMetadata.getBaseMeta(meta))].find((owner) => owner.tableName === meta.tableName && Object.hasOwn(owner.fields, key))?.fields[key];
+	if (!isRelation(field)) return void 0;
+	if (field?.kind === "m2o" || field?.kind === "poly") {
+		if (!field.serde.columns.every((binding) => Object.values(meta.columns).includes(binding.column))) return void 0;
+		return field.kind === "poly" ? {
+			...field,
+			components: field.components.map((component) => ({
+				column: component.column,
+				columnName: component.columnName,
+				otherFieldName: component.otherFieldName,
+				otherMetadata: component.column.idMetadata
+			}))
+		} : field;
+	}
+	return field;
+}
+/**
+* Maps local domain fields to table-bound conditions, encoding each leaf once.
+* I.e. Author.firstName uses the first_name column but resolves its alias in each query scope.
+* Collections, polymorphic references, and inherited nonlocal fields require explicit expressions.
+*/
+function tableWhere(mgmt, filter) {
+	const { meta } = mgmt;
+	const conditions = [];
+	if (!filter || typeof filter !== "object" || Array.isArray(filter)) throw new Error(`Expected a domain field filter for ${meta.type}`);
+	for (const [key, value] of Object.entries(filter)) {
+		const field = key === "id" ? meta.fields.id : Object.hasOwn(meta.allFields, key) ? meta.allFields[key] : void 0;
+		if (!field || ![
+			"primaryKey",
+			"primitive",
+			"enum",
+			"m2o"
+		].includes(field.kind) || !field.serde || field.serde.columns.length !== 1 || !field.serde.columns.every((binding) => Object.values(meta.columns).includes(binding.column))) throw new Error(`Unsupported table filter field ${meta.type}.${key}; use an explicit join`);
+		const column = new TableColumn(meta, field.serde.columns[0].column, mgmt);
+		let leaves;
+		if (field.kind === "m2o") {
+			if (!isTableReferenceFilter(value)) throw new Error(`Unsupported table reference filter ${meta.type}.${key}; use an entity or ID`);
+			const parsed = require_queries_valueFilters.parseEntityFilter(field.otherMetadata(), value);
+			if (parsed?.kind === "join") throw new Error(`Unsupported table reference filter ${meta.type}.${key}; use an entity or ID`);
+			leaves = parsed ? [parsed] : [];
+		} else leaves = require_queries_valueFilters.parseValueFilter(value);
+		for (const leaf of leaves) if (leaf.kind === "between" && leaf.value.some((v) => v === void 0)) {
+			if (leaf.value[0] !== void 0) conditions.push(column.addCondition({
+				kind: "gte",
+				value: leaf.value[0]
+			}));
+			if (leaf.value[1] !== void 0) conditions.push(column.addCondition({
+				kind: "lte",
+				value: leaf.value[1]
+			}));
+		} else if (leaf.kind === "in" && !column.column.isArray && leaf.value.includes(null)) conditions.push({ or: [column.addCondition({ kind: "is-null" }), column.addCondition({
+			kind: "in",
+			value: leaf.value.filter((v) => v !== null)
+		})] });
+		else conditions.push(column.addCondition(leaf));
+	}
+	return conditions.length === 0 ? require_queries_skipCondition.skipCondition : { and: conditions };
+}
+/**
+* Converts relationship filters into conditions on the joined table's id column.
+* I.e. Author's `join: { books: "b:1" }` filters Book.id to 1; `{ books: book }` uses book.id.
+* Lists match any supplied ID, `true` requires a Book, and `null` or `false` requires no Book.
+*/
+function tableEntityWhere(mgmt, value) {
+	const parsed = require_queries_valueFilters.parseEntityFilter(mgmt.meta, value);
+	if (!parsed) return require_queries_skipCondition.skipCondition;
+	if (parsed.kind === "join") require_utils.fail(`Expected an entity or ID filter for ${mgmt.meta.type}`);
+	return new TableColumn(mgmt.meta, mgmt.meta.fields.id.serde.columns[0].column, mgmt).addCondition(parsed);
+}
+/** Rejects nested relations, scopes, and aliases before parsing owning-reference values. */
+function isTableReferenceFilter(value) {
+	if (value == null || typeof value === "boolean" || isTableReferenceValue(value)) return true;
+	if (Array.isArray(value)) return value.every(isTableReferenceValue);
+	if (typeof value === "object" && Object.keys(value).length === 1 && Object.hasOwn(value, "ne")) {
+		const excluded = value.ne;
+		return excluded == null || isTableReferenceValue(excluded);
+	}
+	return false;
+}
+/** Recognizes an entity or public ID without accepting another filter object. */
+function isTableReferenceValue(value) {
+	return typeof value === "string" || typeof value === "number" || require_Entity.isEntity(value);
+}
+//#endregion
+exports.JoinTableHandle = JoinTableHandle;
+exports.collectionJoin = collectionJoin;
+exports.getTableMetadata = getTableMetadata;
+exports.getTableMgmt = getTableMgmt;
+exports.inQueryCondition = inQueryCondition;
+exports.isCustomTable = isCustomTable;
+exports.isEntityTable = isEntityTable;
+exports.isTable = isTable;
+exports.m2mJoinTable = m2mJoinTable;
+exports.newTableProxy = newTableProxy;
+exports.referenceJoinSource = referenceJoinSource;
+exports.table = table;
+exports.tableEntityWhere = tableEntityWhere;
+exports.tableMgmt = tableMgmt;
+exports.tableSqlName = tableSqlName;
+exports.tableWhere = tableWhere;
+exports.tables = tables;
+
+//# sourceMappingURL=Tables.cjs.map