@danceroutine/tango-orm 1.6.0 → 1.8.0

package/dist/{query-C6So1r6H.js → query-DUZnBFhf.js}

@@ -1,75 +1,8 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { SqlSafetyEngine, getLogger, isError } from "@danceroutine/tango-core";
+import { InternalDialect } from "./InternalDialect-ClSaUNso.js";
+import { MultipleObjectsReturned, NotFoundError, SqlSafetyEngine, getLogger, isError } from "@danceroutine/tango-core";
 import { ModelRegistry } from "@danceroutine/tango-schema";
 
-//#region src/query/domain/internal/InternalRelationKind.ts
-const InternalRelationKind = {
-	HAS_MANY: "hasMany",
-	BELONGS_TO: "belongsTo",
-	HAS_ONE: "hasOne",
-	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",
@@ -77,10 +10,10 @@ const InternalRelationHydrationLoadMode = {
 };
 
 //#endregion
-//#region src/query/domain/internal/InternalDialect.ts
-const InternalDialect = {
-	POSTGRES: "postgres",
-	SQLITE: "sqlite"
+//#region src/query/domain/internal/InternalPrefetchQueryKind.ts
+const InternalPrefetchQueryKind = {
+	DIRECT: "direct",
+	MANY_TO_MANY: "manyToMany"
 };
 
 //#endregion
@@ -110,6 +43,22 @@ const InternalLookupType = {
 	IENDSWITH: "iendswith"
 };
 
+//#endregion
+//#region src/validation/internal/InternalSqlValidationPlanKind.ts
+const InternalSqlValidationPlanKind = {
+	SELECT: "select",
+	INSERT: "insert",
+	UPDATE: "update",
+	DELETE: "delete"
+};
+
+//#endregion
+//#region src/validation/internal/InternalValidatedFilterDescriptorKind.ts
+const InternalValidatedFilterDescriptorKind = {
+	COLUMN: "column",
+	RELATION: "relation"
+};
+
 //#endregion
 //#region src/validation/OrmSqlSafetyAdapter.ts
 const ALLOWED_LOOKUPS = Object.values(InternalLookupType);
@@ -121,35 +70,35 @@ var OrmSqlSafetyAdapter = class OrmSqlSafetyAdapter {
 	}
 	validate(plan) {
 		switch (plan.kind) {
-			case "select": {
+			case InternalSqlValidationPlanKind.SELECT: {
 				const meta = this.validateTableMeta(plan.meta, plan.relationNames ?? []);
 				return {
-					kind: "select",
+					kind: InternalSqlValidationPlanKind.SELECT,
 					meta,
 					selectFields: Object.fromEntries((plan.selectFields ?? []).map((field) => [field, `${meta.table}.${this.resolveColumn(meta, field)}`])),
-					filterKeys: Object.fromEntries((plan.filterKeys ?? []).map((rawKey) => [rawKey, this.validateFilterKey(meta, rawKey)])),
+					filterKeys: Object.fromEntries((plan.filterKeys ?? []).map((rawKey) => [rawKey, this.validateFilterKey(meta, plan.meta, rawKey)])),
 					orderFields: Object.fromEntries((plan.orderFields ?? []).map((field) => [field, `${meta.table}.${this.resolveColumn(meta, field)}`])),
 					relations: Object.fromEntries((plan.relationNames ?? []).map((relationName) => [relationName, this.resolveRelation(meta, relationName)]))
 				};
 			}
-			case "insert": {
+			case InternalSqlValidationPlanKind.INSERT: {
 				const meta = this.validateTableMeta(plan.meta);
 				return {
-					kind: "insert",
+					kind: InternalSqlValidationPlanKind.INSERT,
 					meta,
 					writeKeys: plan.writeKeys.map((key) => this.resolveColumn(meta, key))
 				};
 			}
-			case "update": {
+			case InternalSqlValidationPlanKind.UPDATE: {
 				const meta = this.validateTableMeta(plan.meta);
 				return {
-					kind: "update",
+					kind: InternalSqlValidationPlanKind.UPDATE,
 					meta,
 					writeKeys: plan.writeKeys.map((key) => this.resolveColumn(meta, key))
 				};
 			}
-			case "delete": return {
-				kind: "delete",
+			case InternalSqlValidationPlanKind.DELETE: return {
+				kind: InternalSqlValidationPlanKind.DELETE,
 				meta: this.validateTableMeta(plan.meta)
 			};
 		}
@@ -203,6 +152,26 @@ var OrmSqlSafetyAdapter = class OrmSqlSafetyAdapter {
 				role: "relationTargetPrimaryKey",
 				value: relation.targetKey
 			},
+			{
+				key: "targetPrimaryKey",
+				role: "relationTargetPrimaryKey",
+				value: relation.targetPrimaryKey
+			},
+			...relation.throughTable ? [{
+				key: "throughTable",
+				role: "table",
+				value: relation.throughTable
+			}] : [],
+			...relation.throughSourceKey ? [{
+				key: "throughSourceKey",
+				role: "column",
+				value: relation.throughSourceKey
+			}] : [],
+			...relation.throughTargetKey ? [{
+				key: "throughTargetKey",
+				role: "column",
+				value: relation.throughTargetKey
+			}] : [],
 			...Object.keys(relation.targetColumns).map((column) => ({
 				key: `targetColumn:${column}`,
 				role: "column",
@@ -215,24 +184,62 @@ var OrmSqlSafetyAdapter = class OrmSqlSafetyAdapter {
 			alias: validated.identifiers.alias.value,
 			sourceKey: this.resolveColumn(meta, relation.sourceKey),
 			targetKey: validated.identifiers.targetKey.value,
-			targetColumns: Object.fromEntries(Object.keys(relation.targetColumns).map((column) => [validated.identifiers[`targetColumn:${column}`].value, relation.targetColumns[column]]))
+			targetPrimaryKey: validated.identifiers.targetPrimaryKey.value,
+			targetColumns: Object.fromEntries(Object.keys(relation.targetColumns).map((column) => [validated.identifiers[`targetColumn:${column}`].value, relation.targetColumns[column]])),
+			throughTable: validated.identifiers.throughTable?.value,
+			throughSourceKey: validated.identifiers.throughSourceKey?.value,
+			throughTargetKey: validated.identifiers.throughTargetKey?.value
 		};
 	}
-	validateFilterKey(meta, rawKey) {
+	validateFilterKey(meta, rawMeta, rawKey) {
 		const segments = rawKey.split("__");
-		if (segments.length > 2) throw new Error(`Invalid SQL lookup key: '${rawKey}'.`);
-		const field = segments[0];
-		const lookup = segments[1] ?? InternalLookupType.EXACT;
+		if (segments.length === 0 || segments.some((segment) => segment.length === 0)) throw new Error(`Invalid SQL lookup key: '${rawKey}'.`);
+		const lookupToken = segments.at(-1);
+		const hasExplicitLookup = ALLOWED_LOOKUPS.includes(lookupToken);
+		const lookup = hasExplicitLookup ? lookupToken : InternalLookupType.EXACT;
+		const pathSegments = hasExplicitLookup ? segments.slice(0, -1) : segments;
+		if (pathSegments.length === 0) throw new Error(`Invalid SQL lookup key: '${rawKey}'.`);
 		const validated = this.engine.validate({ lookupTokens: [{
 			key: rawKey,
 			lookup,
 			allowed: ALLOWED_LOOKUPS
 		}] });
+		if (pathSegments.length === 1) {
+			const field$1 = pathSegments[0];
+			return {
+				kind: InternalValidatedFilterDescriptorKind.COLUMN,
+				rawKey,
+				field: field$1,
+				lookup: validated.lookupTokens[rawKey].lookup,
+				qualifiedColumn: `${meta.table}.${this.resolveColumn(meta, field$1)}`
+			};
+		}
+		const rootSegment = pathSegments[0];
+		const hasRootColumn = rootSegment in rawMeta.columns;
+		const hasRootRelation = rootSegment in (rawMeta.relations ?? {});
+		if (!hasExplicitLookup && hasRootColumn && !hasRootRelation) throw new Error(`Invalid SQL lookup key: '${rawKey}'.`);
+		const field = pathSegments.at(-1);
+		const relationSegments = pathSegments.slice(0, -1);
+		const relationChain = [];
+		let currentValidatedMeta = meta;
+		let currentRawMeta = rawMeta;
+		for (const relationName of relationSegments) {
+			const relation = currentRawMeta.relations?.[relationName];
+			if (!relation) throw new Error(`Unknown relation '${relationName}' for table '${currentValidatedMeta.table}'.`);
+			if (!relation.targetMeta) throw new Error(`Relation '${relationName}' for table '${currentValidatedMeta.table}' is missing target metadata.`);
+			const validatedRelation = this.validateRelationMeta(currentValidatedMeta, relationName, currentRawMeta.relations);
+			relationChain.push(validatedRelation);
+			currentRawMeta = relation.targetMeta;
+			currentValidatedMeta = this.validateTableMeta(currentRawMeta);
+		}
 		return {
+			kind: InternalValidatedFilterDescriptorKind.RELATION,
 			rawKey,
 			field,
 			lookup: validated.lookupTokens[rawKey].lookup,
-			qualifiedColumn: `${meta.table}.${this.resolveColumn(meta, field)}`
+			relationPath: relationSegments.join("__"),
+			relationChain,
+			terminalColumn: this.resolveColumn(currentValidatedMeta, field)
 		};
 	}
 	resolveColumn(meta, field) {
@@ -287,18 +294,15 @@ var QueryPlanner = class QueryPlanner {
 		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.`);
@@ -317,7 +321,6 @@ var QueryPlanner = class QueryPlanner {
 			currentChildren = nextNode.children;
 			currentMeta = targetMeta;
 		}
-		if (mode === "prefetch" && !containsCollection) throw new Error(`Relation path '${relationPath}' cannot be loaded with prefetchRelated(...).`);
 	}
 	buildPlannedChildren(children) {
 		const joinNodes = [];
@@ -353,9 +356,11 @@ const sqlSafetyAdapter = new OrmSqlSafetyAdapter();
 var QueryCompiler = class QueryCompiler {
 	static BRAND = "tango.orm.query_compiler";
 	__tangoBrand = QueryCompiler.BRAND;
-	constructor(meta, dialect = InternalDialect.POSTGRES) {
+	placeholders;
+	constructor(meta, adapter) {
 		this.meta = meta;
-		this.dialect = dialect;
+		this.adapter = adapter;
+		this.placeholders = adapter.placeholders;
 	}
 	static isQueryCompiler(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === QueryCompiler.BRAND;
@@ -363,7 +368,7 @@ var QueryCompiler = class QueryCompiler {
 	compile(state) {
 		const hydrationPlan = new QueryPlanner(this.meta).plan(state);
 		const validatedPlan = sqlSafetyAdapter.validate({
-			kind: "select",
+			kind: InternalSqlValidationPlanKind.SELECT,
 			meta: this.meta,
 			selectFields: state.select?.map(String),
 			filterKeys: this.collectStateFilterKeys(state),
@@ -437,7 +442,8 @@ var QueryCompiler = class QueryCompiler {
 		};
 	}
 	compilePrefetch(node, sourceValues) {
-		const placeholders = this.dialect === InternalDialect.POSTGRES ? sourceValues.map((_, index) => `$${index + 1}`).join(", ") : sourceValues.map(() => "?").join(", ");
+		if (node.throughTable && node.throughSourceKey && node.throughTargetKey) return this.compileManyToManyPrefetch(node, sourceValues);
+		const placeholders = this.placeholders.list(sourceValues.length);
 		const validatedTarget = this.validatePrefetchTarget(node);
 		const baseAlias = this.buildPrefetchBaseAlias(node.relationPath);
 		const joinCollection = {
@@ -447,12 +453,58 @@ var QueryCompiler = class QueryCompiler {
 		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 {
+			kind: InternalPrefetchQueryKind.DIRECT,
 			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: validatedTarget.targetKey,
 			targetColumns: validatedTarget.columns
 		};
 	}
+	compileManyToManyTargets(node, targetIds) {
+		const placeholders = this.placeholders.list(targetIds.length);
+		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 ${[...baseSelects, ...joinCollection.selects].join(", ")} FROM ${validatedTarget.table} ${baseAlias}${joinCollection.joins.length ? ` ${joinCollection.joins.join(" ")}` : ""} WHERE ${baseAlias}.${validatedTarget.primaryKey} IN (${placeholders}) ORDER BY ${baseAlias}.${validatedTarget.primaryKey} ASC`,
+			params: targetIds
+		};
+	}
+	compileManyToManyPrefetch(node, sourceValues) {
+		const placeholders = this.placeholders.list(sourceValues.length);
+		const throughValidated = sqlSafetyAdapter.validate({
+			kind: InternalSqlValidationPlanKind.SELECT,
+			meta: {
+				table: node.throughTable,
+				pk: node.throughSourceKey,
+				columns: {
+					[node.throughSourceKey]: node.throughSourceColumnType ?? "int",
+					[node.throughTargetKey]: node.throughTargetColumnType ?? "int"
+				}
+			},
+			filterKeys: [node.throughSourceKey, node.throughTargetKey],
+			relationNames: []
+		});
+		const ownerAlias = this.validateInternalAlias("__tango_m2m_owner");
+		const targetAlias = this.validateInternalAlias("__tango_m2m_target");
+		const throughSourceColumn = throughValidated.filterKeys[node.throughSourceKey].field;
+		const throughTargetColumn = throughValidated.filterKeys[node.throughTargetKey].field;
+		return {
+			kind: InternalPrefetchQueryKind.MANY_TO_MANY,
+			throughSql: `SELECT ${throughValidated.meta.table}.${throughSourceColumn} AS ${ownerAlias}, ${throughValidated.meta.table}.${throughTargetColumn} AS ${targetAlias} FROM ${throughValidated.meta.table} WHERE ${throughValidated.meta.table}.${throughSourceColumn} IN (${placeholders}) ORDER BY ${throughValidated.meta.table}.${throughSourceColumn} ASC, ${throughValidated.meta.table}.${throughTargetColumn} ASC`,
+			throughParams: sourceValues,
+			ownerAlias,
+			targetAlias,
+			targetTable: node.targetTable,
+			targetPrimaryKey: node.targetPrimaryKey,
+			targetColumns: node.targetColumns
+		};
+	}
 	compileHydrationNode(node, context) {
 		const validatedRelation = this.validateHydrationRelation(context.ownerMeta, node.relationName);
 		const targetColumns = validatedRelation.targetColumns;
@@ -496,6 +548,11 @@ var QueryCompiler = class QueryCompiler {
 			targetKey: validatedRelation.targetKey,
 			targetTable: validatedRelation.table,
 			targetPrimaryKey: node.relationEdge.targetPrimaryKey,
+			throughTable: node.relationEdge.throughTable,
+			throughSourceKey: node.relationEdge.throughSourceKey,
+			throughTargetKey: node.relationEdge.throughTargetKey,
+			throughSourceColumnType: node.relationEdge.throughSourceColumnType,
+			throughTargetColumnType: node.relationEdge.throughTargetColumnType,
 			targetColumns,
 			provenance: node.provenance,
 			joinChildren: compiledJoinChildren,
@@ -505,7 +562,7 @@ var QueryCompiler = class QueryCompiler {
 	}
 	validateHydrationRelation(ownerMeta, relationName) {
 		return sqlSafetyAdapter.validate({
-			kind: "select",
+			kind: InternalSqlValidationPlanKind.SELECT,
 			meta: ownerMeta,
 			relationNames: [relationName]
 		}).relations[relationName];
@@ -519,7 +576,7 @@ var QueryCompiler = class QueryCompiler {
 	validatePrefetchTarget(node) {
 		try {
 			const validated = sqlSafetyAdapter.validate({
-				kind: "select",
+				kind: InternalSqlValidationPlanKind.SELECT,
 				meta: {
 					table: node.targetTable,
 					pk: node.targetPrimaryKey,
@@ -570,6 +627,9 @@ var QueryCompiler = class QueryCompiler {
 	buildPrefetchSourceAlias(relationPath, sourceKey) {
 		return this.assertInternalAliasDoesNotCollide(`__tango_prefetch_${this.sanitizeRelationPath(relationPath)}_${sourceKey}`);
 	}
+	buildFilterAlias(relationPath, suffix) {
+		return this.assertInternalAliasDoesNotCollide(`__tango_filter_${this.sanitizeRelationPath(relationPath)}_${suffix}`);
+	}
 	sanitizeRelationPath(relationPath) {
 		return relationPath.replace(/[^a-zA-Z0-9]+/g, "_");
 	}
@@ -594,7 +654,7 @@ var QueryCompiler = class QueryCompiler {
 		const { parts, params } = entries.reduce((accumulator, [key, value]) => {
 			const descriptor = filterKeys[String(key)];
 			const idx = paramIndex + accumulator.params.length;
-			const clause = this.lookupToSQL(descriptor.qualifiedColumn, descriptor.lookup, value, idx);
+			const clause = descriptor.kind === InternalValidatedFilterDescriptorKind.COLUMN ? this.lookupToSQL(descriptor.qualifiedColumn, descriptor.lookup, value, idx) : this.compileRelationFilter(descriptor, value, idx);
 			accumulator.parts.push(clause.sql);
 			accumulator.params.push(...clause.params);
 			return accumulator;
@@ -652,8 +712,28 @@ var QueryCompiler = class QueryCompiler {
 			params: result.params
 		};
 	}
+	compileRelationFilter(descriptor, value, paramIndex) {
+		return this.buildRelationFilterExists(this.meta.table, descriptor.relationChain, descriptor.terminalColumn, descriptor.lookup, value, paramIndex, descriptor.relationPath);
+	}
+	buildRelationFilterExists(ownerAlias, relationChain, terminalColumn, lookup, value, paramIndex, relationPath) {
+		const [relation, ...rest] = relationChain;
+		if (!relation) throw new Error(`Cannot compile empty relation filter path '${relationPath}'.`);
+		const targetAlias = this.buildFilterAlias(relationPath, `target_${relation.alias}_${rest.length}`);
+		const targetPredicate = rest.length === 0 ? this.lookupToSQL(`${targetAlias}.${terminalColumn}`, lookup, value, paramIndex) : this.buildRelationFilterExists(targetAlias, rest, terminalColumn, lookup, value, paramIndex, relationPath);
+		if (relation.throughTable && relation.throughSourceKey && relation.throughTargetKey) {
+			const throughAlias = this.buildFilterAlias(relationPath, `through_${relation.alias}_${rest.length}`);
+			return {
+				sql: `EXISTS (SELECT 1 FROM ${relation.throughTable} ${throughAlias} INNER JOIN ${relation.table} ${targetAlias} ON ${targetAlias}.${relation.targetKey} = ${throughAlias}.${relation.throughTargetKey} WHERE ${throughAlias}.${relation.throughSourceKey} = ${ownerAlias}.${relation.sourceKey} AND ${targetPredicate.sql})`,
+				params: targetPredicate.params
+			};
+		}
+		return {
+			sql: `EXISTS (SELECT 1 FROM ${relation.table} ${targetAlias} WHERE ${targetAlias}.${relation.targetKey} = ${ownerAlias}.${relation.sourceKey} AND ${targetPredicate.sql})`,
+			params: targetPredicate.params
+		};
+	}
 	lookupToSQL(col, lookup, value, paramIndex) {
-		const placeholder = this.dialect === InternalDialect.POSTGRES ? `$${paramIndex}` : "?";
+		const placeholder = this.placeholders.at(paramIndex);
 		const normalized = this.normalizeParam(value);
 		switch (lookup) {
 			case InternalLookupType.EXACT:
@@ -687,7 +767,7 @@ var QueryCompiler = class QueryCompiler {
 					sql: "1=0",
 					params: []
 				};
-				const placeholders = this.dialect === InternalDialect.POSTGRES ? entries.map((_, index) => `$${paramIndex + index}`).join(", ") : entries.map(() => "?").join(", ");
+				const placeholders = this.placeholders.listFromOffset(entries.length, paramIndex - 1);
 				return {
 					sql: `${col} IN (${placeholders})`,
 					params: entries
@@ -702,7 +782,7 @@ var QueryCompiler = class QueryCompiler {
 				params: [`%${value}%`]
 			};
 			case InternalLookupType.ICONTAINS: {
-				const lowerCol = this.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
+				const lowerCol = this.adapter.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
 				return {
 					sql: `${lowerCol} LIKE ${placeholder}`,
 					params: [`%${String(value).toLowerCase()}%`]
@@ -713,7 +793,7 @@ var QueryCompiler = class QueryCompiler {
 				params: [`${value}%`]
 			};
 			case InternalLookupType.ISTARTSWITH: {
-				const lowerCol = this.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
+				const lowerCol = this.adapter.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
 				return {
 					sql: `${lowerCol} LIKE ${placeholder}`,
 					params: [`${String(value).toLowerCase()}%`]
@@ -724,7 +804,7 @@ var QueryCompiler = class QueryCompiler {
 				params: [`%${value}`]
 			};
 			case InternalLookupType.IENDSWITH: {
-				const lowerCol = this.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
+				const lowerCol = this.adapter.dialect === InternalDialect.POSTGRES ? `LOWER(${col})` : `${col}`;
 				return {
 					sql: `${lowerCol} LIKE ${placeholder}`,
 					params: [`%${String(value).toLowerCase()}`]
@@ -734,7 +814,7 @@ var QueryCompiler = class QueryCompiler {
 		}
 	}
 	normalizeParam(value) {
-		if (this.dialect === InternalDialect.SQLITE && typeof value === "boolean") return value ? 1 : 0;
+		if (this.adapter.dialect === InternalDialect.SQLITE && typeof value === "boolean") return value ? 1 : 0;
 		return value;
 	}
 	collectStateFilterKeys(state) {
@@ -805,6 +885,87 @@ var QueryResult = class QueryResult {
 	}
 };
 
+//#endregion
+//#region src/query/domain/internal/InternalRelationKind.ts
+const InternalRelationKind = {
+	HAS_MANY: "hasMany",
+	BELONGS_TO: "belongsTo",
+	HAS_ONE: "hasOne",
+	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 targetColumns = Object.fromEntries(targetModel.metadata.fields.map((field) => [field.name, field.type]));
+			let throughSourceColumnType;
+			let throughTargetColumnType;
+			if (relation.kind === InternalRelationKind.MANY_TO_MANY && relation.throughModelKey && relation.throughSourceKey && relation.throughTargetKey) {
+				const throughModel = owner.getByKey(relation.throughModelKey);
+				throughSourceColumnType = throughModel?.metadata.fields.find((field) => field.name === relation.throughSourceKey)?.type;
+				throughTargetColumnType = throughModel?.metadata.fields.find((field) => field.name === relation.throughTargetKey)?.type;
+			}
+			const capabilities = {
+				queryable,
+				hydratable,
+				joinable: isSingleRelation && queryable && hydratable,
+				prefetchable: queryable && hydratable
+			};
+			const sourceKey = relation.kind === InternalRelationKind.MANY_TO_MANY ? tableMeta.pk : relation.kind === InternalRelationKind.BELONGS_TO ? relation.localFieldName : relation.targetFieldName;
+			const targetKey = relation.kind === InternalRelationKind.MANY_TO_MANY ? targetMeta.pk : relation.kind === InternalRelationKind.BELONGS_TO ? relation.targetFieldName : relation.localFieldName;
+			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,
+				throughTable: relation.throughTable,
+				throughModelKey: relation.throughModelKey,
+				throughSourceKey: relation.throughSourceKey,
+				throughTargetKey: relation.throughTargetKey,
+				throughSourceColumnType,
+				throughTargetColumnType,
+				targetPrimaryKey: targetMeta.pk,
+				targetColumns,
+				alias: relation.alias,
+				targetMeta
+			}];
+		}));
+		return tableMeta;
+	}
+};
+
 //#endregion
 //#region src/query/domain/index.ts
 var domain_exports = {};
@@ -821,6 +982,19 @@ const InternalDirection = {
 	DESC: "desc"
 };
 
+//#endregion
+//#region src/query/internal/isQNodeLike.ts
+function isQNodeLike(value) {
+	if (typeof value !== "object" || value === null || "__tangoBrand" in value) return false;
+	switch (value.kind) {
+		case InternalQNodeType.ATOM: return "where" in value;
+		case InternalQNodeType.AND:
+		case InternalQNodeType.OR: return Array.isArray(value.nodes);
+		case InternalQNodeType.NOT: return "node" in value;
+		default: return false;
+	}
+}
+
 //#endregion
 //#region src/query/QBuilder.ts
 var QBuilder = class QBuilder {
@@ -860,7 +1034,7 @@ var QBuilder = class QBuilder {
 		};
 	}
 	static wrapNode(input) {
-		if (input.kind) return input;
+		if (isQNodeLike(input)) return input;
 		return {
 			kind: InternalQNodeType.ATOM,
 			where: input
@@ -885,17 +1059,45 @@ var QuerySet = class QuerySet {
 		return typeof value === "object" && value !== null && value.__tangoBrand === QuerySet.BRAND;
 	}
 	/**
+	* Translate user-facing order tokens like `'name'` or `'-createdAt'` into
+	* the internal `OrderSpec` array used by `QuerySetState`.
+	*
+	* Exposed as `protected` so subclasses can compose the same parse logic
+	* when they need to return their own concrete type from `orderBy` without
+	* reaching into a base-class instance's protected state.
+	*/
+	static buildOrderSpecs(tokens) {
+		return tokens.map((t) => {
+			const str = String(t);
+			if (str.startsWith("-")) return {
+				by: str.slice(1),
+				dir: InternalDirection.DESC
+			};
+			return {
+				by: t,
+				dir: InternalDirection.ASC
+			};
+		});
+	}
+	static invertOrderSpec(order) {
+		if (!order?.length) return [];
+		return order.map((spec) => ({
+			by: spec.by,
+			dir: spec.dir === InternalDirection.ASC ? InternalDirection.DESC : InternalDirection.ASC
+		}));
+	}
+	/**
 	* Add a filter expression to the query.
 	*
 	* Multiple `filter()` calls are composed with `AND`.
 	*/
 	filter(q) {
-		const wrapped = q.kind ? q : {
+		const wrapped = isQNodeLike(q) ? q : {
 			kind: InternalQNodeType.ATOM,
 			where: q
 		};
 		const merged = this.state.q ? QBuilder.and(this.state.q, wrapped) : wrapped;
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			q: merged
 		});
@@ -906,12 +1108,12 @@ var QuerySet = class QuerySet {
 	* Exclusions are translated to `NOT (...)` predicates.
 	*/
 	exclude(q) {
-		const wrapped = q.kind ? q : {
+		const wrapped = isQNodeLike(q) ? q : {
 			kind: InternalQNodeType.ATOM,
 			where: q
 		};
 		const excludes = [...this.state.excludes ?? [], wrapped];
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			excludes
 		});
@@ -920,27 +1122,16 @@ var QuerySet = class QuerySet {
 	* Apply ordering tokens such as `'name'` or `'-createdAt'`.
 	*/
 	orderBy(...tokens) {
-		const order = tokens.map((t) => {
-			const str = String(t);
-			if (str.startsWith("-")) return {
-				by: str.slice(1),
-				dir: InternalDirection.DESC
-			};
-			return {
-				by: t,
-				dir: InternalDirection.ASC
-			};
-		});
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
-			order
+			order: QuerySet.buildOrderSpecs(tokens)
 		});
 	}
 	/**
 	* Limit the maximum number of rows returned.
 	*/
 	limit(n) {
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			limit: n
 		});
@@ -949,13 +1140,13 @@ var QuerySet = class QuerySet {
 	* Skip the first `n` rows.
 	*/
 	offset(n) {
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			offset: n
 		});
 	}
 	select(fields) {
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			select: [...fields]
 		});
@@ -970,7 +1161,7 @@ var QuerySet = class QuerySet {
 	* path keys for applications that keep the app-local registry current.
 	*/
 	selectRelated(...rels) {
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			selectRelated: [...rels]
 		});
@@ -984,11 +1175,14 @@ var QuerySet = class QuerySet {
 	* app-local registry current.
 	*/
 	prefetchRelated(...rels) {
-		return new QuerySet(this.executor, {
+		return this.spawn({
 			...this.state,
 			prefetchRelated: [...rels]
 		});
 	}
+	all() {
+		return this.spawn({ ...this.state });
+	}
 	async fetch(shape) {
 		const baseResult = await this.getOrCreateEvaluationCache();
 		if (!shape) return baseResult;
@@ -998,9 +1192,10 @@ var QuerySet = class QuerySet {
 	/**
 	* Async iterable surface for `for await (... of queryset)`.
 	*
-	* Evaluates this queryset on first use by awaiting {@link QuerySet.fetch} without arguments, then
-	* yields each element from that {@link QueryResult}. Later async iterations over the same queryset
-	* instance reuse the cached materialized result instead of issuing another database round-trip.
+	* Evaluates this queryset on first use by awaiting `fetch()` without
+	* arguments, then yields each element from that materialized result.
+	* Later async iterations over the same queryset instance reuse the cached
+	* materialized result instead of issuing another database round-trip.
 	*/
 	async *[Symbol.asyncIterator]() {
 		const result = await this.fetch();
@@ -1012,11 +1207,40 @@ var QuerySet = class QuerySet {
 		for (const row of result) return row;
 		return null;
 	}
+	async first(shape) {
+		return this.fetchOne(shape);
+	}
+	async last(shape) {
+		if (this.state.limit !== undefined || this.state.offset !== undefined) {
+			const page = await this.fetch();
+			const row = page.at(-1);
+			if (!row) return null;
+			return this.shapeFetchedRow(row, shape);
+		}
+		const invertedOrder = QuerySet.invertOrderSpec(this.state.order);
+		const effectiveOrder = invertedOrder.length > 0 ? invertedOrder : [{
+			by: this.executor.meta.pk,
+			dir: InternalDirection.DESC
+		}];
+		const qs = this.spawn({
+			...this.state,
+			order: effectiveOrder
+		});
+		return qs.limit(1).fetchOne(shape);
+	}
+	async get(q, shape) {
+		const limited = this.filter(q).limit(2);
+		const page = await limited.fetch();
+		const rows = page.items;
+		if (rows.length === 0) throw new NotFoundError(`${this.executor.meta.table}: no matching record`);
+		if (rows.length > 1) throw new MultipleObjectsReturned(`${this.executor.meta.table}: more than one matching record`);
+		return this.shapeFetchedRow(rows[0], shape);
+	}
 	/**
 	* Execute a `COUNT(*)` query for the current filtered state.
 	*/
 	async count() {
-		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
+		const compiler = new QueryCompiler(this.executor.meta, this.executor.adapter);
 		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);
@@ -1029,6 +1253,12 @@ var QuerySet = class QuerySet {
 		const count = await this.count();
 		return count > 0;
 	}
+	shapeFetchedRow(row, shape) {
+		if (!shape) return row;
+		if (typeof shape === "function") return shape(row);
+		const normalizedRow = this.normalizeHydratedRowsForParserShape([row])[0] ?? row;
+		return shape.parse(normalizedRow);
+	}
 	getOrCreateEvaluationCache() {
 		if (!this.evaluationCache) this.evaluationCache = this.evaluateRows().catch((error) => {
 			this.evaluationCache = undefined;
@@ -1037,15 +1267,23 @@ var QuerySet = class QuerySet {
 		return this.evaluationCache;
 	}
 	async evaluateRows() {
-		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
+		const compiler = new QueryCompiler(this.executor.meta, this.executor.adapter);
 		const compiled = compiler.compile(this.state);
 		const rows = await this.executor.run(compiled);
-		const hydratedRows = await this.hydrateRows(rows, compiled);
+		const normalizedRows = this.normalizeRowsForSchemaParsing(rows);
+		const hydratedRows = await this.hydrateRows(normalizedRows, compiled);
+		this.attachRootRecordAccessors(hydratedRows);
 		const projectedRows = hydratedRows;
 		return new QueryResult(projectedRows);
 	}
+	normalizeRowsForSchemaParsing(rows) {
+		if (this.executor.adapter.dialect !== InternalDialect.SQLITE) return [...rows];
+		const booleanColumns = Object.entries(this.executor.meta.columns).filter(([, value]) => this.isBooleanColumnType(value)).map(([column]) => column);
+		if (booleanColumns.length === 0) return [...rows];
+		return rows.map((row) => this.normalizeBooleanColumns(row, booleanColumns));
+	}
 	normalizeHydratedRowsForParserShape(rows) {
-		if (this.executor.dialect !== InternalDialect.SQLITE) return [...rows];
+		if (this.executor.adapter.dialect !== InternalDialect.SQLITE) return [...rows];
 		const booleanColumns = Object.entries(this.executor.meta.columns).filter(([, value]) => this.isBooleanColumnType(value)).map(([column]) => column);
 		if (booleanColumns.length === 0) return [...rows];
 		return rows.map((row) => this.normalizeBooleanColumns(row, booleanColumns));
@@ -1053,15 +1291,29 @@ var QuerySet = class QuerySet {
 	async hydrateRows(rows, compiled) {
 		if (!compiled.hydrationPlan) return rows;
 		const hydratedRows = rows.map((row) => ({ ...row }));
+		this.attachRootRecordAccessors(hydratedRows);
 		const canonicalEntities = new Map();
 		const queuedJoinPrefetchOwners = new Map();
-		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
+		const compiler = new QueryCompiler(this.executor.meta, this.executor.adapter);
 		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;
 	}
+	primeManyToManyOwnerCache(owner, relationName, bucket) {
+		const existing = owner[relationName];
+		if (existing && typeof existing.primePrefetchCache === "function") {
+			existing.primePrefetchCache(bucket);
+			return;
+		}
+		owner[relationName] = bucket.slice();
+	}
+	attachRootRecordAccessors(rows) {
+		if (!this.executor.attachPersistedRecordAccessors) return;
+		const sourceModelKey = this.executor.meta.modelKey;
+		for (const row of rows) this.executor.attachPersistedRecordAccessors(row, sourceModelKey);
+	}
 	hydrateJoinNodesForOwner(owner, rawRow, nodes, canonicalEntities, queuedJoinPrefetchOwners) {
 		for (const node of nodes) {
 			if (!node.join) continue;
@@ -1094,28 +1346,81 @@ var QuerySet = class QuerySet {
 		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;
+		const isManyToMany = !!node.throughTable;
+		if (!isManyToMany) 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);
-		const groupedTargets = new Map();
+		const sourceChunks = this.chunkValues(sourceValues, 500);
+		const compiledPrefetch = compiler.compilePrefetch(node, sourceChunks[0]);
+		if (compiledPrefetch.kind === InternalPrefetchQueryKind.MANY_TO_MANY) {
+			const idsByOwner = new Map();
+			const uniqueTargetIds = new Set();
+			for (const chunk of sourceChunks) {
+				const chunkCompiled = compiler.compilePrefetch(node, chunk);
+				const throughResult = await this.executor.client.query(chunkCompiled.throughSql, chunkCompiled.throughParams);
+				for (const row of throughResult.rows) {
+					const ownerId = row[chunkCompiled.ownerAlias];
+					const targetId = row[chunkCompiled.targetAlias];
+					if (typeof ownerId !== "string" && typeof ownerId !== "number" || typeof targetId !== "string" && typeof targetId !== "number") continue;
+					const bucket = idsByOwner.get(ownerId) ?? [];
+					bucket.push(targetId);
+					idsByOwner.set(ownerId, bucket);
+					uniqueTargetIds.add(targetId);
+				}
+			}
+			const targets = {};
+			const targetIds = [...uniqueTargetIds.values()];
+			if (targetIds.length > 0) for (const targetChunk of this.chunkValues(targetIds, 500)) {
+				const targetQuery = compiler.compileManyToManyTargets(node, targetChunk);
+				const targetResult = await this.executor.client.query(targetQuery.sql, targetQuery.params);
+				for (const rawTargetRow of targetResult.rows) {
+					const normalized = this.normalizeTargetRow({ targetColumns: compiledPrefetch.targetColumns }, rawTargetRow);
+					const canonical = this.canonicalizeEntity(node, normalized, canonicalEntities);
+					this.hydrateJoinNodesForOwner(canonical, normalized, node.joinChildren, canonicalEntities);
+					const primaryKey = canonical[node.targetPrimaryKey];
+					if (typeof primaryKey === "string" || typeof primaryKey === "number") targets[primaryKey] = canonical;
+				}
+			}
+			const canonicalChildren$1 = new Map();
+			const handledOwners = new Set();
+			for (const [ownerId, ids] of idsByOwner.entries()) {
+				const bucket = ids.map((id) => targets[id]).filter((value) => !!value);
+				for (const owner of groupedOwners.get(ownerId) ?? []) {
+					this.primeManyToManyOwnerCache(owner, node.relationName, bucket);
+					handledOwners.add(owner);
+				}
+				for (const child of bucket) canonicalChildren$1.set(child[node.targetPrimaryKey], child);
+			}
+			for (const owner of owners) if (!handledOwners.has(owner)) this.primeManyToManyOwnerCache(owner, node.relationName, []);
+			const childOwners$1 = [...canonicalChildren$1.values()];
+			for (const childNode of node.prefetchChildren) await this.hydratePrefetchNode(childNode, childOwners$1, canonicalEntities, compiler);
+			return;
+		}
 		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 chunk of sourceChunks) {
+			const chunkCompiled = compiler.compilePrefetch(node, chunk);
+			const result = await this.executor.client.query(chunkCompiled.sql, chunkCompiled.params);
+			for (const rawResultRow of result.rows) {
+				const normalized = this.normalizeTargetRow(chunkCompiled, rawResultRow);
+				const canonical = this.canonicalizeEntity(node, normalized, canonicalEntities);
+				this.hydrateJoinNodesForOwner(canonical, normalized, node.joinChildren, canonicalEntities);
+				const key = normalized[chunkCompiled.targetKey];
+				if (typeof key !== "string" && typeof key !== "number") continue;
+				for (const owner of groupedOwners.get(key) ?? []) if (node.cardinality === InternalRelationHydrationCardinality.MANY) owner[node.relationName].push(canonical);
+else if (owner[node.relationName] === null) owner[node.relationName] = canonical;
+				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);
 	}
+	chunkValues(values, size) {
+		if (values.length === 0) return [];
+		if (values.length <= size) return [Array.from(values)];
+		const chunks = [];
+		for (let i = 0; i < values.length; i += size) chunks.push(values.slice(i, i + size));
+		return chunks;
+	}
 	groupOwnersByAccessor(owners, accessor) {
 		const grouped = new Map();
 		for (const owner of owners) {
@@ -1138,10 +1443,11 @@ var QuerySet = class QuerySet {
 		}
 		byModel.set(primaryKeyValue, row);
 		canonicalEntities.set(node.targetModelKey, byModel);
+		this.executor.attachPersistedRecordAccessors?.(row, node.targetModelKey);
 		return row;
 	}
 	normalizeTargetRow(prefetch, row) {
-		if (this.executor.dialect !== InternalDialect.SQLITE) return row;
+		if (this.executor.adapter.dialect !== InternalDialect.SQLITE) return row;
 		let normalized = null;
 		for (const [column, type] of Object.entries(prefetch.targetColumns)) {
 			if (!this.isBooleanColumnType(type)) continue;
@@ -1153,7 +1459,7 @@ var QuerySet = class QuerySet {
 		return normalized ?? row;
 	}
 	normalizeColumnValue(columnType, value) {
-		return this.executor.dialect === InternalDialect.SQLITE && this.isBooleanColumnType(columnType) ? this.normalizeSqliteBoolean(value) : value;
+		return this.executor.adapter.dialect === InternalDialect.SQLITE && this.isBooleanColumnType(columnType) ? this.normalizeSqliteBoolean(value) : value;
 	}
 	isBooleanColumnType(value) {
 		return typeof value === "string" && ["bool", "boolean"].includes(value.trim().toLowerCase());
@@ -1180,10 +1486,22 @@ var QuerySet = class QuerySet {
 	}
 };
 
+//#endregion
+//#region src/query/ModelQuerySet.ts
+var ModelQuerySet = class ModelQuerySet extends QuerySet {
+	constructor(executor, state = {}) {
+		super(executor, state);
+	}
+	spawn(state) {
+		return new ModelQuerySet(this.executor, state);
+	}
+};
+
 //#endregion
 //#region src/query/index.ts
 var query_exports = {};
 __export(query_exports, {
+	ModelQuerySet: () => ModelQuerySet,
 	Q: () => QBuilder,
 	QBuilder: () => QBuilder,
 	QueryCompiler: () => QueryCompiler,
@@ -1194,5 +1512,5 @@ __export(query_exports, {
 });
 
 //#endregion
-export { OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QueryResult, QuerySet, TableMetaFactory, compiler_exports, domain_exports, query_exports };
-//# sourceMappingURL=query-C6So1r6H.js.map
+export { InternalQNodeType, InternalRelationKind, InternalSqlValidationPlanKind, ModelQuerySet, OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QueryResult, QuerySet, TableMetaFactory, compiler_exports, domain_exports, isQNodeLike, query_exports };
+//# sourceMappingURL=query-DUZnBFhf.js.map