@danceroutine/tango-orm 1.4.0 → 1.5.0

package/dist/{query-CWZ1cfjo.js → query-DYiJ5m_B.js}

@@ -1,5 +1,6 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { SqlSafetyEngine } from "@danceroutine/tango-core";
+import { SqlSafetyEngine, isError } from "@danceroutine/tango-core";
+import { ModelRegistry } from "@danceroutine/tango-schema";
 
 //#region src/query/domain/internal/InternalRelationKind.ts
 const InternalRelationKind = {
@@ -9,6 +10,72 @@ const InternalRelationKind = {
 	MANY_TO_MANY: "manyToMany"
 };
 
+//#endregion
+//#region src/query/domain/TableMetaFactory.ts
+var TableMetaFactory = class TableMetaFactory {
+	static create(model) {
+		const owner = model.metadata.key ? ModelRegistry.getOwner(model) : undefined;
+		const cache = new Map();
+		return TableMetaFactory.createWithCache(model, owner, cache);
+	}
+	static createWithCache(model, owner, cache) {
+		if (model.metadata.key) {
+			const cached = cache.get(model.metadata.key);
+			if (cached) return cached;
+		}
+		const pkField = model.metadata.fields.find((field) => field.primaryKey);
+		if (!pkField) throw new Error(`Model '${model.metadata.name}' cannot attach a manager without a primary key field.`);
+		const tableMeta = {
+			modelKey: model.metadata.key,
+			table: model.metadata.table,
+			pk: pkField.name,
+			columns: Object.fromEntries(model.metadata.fields.map((field) => [field.name, field.type]))
+		};
+		if (model.metadata.key) cache.set(model.metadata.key, tableMeta);
+		if (!model.metadata.key || !owner) return tableMeta;
+		const relations = owner.getResolvedRelationGraph().byModel.get(model.metadata.key);
+		if (!relations || relations.size === 0) return tableMeta;
+		tableMeta.relations = Object.fromEntries(Array.from(relations.entries()).filter(([, relation]) => relation.capabilities.queryable && relation.capabilities.hydratable).map(([name, relation]) => {
+			const targetModel = owner.getByKey(relation.targetModelKey);
+			const targetMeta = TableMetaFactory.createWithCache(targetModel, owner, cache);
+			const { queryable, hydratable } = relation.capabilities;
+			const isSingleRelation = relation.kind === InternalRelationKind.BELONGS_TO || relation.kind === InternalRelationKind.HAS_ONE;
+			const sourceKey = relation.kind === InternalRelationKind.BELONGS_TO ? relation.localFieldName : relation.targetFieldName;
+			const targetKey = relation.kind === InternalRelationKind.BELONGS_TO ? relation.targetFieldName : relation.localFieldName;
+			const targetColumns = Object.fromEntries(targetModel.metadata.fields.map((field) => [field.name, field.type]));
+			const capabilities = {
+				queryable,
+				hydratable,
+				joinable: isSingleRelation && queryable && hydratable,
+				prefetchable: queryable && hydratable
+			};
+			return [name, {
+				edgeId: relation.edgeId,
+				sourceModelKey: relation.sourceModelKey,
+				targetModelKey: relation.targetModelKey,
+				kind: relation.kind,
+				cardinality: isSingleRelation ? "single" : "many",
+				capabilities,
+				table: targetModel.metadata.table,
+				sourceKey,
+				targetKey,
+				targetPrimaryKey: targetMeta.pk,
+				targetColumns,
+				alias: relation.alias,
+				targetMeta
+			}];
+		}));
+		return tableMeta;
+	}
+};
+
+//#endregion
+//#region src/query/domain/RelationMeta.ts
+const InternalRelationHydrationLoadMode = {
+	JOIN: "join",
+	PREFETCH: "prefetch"
+};
+
 //#endregion
 //#region src/query/domain/internal/InternalDialect.ts
 const InternalDialect = {
@@ -179,39 +246,129 @@ var OrmSqlSafetyAdapter = class OrmSqlSafetyAdapter {
 	}
 };
 
+//#endregion
+//#region src/query/domain/RelationTyping.ts
+const InternalRelationHydrationCardinality = {
+	SINGLE: "single",
+	MANY: "many"
+};
+
+//#endregion
+//#region src/query/planning/QueryPlanner.ts
+var QueryPlanner = class QueryPlanner {
+	static BRAND = "tango.orm.query_planner";
+	__tangoBrand = QueryPlanner.BRAND;
+	constructor(meta) {
+		this.meta = meta;
+	}
+	static isQueryPlanner(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === QueryPlanner.BRAND;
+	}
+	plan(state) {
+		const requestedPaths = Array.from(new Set([...state.selectRelated ?? [], ...state.prefetchRelated ?? []]));
+		if (requestedPaths.length === 0) return {
+			joinNodes: [],
+			prefetchNodes: [],
+			requestedPaths: []
+		};
+		const rootChildren = new Map();
+		for (const relationPath of new Set(state.selectRelated ?? [])) this.addPath(rootChildren, relationPath, "select");
+		for (const relationPath of new Set(state.prefetchRelated ?? [])) this.addPath(rootChildren, relationPath, "prefetch");
+		const { joinNodes, prefetchNodes } = this.buildPlannedChildren(rootChildren);
+		return {
+			joinNodes,
+			prefetchNodes,
+			requestedPaths
+		};
+	}
+	addPath(rootChildren, relationPath, mode) {
+		const segments = relationPath.split("__").filter(Boolean);
+		if (segments.length === 0) throw new Error(`Invalid empty relation path '${relationPath}'.`);
+		let currentMeta = this.meta;
+		let currentChildren = rootChildren;
+		let builtPath = "";
+		let containsCollection = false;
+		for (const segment of segments) {
+			const relation = currentMeta.relations?.[segment];
+			if (!relation) throw new Error(`Unknown relation path '${relationPath}' for table '${currentMeta.table}'.`);
+			if (segment in currentMeta.columns && relation.sourceKey !== segment) throw new Error(`Relation path '${relationPath}' collides with an existing field on table '${currentMeta.table}'.`);
+			if (relation.kind === InternalRelationKind.MANY_TO_MANY) throw new Error(`Relation path '${relationPath}' uses unsupported many-to-many hydration.`);
+			if (!relation.capabilities.queryable || !relation.capabilities.hydratable) throw new Error(`Relation path '${relationPath}' cannot be hydrated.`);
+			if (mode === "select") {
+				if (relation.cardinality !== InternalRelationHydrationCardinality.SINGLE || !relation.capabilities.joinable) throw new Error(`Relation path '${relationPath}' cannot be loaded with selectRelated(...).`);
+			} else if (relation.cardinality === InternalRelationHydrationCardinality.MANY) {
+				if (!relation.capabilities.prefetchable) throw new Error(`Relation path '${relationPath}' cannot be loaded with prefetchRelated(...).`);
+				containsCollection = true;
+			} else if (!relation.capabilities.joinable) throw new Error(`Relation path '${relationPath}' cannot be loaded with prefetchRelated(...).`);
+			const targetMeta = relation.targetMeta;
+			if (!targetMeta) throw new Error(`Relation path '${relationPath}' is missing target metadata.`);
+			builtPath = builtPath.length > 0 ? `${builtPath}__${segment}` : segment;
+			const existing = currentChildren.get(segment);
+			const nextNode = existing ?? {
+				segment,
+				relationEdge: relation,
+				relationPath: builtPath,
+				targetMeta,
+				provenance: new Set(),
+				children: new Map()
+			};
+			nextNode.provenance.add(relationPath);
+			currentChildren.set(segment, nextNode);
+			currentChildren = nextNode.children;
+			currentMeta = targetMeta;
+		}
+		if (mode === "prefetch" && !containsCollection) throw new Error(`Relation path '${relationPath}' cannot be loaded with prefetchRelated(...).`);
+	}
+	buildPlannedChildren(children) {
+		const joinNodes = [];
+		const prefetchNodes = [];
+		for (const child of children.values()) {
+			const { joinNodes: joinChildren, prefetchNodes: prefetchChildren } = this.buildPlannedChildren(child.children);
+			const plannedNode = {
+				nodeId: child.relationPath,
+				relationName: child.segment,
+				relationPath: child.relationPath,
+				ownerModelKey: child.relationEdge.sourceModelKey,
+				relationEdge: child.relationEdge,
+				targetModelKey: child.relationEdge.targetModelKey,
+				loadMode: child.relationEdge.cardinality === InternalRelationHydrationCardinality.SINGLE ? InternalRelationHydrationLoadMode.JOIN : InternalRelationHydrationLoadMode.PREFETCH,
+				cardinality: child.relationEdge.cardinality,
+				provenance: [...child.provenance],
+				joinChildren,
+				prefetchChildren
+			};
+			if (plannedNode.loadMode === InternalRelationHydrationLoadMode.JOIN) joinNodes.push(plannedNode);
+else prefetchNodes.push(plannedNode);
+		}
+		return {
+			joinNodes,
+			prefetchNodes
+		};
+	}
+};
+
 //#endregion
 //#region src/query/compiler/QueryCompiler.ts
 const sqlSafetyAdapter = new OrmSqlSafetyAdapter();
 var QueryCompiler = class QueryCompiler {
 	static BRAND = "tango.orm.query_compiler";
 	__tangoBrand = QueryCompiler.BRAND;
-	/**
-	* Build a compiler for the given repository metadata and SQL dialect.
-	*/
 	constructor(meta, dialect = InternalDialect.POSTGRES) {
 		this.meta = meta;
 		this.dialect = dialect;
 	}
-	/**
-	* Narrow an unknown value to `QueryCompiler`.
-	*/
 	static isQueryCompiler(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === QueryCompiler.BRAND;
 	}
-	/**
-	* Compile a query state tree into a SQL statement and bound parameters.
-	*/
 	compile(state) {
-		const selectRelationNames = state.selectRelated ?? [];
-		const prefetchRelationNames = state.prefetchRelated ?? [];
-		const relationNames = [...new Set([...selectRelationNames, ...prefetchRelationNames])];
+		const hydrationPlan = new QueryPlanner(this.meta).plan(state);
 		const validatedPlan = sqlSafetyAdapter.validate({
 			kind: "select",
 			meta: this.meta,
 			selectFields: state.select?.map(String),
 			filterKeys: this.collectStateFilterKeys(state),
 			orderFields: state.order?.map((order) => String(order.by)),
-			relationNames
+			relationNames: []
 		});
 		const table = validatedPlan.meta.table;
 		const whereParts = [];
@@ -233,87 +390,188 @@ var QueryCompiler = class QueryCompiler {
 				params.push(...result.params);
 			}
 		});
-		const baseSelect = state.select?.length ? state.select.map((field) => validatedPlan.selectFields[String(field)]).join(", ") : `${table}.*`;
-		const relationSelects = selectRelationNames.flatMap((relationName) => {
-			const relation = validatedPlan.relations[relationName];
-			return Object.keys(relation.targetColumns).map((column) => `${relation.alias}.${column} AS ${this.buildHydrationColumnAlias(relation.alias, column)}`);
-		});
-		const prefetchSourceSelects = state.select?.length && prefetchRelationNames.length ? prefetchRelationNames.map((relationName) => validatedPlan.relations[relationName]).filter((relation) => !state.select.map(String).includes(relation.sourceKey)).map((relation) => `${table}.${relation.sourceKey} AS ${this.buildPrefetchSourceAlias(relation.sourceKey)}`) : [];
+		const baseSelects = state.select?.length ? state.select.map((field) => validatedPlan.selectFields[String(field)]) : [`${table}.*`];
+		const joinCollection = {
+			selects: [],
+			joins: []
+		};
+		const hiddenRootAliases = [];
+		const compiledJoinNodes = hydrationPlan.joinNodes.map((node) => this.compileHydrationNode(node, {
+			rootTable: table,
+			ownerMeta: this.meta,
+			ownerAlias: table,
+			collectRootJoins: true,
+			rootSelectedFields: state.select?.map(String) ?? undefined,
+			hiddenRootAliases,
+			joinCollection
+		}));
+		const compiledPrefetchNodes = hydrationPlan.prefetchNodes.map((node) => this.compileHydrationNode(node, {
+			rootTable: table,
+			ownerMeta: this.meta,
+			ownerAlias: table,
+			collectRootJoins: false,
+			rootSelectedFields: state.select?.map(String) ?? undefined,
+			hiddenRootAliases,
+			joinCollection
+		}));
 		const select = [
-			baseSelect,
-			...relationSelects,
-			...prefetchSourceSelects
+			...baseSelects,
+			...joinCollection.selects,
+			...this.buildRootHiddenSelects(compiledPrefetchNodes, table)
 		].join(", ");
-		const joins = selectRelationNames.map((rel) => {
-			const relation = validatedPlan.relations[rel];
-			if (relation.kind !== InternalRelationKind.BELONGS_TO && relation.kind !== InternalRelationKind.HAS_ONE) throw new Error(`Relation '${rel}' cannot be loaded with selectRelated(...).`);
-			return `LEFT JOIN ${relation.table} ${relation.alias} ON ${relation.alias}.${relation.targetKey} = ${table}.${relation.sourceKey}`;
-		}).filter(Boolean).join(" ");
-		for (const rel of prefetchRelationNames) {
-			const relation = validatedPlan.relations[rel];
-			if (relation?.kind !== InternalRelationKind.HAS_MANY) throw new Error(`Relation '${rel}' cannot be loaded with prefetchRelated(...).`);
-		}
 		const whereSQL = whereParts.length ? ` WHERE ${whereParts.join(" AND ")}` : "";
 		const orderSQL = ` ORDER BY ${state.order?.length ? state.order.map((order) => `${validatedPlan.orderFields[String(order.by)]} ${order.dir.toUpperCase()}`).join(", ") : `${table}.${validatedPlan.meta.pk} ASC`}`;
 		const limitSQL = state.limit ? ` LIMIT ${state.limit}` : "";
 		const offsetSQL = state.offset ? ` OFFSET ${state.offset}` : "";
-		const sql = `SELECT ${select} FROM ${table}${joins ? ` ${joins}` : ""}${whereSQL}${orderSQL}${limitSQL}${offsetSQL}`;
+		const sql = `SELECT ${select} FROM ${table}${joinCollection.joins.length ? ` ${joinCollection.joins.join(" ")}` : ""}${whereSQL}${orderSQL}${limitSQL}${offsetSQL}`;
+		const compiledHydrationPlan = compiledJoinNodes.length > 0 || compiledPrefetchNodes.length > 0 ? {
+			requestedPaths: hydrationPlan.requestedPaths,
+			hiddenRootAliases: [...new Set(hiddenRootAliases)],
+			joinNodes: compiledJoinNodes,
+			prefetchNodes: compiledPrefetchNodes
+		} : undefined;
 		return {
 			sql,
 			params,
-			hydrations: selectRelationNames.map((relationName) => {
-				const relation = validatedPlan.relations[relationName];
-				return {
-					relationName,
-					alias: relation.alias,
-					columns: Object.fromEntries(Object.keys(relation.targetColumns).map((column) => [column, this.buildHydrationColumnAlias(relation.alias, column)]))
-				};
-			}),
-			prefetches: prefetchRelationNames.map((relationName) => {
-				const relation = validatedPlan.relations[relationName];
-				const needsAlias = !!state.select?.length && !state.select.map(String).includes(relation.sourceKey);
-				return {
-					relationName,
-					sourceKey: relation.sourceKey,
-					sourceKeyAlias: needsAlias ? this.buildPrefetchSourceAlias(relation.sourceKey) : undefined,
-					table: relation.table,
-					targetKey: relation.targetKey,
-					targetColumns: relation.targetColumns
-				};
-			})
+			hydrationPlan: compiledHydrationPlan
 		};
 	}
-	/**
-	* Compile the follow-up query used by `prefetchRelated(...)`.
-	*
-	* The base query cannot bind source values until after it has returned rows,
-	* but SQL rendering and validation still belong to the compiler.
-	*/
-	compilePrefetch(prefetch, sourceValues) {
-		const validatedPlan = sqlSafetyAdapter.validate({
-			kind: "select",
-			meta: this.meta,
-			relationNames: [prefetch.relationName]
-		});
-		const relation = validatedPlan.relations[prefetch.relationName];
-		const compiledTargetColumns = Object.keys(prefetch.targetColumns).sort();
-		const validatedTargetColumns = Object.keys(relation.targetColumns).sort();
-		const compiledMatchesValidated = prefetch.sourceKey === relation.sourceKey && prefetch.table === relation.table && prefetch.targetKey === relation.targetKey && compiledTargetColumns.length === validatedTargetColumns.length && compiledTargetColumns.every((column, index) => column === validatedTargetColumns[index] && prefetch.targetColumns[column] === relation.targetColumns[column]);
-		if (!compiledMatchesValidated) throw new Error(`Compiled prefetch metadata for relation '${prefetch.relationName}' failed validation.`);
-		const columns = Object.keys(relation.targetColumns);
+	compilePrefetch(node, sourceValues) {
 		const placeholders = this.dialect === InternalDialect.POSTGRES ? sourceValues.map((_, index) => `$${index + 1}`).join(", ") : sourceValues.map(() => "?").join(", ");
+		const validatedTarget = this.validatePrefetchTarget(node);
+		const baseAlias = this.buildPrefetchBaseAlias(node.relationPath);
+		const joinCollection = {
+			selects: [],
+			joins: []
+		};
+		for (const joinChild of node.joinChildren) this.collectNestedJoinSql(joinChild, baseAlias, validatedTarget.columns, joinCollection);
+		const baseSelects = Object.keys(validatedTarget.columns).map((column) => `${baseAlias}.${column} AS ${column}`);
 		return {
-			sql: `SELECT ${columns.join(", ")} FROM ${relation.table} WHERE ${relation.targetKey} IN (${placeholders}) ORDER BY ${relation.targetKey} ASC`,
+			sql: `SELECT ${[...baseSelects, ...joinCollection.selects].join(", ")} FROM ${validatedTarget.table} ${baseAlias}${joinCollection.joins.length ? ` ${joinCollection.joins.join(" ")}` : ""} WHERE ${baseAlias}.${validatedTarget.targetKey} IN (${placeholders}) ORDER BY ${baseAlias}.${validatedTarget.targetKey} ASC, ${baseAlias}.${validatedTarget.primaryKey} ASC`,
 			params: sourceValues,
-			targetKey: relation.targetKey,
-			targetColumns: relation.targetColumns
+			targetKey: validatedTarget.targetKey,
+			targetColumns: validatedTarget.columns
 		};
 	}
-	buildHydrationColumnAlias(alias, column) {
-		return this.assertInternalAliasDoesNotCollide(`__tango_hydrate_${alias}_${column}`);
+	compileHydrationNode(node, context) {
+		const validatedRelation = this.validateHydrationRelation(context.ownerMeta, node.relationName);
+		const targetColumns = validatedRelation.targetColumns;
+		const targetMeta = node.relationEdge.targetMeta;
+		if (!targetMeta) throw new Error(`Relation path '${node.relationPath}' is missing target metadata.`);
+		const compiledJoinChildren = node.joinChildren.map((child) => this.compileHydrationNode(child, {
+			...context,
+			ownerMeta: targetMeta,
+			ownerAlias: this.buildJoinAlias(node.relationPath),
+			collectRootJoins: context.collectRootJoins
+		}));
+		const compiledPrefetchChildren = node.prefetchChildren.map((child) => this.compileHydrationNode(child, {
+			...context,
+			ownerMeta: targetMeta,
+			ownerAlias: this.buildJoinAlias(node.relationPath),
+			collectRootJoins: false
+		}));
+		let joinDescriptor;
+		if (node.loadMode === InternalRelationHydrationLoadMode.JOIN) {
+			joinDescriptor = {
+				alias: this.buildJoinAlias(node.relationPath),
+				columns: Object.fromEntries(Object.keys(targetColumns).map((column) => [column, this.buildHydrationColumnAlias(node.relationPath, column)]))
+			};
+			if (context.collectRootJoins) {
+				context.joinCollection.joins.push(`LEFT JOIN ${validatedRelation.table} ${joinDescriptor.alias} ON ${joinDescriptor.alias}.${validatedRelation.targetKey} = ${context.ownerAlias}.${validatedRelation.sourceKey}`);
+				context.joinCollection.selects.push(...Object.entries(joinDescriptor.columns).map(([column, alias]) => `${joinDescriptor.alias}.${column} AS ${alias}`));
+			}
+		}
+		const ownerSourceAccessor = node.loadMode === InternalRelationHydrationLoadMode.PREFETCH && context.collectRootJoins === false && context.ownerAlias === context.rootTable && context.rootSelectedFields?.length && !context.rootSelectedFields.includes(validatedRelation.sourceKey) ? this.buildPrefetchSourceAlias(node.relationPath, validatedRelation.sourceKey) : validatedRelation.sourceKey;
+		if (node.loadMode === InternalRelationHydrationLoadMode.PREFETCH && ownerSourceAccessor !== validatedRelation.sourceKey) context.hiddenRootAliases.push(ownerSourceAccessor);
+		return {
+			nodeId: node.nodeId,
+			relationName: node.relationName,
+			relationPath: node.relationPath,
+			ownerModelKey: node.ownerModelKey,
+			targetModelKey: node.targetModelKey,
+			loadMode: node.loadMode,
+			cardinality: node.cardinality,
+			sourceKey: validatedRelation.sourceKey,
+			ownerSourceAccessor,
+			targetKey: validatedRelation.targetKey,
+			targetTable: validatedRelation.table,
+			targetPrimaryKey: node.relationEdge.targetPrimaryKey,
+			targetColumns,
+			provenance: node.provenance,
+			joinChildren: compiledJoinChildren,
+			prefetchChildren: compiledPrefetchChildren,
+			join: joinDescriptor
+		};
 	}
-	buildPrefetchSourceAlias(sourceKey) {
-		return this.assertInternalAliasDoesNotCollide(`__tango_prefetch_${sourceKey}`);
+	validateHydrationRelation(ownerMeta, relationName) {
+		return sqlSafetyAdapter.validate({
+			kind: "select",
+			meta: ownerMeta,
+			relationNames: [relationName]
+		}).relations[relationName];
+	}
+	buildRootHiddenSelects(nodes, table) {
+		return nodes.flatMap((node) => {
+			const select = node.ownerSourceAccessor !== node.sourceKey ? [`${table}.${node.sourceKey} AS ${node.ownerSourceAccessor}`] : [];
+			return [...select, ...this.buildRootHiddenSelects(node.prefetchChildren, table)];
+		});
+	}
+	validatePrefetchTarget(node) {
+		try {
+			const validated = sqlSafetyAdapter.validate({
+				kind: "select",
+				meta: {
+					table: node.targetTable,
+					pk: node.targetPrimaryKey,
+					columns: node.targetColumns
+				},
+				filterKeys: [node.targetKey]
+			});
+			return {
+				table: validated.meta.table,
+				primaryKey: validated.meta.pk,
+				targetKey: validated.filterKeys[node.targetKey].field,
+				columns: validated.meta.columns
+			};
+		} catch (error) {
+			const message = isError(error) ? error.message : String(error);
+			throw new Error(`Compiled prefetch query failed validation: ${message}`, { cause: error });
+		}
+	}
+	collectNestedJoinSql(node, ownerAlias, ownerColumns, collection) {
+		if (!node.join) return;
+		const validatedTarget = this.validatePrefetchJoinTarget(node, ownerColumns);
+		const validatedJoinAlias = this.validateInternalAlias(node.join.alias);
+		const validatedJoinColumns = Object.fromEntries(Object.entries(node.join.columns).map(([column, alias]) => {
+			if (!(column in validatedTarget.columns)) throw new Error(`Compiled prefetch query failed validation: unknown nested join column '${column}'.`);
+			return [column, this.validateInternalAlias(alias)];
+		}));
+		collection.joins.push(`LEFT JOIN ${validatedTarget.table} ${validatedJoinAlias} ON ${validatedJoinAlias}.${validatedTarget.targetKey} = ${ownerAlias}.${node.sourceKey}`);
+		collection.selects.push(...Object.entries(validatedJoinColumns).map(([column, alias]) => `${validatedJoinAlias}.${column} AS ${alias}`));
+		for (const child of node.joinChildren) this.collectNestedJoinSql(child, validatedJoinAlias, validatedTarget.columns, collection);
+	}
+	validatePrefetchJoinTarget(node, ownerColumns) {
+		if (!(node.sourceKey in ownerColumns)) throw new Error(`Compiled prefetch query failed validation: unknown owner column '${node.sourceKey}' for nested join.`);
+		return this.validatePrefetchTarget(node);
+	}
+	validateInternalAlias(alias) {
+		if (!/^__tango_[A-Za-z0-9_]+$/.test(alias)) throw new Error(`Compiled prefetch query failed validation: invalid internal alias '${alias}'.`);
+		return alias;
+	}
+	buildJoinAlias(relationPath) {
+		return this.assertInternalAliasDoesNotCollide(`__tango_join_${this.sanitizeRelationPath(relationPath)}`);
+	}
+	buildPrefetchBaseAlias(relationPath) {
+		return this.assertInternalAliasDoesNotCollide(`__tango_prefetch_base_${this.sanitizeRelationPath(relationPath)}`);
+	}
+	buildHydrationColumnAlias(relationPath, column) {
+		return this.assertInternalAliasDoesNotCollide(`__tango_hydrate_${this.sanitizeRelationPath(relationPath)}_${column}`);
+	}
+	buildPrefetchSourceAlias(relationPath, sourceKey) {
+		return this.assertInternalAliasDoesNotCollide(`__tango_prefetch_${this.sanitizeRelationPath(relationPath)}_${sourceKey}`);
+	}
+	sanitizeRelationPath(relationPath) {
+		return relationPath.replace(/[^a-zA-Z0-9]+/g, "_");
 	}
 	assertInternalAliasDoesNotCollide(alias) {
 		if (alias in this.meta.columns) throw new Error(`Internal query alias '${alias}' collides with a field on table '${this.meta.table}'.`);
@@ -497,17 +755,13 @@ var QueryCompiler = class QueryCompiler {
 var compiler_exports = {};
 __export(compiler_exports, { QueryCompiler: () => QueryCompiler });
 
-//#endregion
-//#region src/query/domain/RelationTyping.ts
-const InternalRelationHydrationCardinality = {
-	SINGLE: "single",
-	MANY: "many"
-};
-
 //#endregion
 //#region src/query/domain/index.ts
 var domain_exports = {};
-__export(domain_exports, { InternalRelationHydrationCardinality: () => InternalRelationHydrationCardinality });
+__export(domain_exports, {
+	InternalRelationHydrationCardinality: () => InternalRelationHydrationCardinality,
+	TableMetaFactory: () => TableMetaFactory
+});
 
 //#endregion
 //#region src/query/domain/internal/InternalDirection.ts
@@ -655,12 +909,13 @@ var QuerySet = class QuerySet {
 		});
 	}
 	/**
-	* Hydrate single-valued relations through SQL joins.
+	* Hydrate single-valued relation paths through SQL joins.
 	*
 	* Forward `belongsTo` relations can be inferred from the source model's
 	* field-authored relation metadata. Reverse `hasOne` relations can be
 	* selected with a target model generic when the target model points back to
-	* the source model.
+	* the source model. Generated relation typing also enables nested `__`
+	* path keys for applications that keep the app-local registry current.
 	*/
 	selectRelated(...rels) {
 		return new QuerySet(this.executor, {
@@ -669,10 +924,12 @@ var QuerySet = class QuerySet {
 		});
 	}
 	/**
-	* Hydrate collection relations with a follow-up query.
+	* Hydrate collection-rooted relation paths with follow-up queries.
 	*
 	* Reverse `hasMany` relations can be prefetched with a target model generic
-	* when the target model points back to the source model.
+	* when the target model points back to the source model. Generated relation
+	* typing also enables nested `__` path keys for applications that keep the
+	* app-local registry current.
 	*/
 	prefetchRelated(...rels) {
 		return new QuerySet(this.executor, {
@@ -681,7 +938,6 @@ var QuerySet = class QuerySet {
 		});
 	}
 	async fetch(shape) {
-		this.validateHydrationState();
 		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
 		const compiled = compiler.compile(this.state);
 		const rows = await this.executor.run(compiled);
@@ -703,9 +959,8 @@ var QuerySet = class QuerySet {
 	* Execute a `COUNT(*)` query for the current filtered state.
 	*/
 	async count() {
-		this.validateHydrationState();
 		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
-		const compiled = compiler.compile(this.state);
+		const compiled = compiler.compile(this.withoutHydrationState());
 		const countQuery = `SELECT COUNT(*) as count FROM (${compiled.sql}) AS tango_count_subquery`;
 		const rows = await this.executor.client.query(countQuery, compiled.params);
 		return Number(rows.rows[0]?.count ?? 0);
@@ -723,84 +978,96 @@ var QuerySet = class QuerySet {
 		if (booleanColumns.length === 0) return rows;
 		return rows.map((row) => this.normalizeBooleanColumns(row, booleanColumns));
 	}
-	validateHydrationState() {
-		const seen = new Set();
-		for (const relationName of [...this.state.selectRelated ?? [], ...this.state.prefetchRelated ?? []]) {
-			if (seen.has(relationName)) throw new Error(`Relation '${relationName}' was requested more than once.`);
-			seen.add(relationName);
-			const relation = this.executor.meta.relations?.[relationName];
-			if (!relation) throw new Error(`Unknown relation '${relationName}' for table '${this.executor.meta.table}'.`);
-			if (relation.kind === InternalRelationKind.MANY_TO_MANY) throw new Error(`Relation '${relationName}' is many-to-many and cannot be hydrated yet.`);
-			if (relationName in this.executor.meta.columns && !(relation.kind === InternalRelationKind.BELONGS_TO && relationName === relation.sourceKey)) throw new Error(`Relation '${relationName}' on table '${this.executor.meta.table}' collides with an existing field.`);
-		}
-		for (const relationName of this.state.selectRelated ?? []) {
-			const relation = this.executor.meta.relations[relationName];
-			if (relation.kind !== InternalRelationKind.BELONGS_TO && relation.kind !== InternalRelationKind.HAS_ONE) throw new Error(`Relation '${relationName}' cannot be loaded with selectRelated(...).`);
-		}
-		for (const relationName of this.state.prefetchRelated ?? []) {
-			const relation = this.executor.meta.relations[relationName];
-			if (relation.kind !== InternalRelationKind.HAS_MANY) throw new Error(`Relation '${relationName}' cannot be loaded with prefetchRelated(...).`);
-		}
-	}
 	async hydrateRows(rows, compiled) {
-		const selectedRows = this.hydrateSelectedRows(rows, compiled);
-		return this.hydratePrefetchedRows(selectedRows, compiled);
-	}
-	hydrateSelectedRows(rows, compiled) {
-		const hydrations = compiled.hydrations;
-		if (!hydrations?.length) return rows;
-		return rows.map((row) => {
-			const next = { ...row };
-			for (const hydration of hydrations) {
-				const target = {};
-				let hasTargetValue = false;
-				for (const [column, alias] of Object.entries(hydration.columns)) {
-					const value = next[alias];
-					delete next[alias];
-					target[column] = this.normalizeTargetValue(hydration.relationName, column, value);
-					if (value !== null && value !== undefined) hasTargetValue = true;
-				}
-				next[hydration.relationName] = hasTargetValue ? target : null;
-			}
-			return next;
-		});
+		if (!compiled.hydrationPlan) return rows;
+		const hydratedRows = rows.map((row) => ({ ...row }));
+		const canonicalEntities = new Map();
+		const queuedJoinPrefetchOwners = new Map();
+		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
+		for (const row of hydratedRows) this.hydrateJoinNodesForOwner(row, row, compiled.hydrationPlan.joinNodes, canonicalEntities, queuedJoinPrefetchOwners);
+		for (const node of compiled.hydrationPlan.prefetchNodes) await this.hydratePrefetchNode(node, hydratedRows, canonicalEntities, compiler);
+		for (const [node, owners] of queuedJoinPrefetchOwners.entries()) await this.hydratePrefetchNode(node, [...owners], canonicalEntities, compiler);
+		for (const row of hydratedRows) for (const alias of compiled.hydrationPlan.hiddenRootAliases) delete row[alias];
+		return hydratedRows;
 	}
-	async hydratePrefetchedRows(rows, compiled) {
-		if (!compiled.prefetches?.length || rows.length === 0) return rows;
-		const prefetchGroups = await Promise.all(compiled.prefetches.map(async (prefetch) => {
-			const sourceValues = rows.map((row) => row[prefetch.sourceKeyAlias ?? prefetch.sourceKey]).filter((value) => typeof value === "string" || typeof value === "number");
-			const uniqueSourceValues = [...new Set(sourceValues)];
-			return {
-				prefetch,
-				grouped: await this.fetchPrefetchGroup(prefetch, uniqueSourceValues)
-			};
-		}));
-		const hiddenSourceAliases = new Set(compiled.prefetches.map((prefetch) => prefetch.sourceKeyAlias).filter((alias) => typeof alias === "string"));
-		return rows.map((row) => {
-			const next = { ...row };
-			for (const { prefetch, grouped } of prefetchGroups) {
-				const sourceValue = row[prefetch.sourceKeyAlias ?? prefetch.sourceKey];
-				next[prefetch.relationName] = typeof sourceValue === "string" || typeof sourceValue === "number" ? grouped.get(sourceValue) ?? [] : [];
+	hydrateJoinNodesForOwner(owner, rawRow, nodes, canonicalEntities, queuedJoinPrefetchOwners) {
+		for (const node of nodes) {
+			if (!node.join) continue;
+			const target = {};
+			let hasTargetValue = false;
+			for (const [column, alias] of Object.entries(node.join.columns)) {
+				const value = rawRow[alias];
+				delete rawRow[alias];
+				target[column] = this.normalizeColumnValue(node.targetColumns[column], value);
+				if (value !== null && value !== undefined) hasTargetValue = true;
 			}
-			for (const alias of hiddenSourceAliases) delete next[alias];
-			return next;
-		});
+			if (!hasTargetValue) {
+				owner[node.relationName] = null;
+				continue;
+			}
+			const canonical = this.canonicalizeEntity(node, target, canonicalEntities);
+			owner[node.relationName] = canonical;
+			for (const childNode of node.prefetchChildren) {
+				const queuedOwners = queuedJoinPrefetchOwners?.get(childNode);
+				if (queuedOwners) {
+					queuedOwners.add(canonical);
+					continue;
+				}
+				queuedJoinPrefetchOwners?.set(childNode, new Set([canonical]));
+			}
+			this.hydrateJoinNodesForOwner(canonical, rawRow, node.joinChildren, canonicalEntities, queuedJoinPrefetchOwners);
+		}
 	}
-	async fetchPrefetchGroup(prefetch, sourceValues) {
-		const compiledPrefetch = new QueryCompiler(this.executor.meta, this.executor.dialect).compilePrefetch(prefetch, sourceValues);
-		const grouped = new Map();
-		if (sourceValues.length === 0) return grouped;
+	async hydratePrefetchNode(node, owners, canonicalEntities, compiler) {
+		if (owners.length === 0) return;
+		const groupedOwners = this.groupOwnersByAccessor(owners, node.ownerSourceAccessor);
+		const sourceValues = [...groupedOwners.keys()];
+		for (const owner of owners) owner[node.relationName] = node.cardinality === InternalRelationHydrationCardinality.MANY ? [] : null;
+		if (sourceValues.length === 0) return;
+		const compiledPrefetch = compiler.compilePrefetch(node, sourceValues);
 		const result = await this.executor.client.query(compiledPrefetch.sql, compiledPrefetch.params);
-		for (const row of result.rows) {
-			const normalized = this.normalizeTargetRow(compiledPrefetch, row);
+		const groupedTargets = new Map();
+		const canonicalChildren = new Map();
+		for (const rawResultRow of result.rows) {
+			const normalized = this.normalizeTargetRow(compiledPrefetch, rawResultRow);
+			const canonical = this.canonicalizeEntity(node, normalized, canonicalEntities);
+			this.hydrateJoinNodesForOwner(canonical, normalized, node.joinChildren, canonicalEntities);
 			const key = normalized[compiledPrefetch.targetKey];
 			if (typeof key !== "string" && typeof key !== "number") continue;
+			const bucket = groupedTargets.get(key) ?? [];
+			bucket.push(canonical);
+			groupedTargets.set(key, bucket);
+			const childPrimaryKey = canonical[node.targetPrimaryKey];
+			if (typeof childPrimaryKey === "string" || typeof childPrimaryKey === "number") canonicalChildren.set(childPrimaryKey, canonical);
+		}
+		for (const [sourceValue, grouped] of groupedTargets.entries()) for (const owner of groupedOwners.get(sourceValue) ?? []) owner[node.relationName] = node.cardinality === InternalRelationHydrationCardinality.MANY ? grouped : grouped[0];
+		const childOwners = [...canonicalChildren.values()];
+		for (const childNode of node.prefetchChildren) await this.hydratePrefetchNode(childNode, childOwners, canonicalEntities, compiler);
+	}
+	groupOwnersByAccessor(owners, accessor) {
+		const grouped = new Map();
+		for (const owner of owners) {
+			const key = owner[accessor];
+			if (typeof key !== "string" && typeof key !== "number") continue;
 			const bucket = grouped.get(key) ?? [];
-			bucket.push(normalized);
+			bucket.push(owner);
 			grouped.set(key, bucket);
 		}
 		return grouped;
 	}
+	canonicalizeEntity(node, row, canonicalEntities) {
+		const primaryKeyValue = row[node.targetPrimaryKey];
+		if (typeof primaryKeyValue !== "string" && typeof primaryKeyValue !== "number") return row;
+		const byModel = canonicalEntities.get(node.targetModelKey) ?? new Map();
+		const existing = byModel.get(primaryKeyValue);
+		if (existing) {
+			Object.assign(existing, row);
+			return existing;
+		}
+		byModel.set(primaryKeyValue, row);
+		canonicalEntities.set(node.targetModelKey, byModel);
+		return row;
+	}
 	normalizeTargetRow(prefetch, row) {
 		if (this.executor.dialect !== InternalDialect.SQLITE) return row;
 		let normalized = null;
@@ -813,10 +1080,8 @@ var QuerySet = class QuerySet {
 		}
 		return normalized ?? row;
 	}
-	normalizeTargetValue(relationName, column, value) {
-		if (this.executor.dialect !== InternalDialect.SQLITE) return value;
-		const relation = this.executor.meta.relations[relationName];
-		return this.isBooleanColumnType(relation.targetColumns[column]) ? this.normalizeSqliteBoolean(value) : value;
+	normalizeColumnValue(columnType, value) {
+		return this.executor.dialect === InternalDialect.SQLITE && this.isBooleanColumnType(columnType) ? this.normalizeSqliteBoolean(value) : value;
 	}
 	isBooleanColumnType(value) {
 		return typeof value === "string" && ["bool", "boolean"].includes(value.trim().toLowerCase());
@@ -837,6 +1102,10 @@ var QuerySet = class QuerySet {
 		}
 		return normalized ?? row;
 	}
+	withoutHydrationState() {
+		const { selectRelated: _selectRelated, prefetchRelated: _prefetchRelated,...rest } = this.state;
+		return rest;
+	}
 };
 
 //#endregion
@@ -852,5 +1121,5 @@ __export(query_exports, {
 });
 
 //#endregion
-export { InternalRelationKind, OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QuerySet, compiler_exports, domain_exports, query_exports };
-//# sourceMappingURL=query-CWZ1cfjo.js.map
+export { OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QuerySet, TableMetaFactory, compiler_exports, domain_exports, query_exports };
+//# sourceMappingURL=query-DYiJ5m_B.js.map