arkormx 2.0.0-next.0 → 2.0.0-next.2

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { str } from "@h3ravel/support";
 import { sql } from "kysely";
 import { AsyncLocalStorage } from "async_hooks";
 import { createJiti } from "@rexxars/jiti";
@@ -7,7 +8,6 @@ import { createRequire } from "module";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
 import { fileURLToPath } from "url";
 import path, { dirname as dirname$1, extname as extname$1, join as join$1, relative } from "path";
-import { str } from "@h3ravel/support";
 import { existsSync as existsSync$1, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdirSync as readdirSync$1, rmSync as rmSync$1, writeFileSync as writeFileSync$1 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { Logger } from "@h3ravel/shared";
@@ -70,24 +70,66 @@ var UnsupportedAdapterFeatureException = class extends ArkormException {
 
 //#endregion
 //#region src/adapters/KyselyDatabaseAdapter.ts
+/**
+* Database adapter implementation for Kysely, allowing Arkorm to execute queries using Kysely 
+* as the underlying query builder and executor.
+* 
+* @author Legacy (3m1n3nc3)
+* @since 2.0.0-next.0
+*/
 var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	capabilities = {
 		transactions: true,
 		returning: true,
 		insertMany: true,
+		upsert: true,
 		updateMany: true,
 		deleteMany: true,
 		exists: true,
 		relationLoads: false,
-		relationAggregates: false,
-		relationFilters: false,
+		relationAggregates: true,
+		relationFilters: true,
 		rawWhere: false
 	};
-	constructor(db) {
+	constructor(db, mapping = {}) {
 		this.db = db;
+		this.mapping = mapping;
+	}
+	introspectionTypeToTs(typeName, enumValues) {
+		if (enumValues && enumValues.length > 0) return enumValues.map((value) => `'${value.replace(/'/g, "\\'")}'`).join(" | ");
+		switch (typeName) {
+			case "bool": return "boolean";
+			case "int2":
+			case "int4":
+			case "int8":
+			case "float4":
+			case "float8":
+			case "numeric":
+			case "money": return "number";
+			case "json":
+			case "jsonb": return "Record<string, unknown> | unknown[]";
+			case "date":
+			case "timestamp":
+			case "timestamptz": return "Date";
+			case "bytea": return "Uint8Array";
+			case "uuid":
+			case "varchar":
+			case "bpchar":
+			case "char":
+			case "text":
+			case "citext":
+			case "time":
+			case "timetz":
+			case "interval":
+			case "inet":
+			case "cidr":
+			case "macaddr":
+			case "macaddr8": return "string";
+			default: return "unknown";
+		}
 	}
 	resolveTable(target) {
-		if (target.table && target.table.trim().length > 0) return target.table;
+		if (target.table && target.table.trim().length > 0) return this.mapping[target.table] ?? target.table;
 		throw new ArkormException("Kysely adapter requires a concrete target table.", {
 			operation: "adapter.table",
 			model: target.modelName,
@@ -196,29 +238,223 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		if (clauses.length === 0) return sql``;
 		return sql.join(clauses, sql``);
 	}
+	buildColumnReference(table, column) {
+		return sql`${sql.table(table)}.${sql.id(column)}`;
+	}
+	buildRelatedTargetFromRelation(target, relation) {
+		const metadata = target.model?.getRelationMetadata(relation);
+		if (!metadata) throw new UnsupportedAdapterFeatureException(`Relation [${relation}] could not be resolved for SQL-backed relation execution.`, {
+			operation: "adapter.relation.metadata",
+			model: target.modelName,
+			relation
+		});
+		if (metadata.type !== "hasMany" && metadata.type !== "hasOne" && metadata.type !== "belongsTo" && metadata.type !== "belongsToMany" && metadata.type !== "hasOneThrough" && metadata.type !== "hasManyThrough") throw new UnsupportedAdapterFeatureException(`Relation [${relation}] is not supported for SQL-backed relation execution by the Kysely adapter yet.`, {
+			operation: "adapter.relation.metadata",
+			model: target.modelName,
+			relation,
+			meta: {
+				feature: "relationFilters",
+				relationType: metadata.type
+			}
+		});
+		const relatedMetadata = metadata.relatedModel.getModelMetadata();
+		return {
+			metadata,
+			relatedTarget: {
+				model: metadata.relatedModel,
+				modelName: metadata.relatedModel.name,
+				table: relatedMetadata.table,
+				primaryKey: relatedMetadata.primaryKey,
+				columns: relatedMetadata.columns,
+				softDelete: relatedMetadata.softDelete
+			}
+		};
+	}
+	resolveMappedTable(table) {
+		return this.mapping[table] ?? table;
+	}
+	buildBelongsToManyJoinSource(outerTarget, relatedTarget, metadata) {
+		const outerTable = this.resolveTable(outerTarget);
+		const relatedTable = this.resolveTable(relatedTarget);
+		const pivotTable = this.resolveMappedTable(metadata.throughTable);
+		return {
+			from: sql`${sql.table(relatedTable)} inner join ${sql.table(pivotTable)} on ${this.buildColumnReference(relatedTable, this.mapColumn(relatedTarget, metadata.relatedKey))} = ${this.buildColumnReference(pivotTable, metadata.relatedPivotKey)}`,
+			condition: sql`
+                ${this.buildColumnReference(pivotTable, metadata.foreignPivotKey)}
+                =
+                ${this.buildColumnReference(outerTable, this.mapColumn(outerTarget, metadata.parentKey))}
+            `
+		};
+	}
+	buildThroughJoinSource(outerTarget, relatedTarget, metadata) {
+		const outerTable = this.resolveTable(outerTarget);
+		const relatedTable = this.resolveTable(relatedTarget);
+		const throughTable = this.resolveMappedTable(metadata.throughTable);
+		return {
+			from: sql`${sql.table(relatedTable)} inner join ${sql.table(throughTable)} on ${this.buildColumnReference(relatedTable, this.mapColumn(relatedTarget, metadata.secondKey))} = ${this.buildColumnReference(throughTable, metadata.secondLocalKey)}`,
+			condition: sql`
+                ${this.buildColumnReference(throughTable, metadata.firstKey)}
+                =
+                ${this.buildColumnReference(outerTable, this.mapColumn(outerTarget, metadata.localKey))}
+            `
+		};
+	}
+	buildRelatedJoinCondition(outerTarget, relation) {
+		const { metadata, relatedTarget } = this.buildRelatedTargetFromRelation(outerTarget, relation);
+		const outerTable = this.resolveTable(outerTarget);
+		const relatedTable = this.resolveTable(relatedTarget);
+		if (metadata.type === "belongsToMany") {
+			const joinSource = this.buildBelongsToManyJoinSource(outerTarget, relatedTarget, metadata);
+			return {
+				relatedTarget,
+				from: joinSource.from,
+				condition: joinSource.condition
+			};
+		}
+		if (metadata.type === "hasOneThrough" || metadata.type === "hasManyThrough") {
+			const joinSource = this.buildThroughJoinSource(outerTarget, relatedTarget, metadata);
+			return {
+				relatedTarget,
+				from: joinSource.from,
+				condition: joinSource.condition
+			};
+		}
+		if (metadata.type === "hasMany" || metadata.type === "hasOne") return {
+			relatedTarget,
+			from: sql`${sql.table(relatedTable)}`,
+			condition: sql`
+                    ${this.buildColumnReference(relatedTable, this.mapColumn(relatedTarget, metadata.foreignKey))}
+                    =
+                    ${this.buildColumnReference(outerTable, this.mapColumn(outerTarget, metadata.localKey))}
+                `
+		};
+		return {
+			relatedTarget,
+			from: sql`${sql.table(relatedTable)}`,
+			condition: sql`
+                ${this.buildColumnReference(relatedTable, this.mapColumn(relatedTarget, metadata.ownerKey))}
+                =
+                ${this.buildColumnReference(outerTable, this.mapColumn(outerTarget, metadata.foreignKey))}
+            `
+		};
+	}
+	combineConditions(conditions) {
+		const filtered = conditions.filter((condition) => Boolean(condition));
+		if (filtered.length === 0) return sql`1 = 1`;
+		if (filtered.length === 1) return filtered[0];
+		return sql`(${sql.join(filtered, sql` and `)})`;
+	}
+	buildRelationFilterExpression(target, filter) {
+		const { relatedTarget, from, condition } = this.buildRelatedJoinCondition(target, filter.relation);
+		return sql`(
+            select count(*)::int
+            from ${from}
+            where ${this.combineConditions([condition, filter.where ? this.buildWhereCondition(relatedTarget, filter.where) : void 0])}
+        ) ${filter.operator === "!=" ? sql.raw("!=") : sql.raw(filter.operator)} ${filter.count}`;
+	}
+	buildRelationFilterCondition(target, relationFilters) {
+		if (!relationFilters || relationFilters.length === 0) return sql`1 = 1`;
+		let expression = null;
+		relationFilters.forEach((filter) => {
+			const next = this.buildRelationFilterExpression(target, filter);
+			if (!expression) {
+				expression = next;
+				return;
+			}
+			expression = filter.boolean === "OR" ? sql`(${expression} or ${next})` : sql`(${expression} and ${next})`;
+		});
+		return expression ?? sql`1 = 1`;
+	}
+	buildQueryFilterCondition(target, condition, relationFilters) {
+		let expression = condition ? this.buildWhereCondition(target, condition) : null;
+		relationFilters?.forEach((filter) => {
+			const next = this.buildRelationFilterExpression(target, filter);
+			if (!expression) {
+				expression = next;
+				return;
+			}
+			expression = filter.boolean === "OR" ? sql`(${expression} or ${next})` : sql`(${expression} and ${next})`;
+		});
+		return expression ?? sql`1 = 1`;
+	}
+	buildRelationAggregateSelectList(target, relationAggregates) {
+		if (!relationAggregates || relationAggregates.length === 0) return sql``;
+		return sql.join(relationAggregates.map((aggregate) => {
+			const { relatedTarget, from, condition } = this.buildRelatedJoinCondition(target, aggregate.relation);
+			const relatedTable = this.resolveTable(relatedTarget);
+			const whereCondition = this.combineConditions([condition, aggregate.where ? this.buildWhereCondition(relatedTarget, aggregate.where) : void 0]);
+			if (aggregate.type === "exists") return sql`, exists(
+                    select 1
+                    from ${from}
+                    where ${whereCondition}
+                ) as ${sql.id(aggregate.alias ?? `${aggregate.relation}Exists`)}`;
+			const selectedColumn = aggregate.column ? this.buildColumnReference(relatedTable, this.mapColumn(relatedTarget, aggregate.column)) : sql.raw("*");
+			return sql`, (
+                select ${aggregate.type === "count" ? sql`count(*)::int` : aggregate.type === "sum" ? sql`sum(${selectedColumn})::double precision` : aggregate.type === "avg" ? sql`avg(${selectedColumn})::double precision` : aggregate.type === "min" ? sql`min(${selectedColumn})` : sql`max(${selectedColumn})`}
+                from ${from}
+                where ${whereCondition}
+            ) as ${sql.id(aggregate.alias ?? `${aggregate.relation}${aggregate.type}`)}`;
+		}), sql``);
+	}
+	buildCombinedWhereClause(target, condition, relationFilters) {
+		if (!condition && (!relationFilters || relationFilters.length === 0)) return sql``;
+		return sql` where ${this.buildQueryFilterCondition(target, condition, relationFilters)}`;
+	}
+	buildSingleRowTargetCte(target, where) {
+		const primaryKey = this.resolvePrimaryKey(target);
+		return sql`target_row as (
+            select ${sql.id(primaryKey)}
+            from ${sql.table(this.resolveTable(target))}
+            where ${this.buildWhereCondition(target, where)}
+            limit 1
+        )`;
+	}
 	assertNoRelationLoads(spec) {
 		if ("relationLoads" in spec && spec.relationLoads && spec.relationLoads.length > 0) throw new UnsupportedAdapterFeatureException("Kysely adapter relation-load execution is planned for a later phase.", {
 			operation: "adapter.relationLoads",
 			meta: { feature: "relationLoads" }
 		});
 	}
+	/**
+	* Selects records from the database matching the specified criteria and returns 
+	* them as an array of database rows.
+	* 
+	* @param spec  The specification defining the selection criteria.
+	* @returns     A promise that resolves to an array of database rows.
+	*/
 	async select(spec) {
 		this.assertNoRelationLoads(spec);
 		const result = await sql`
             select ${this.buildSelectList(spec.target, spec.columns)}
+            ${this.buildRelationAggregateSelectList(spec.target, spec.relationAggregates)}
             from ${sql.table(this.resolveTable(spec.target))}
-            ${this.buildWhereClause(spec.target, spec.where)}
+            ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
             ${this.buildOrderBy(spec.target, spec.orderBy)}
             ${this.buildPaginationClause(spec)}
         `.execute(this.db);
 		return this.mapRows(spec.target, result.rows);
 	}
+	/**
+	* Selects a single record from the database matching the specified criteria and returns it as 
+	* a database row. If multiple records match the criteria, only the first one is returned. 
+	* If no records match, null is returned.
+	* 
+	* @param spec  The specification defining the selection criteria.
+	* @returns     A promise that resolves to a database row or null if no records match.
+	*/
 	async selectOne(spec) {
 		return (await this.select({
 			...spec,
 			limit: spec.limit ?? 1
 		}))[0] ?? null;
 	}
+	/**
+	* Inserts a new record into the database with the specified values and returns the 
+	* inserted record as a database row.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async insert(spec) {
 		const values = this.mapValues(spec.target, spec.values);
 		const columns = Object.keys(values);
@@ -233,6 +469,13 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             `.execute(this.db);
 		return this.mapRow(spec.target, result.rows[0]);
 	}
+	/**
+	* Inserts multiple records into the database with the specified values and returns the number 
+	* of records successfully inserted. 
+	* 
+	* @param spec  The specification defining the values to be inserted.
+	* @returns     A promise that resolves to the number of records successfully inserted.
+	*/
 	async insertMany(spec) {
 		if (spec.values.length === 0) return 0;
 		const rows = spec.values.map((row) => this.mapValues(spec.target, row));
@@ -253,6 +496,39 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             returning ${sql.id(this.resolvePrimaryKey(spec.target))}
         `.execute(this.db)).rows.length;
 	}
+	async upsert(spec) {
+		if (spec.values.length === 0) return 0;
+		const rows = spec.values.map((row) => this.mapValues(spec.target, row));
+		const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
+		const uniqueColumns = spec.uniqueBy.map((column) => this.mapColumn(spec.target, column));
+		const updateColumns = (spec.updateColumns ?? []).map((column) => this.mapColumn(spec.target, column)).filter((column) => !uniqueColumns.includes(column));
+		const conflictTarget = sql.join(uniqueColumns.map((column) => sql.id(column)), sql`, `);
+		if (columns.length === 0) {
+			await sql`
+                insert into ${sql.table(this.resolveTable(spec.target))}
+                default values
+                on conflict (${conflictTarget}) do nothing
+            `.execute(this.db);
+			return spec.values.length;
+		}
+		const values = sql.join(rows.map((row) => {
+			return sql`(${sql.join(columns.map((column) => row[column] ?? null), sql`, `)})`;
+		}), sql`, `);
+		const conflictAction = updateColumns.length === 0 ? sql`do nothing` : sql`do update set ${sql.join(updateColumns.map((column) => sql`${sql.id(column)} = excluded.${sql.id(column)}`), sql`, `)}`;
+		await sql`
+            insert into ${sql.table(this.resolveTable(spec.target))} (${sql.join(columns.map((column) => sql.id(column)), sql`, `)})
+            values ${values}
+            on conflict (${conflictTarget}) ${conflictAction}
+        `.execute(this.db);
+		return spec.values.length;
+	}
+	/**
+	* Updates records in the database matching the specified criteria with the given values 
+	* and returns the updated record as a database row. 
+	* 
+	* @param spec  The specification defining the update criteria and values.
+	* @returns     A promise that resolves to the updated record as a database row, or null if no records match the criteria.  
+	*/
 	async update(spec) {
 		const values = this.mapValues(spec.target, spec.values);
 		const assignments = Object.entries(values).map(([column, value]) => {
@@ -271,6 +547,41 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
         `.execute(this.db);
 		return this.mapRow(spec.target, result.rows[0]);
 	}
+	/**
+	* Updates a single record in the database matching the specified criteria with the given values.
+	* 
+	* @param spec 
+	* @returns 
+	*/
+	async updateFirst(spec) {
+		const values = this.mapValues(spec.target, spec.values);
+		const assignments = Object.entries(values).map(([column, value]) => {
+			return sql`${sql.id(column)} = ${value}`;
+		});
+		if (assignments.length === 0) return await this.selectOne({
+			target: spec.target,
+			where: spec.where,
+			limit: 1
+		});
+		const primaryKey = this.resolvePrimaryKey(spec.target);
+		const table = this.resolveTable(spec.target);
+		const result = await sql`
+            with ${this.buildSingleRowTargetCte(spec.target, spec.where)}
+            update ${sql.table(table)}
+            set ${sql.join(assignments, sql`, `)}
+            from target_row
+            where ${this.buildColumnReference(table, primaryKey)} = ${sql`target_row.${sql.id(primaryKey)}`}
+            returning ${sql.table(table)}.*
+        `.execute(this.db);
+		return this.mapRow(spec.target, result.rows[0]);
+	}
+	/**
+	* Updates multiple records in the database matching the specified criteria with the 
+	* given values and returns the number of records successfully updated.
+	* 
+	* @param spec  The specification defining the update criteria and values.
+	* @returns     A promise that resolves to the number of records successfully updated.
+	*/
 	async updateMany(spec) {
 		const values = this.mapValues(spec.target, spec.values);
 		const assignments = Object.entries(values).map(([column, value]) => {
@@ -284,6 +595,13 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             returning ${sql.id(this.resolvePrimaryKey(spec.target))}
         `.execute(this.db)).rows.length;
 	}
+	/**
+	* Deletes records from the database matching the specified criteria and returns the 
+	* deleted record as a database row.
+	* 
+	* @param spec  The specification defining the delete criteria.
+	* @returns     A promise that resolves to the deleted record as a database row, or null if no records match the criteria.
+	*/
 	async delete(spec) {
 		const result = await sql`
             delete from ${sql.table(this.resolveTable(spec.target))}
@@ -292,6 +610,31 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
         `.execute(this.db);
 		return this.mapRow(spec.target, result.rows[0]);
 	}
+	/**
+	* Deletes a single record from the database matching the specified criteria and returns it as a database row.
+	* 
+	* @param spec 
+	* @returns 
+	*/
+	async deleteFirst(spec) {
+		const primaryKey = this.resolvePrimaryKey(spec.target);
+		const table = this.resolveTable(spec.target);
+		const result = await sql`
+            with ${this.buildSingleRowTargetCte(spec.target, spec.where)}
+            delete from ${sql.table(table)}
+            using target_row
+            where ${this.buildColumnReference(table, primaryKey)} = ${sql`target_row.${sql.id(primaryKey)}`}
+            returning ${sql.table(table)}.*
+        `.execute(this.db);
+		return this.mapRow(spec.target, result.rows[0]);
+	}
+	/**
+	* Deletes multiple records from the database matching the specified criteria and 
+	* returns the number of records successfully deleted.
+	* 
+	* @param spec  The specification defining the delete criteria.
+	* @returns     A promise that resolves to the number of records successfully deleted.
+	*/
 	async deleteMany(spec) {
 		return (await sql`
             delete from ${sql.table(this.resolveTable(spec.target))}
@@ -299,36 +642,113 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             returning ${sql.id(this.resolvePrimaryKey(spec.target))}
         `.execute(this.db)).rows.length;
 	}
+	/**
+	* Counts the number of records in the database matching the specified criteria and returns 
+	* the count as a number.
+	* 
+	* @param spec  The specification defining the count criteria.
+	* @returns     A promise that resolves to the number of records matching the criteria.
+	*/
 	async count(spec) {
 		const result = await sql`
             select count(*)::int as count
             from ${sql.table(this.resolveTable(spec.target))}
-            ${this.buildWhereClause(spec.target, spec.where)}
+            ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
         `.execute(this.db);
 		return Number(result.rows[0]?.count ?? 0);
 	}
+	/**
+	* Checks for the existence of records matching the specified criteria.
+	* 
+	* @param spec  The specification defining the existence criteria.
+	* @returns     A promise that resolves to a boolean indicating whether any records match the criteria.
+	*/
 	async exists(spec) {
 		const result = await sql`
             select exists(
                 select 1
                 from ${sql.table(this.resolveTable(spec.target))}
-                ${this.buildWhereClause(spec.target, spec.where)}
+                ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
                 limit 1
             ) as exists
         `.execute(this.db);
 		return Boolean(result.rows[0]?.exists);
 	}
+	async introspectModels(options = {}) {
+		const tables = options.tables?.filter(Boolean) ?? [];
+		const result = await sql`
+            select
+                cls.relname as table_name,
+                att.attname as column_name,
+                not att.attnotnull as is_nullable,
+                typ.typname as type_name,
+                case when typ.typcategory = 'A' then elem.typname else null end as element_type_name,
+                case when typ.typtype = 'e'
+                    then array(select enumlabel from pg_enum where enumtypid = typ.oid order by enumsortorder)
+                    else null
+                end as enum_values,
+                case when elem.typtype = 'e'
+                    then array(select enumlabel from pg_enum where enumtypid = elem.oid order by enumsortorder)
+                    else null
+                end as element_enum_values
+            from pg_attribute att
+            inner join pg_class cls on cls.oid = att.attrelid
+            inner join pg_namespace ns on ns.oid = cls.relnamespace
+            inner join pg_type typ on typ.oid = att.atttypid
+            left join pg_type elem on elem.oid = typ.typelem and typ.typcategory = 'A'
+            where cls.relkind in ('r', 'p')
+                and att.attnum > 0
+                and not att.attisdropped
+                and ns.nspname not in ('pg_catalog', 'information_schema')
+                ${tables.length > 0 ? sql` and cls.relname in (${sql.join(tables)})` : sql``}
+            order by cls.relname asc, att.attnum asc
+        `.execute(this.db);
+		const models = /* @__PURE__ */ new Map();
+		result.rows.forEach((row) => {
+			const existing = models.get(row.table_name) ?? {
+				name: str(row.table_name).studly().singular().toString(),
+				table: row.table_name,
+				fields: []
+			};
+			const isArray = row.element_type_name !== null;
+			const baseType = isArray ? this.introspectionTypeToTs(row.element_type_name ?? "unknown", row.element_enum_values) : this.introspectionTypeToTs(row.type_name, row.enum_values);
+			existing.fields.push({
+				name: row.column_name,
+				type: isArray ? `Array<${baseType}>` : baseType,
+				nullable: row.is_nullable
+			});
+			models.set(row.table_name, existing);
+		});
+		return [...models.values()];
+	}
+	/**
+	* Executes a series of database operations within a transaction. 
+	* The provided callback function is called with a new instance of the 
+	* KyselyDatabaseAdapter that is bound to the transaction context.
+	* 
+	* @param callback  The callback function containing the database operations to be executed within the transaction.
+	* @param context   The transaction context specifying options such as read-only mode and isolation level.
+	* @returns         A promise that resolves to the result of the callback function.
+	*/
 	async transaction(callback, context = {}) {
 		let transactionBuilder = this.db.transaction();
 		if (context.readOnly !== void 0) transactionBuilder = transactionBuilder.setAccessMode(context.readOnly ? "read only" : "read write");
 		if (context.isolationLevel) transactionBuilder = transactionBuilder.setIsolationLevel(context.isolationLevel);
 		return await transactionBuilder.execute(async (transaction) => {
-			return await callback(new KyselyDatabaseAdapter(transaction));
+			return await callback(new KyselyDatabaseAdapter(transaction, this.mapping));
 		});
 	}
 };
-const createKyselyAdapter = (db) => {
-	return new KyselyDatabaseAdapter(db);
+/**
+* Factory function to create a KyselyDatabaseAdapter instance with the given Kysely executor 
+* and optional table name mapping.
+* 
+* @param db        The Kysely executor to be used by the adapter.
+* @param mapping   Optional table name mapping for the adapter.
+* @returns         A new instance of KyselyDatabaseAdapter.   
+*/
+const createKyselyAdapter = (db, mapping = {}) => {
+	return new KyselyDatabaseAdapter(db, mapping);
 };
 
 //#endregion
@@ -387,6 +807,7 @@ const userConfig = {
 let runtimeConfigLoaded = false;
 let runtimeConfigLoadingPromise;
 let runtimeClientResolver;
+let runtimeAdapter;
 let runtimePaginationURLDriverFactory;
 let runtimePaginationCurrentPageResolver;
 const transactionClientStorage = new AsyncLocalStorage();
@@ -412,6 +833,12 @@ const mergePathConfig = (paths) => {
 const defineConfig = (config) => {
 	return config;
 };
+const bindAdapterToModels = (adapter, models) => {
+	models.forEach((model) => {
+		model.setAdapter(adapter);
+	});
+	return adapter;
+};
 /**
 * Get the user-provided ArkORM configuration. 
 * 
@@ -431,15 +858,22 @@ const getUserConfig = (key) => {
 const configureArkormRuntime = (prisma, options = {}) => {
 	const nextConfig = {
 		...userConfig,
-		prisma,
 		paths: mergePathConfig(options.paths)
 	};
+	nextConfig.prisma = prisma;
 	if (options.pagination !== void 0) nextConfig.pagination = options.pagination;
+	if (options.adapter !== void 0) nextConfig.adapter = options.adapter;
+	if (options.boot !== void 0) nextConfig.boot = options.boot;
 	if (options.outputExt !== void 0) nextConfig.outputExt = options.outputExt;
 	Object.assign(userConfig, { ...nextConfig });
 	runtimeClientResolver = prisma;
+	runtimeAdapter = options.adapter;
 	runtimePaginationURLDriverFactory = nextConfig.pagination?.urlDriver;
 	runtimePaginationCurrentPageResolver = nextConfig.pagination?.resolveCurrentPage;
+	options.boot?.({
+		prisma: resolveClient(prisma),
+		bindAdapter: bindAdapterToModels
+	});
 };
 /**
 * Reset the ArkORM runtime configuration. 
@@ -453,6 +887,7 @@ const resetArkormRuntimeForTests = () => {
 	runtimeConfigLoaded = false;
 	runtimeConfigLoadingPromise = void 0;
 	runtimeClientResolver = void 0;
+	runtimeAdapter = void 0;
 	runtimePaginationURLDriverFactory = void 0;
 	runtimePaginationCurrentPageResolver = void 0;
 };
@@ -479,8 +914,10 @@ const resolveClient = (resolver) => {
 */
 const resolveAndApplyConfig = (imported) => {
 	const config = imported?.default ?? imported;
-	if (!config || typeof config !== "object" || !config.prisma) return;
+	if (!config || typeof config !== "object") return;
 	configureArkormRuntime(config.prisma, {
+		adapter: config.adapter,
+		boot: config.boot,
 		pagination: config.pagination,
 		paths: config.paths,
 		outputExt: config.outputExt
@@ -562,6 +999,10 @@ const getRuntimePrismaClient = () => {
 	if (!runtimeConfigLoaded) loadRuntimeConfigSync();
 	return resolveClient(runtimeClientResolver);
 };
+const getRuntimeAdapter = () => {
+	if (!runtimeConfigLoaded) loadRuntimeConfigSync();
+	return runtimeAdapter;
+};
 const getActiveTransactionClient = () => {
 	return transactionClientStorage.getStore();
 };
@@ -629,9 +1070,11 @@ loadArkormConfig();
 //#endregion
 //#region src/helpers/prisma.ts
 /**
-* Create an adapter to convert a Prisma client instance into a format 
+* Create an adapter to convert a Prisma client instance into a format
 * compatible with ArkORM's expectations.
-* 
+*
+* @deprecated Prefer createPrismaDatabaseAdapter(prisma) for runtime usage.
+*
 * @param prisma The Prisma client instance to adapt.
 * @param mapping An optional mapping of Prisma delegate names to ArkORM delegate names.
 * @returns A record of adapted Prisma delegates compatible with ArkORM.
@@ -646,6 +1089,9 @@ function createPrismaAdapter(prisma) {
 /**
 * Create a delegate mapping record for Model.setClient() from a Prisma client.
 *
+* @deprecated Prefer createPrismaDatabaseAdapter(prisma, mapping) and bind the
+* resulting adapter with Model.setAdapter(...).
+*
 * @param prisma The Prisma client instance.
 * @param mapping Optional mapping of Arkormˣ delegate names to Prisma delegate names.
 * @returns A delegate map keyed by Arkormˣ delegate names.
@@ -672,6 +1118,13 @@ function inferDelegateName(modelName) {
 
 //#endregion
 //#region src/adapters/PrismaDatabaseAdapter.ts
+/**
+* Database adapter implementation for Prisma, allowing Arkorm to execute queries using Prisma 
+* as the underlying query builder and executor.
+* 
+* @author Legacy (3m1n3nc3)
+* @since 2.0.0-next.0
+*/
 var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 	capabilities;
 	delegates;
@@ -686,6 +1139,7 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 		this.capabilities = {
 			transactions: this.hasTransactionSupport(prisma),
 			insertMany: Object.values(this.delegates).some((delegate) => typeof delegate.createMany === "function"),
+			upsert: false,
 			updateMany: Object.values(this.delegates).some((delegate) => typeof delegate.updateMany === "function"),
 			deleteMany: false,
 			exists: true,
@@ -705,6 +1159,27 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 	unique(values) {
 		return [...new Set(values.filter(Boolean))];
 	}
+	runtimeModelTypeToTs(typeName, kind, enumValues) {
+		if (kind === "enum" && enumValues && enumValues.length > 0) return enumValues.map((value) => `'${value.replace(/'/g, "\\'")}'`).join(" | ");
+		switch (typeName) {
+			case "Int":
+			case "Float":
+			case "Decimal":
+			case "BigInt": return "number";
+			case "Boolean": return "boolean";
+			case "DateTime": return "Date";
+			case "Json": return "Record<string, unknown> | unknown[]";
+			case "Bytes": return "Uint8Array";
+			case "String":
+			case "UUID": return "string";
+			default: return "string";
+		}
+	}
+	getRuntimeDataModel() {
+		const runtimeDataModel = this.prisma._runtimeDataModel;
+		if (runtimeDataModel && typeof runtimeDataModel === "object") return runtimeDataModel;
+		return null;
+	}
 	toQuerySelect(columns) {
 		if (!columns || columns.length === 0) return void 0;
 		return columns.reduce((select, column) => {
@@ -786,6 +1261,29 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			return include;
 		}, {});
 	}
+	async introspectModels(options = {}) {
+		const runtimeDataModel = this.getRuntimeDataModel();
+		if (!runtimeDataModel?.models) return [];
+		const requestedTables = new Set(options.tables?.filter(Boolean) ?? []);
+		const enums = runtimeDataModel.enums ?? {};
+		return Object.entries(runtimeDataModel.models).flatMap(([name, model]) => {
+			const table = model.dbName ?? `${str(name).camel().plural()}`;
+			if (requestedTables.size > 0 && !requestedTables.has(table)) return [];
+			return [{
+				name,
+				table,
+				fields: (model.fields ?? []).filter((field) => field.kind !== "object").map((field) => {
+					const enumValues = field.kind === "enum" ? (enums[field.type]?.values ?? []).map((value) => typeof value === "string" ? value : value.name ?? "").filter(Boolean) : null;
+					const baseType = this.runtimeModelTypeToTs(field.type, field.kind, enumValues);
+					return {
+						name: field.name,
+						type: field.isList ? `Array<${baseType}>` : baseType,
+						nullable: field.isRequired === false
+					};
+				})
+			}];
+		});
+	}
 	resolveDelegate(target) {
 		const tableName = target.table ? this.normalizeCandidate(target.table) : "";
 		const singularTableName = tableName ? `${str(tableName).singular()}` : "";
@@ -817,15 +1315,41 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			}
 		});
 	}
+	/**
+	* @todo Implement relationLoads by performing separate queries and merging results 
+	* in-memory, since Prisma does not support nested reads with constraints, ordering, or
+	* pagination on related models as of now.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async select(spec) {
 		return await this.resolveDelegate(spec.target).findMany(this.buildFindArgs(spec));
 	}
+	/**
+	* Selects a single record matching the specified criteria. 
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async selectOne(spec) {
 		return await this.resolveDelegate(spec.target).findFirst(this.buildFindArgs(spec));
 	}
+	/**
+	* Inserts a single record into the database and returns the created record.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async insert(spec) {
 		return await this.resolveDelegate(spec.target).create({ data: spec.values });
 	}
+	/**
+	* Inserts multiple records into the database. 
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async insertMany(spec) {
 		const delegate = this.resolveDelegate(spec.target);
 		if (typeof delegate.createMany === "function") {
@@ -845,6 +1369,12 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 		}
 		return spec.ignoreDuplicates ? inserted : spec.values.length;
 	}
+	/**
+	* Updates a single record matching the specified criteria and returns the updated record.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async update(spec) {
 		const delegate = this.resolveDelegate(spec.target);
 		const where = this.toQueryWhere(spec.where);
@@ -854,6 +1384,12 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			data: spec.values
 		});
 	}
+	/**
+	* Updates multiple records matching the specified criteria. 
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async updateMany(spec) {
 		const delegate = this.resolveDelegate(spec.target);
 		const where = this.toQueryWhere(spec.where);
@@ -874,12 +1410,24 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 		}));
 		return rows.length;
 	}
+	/**
+	* Deletes a single record matching the specified criteria and returns the deleted record.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async delete(spec) {
 		const delegate = this.resolveDelegate(spec.target);
 		const where = this.toQueryWhere(spec.where);
 		if (!where) return null;
 		return await delegate.delete({ where });
 	}
+	/**
+	* Deletes multiple records matching the specified criteria. 
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async deleteMany(spec) {
 		const delegate = this.resolveDelegate(spec.target);
 		const where = this.toQueryWhere(spec.where);
@@ -889,21 +1437,46 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 		}));
 		return rows.length;
 	}
+	/**
+	* Counts the number of records matching the specified criteria.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async count(spec) {
 		return await this.resolveDelegate(spec.target).count({ where: this.toQueryWhere(spec.where) });
 	}
+	/**
+	* Checks for the existence of records matching the specified criteria.
+	* 
+	* @param spec 
+	* @returns 
+	*/
 	async exists(spec) {
 		return await this.selectOne({
 			...spec,
 			limit: 1
 		}) != null;
 	}
+	/**
+	* Loads related models for a batch of parent records based on the specified relation load plans.
+	* 
+	* @param _spec 
+	*/
 	async loadRelations(_spec) {
 		throw new UnsupportedAdapterFeatureException("Relation batch loading is not supported by the Prisma compatibility adapter yet.", {
 			operation: "adapter.loadRelations",
 			meta: { feature: "relationLoads" }
 		});
 	}
+	/**
+	* Executes a series of database operations within a transaction. 
+	* If the underlying Prisma client does not support transactions, an exception is thrown.
+	* 
+	* @param callback 
+	* @param context 
+	* @returns 
+	*/
 	async transaction(callback, context = {}) {
 		if (!this.hasTransactionSupport(this.prisma)) throw new UnsupportedAdapterFeatureException("Transactions are not supported by the Prisma compatibility adapter.", {
 			operation: "adapter.transaction",
@@ -918,9 +1491,25 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 		});
 	}
 };
+/**
+* Factory function to create a PrismaDatabaseAdapter instance with the given 
+* Prisma client and optional delegate name mapping.
+* 
+* @param prisma    The Prisma client instance to be used by the adapter.
+* @param mapping   Optional mapping of delegate names.
+* @returns         A new instance of PrismaDatabaseAdapter.
+*/
 const createPrismaDatabaseAdapter = (prisma, mapping = {}) => {
 	return new PrismaDatabaseAdapter(prisma, mapping);
 };
+/**
+* Alias for createPrismaDatabaseAdapter to maintain backward compatibility with 
+* previous versions of Arkorm that exported the adapter factory under a different name.
+* 
+* @param prisma    The Prisma client instance to be used by the adapter.
+* @param mapping   Optional mapping of delegate names.
+* @returns         A new instance of PrismaDatabaseAdapter.
+*/
 const createPrismaCompatibilityAdapter = createPrismaDatabaseAdapter;
 
 //#endregion
@@ -2892,6 +3481,40 @@ var CliApp = class {
 		lines.splice(insertionIndex, 0, `import type { ${enumTypes.join(", ")} } from '@prisma/client'`);
 		return lines.join("\n");
 	}
+	parseModelSyncSource(modelSource) {
+		const classMatch = modelSource.match(/export\s+class\s+(\w+)\s+extends\s+Model(?:<[^\n]+>)?\s*\{/);
+		if (!classMatch) return null;
+		const className = classMatch[1];
+		const tableMatch = modelSource.match(/protected\s+static\s+override\s+table\s*=\s*['"]([^'"]+)['"]/) ?? modelSource.match(/static\s+table\s*=\s*['"]([^'"]+)['"]/);
+		const delegateMatch = modelSource.match(/protected\s+static\s+override\s+delegate\s*=\s*['"]([^'"]+)['"]/) ?? modelSource.match(/static\s+delegate\s*=\s*['"]([^'"]+)['"]/);
+		return {
+			className,
+			table: tableMatch?.[1] ?? delegateMatch?.[1] ?? str(className).camel().plural().toString()
+		};
+	}
+	syncModelFiles(modelFiles, resolveStructure, enums) {
+		const updated = [];
+		const skipped = [];
+		modelFiles.forEach((filePath) => {
+			const source = readFileSync(filePath, "utf-8");
+			const structure = resolveStructure(filePath, source);
+			if (!structure || structure.fields.length === 0) {
+				skipped.push(filePath);
+				return;
+			}
+			const synced = this.syncModelDeclarations(source, structure.fields, enums);
+			if (!synced.updated) {
+				skipped.push(filePath);
+				return;
+			}
+			writeFileSync(filePath, synced.content);
+			updated.push(filePath);
+		});
+		return {
+			updated,
+			skipped
+		};
+	}
 	/**
 	* Parse Prisma enum definitions from a schema and return their member names.
 	*
@@ -2984,7 +3607,7 @@ var CliApp = class {
 	*/
 	syncModelDeclarations(modelSource, declarations, enums) {
 		const lines = modelSource.split("\n");
-		const classIndex = lines.findIndex((line) => /export\s+class\s+\w+\s+extends\s+Model<.+>\s*\{/.test(line));
+		const classIndex = lines.findIndex((line) => /export\s+class\s+\w+\s+extends\s+Model(?:<[^\n]+>)?\s*\{/.test(line));
 		if (classIndex < 0) return {
 			content: modelSource,
 			updated: false
@@ -3038,6 +3661,36 @@ var CliApp = class {
 			updated: contentWithImports !== modelSource
 		};
 	}
+	async syncModels(options = {}) {
+		const modelsDir = options.modelsDir ?? this.resolveConfigPath("models", join$1(process.cwd(), "src", "models"));
+		if (!existsSync(modelsDir)) throw new Error(`Models directory not found: ${modelsDir}`);
+		const modelFiles = readdirSync(modelsDir).filter((file) => file.endsWith(".ts")).map((file) => join$1(modelsDir, file));
+		const adapter = this.getConfig("adapter");
+		if (adapter && typeof adapter.introspectModels === "function") {
+			const sources = modelFiles.reduce((all, filePath) => {
+				const parsed = this.parseModelSyncSource(readFileSync(filePath, "utf-8"));
+				if (parsed) all.set(filePath, parsed);
+				return all;
+			}, /* @__PURE__ */ new Map());
+			const discovered = await adapter.introspectModels({ tables: [...new Set([...sources.values()].map((source) => source.table))] });
+			const structuresByTable = new Map(discovered.map((model) => [model.table, model]));
+			const result = this.syncModelFiles(modelFiles, (filePath) => {
+				const parsed = sources.get(filePath);
+				return parsed ? structuresByTable.get(parsed.table) : void 0;
+			}, /* @__PURE__ */ new Map());
+			return {
+				source: "adapter",
+				modelsDir,
+				total: modelFiles.length,
+				updated: result.updated,
+				skipped: result.skipped
+			};
+		}
+		return {
+			source: "prisma",
+			...this.syncModelsFromPrisma(options)
+		};
+	}
 	/**
 	* Sync model attribute declarations in model files based on the Prisma schema.
 	* This method reads the Prisma schema to extract model definitions and their 
@@ -3057,38 +3710,18 @@ var CliApp = class {
 		const schema = readFileSync(schemaPath, "utf-8");
 		const prismaEnums = this.parsePrismaEnums(schema);
 		const prismaModels = this.parsePrismaModels(schema);
-		const modelFiles = readdirSync(modelsDir).filter((file) => file.endsWith(".ts"));
-		const updated = [];
-		const skipped = [];
-		modelFiles.forEach((file) => {
-			const filePath = join$1(modelsDir, file);
-			const source = readFileSync(filePath, "utf-8");
-			const classMatch = source.match(/export\s+class\s+(\w+)\s+extends\s+Model<'([^']+)'>/);
-			if (!classMatch) {
-				skipped.push(filePath);
-				return;
-			}
-			const className = classMatch[1];
-			const delegate = classMatch[2];
-			const prismaModel = prismaModels.find((model) => model.table === delegate) ?? prismaModels.find((model) => model.name === className);
-			if (!prismaModel || prismaModel.fields.length === 0) {
-				skipped.push(filePath);
-				return;
-			}
-			const synced = this.syncModelDeclarations(source, prismaModel.fields, prismaEnums);
-			if (!synced.updated) {
-				skipped.push(filePath);
-				return;
-			}
-			writeFileSync(filePath, synced.content);
-			updated.push(filePath);
-		});
+		const modelFiles = readdirSync(modelsDir).filter((file) => file.endsWith(".ts")).map((file) => join$1(modelsDir, file));
+		const result = this.syncModelFiles(modelFiles, (filePath, source) => {
+			const parsed = this.parseModelSyncSource(source);
+			if (!parsed) return void 0;
+			return prismaModels.find((model) => model.table === parsed.table) ?? prismaModels.find((model) => model.name === parsed.className);
+		}, prismaEnums);
 		return {
 			schemaPath,
 			modelsDir,
 			total: modelFiles.length,
-			updated,
-			skipped
+			updated: result.updated,
+			skipped: result.skipped
 		};
 	}
 };
@@ -3666,20 +4299,21 @@ var MigrationHistoryCommand = class extends Command {
 //#region src/cli/commands/ModelsSyncCommand.ts
 var ModelsSyncCommand = class extends Command {
 	signature = `models:sync
-        {--schema= : Path to prisma schema file}
+        {--schema= : Path to prisma schema file used when adapter introspection is unavailable}
         {--models= : Path to models directory}
     `;
-	description = "Sync model declare attributes from prisma schema for all model files";
+	description = "Sync model declare attributes from the active adapter when supported, otherwise fall back to the Prisma schema";
 	async handle() {
 		this.app.command = this;
-		const result = this.app.syncModelsFromPrisma({
+		const result = await this.app.syncModels({
 			schemaPath: this.option("schema") ? resolve(String(this.option("schema"))) : void 0,
 			modelsDir: this.option("models") ? resolve(String(this.option("models"))) : void 0
 		});
 		const updatedLines = result.updated.length === 0 ? [this.app.splitLogger("Updated", "none")] : result.updated.map((path) => this.app.splitLogger("Updated", path));
 		this.success("SUCCESS: Model sync completed with the following results:");
 		[
-			this.app.splitLogger("Schema", result.schemaPath),
+			this.app.splitLogger("Source", result.source === "adapter" ? "adapter introspection" : "prisma schema"),
+			...result.schemaPath ? [this.app.splitLogger("Schema", result.schemaPath)] : [],
 			this.app.splitLogger("Models", result.modelsDir),
 			this.app.splitLogger("Processed", String(result.total)),
 			...updatedLines,
@@ -4039,6 +4673,13 @@ var UniqueConstraintResolutionException = class extends ArkormException {
 
 //#endregion
 //#region src/relationship/RelationTableLoader.ts
+/**
+* Utility class responsible for loading data from relation tables, which are used to 
+* manage relationships between models in Arkorm. 
+* 
+* @author Legacy (3m1n3nc3)
+* @since 2.0.0-next.0
+*/
 var RelationTableLoader = class {
 	constructor(adapter) {
 		this.adapter = adapter;
@@ -4800,6 +5441,472 @@ var MorphToManyRelation = class extends Relation {
 	}
 };
 
+//#endregion
+//#region src/relationship/SetBasedEagerLoader.ts
+/**
+* Utility class responsible for performing set-based eager loading of relationships for 
+* a collection of models.
+* 
+* @author Legacy (3m1n3nc3)
+* @since 2.0.0-next.2
+*/
+var SetBasedEagerLoader = class {
+	constructor(models, relations) {
+		this.models = models;
+		this.relations = relations;
+	}
+	/**
+	* Performs eager loading of all specified relationships for the set of models. 
+	* 
+	* @returns 
+	*/
+	async load() {
+		if (this.models.length === 0) return;
+		await Promise.all(Object.entries(this.relations).map(async ([name, constraint]) => {
+			await this.loadRelation(name, constraint);
+		}));
+	}
+	/**
+	* Loads a specific relationship for the set of models based on the relationship name 
+	* and an optional constraint.
+	* 
+	* @param name          The name of the relationship to load.
+	* @param constraint    An optional constraint to apply to the query.
+	* @returns             A promise that resolves when the relationship is loaded.
+	*/
+	async loadRelation(name, constraint) {
+		const resolver = this.resolveRelationResolver(name);
+		if (!resolver) return;
+		const metadata = resolver.call(this.models[0]).getMetadata();
+		switch (metadata.type) {
+			case "belongsTo":
+				await this.loadBelongsTo(name, resolver, metadata, constraint);
+				return;
+			case "belongsToMany":
+				await this.loadBelongsToMany(name, metadata, constraint);
+				return;
+			case "hasMany":
+				await this.loadHasMany(name, metadata, constraint);
+				return;
+			case "hasOne":
+				await this.loadHasOne(name, resolver, metadata, constraint);
+				return;
+			case "hasManyThrough":
+				await this.loadHasManyThrough(name, metadata, constraint);
+				return;
+			case "hasOneThrough":
+				await this.loadHasOneThrough(name, resolver, metadata, constraint);
+				return;
+			default: await this.loadIndividually(name, resolver, constraint);
+		}
+	}
+	/**
+	* Resolves the relation resolver function for a given relationship name by inspecting 
+	* the first model in the set.
+	* 
+	* @param name  The name of the relationship to resolve.
+	* @returns     The relation resolver function or null if not found.
+	*/
+	resolveRelationResolver(name) {
+		const resolver = this.models[0][name];
+		if (typeof resolver !== "function") return null;
+		return resolver;
+	}
+	/**
+	* Loads a "belongs to" relationship for the set of models.
+	* 
+	* @param name          The name of the relationship to load.
+	* @param resolver      The relation resolver function.
+	* @param metadata      The metadata for the relationship.
+	* @param constraint    An optional constraint to apply to the query.
+	* @returns             A promise that resolves when the relationship is loaded.
+	*/
+	async loadBelongsTo(name, resolver, metadata, constraint) {
+		const keys = this.collectUniqueKeys((model) => model.getAttribute(metadata.foreignKey));
+		if (keys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, this.resolveSingleDefault(resolver, model));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.ownerKey, keys);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByOwnerKey = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const value = this.readModelAttribute(related, metadata.ownerKey);
+			if (value == null) return;
+			const lookupKey = this.toLookupKey(value);
+			if (!relatedByOwnerKey.has(lookupKey)) relatedByOwnerKey.set(lookupKey, related);
+		});
+		this.models.forEach((model) => {
+			const foreignValue = model.getAttribute(metadata.foreignKey);
+			const relationValue = foreignValue == null ? void 0 : relatedByOwnerKey.get(this.toLookupKey(foreignValue));
+			model.setLoadedRelation(name, relationValue ?? this.resolveSingleDefault(resolver, model));
+		});
+	}
+	/**
+	* Loads a "has many" relationship for the set of models. 
+	* 
+	* @param name 
+	* @param metadata 
+	* @param constraint 
+	* @returns 
+	*/
+	async loadHasMany(name, metadata, constraint) {
+		const keys = this.collectUniqueKeys((model) => model.getAttribute(metadata.localKey));
+		if (keys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, new ArkormCollection([]));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.foreignKey, keys);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByForeignKey = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const value = this.readModelAttribute(related, metadata.foreignKey);
+			if (value == null) return;
+			const lookupKey = this.toLookupKey(value);
+			const bucket = relatedByForeignKey.get(lookupKey) ?? [];
+			bucket.push(related);
+			relatedByForeignKey.set(lookupKey, bucket);
+		});
+		this.models.forEach((model) => {
+			const localValue = model.getAttribute(metadata.localKey);
+			const related = localValue == null ? [] : relatedByForeignKey.get(this.toLookupKey(localValue)) ?? [];
+			model.setLoadedRelation(name, new ArkormCollection(related));
+		});
+	}
+	/**
+	* Loads a "belongs to many" relationship for the set of models. 
+	* 
+	* @param name 
+	* @param metadata 
+	* @param constraint 
+	* @returns 
+	*/
+	async loadBelongsToMany(name, metadata, constraint) {
+		const parentKeys = this.collectUniqueKeys((model) => model.getAttribute(metadata.parentKey));
+		if (parentKeys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, new ArkormCollection([]));
+			});
+			return;
+		}
+		const pivotRows = await this.createRelationTableLoader().selectRows({
+			table: metadata.throughTable,
+			where: {
+				type: "comparison",
+				column: metadata.foreignPivotKey,
+				operator: "in",
+				value: parentKeys
+			}
+		});
+		const relatedIds = this.collectUniqueRowValues(pivotRows, metadata.relatedPivotKey);
+		if (relatedIds.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, new ArkormCollection([]));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.relatedKey, relatedIds);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByKey = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const relatedValue = this.readModelAttribute(related, metadata.relatedKey);
+			if (relatedValue == null) return;
+			relatedByKey.set(this.toLookupKey(relatedValue), related);
+		});
+		const relatedKeysByParent = /* @__PURE__ */ new Map();
+		pivotRows.forEach((row) => {
+			const parentValue = row[metadata.foreignPivotKey];
+			const relatedValue = row[metadata.relatedPivotKey];
+			if (parentValue == null || relatedValue == null) return;
+			const bucket = relatedKeysByParent.get(this.toLookupKey(parentValue)) ?? [];
+			bucket.push(relatedValue);
+			relatedKeysByParent.set(this.toLookupKey(parentValue), bucket);
+		});
+		this.models.forEach((model) => {
+			const parentValue = model.getAttribute(metadata.parentKey);
+			const related = (parentValue == null ? [] : relatedKeysByParent.get(this.toLookupKey(parentValue)) ?? []).reduce((all, relatedValue) => {
+				const candidate = relatedByKey.get(this.toLookupKey(relatedValue));
+				if (candidate) all.push(candidate);
+				return all;
+			}, []);
+			model.setLoadedRelation(name, new ArkormCollection(related));
+		});
+	}
+	/**
+	* Loads a "belongs to many" relationship for the set of models.
+	* 
+	* @param name 
+	* @param resolver 
+	* @param metadata 
+	* @param constraint 
+	* @returns 
+	*/
+	async loadHasOne(name, resolver, metadata, constraint) {
+		const keys = this.collectUniqueKeys((model) => model.getAttribute(metadata.localKey));
+		if (keys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, this.resolveSingleDefault(resolver, model));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.foreignKey, keys);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByForeignKey = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const value = this.readModelAttribute(related, metadata.foreignKey);
+			if (value == null) return;
+			const lookupKey = this.toLookupKey(value);
+			if (!relatedByForeignKey.has(lookupKey)) relatedByForeignKey.set(lookupKey, related);
+		});
+		this.models.forEach((model) => {
+			const localValue = model.getAttribute(metadata.localKey);
+			const relationValue = localValue == null ? void 0 : relatedByForeignKey.get(this.toLookupKey(localValue));
+			model.setLoadedRelation(name, relationValue ?? this.resolveSingleDefault(resolver, model));
+		});
+	}
+	/**
+	* Loads a "has many through" relationship for the set of models.
+	* 
+	* @param name 
+	* @param metadata 
+	* @param constraint 
+	* @returns 
+	*/
+	async loadHasManyThrough(name, metadata, constraint) {
+		const parentKeys = this.collectUniqueKeys((model) => model.getAttribute(metadata.localKey));
+		if (parentKeys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, new ArkormCollection([]));
+			});
+			return;
+		}
+		const throughRows = await this.createRelationTableLoader().selectRows({
+			table: metadata.throughTable,
+			where: {
+				type: "comparison",
+				column: metadata.firstKey,
+				operator: "in",
+				value: parentKeys
+			}
+		});
+		const intermediateKeys = this.collectUniqueRowValues(throughRows, metadata.secondLocalKey);
+		if (intermediateKeys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, new ArkormCollection([]));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.secondKey, intermediateKeys);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByIntermediate = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const relatedValue = this.readModelAttribute(related, metadata.secondKey);
+			if (relatedValue == null) return;
+			const bucket = relatedByIntermediate.get(this.toLookupKey(relatedValue)) ?? [];
+			bucket.push(related);
+			relatedByIntermediate.set(this.toLookupKey(relatedValue), bucket);
+		});
+		const intermediateByParent = /* @__PURE__ */ new Map();
+		throughRows.forEach((row) => {
+			const parentValue = row[metadata.firstKey];
+			const intermediateValue = row[metadata.secondLocalKey];
+			if (parentValue == null || intermediateValue == null) return;
+			const bucket = intermediateByParent.get(this.toLookupKey(parentValue)) ?? [];
+			bucket.push(intermediateValue);
+			intermediateByParent.set(this.toLookupKey(parentValue), bucket);
+		});
+		this.models.forEach((model) => {
+			const parentValue = model.getAttribute(metadata.localKey);
+			const related = (parentValue == null ? [] : intermediateByParent.get(this.toLookupKey(parentValue)) ?? []).flatMap((intermediateValue) => relatedByIntermediate.get(this.toLookupKey(intermediateValue)) ?? []);
+			model.setLoadedRelation(name, new ArkormCollection(related));
+		});
+	}
+	/**
+	* Loads a "has one through" relationship for the set of models.
+	* 
+	* @param name 
+	* @param resolver 
+	* @param metadata 
+	* @param constraint 
+	* @returns 
+	*/
+	async loadHasOneThrough(name, resolver, metadata, constraint) {
+		const parentKeys = this.collectUniqueKeys((model) => model.getAttribute(metadata.localKey));
+		if (parentKeys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, this.resolveSingleDefault(resolver, model));
+			});
+			return;
+		}
+		const throughRows = await this.createRelationTableLoader().selectRows({
+			table: metadata.throughTable,
+			where: {
+				type: "comparison",
+				column: metadata.firstKey,
+				operator: "in",
+				value: parentKeys
+			}
+		});
+		const intermediateKeys = this.collectUniqueRowValues(throughRows, metadata.secondLocalKey);
+		if (intermediateKeys.length === 0) {
+			this.models.forEach((model) => {
+				model.setLoadedRelation(name, this.resolveSingleDefault(resolver, model));
+			});
+			return;
+		}
+		let query = metadata.relatedModel.query().whereIn(metadata.secondKey, intermediateKeys);
+		query = this.applyConstraint(query, constraint);
+		const relatedModels = (await query.get()).all();
+		const relatedByIntermediate = /* @__PURE__ */ new Map();
+		relatedModels.forEach((related) => {
+			const relatedValue = this.readModelAttribute(related, metadata.secondKey);
+			if (relatedValue == null) return;
+			const lookupKey = this.toLookupKey(relatedValue);
+			if (!relatedByIntermediate.has(lookupKey)) relatedByIntermediate.set(lookupKey, related);
+		});
+		const intermediateByParent = /* @__PURE__ */ new Map();
+		throughRows.forEach((row) => {
+			const parentValue = row[metadata.firstKey];
+			const intermediateValue = row[metadata.secondLocalKey];
+			if (parentValue == null || intermediateValue == null) return;
+			const lookupKey = this.toLookupKey(parentValue);
+			if (!intermediateByParent.has(lookupKey)) intermediateByParent.set(lookupKey, intermediateValue);
+		});
+		this.models.forEach((model) => {
+			const parentValue = model.getAttribute(metadata.localKey);
+			const intermediateValue = parentValue == null ? void 0 : intermediateByParent.get(this.toLookupKey(parentValue));
+			const relationValue = intermediateValue == null ? void 0 : relatedByIntermediate.get(this.toLookupKey(intermediateValue));
+			model.setLoadedRelation(name, relationValue ?? this.resolveSingleDefault(resolver, model));
+		});
+	}
+	/**
+	* Fallback method to load relationships individually for each model when the 
+	* relationship type is not supported for set-based loading.
+	* 
+	* @param name 
+	* @param resolver 
+	* @param constraint 
+	*/
+	async loadIndividually(name, resolver, constraint) {
+		await Promise.all(this.models.map(async (model) => {
+			const relation = resolver.call(model);
+			if (constraint) relation.constrain(constraint);
+			model.setLoadedRelation(name, await relation.getResults());
+		}));
+	}
+	/**
+	* Applies an eager load constraint to a query if provided.
+	* 
+	* @param query 
+	* @param constraint 
+	* @returns 
+	*/
+	applyConstraint(query, constraint) {
+		if (!constraint) return query;
+		return constraint(query) ?? query;
+	}
+	/**
+	* Collects unique values from the set of models based on a resolver function, which 
+	* is used to extract the value from each model.
+	* 
+	* @param resolve   A function that takes a model and returns the value to be collected.
+	* @returns         An array of unique values.
+	*/
+	collectUniqueKeys(resolve) {
+		const seen = /* @__PURE__ */ new Set();
+		const values = [];
+		this.models.forEach((model) => {
+			const value = resolve(model);
+			if (value == null) return;
+			const lookupKey = this.toLookupKey(value);
+			if (seen.has(lookupKey)) return;
+			seen.add(lookupKey);
+			values.push(value);
+		});
+		return values;
+	}
+	/**
+	* Collects unique values from an array of database rows based on a specified key, which 
+	* is used to extract the value from each row.
+	* 
+	* @param rows  An array of database rows.
+	* @param key   The key to extract values from each row.
+	* @returns     An array of unique values.
+	*/
+	collectUniqueRowValues(rows, key) {
+		const seen = /* @__PURE__ */ new Set();
+		const values = [];
+		rows.forEach((row) => {
+			const value = row[key];
+			if (value == null) return;
+			const lookupKey = this.toLookupKey(value);
+			if (seen.has(lookupKey)) return;
+			seen.add(lookupKey);
+			values.push(value);
+		});
+		return values;
+	}
+	/**
+	* Loads a "belongs to many" relationship for the set of models.
+	* 
+	* @returns 
+	*/
+	createRelationTableLoader() {
+		return new RelationTableLoader(this.resolveAdapter());
+	}
+	/**
+	* Loads a "belongs to many" relationship for the set of models.
+	* 
+	* @returns 
+	*/
+	resolveAdapter() {
+		const adapter = this.models[0].constructor.getAdapter?.();
+		if (!adapter) throw new Error("Set-based eager loading requires a configured adapter.");
+		return adapter;
+	}
+	/**
+	* Reads an attribute value from a model using the getAttribute method, which is used 
+	* to access model attributes in a way that is compatible with Arkorm's internal model structure.
+	* 
+	* @param model The model to read the attribute from.
+	* @param key The name of the attribute to read.
+	* @returns 
+	*/
+	readModelAttribute(model, key) {
+		return model.getAttribute?.(key);
+	}
+	/**
+	* Resolves the default result for a relationship when no related models are found. 
+	* 
+	* @param resolver 
+	* @param model 
+	* @returns 
+	*/
+	resolveSingleDefault(resolver, model) {
+		return resolver.call(model).resolveDefaultResult?.() ?? null;
+	}
+	/**
+	* Generates a unique lookup key for a given value, which is used to store and retrieve 
+	* values in maps during the eager loading process.
+	* 
+	* @param value     The value to generate a lookup key for.
+	* @returns         A unique string representing the value.
+	*/
+	toLookupKey(value) {
+		if (value instanceof Date) return `date:${value.toISOString()}`;
+		return `${typeof value}:${String(value)}`;
+	}
+};
+
 //#endregion
 //#region src/URLDriver.ts
 /**
@@ -5698,21 +6805,20 @@ var QueryBuilder = class QueryBuilder {
 	* @returns 
 	*/
 	async get() {
+		const useAdapterRelationFeatures = this.canExecuteRelationFeaturesInAdapter();
 		const relationCache = /* @__PURE__ */ new WeakMap();
 		const rows = await this.executeReadRows();
 		const normalizedRows = this.randomOrderEnabled ? this.shuffleRows(rows) : rows;
 		const models = await this.model.hydrateManyRetrieved(normalizedRows);
 		let filteredModels = models;
-		if (this.hasRelationFilters()) if (this.hasOrRelationFilters() && this.hasBaseWhereConstraints()) {
+		if (this.hasRelationFilters() && !useAdapterRelationFeatures) if (this.hasOrRelationFilters() && this.hasBaseWhereConstraints()) {
 			const baseIds = new Set(models.map((model) => this.getModelId(model)).filter((id) => id != null));
 			const allRows = await this.executeReadRows(this.buildSoftDeleteOnlyWhere(), true);
 			const allModels = this.model.hydrateMany(allRows);
 			filteredModels = await this.filterModelsByRelationConstraints(allModels, relationCache, baseIds);
 		} else filteredModels = await this.filterModelsByRelationConstraints(models, relationCache);
-		if (this.hasRelationAggregates()) await this.applyRelationAggregates(filteredModels, relationCache);
-		await Promise.all(filteredModels.map(async (model) => {
-			await model.load(this.eagerLoads);
-		}));
+		if (this.hasRelationAggregates() && !useAdapterRelationFeatures) await this.applyRelationAggregates(filteredModels, relationCache);
+		await this.eagerLoadModels(filteredModels);
 		return new ArkormCollection(filteredModels);
 	}
 	/**
@@ -5722,20 +6828,20 @@ var QueryBuilder = class QueryBuilder {
 	* @returns 
 	*/
 	async first() {
-		if (this.hasRelationFilters() || this.hasRelationAggregates()) return (await this.get()).all()[0] ?? null;
+		if ((this.hasRelationFilters() || this.hasRelationAggregates()) && !this.canExecuteRelationFeaturesInAdapter()) return (await this.get()).all()[0] ?? null;
 		if (this.randomOrderEnabled) {
 			const rows = await this.executeReadRows();
 			if (rows.length === 0) return null;
 			const row = this.shuffleRows(rows)[0];
 			if (!row) return null;
 			const model = await this.model.hydrateRetrieved(row);
-			await model.load(this.eagerLoads);
+			await this.eagerLoadModels([model]);
 			return model;
 		}
 		const row = await this.executeReadRow();
 		if (!row) return null;
 		const model = await this.model.hydrateRetrieved(row);
-		await model.load(this.eagerLoads);
+		await this.eagerLoadModels([model]);
 		return model;
 	}
 	/**
@@ -5899,6 +7005,13 @@ var QueryBuilder = class QueryBuilder {
 			operation: "update",
 			model: this.model.name
 		});
+		const directSpec = this.tryBuildUpdateSpec(where, data);
+		const adapter = this.requireAdapter();
+		if (!this.isUniqueWhere(where) && directSpec && typeof adapter.updateFirst === "function") {
+			const updated = await adapter.updateFirst(directSpec);
+			if (!updated) throw new ModelNotFoundException(this.model.name, "Record not found for update operation.", { operation: "update" });
+			return this.model.hydrate(updated);
+		}
 		const uniqueWhere = await this.resolveUniqueWhere(where);
 		const updated = await this.executeUpdateRow(uniqueWhere, data);
 		return this.model.hydrate(updated);
@@ -5925,6 +7038,13 @@ var QueryBuilder = class QueryBuilder {
 	* @returns
 	*/
 	async updateOrInsert(attributes, values = {}) {
+		if (typeof values !== "function" && this.adapter?.capabilities?.upsert && typeof this.requireAdapter().upsert === "function") {
+			await this.executeUpsertRows([{
+				...attributes,
+				...values
+			}], Object.keys(attributes), Object.keys(values));
+			return true;
+		}
 		const exists = await this.clone().where(attributes).first() != null;
 		const resolvedValues = typeof values === "function" ? await values(exists) : values;
 		if (!exists) {
@@ -5947,6 +7067,7 @@ var QueryBuilder = class QueryBuilder {
 	async upsert(values, uniqueBy, update = null) {
 		if (values.length === 0) return 0;
 		const uniqueKeys = Array.isArray(uniqueBy) ? uniqueBy : [uniqueBy];
+		if (this.adapter?.capabilities?.upsert && typeof this.requireAdapter().upsert === "function") return await this.executeUpsertRows(values, uniqueKeys, update ?? void 0);
 		let affected = 0;
 		for (const row of values) {
 			const attributes = uniqueKeys.reduce((all, key) => {
@@ -5974,6 +7095,13 @@ var QueryBuilder = class QueryBuilder {
 			operation: "delete",
 			model: this.model.name
 		});
+		const directSpec = this.tryBuildDeleteSpec(where);
+		const adapter = this.requireAdapter();
+		if (!this.isUniqueWhere(where) && directSpec && typeof adapter.deleteFirst === "function") {
+			const deleted = await adapter.deleteFirst(directSpec);
+			if (!deleted) throw new ModelNotFoundException(this.model.name, "Record not found for delete operation.", { operation: "delete" });
+			return this.model.hydrate(deleted);
+		}
 		const uniqueWhere = await this.resolveUniqueWhere(where);
 		const deleted = await this.executeDeleteRow(uniqueWhere);
 		return this.model.hydrate(deleted);
@@ -5990,6 +7118,14 @@ var QueryBuilder = class QueryBuilder {
 			values
 		};
 	}
+	tryBuildUpsertSpec(values, uniqueBy, updateColumns) {
+		return {
+			target: this.buildQueryTarget(),
+			values,
+			uniqueBy,
+			updateColumns
+		};
+	}
 	tryBuildInsertOrIgnoreManySpec(values) {
 		return {
 			...this.tryBuildInsertManySpec(values),
@@ -6028,7 +7164,7 @@ var QueryBuilder = class QueryBuilder {
 	* @returns 
 	*/
 	async count() {
-		if (this.hasRelationFilters()) return (await this.get()).all().length;
+		if (this.hasRelationFilters() && !this.canExecuteRelationFeaturesInAdapter()) return (await this.get()).all().length;
 		return this.executeReadCount();
 	}
 	/**
@@ -6037,7 +7173,7 @@ var QueryBuilder = class QueryBuilder {
 	* @returns
 	*/
 	async exists() {
-		if (this.hasRelationFilters()) return await this.count() > 0;
+		if (this.hasRelationFilters() && !this.canExecuteRelationFeaturesInAdapter()) return await this.count() > 0;
 		return await this.executeReadExists();
 	}
 	/**
@@ -6212,7 +7348,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async paginate(perPage = 15, page = void 0, options = {}) {
 		const currentPage = this.resolvePaginationPage(page, options);
-		if (this.hasRelationFilters() || this.hasRelationAggregates()) {
+		if ((this.hasRelationFilters() || this.hasRelationAggregates()) && !this.canExecuteRelationFeaturesInAdapter()) {
 			const pageSize = Math.max(1, perPage);
 			const rows = (await this.get()).all();
 			const start = (currentPage - 1) * pageSize;
@@ -6231,7 +7367,7 @@ var QueryBuilder = class QueryBuilder {
 	*/
 	async simplePaginate(perPage = 15, page = void 0, options = {}) {
 		const currentPage = this.resolvePaginationPage(page, options);
-		if (this.hasRelationFilters() || this.hasRelationAggregates()) {
+		if ((this.hasRelationFilters() || this.hasRelationAggregates()) && !this.canExecuteRelationFeaturesInAdapter()) {
 			const pageSize = Math.max(1, perPage);
 			const rows = (await this.get()).all();
 			const start = (currentPage - 1) * pageSize;
@@ -6335,6 +7471,10 @@ var QueryBuilder = class QueryBuilder {
 			};
 		});
 	}
+	async eagerLoadModels(models) {
+		if (models.length === 0 || Object.keys(this.eagerLoads).length === 0) return;
+		await new SetBasedEagerLoader(models, this.eagerLoads).load();
+	}
 	normalizeRelationLoadSelect(select) {
 		if (Array.isArray(select) || typeof select !== "object" || !select) return null;
 		const entries = Object.entries(select);
@@ -6572,7 +7712,11 @@ var QueryBuilder = class QueryBuilder {
 		const columns = this.tryBuildQuerySelectColumns();
 		const orderBy = this.tryBuildQueryOrderBy();
 		const condition = this.buildQueryWhereCondition(softDeleteOnly);
+		const relationFilters = this.tryBuildRelationFilterSpecs();
+		const relationAggregates = this.tryBuildRelationAggregateSpecs();
 		if (columns === null || orderBy === null || condition === null) return null;
+		if (this.hasRelationFilters() && this.canExecuteRelationFiltersInAdapter() && relationFilters === null) return null;
+		if (this.hasRelationAggregates() && this.canExecuteRelationAggregatesInAdapter() && relationAggregates === null) return null;
 		return {
 			target: this.buildQueryTarget(),
 			columns,
@@ -6580,15 +7724,20 @@ var QueryBuilder = class QueryBuilder {
 			orderBy,
 			limit: this.limitValue,
 			offset: this.offsetValue,
-			relationLoads: this.queryRelationLoads
+			relationLoads: this.queryRelationLoads,
+			relationFilters: this.canExecuteRelationFiltersInAdapter() ? relationFilters ?? void 0 : void 0,
+			relationAggregates: this.canExecuteRelationAggregatesInAdapter() ? relationAggregates ?? void 0 : void 0
 		};
 	}
 	tryBuildAggregateSpec() {
 		const condition = this.buildQueryWhereCondition(false);
+		const relationFilters = this.tryBuildRelationFilterSpecs();
 		if (condition === null) return null;
+		if (this.hasRelationFilters() && this.canExecuteRelationFiltersInAdapter() && relationFilters === null) return null;
 		return {
 			target: this.buildQueryTarget(),
 			where: condition,
+			relationFilters: this.canExecuteRelationFiltersInAdapter() ? relationFilters ?? void 0 : void 0,
 			aggregate: { type: "count" }
 		};
 	}
@@ -6658,6 +7807,14 @@ var QueryBuilder = class QueryBuilder {
 		}
 		return inserted;
 	}
+	async executeUpsertRows(values, uniqueBy, updateColumns) {
+		const adapter = this.requireAdapter();
+		if (typeof adapter.upsert !== "function") throw new UnsupportedAdapterFeatureException("Upsert is not supported by the current adapter.", {
+			operation: "query.upsert",
+			model: this.model.name
+		});
+		return await adapter.upsert(this.tryBuildUpsertSpec(values, uniqueBy, updateColumns));
+	}
 	async executeUpdateRow(where, values) {
 		const adapter = this.requireAdapter();
 		const spec = this.tryBuildUpdateSpec(where, values);
@@ -6786,6 +7943,71 @@ var QueryBuilder = class QueryBuilder {
 	hasRelationAggregates() {
 		return this.relationAggregates.length > 0;
 	}
+	canExecuteRelationFiltersInAdapter() {
+		const adapter = this.adapter;
+		if (!this.hasRelationFilters()) return false;
+		return adapter?.capabilities?.relationFilters === true && this.tryBuildRelationFilterSpecs() !== null;
+	}
+	canExecuteRelationAggregatesInAdapter() {
+		const adapter = this.adapter;
+		if (!this.hasRelationAggregates()) return false;
+		return adapter?.capabilities?.relationAggregates === true && this.tryBuildRelationAggregateSpecs() !== null;
+	}
+	canExecuteRelationFeaturesInAdapter() {
+		const filtersSupported = !this.hasRelationFilters() || this.canExecuteRelationFiltersInAdapter();
+		const aggregatesSupported = !this.hasRelationAggregates() || this.canExecuteRelationAggregatesInAdapter();
+		return filtersSupported && aggregatesSupported;
+	}
+	tryBuildRelationFilterSpecs() {
+		return this.relationFilters.reduce((specs, filter) => {
+			if (!specs) return null;
+			const metadata = this.model.getRelationMetadata(filter.relation);
+			if (!this.isSqlRelationFeatureMetadata(metadata)) return null;
+			const where = this.tryBuildRelationConstraintWhere(filter.relation, filter.callback);
+			if (where === null) return null;
+			specs.push({
+				relation: filter.relation,
+				operator: filter.operator,
+				count: filter.count,
+				boolean: filter.boolean,
+				where
+			});
+			return specs;
+		}, []);
+	}
+	tryBuildRelationAggregateSpecs() {
+		return this.relationAggregates.reduce((specs, aggregate) => {
+			if (!specs) return null;
+			const metadata = this.model.getRelationMetadata(aggregate.relation);
+			if (!this.isSqlRelationFeatureMetadata(metadata)) return null;
+			const where = this.tryBuildRelationConstraintWhere(aggregate.relation);
+			if (where === null) return null;
+			specs.push({
+				relation: aggregate.relation,
+				type: aggregate.type,
+				column: aggregate.column,
+				alias: this.buildAggregateAttributeKey(aggregate),
+				where
+			});
+			return specs;
+		}, []);
+	}
+	tryBuildRelationConstraintWhere(relation, callback) {
+		const metadata = this.model.getRelationMetadata(relation);
+		if (!this.isSqlRelationFeatureMetadata(metadata)) return null;
+		const relatedQuery = metadata?.relatedModel.query();
+		if (!relatedQuery) return null;
+		if (callback) {
+			const constrained = callback(relatedQuery);
+			if (constrained && constrained !== relatedQuery) return null;
+		}
+		if (relatedQuery.hasRelationFilters() || relatedQuery.hasRelationAggregates() || relatedQuery.queryRelationLoads || relatedQuery.querySelect || relatedQuery.queryOrderBy || relatedQuery.offsetValue !== void 0 || relatedQuery.limitValue !== void 0 || relatedQuery.randomOrderEnabled) return null;
+		return relatedQuery.buildQueryWhereCondition(false);
+	}
+	isSqlRelationFeatureMetadata(metadata) {
+		if (!metadata) return false;
+		return metadata.type === "hasMany" || metadata.type === "hasOne" || metadata.type === "belongsTo" || metadata.type === "belongsToMany" || metadata.type === "hasOneThrough" || metadata.type === "hasManyThrough";
+	}
 	async filterModelsByRelationConstraints(models, relationCache, baseIds) {
 		return (await Promise.all(models.map(async (model) => {
 			let result = null;
@@ -6942,6 +8164,7 @@ var QueryBuilder = class QueryBuilder {
 */
 var Model = class Model {
 	static lifecycleStates = /* @__PURE__ */ new WeakMap();
+	static emittedDeprecationWarnings = /* @__PURE__ */ new Set();
 	static eventsSuppressed = 0;
 	static factoryClass;
 	static adapter;
@@ -6985,12 +8208,24 @@ var Model = class Model {
 			}
 		});
 	}
+	static emitDeprecationWarning(code, message) {
+		if (Model.emittedDeprecationWarnings.has(code)) return;
+		Model.emittedDeprecationWarnings.add(code);
+		process.emitWarning(message, {
+			type: "DeprecationWarning",
+			code
+		});
+	}
 	/**
-	* Set the Prisma client delegates for all models. 
-	* 
-	* @param client 
+	* Set the Prisma client delegates for all models.
+	*
+	* @deprecated Use Model.setAdapter(createPrismaDatabaseAdapter(...)) or another
+	* adapter-first bootstrap path instead.
+	*
+	* @param client
 	*/
 	static setClient(client) {
+		Model.emitDeprecationWarning("ARKORM_SET_CLIENT_DEPRECATED", "Model.setClient() is deprecated and will be removed in Arkorm 3.0. Use Model.setAdapter(createPrismaDatabaseAdapter(...)) or another adapter-first setup path instead.");
 		this.client = client;
 	}
 	static setAdapter(adapter) {
@@ -7223,6 +8458,8 @@ var Model = class Model {
 	static getAdapter() {
 		ensureArkormConfigLoading();
 		if (this.adapter) return this.adapter;
+		const runtimeAdapter = getRuntimeAdapter();
+		if (runtimeAdapter) return runtimeAdapter;
 		const client = getActiveTransactionClient() ?? this.client ?? getRuntimePrismaClient();
 		if (!client || typeof client !== "object") return void 0;
 		return createPrismaCompatibilityAdapter(client);
@@ -7527,14 +8764,11 @@ var Model = class Model {
 	*/
 	async load(relations) {
 		const relationMap = this.normalizeRelationMap(relations);
-		await Promise.all(Object.entries(relationMap).map(async ([name, constraint]) => {
-			const resolver = this[name];
-			if (typeof resolver !== "function") return;
-			const relation = resolver.call(this);
-			if (constraint) relation.constrain(constraint);
-			const results = await relation.getResults();
-			this.attributes[name] = results;
-		}));
+		await new SetBasedEagerLoader([this], relationMap).load();
+		return this;
+	}
+	setLoadedRelation(name, value) {
+		this.attributes[name] = value;
 		return this;
 	}
 	/**
@@ -8016,4 +9250,4 @@ var Model = class Model {
 };
 
 //#endregion
-export { ArkormCollection, ArkormException, Attribute, CliApp, EnumBuilder, ForeignKeyBuilder, InitCommand, InlineFactory, KyselyDatabaseAdapter, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, MissingDelegateException, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_ENUM_MEMBER_REGEX, PRISMA_ENUM_REGEX, PRISMA_MODEL_REGEX, Paginator, PrismaDatabaseAdapter, QueryBuilder, QueryConstraintException, RelationResolutionException, RuntimeModuleLoader, SEEDER_BRAND, SchemaBuilder, ScopeNotDefinedException, SeedCommand, Seeder, TableBuilder, URLDriver, UniqueConstraintResolutionException, UnsupportedAdapterFeatureException, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, buildEnumBlock, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createKyselyAdapter, createMigrationTimestamp, createPrismaAdapter, createPrismaCompatibilityAdapter, createPrismaDatabaseAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationAlias, deriveRelationFieldName, deriveSingularFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findEnumBlock, findModelBlock, formatDefaultValue, formatEnumDefaultValue, formatRelationAction, generateMigrationFile, getActiveTransactionClient, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, isTransactionCapableClient, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveEnumName, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runArkormTransaction, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };
+export { ArkormCollection, ArkormException, Attribute, CliApp, EnumBuilder, ForeignKeyBuilder, InitCommand, InlineFactory, KyselyDatabaseAdapter, LengthAwarePaginator, MIGRATION_BRAND, MakeFactoryCommand, MakeMigrationCommand, MakeModelCommand, MakeSeederCommand, MigrateCommand, MigrateRollbackCommand, Migration, MigrationHistoryCommand, MissingDelegateException, Model, ModelFactory, ModelNotFoundException, ModelsSyncCommand, PRISMA_ENUM_MEMBER_REGEX, PRISMA_ENUM_REGEX, PRISMA_MODEL_REGEX, Paginator, PrismaDatabaseAdapter, QueryBuilder, QueryConstraintException, RelationResolutionException, RuntimeModuleLoader, SEEDER_BRAND, SchemaBuilder, ScopeNotDefinedException, SeedCommand, Seeder, TableBuilder, URLDriver, UniqueConstraintResolutionException, UnsupportedAdapterFeatureException, applyAlterTableOperation, applyCreateTableOperation, applyDropTableOperation, applyMigrationRollbackToPrismaSchema, applyMigrationToPrismaSchema, applyOperationsToPrismaSchema, bindAdapterToModels, buildEnumBlock, buildFieldLine, buildIndexLine, buildInverseRelationLine, buildMigrationIdentity, buildMigrationRunId, buildMigrationSource, buildModelBlock, buildRelationLine, computeMigrationChecksum, configureArkormRuntime, createKyselyAdapter, createMigrationTimestamp, createPrismaAdapter, createPrismaCompatibilityAdapter, createPrismaDatabaseAdapter, createPrismaDelegateMap, defineConfig, defineFactory, deriveCollectionFieldName, deriveInverseRelationAlias, deriveRelationAlias, deriveRelationFieldName, deriveSingularFieldName, ensureArkormConfigLoading, escapeRegex, findAppliedMigration, findEnumBlock, findModelBlock, formatDefaultValue, formatEnumDefaultValue, formatRelationAction, generateMigrationFile, getActiveTransactionClient, getDefaultStubsPath, getLastMigrationRun, getLatestAppliedMigrations, getMigrationPlan, getRuntimeAdapter, getRuntimePaginationCurrentPageResolver, getRuntimePaginationURLDriverFactory, getRuntimePrismaClient, getUserConfig, inferDelegateName, isDelegateLike, isMigrationApplied, isTransactionCapableClient, loadArkormConfig, markMigrationApplied, markMigrationRun, pad, readAppliedMigrationsState, removeAppliedMigration, resetArkormRuntimeForTests, resolveCast, resolveEnumName, resolveMigrationClassName, resolveMigrationStateFilePath, resolvePrismaType, runArkormTransaction, runMigrationWithPrisma, runPrismaCommand, toMigrationFileSlug, toModelName, writeAppliedMigrationsState };