arkormx 2.6.0 → 2.7.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_relationship = require('./relationship-D9u7BlWh.cjs');
+const require_relationship = require('./relationship-B8FaJYIx.cjs');
 let pg = require("pg");
 let node_path = require("node:path");
 let module$1 = require("module");
@@ -64,7 +64,8 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 			rawSelect: true,
 			rawWhere: true,
 			distinct: true,
-			groupBy: true
+			groupBy: true,
+			joins: true
 		};
 	}
 	resolveConfiguredDatabaseName(connectionString) {
@@ -89,6 +90,85 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	quoteIdentifier(value) {
 		return `"${value.replace(/"/g, "\"\"")}"`;
 	}
+	/**
+	* Wraps bare camelCase identifiers in a fragment of raw SQL with double quotes
+	* so PostgreSQL preserves their casing instead of folding them to lower case.
+	*
+	* Identifiers that are already quoted, string literals, dollar-quoted bodies,
+	* comments and function names (a camelCase token immediately followed by `(`)
+	* are left untouched. Lower-case identifiers are also left alone since
+	* PostgreSQL folds them to the same value with or without quotes.
+	*
+	* @param sql The raw SQL fragment to normalize.
+	* @returns
+	*/
+	quoteCamelCaseIdentifiers(sql) {
+		let result = "";
+		let index = 0;
+		const isIdentifierStart = (char) => /[A-Za-z_]/.test(char);
+		const isIdentifierPart = (char) => /[A-Za-z0-9_$]/.test(char);
+		const isMixedCase = (token) => /[A-Z]/.test(token) && /[a-z]/.test(token);
+		while (index < sql.length) {
+			const char = sql[index];
+			if (char === "'") {
+				const start = index;
+				index += 1;
+				while (index < sql.length) {
+					if (sql[index] === "'" && sql[index + 1] === "'") {
+						index += 2;
+						continue;
+					}
+					if (sql[index] === "'") {
+						index += 1;
+						break;
+					}
+					index += 1;
+				}
+				result += sql.slice(start, index);
+				continue;
+			}
+			if (char === "\"") {
+				const start = index;
+				index += 1;
+				while (index < sql.length) {
+					if (sql[index] === "\"" && sql[index + 1] === "\"") {
+						index += 2;
+						continue;
+					}
+					if (sql[index] === "\"") {
+						index += 1;
+						break;
+					}
+					index += 1;
+				}
+				result += sql.slice(start, index);
+				continue;
+			}
+			if (char === "$") {
+				const tagMatch = /^\$[A-Za-z0-9_]*\$/.exec(sql.slice(index));
+				if (tagMatch) {
+					const tag = tagMatch[0];
+					const closeIndex = sql.indexOf(tag, index + tag.length);
+					const end = closeIndex === -1 ? sql.length : closeIndex + tag.length;
+					result += sql.slice(index, end);
+					index = end;
+					continue;
+				}
+			}
+			if (isIdentifierStart(char)) {
+				const start = index;
+				while (index < sql.length && isIdentifierPart(sql[index])) index += 1;
+				const token = sql.slice(start, index);
+				const isFunctionCall = sql[index] === "(";
+				if (isMixedCase(token) && !isFunctionCall) result += this.quoteIdentifier(token);
+				else result += token;
+				continue;
+			}
+			result += char;
+			index += 1;
+		}
+		return result;
+	}
 	quoteLiteral(value) {
 		if (value == null) return "null";
 		if (typeof value === "number" || typeof value === "bigint") return String(value);
@@ -108,10 +188,102 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	async executeRawStatement(statement, executor = this.db) {
 		await kysely.sql.raw(statement).execute(executor);
 	}
+	/**
+	* Splits a SQL script into individual top-level statements.
+	*
+	* The PostgreSQL wire protocol used by Kysely rejects scripts that contain
+	* more than one command, so multi-statement raw SQL (for example a migration
+	* that mixes `do $$ ... $$` blocks with `alter table` statements) must be
+	* executed one statement at a time. Semicolons inside single-quoted strings,
+	* double-quoted identifiers, dollar-quoted bodies and comments are ignored.
+	*
+	* @param sql The raw SQL script to split.
+	* @returns
+	*/
+	splitSqlStatements(sql) {
+		const statements = [];
+		let current = "";
+		let index = 0;
+		while (index < sql.length) {
+			const char = sql[index];
+			const next = sql[index + 1];
+			if (char === "-" && next === "-") {
+				const end = sql.indexOf("\n", index);
+				const stop = end === -1 ? sql.length : end;
+				current += sql.slice(index, stop);
+				index = stop;
+				continue;
+			}
+			if (char === "/" && next === "*") {
+				const end = sql.indexOf("*/", index + 2);
+				const stop = end === -1 ? sql.length : end + 2;
+				current += sql.slice(index, stop);
+				index = stop;
+				continue;
+			}
+			if (char === "'") {
+				const start = index;
+				index += 1;
+				while (index < sql.length) {
+					if (sql[index] === "'" && sql[index + 1] === "'") {
+						index += 2;
+						continue;
+					}
+					if (sql[index] === "'") {
+						index += 1;
+						break;
+					}
+					index += 1;
+				}
+				current += sql.slice(start, index);
+				continue;
+			}
+			if (char === "\"") {
+				const start = index;
+				index += 1;
+				while (index < sql.length) {
+					if (sql[index] === "\"" && sql[index + 1] === "\"") {
+						index += 2;
+						continue;
+					}
+					if (sql[index] === "\"") {
+						index += 1;
+						break;
+					}
+					index += 1;
+				}
+				current += sql.slice(start, index);
+				continue;
+			}
+			if (char === "$") {
+				const tagMatch = /^\$[A-Za-z0-9_]*\$/.exec(sql.slice(index));
+				if (tagMatch) {
+					const tag = tagMatch[0];
+					const closeIndex = sql.indexOf(tag, index + tag.length);
+					const end = closeIndex === -1 ? sql.length : closeIndex + tag.length;
+					current += sql.slice(index, end);
+					index = end;
+					continue;
+				}
+			}
+			if (char === ";") {
+				if (current.trim().length > 0) statements.push(current.trim());
+				current = "";
+				index += 1;
+				continue;
+			}
+			current += char;
+			index += 1;
+		}
+		if (current.trim().length > 0) statements.push(current.trim());
+		return statements;
+	}
 	async rawQuery(spec) {
 		const statement = this.interpolateRawSql(spec.sql, spec.bindings);
+		const statements = this.splitSqlStatements(statement);
+		if (statements.length > 1) return await this.runMultiStatementRawQuery(statements, statement);
 		try {
-			return (await kysely.sql.raw(statement).execute(this.db)).rows ?? [];
+			return (await kysely.sql.raw(statements[0] ?? statement).execute(this.db)).rows ?? [];
 		} catch (error) {
 			throw new QueryExecutionException("Raw query execution failed for the Kysely adapter.", {
 				code: "QUERY_EXECUTION_FAILED",
@@ -123,6 +295,45 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 			});
 		}
 	}
+	/**
+	* Executes a multi-statement raw SQL script one statement at a time.
+	*
+	* Each statement is sent individually so the PostgreSQL extended protocol
+	* accepts it, and the rows of the last statement that returns any are used as
+	* the result. The script is wrapped in a transaction when the adapter is not
+	* already operating inside one so partial failures do not leave the database
+	* in a half-applied state.
+	*
+	* @param statements The individual statements to execute in order.
+	* @param fullScript The original (joined) script, used for error context.
+	* @returns
+	*/
+	async runMultiStatementRawQuery(statements, fullScript) {
+		const execute = async (executor) => {
+			let rows = [];
+			for (const statement of statements) {
+				const result = await kysely.sql.raw(statement).execute(executor);
+				if (result.rows && result.rows.length > 0) rows = result.rows;
+			}
+			return rows;
+		};
+		try {
+			if (!this.db.isTransaction) return await this.db.transaction().execute((transaction) => execute(transaction));
+			return await execute(this.db);
+		} catch (error) {
+			throw new QueryExecutionException("Raw query execution failed for the Kysely adapter.", {
+				code: "QUERY_EXECUTION_FAILED",
+				operation: "adapter.rawQuery",
+				delegate: "raw",
+				inspection: this.tryInspectRawQuery(fullScript),
+				meta: {
+					sql: fullScript,
+					statements
+				},
+				cause: error
+			});
+		}
+	}
 	tryInspectRawQuery(statement) {
 		return {
 			adapter: "kysely",
@@ -404,6 +615,70 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		if (!groupBy || groupBy.length === 0) return kysely.sql``;
 		return kysely.sql` group by ${kysely.sql.join(groupBy.map((column) => kysely.sql.ref(this.mapColumn(target, column))), kysely.sql`, `)}`;
 	}
+	buildJoinClause(target, joins) {
+		if (!joins || joins.length === 0) return kysely.sql``;
+		return kysely.sql` ${kysely.sql.join(joins.map((join) => this.buildSingleJoin(target, join)), kysely.sql` `)}`;
+	}
+	joinKeyword(join) {
+		const base = {
+			inner: "inner join",
+			left: "left join",
+			right: "right join",
+			full: "full join",
+			cross: "cross join"
+		}[join.type];
+		return join.lateral ? `${base} lateral` : base;
+	}
+	buildJoinSource(join) {
+		if (join.subquery) {
+			const subquery = this.buildSelectStatement(join.subquery);
+			return join.alias ? kysely.sql`(${subquery}) as ${kysely.sql.id(join.alias)}` : kysely.sql`(${subquery})`;
+		}
+		if (join.subquerySql) return join.alias ? kysely.sql`(${kysely.sql.raw(join.subquerySql)}) as ${kysely.sql.id(join.alias)}` : kysely.sql.raw(`(${join.subquerySql})`);
+		const table = this.resolveMappedTable(join.table ?? "");
+		return join.alias ? kysely.sql`${kysely.sql.table(table)} as ${kysely.sql.id(join.alias)}` : kysely.sql.table(table);
+	}
+	buildSingleJoin(target, join) {
+		const keyword = kysely.sql.raw(this.joinKeyword(join));
+		const source = this.buildJoinSource(join);
+		if (join.type === "cross") return kysely.sql`${keyword} ${source}`;
+		if (join.constraints.length === 0) return join.lateral ? kysely.sql`${keyword} ${source} on true` : kysely.sql`${keyword} ${source}`;
+		return kysely.sql`${keyword} ${source} on ${this.buildJoinConstraints(target, join.constraints)}`;
+	}
+	buildJoinConstraints(target, constraints) {
+		const parts = [];
+		constraints.forEach((constraint, index) => {
+			if (index > 0) parts.push(kysely.sql.raw(` ${constraint.boolean} `));
+			parts.push(this.buildJoinConstraint(target, constraint));
+		});
+		return kysely.sql`${kysely.sql.join(parts, kysely.sql``)}`;
+	}
+	buildJoinConstraint(target, constraint) {
+		if (constraint.type === "column") return kysely.sql`${kysely.sql.ref(constraint.first)} ${kysely.sql.raw(constraint.operator)} ${kysely.sql.ref(constraint.second)}`;
+		if (constraint.type === "null") return constraint.not ? kysely.sql`${kysely.sql.ref(constraint.column)} is not null` : kysely.sql`${kysely.sql.ref(constraint.column)} is null`;
+		if (constraint.type === "raw") return this.buildRawWhereCondition({
+			type: "raw",
+			sql: constraint.sql,
+			bindings: constraint.bindings
+		});
+		if (constraint.type === "nested") return kysely.sql`(${this.buildJoinConstraints(target, constraint.constraints)})`;
+		const column = kysely.sql.ref(constraint.column);
+		const operator = constraint.operator;
+		if (operator === "is-null") return kysely.sql`${column} is null`;
+		if (operator === "is-not-null") return kysely.sql`${column} is not null`;
+		if (operator === "in") {
+			const values = this.buildConditionValueList(constraint.value);
+			return values.length === 0 ? kysely.sql`1 = 0` : kysely.sql`${column} in (${kysely.sql.join(values)})`;
+		}
+		if (operator === "not-in") {
+			const values = this.buildConditionValueList(constraint.value);
+			return values.length === 0 ? kysely.sql`1 = 1` : kysely.sql`${column} not in (${kysely.sql.join(values)})`;
+		}
+		if (operator === "contains") return kysely.sql`${column} like ${`%${String(constraint.value ?? "")}%`}`;
+		if (operator === "starts-with") return kysely.sql`${column} like ${`${String(constraint.value ?? "")}%`}`;
+		if (operator === "ends-with") return kysely.sql`${column} like ${`%${String(constraint.value ?? "")}`}`;
+		return kysely.sql`${column} ${kysely.sql.raw(operator)} ${constraint.value}`;
+	}
 	buildConditionValueList(value) {
 		if (Array.isArray(value)) return value;
 		return typeof value === "undefined" ? [] : [value];
@@ -433,7 +708,7 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		if (segments.length !== bindings.length + 1) throw new require_relationship.ArkormException("Raw where bindings do not match the number of placeholders.");
 		const parts = [];
 		segments.forEach((segment, index) => {
-			if (segment.length > 0) parts.push(kysely.sql.raw(segment));
+			if (segment.length > 0) parts.push(kysely.sql.raw(this.quoteCamelCaseIdentifiers(segment)));
 			if (index < bindings.length) parts.push(kysely.sql`${bindings[index]}`);
 		});
 		if (parts.length === 0) return kysely.sql`1 = 1`;
@@ -697,6 +972,7 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             select ${spec.distinct ? kysely.sql`distinct ` : kysely.sql``}${this.buildSelectList(spec.target, spec.columns)}
             ${this.buildRelationAggregateSelectList(spec.target, spec.relationAggregates)}
             from ${kysely.sql.table(this.resolveTable(spec.target))}
+            ${this.buildJoinClause(spec.target, spec.joins)}
             ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
             ${this.buildGroupBy(spec.target, spec.groupBy)}
             ${this.buildOrderBy(spec.target, spec.orderBy)}
@@ -707,6 +983,7 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		return kysely.sql`
             select count(*)::int as count
             from ${kysely.sql.table(this.resolveTable(spec.target))}
+            ${this.buildJoinClause(spec.target, spec.joins)}
             ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
         `;
 	}
@@ -715,6 +992,7 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
             select exists(
                 select 1
                 from ${kysely.sql.table(this.resolveTable(spec.target))}
+                ${this.buildJoinClause(spec.target, spec.joins)}
                 ${this.buildCombinedWhereClause(spec.target, spec.where, spec.relationFilters)}
                 ${this.buildGroupBy(spec.target, spec.groupBy)}
                 limit 1
@@ -1446,6 +1724,10 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			operation: "adapter.select",
 			meta: { feature: "groupBy" }
 		});
+		if (spec.joins?.length) throw new require_relationship.UnsupportedAdapterFeatureException("Join clauses are not supported by the Prisma compatibility adapter; use a SQL-backed adapter or DB.raw().", {
+			operation: "adapter.select",
+			meta: { feature: "joins" }
+		});
 		return {
 			include: this.toQueryInclude(spec.relationLoads),
 			where: this.toQueryWhere(spec.where),
@@ -3800,6 +4082,204 @@ const resolveRuntimeCompatibilityQuerySchemaOrThrow = (key, candidates, modelNam
 	return resolved;
 };
 
+//#endregion
+//#region src/JoinClause.ts
+/**
+* A fluent builder for the `on`/`where` constraints of a join clause.
+*
+* Instances are handed to the closure form of the query builder join helpers
+* (for example `query.join('posts', join => join.on(...).where(...))`) and
+* mirror Laravel's `JoinClause` surface. Column identifiers are treated as raw
+* database identifiers (qualify them as `table.column` when needed).
+*
+* @author Legacy (3m1n3nc3)
+*/
+var JoinClause = class JoinClause {
+	constructor() {
+		this.constraints = [];
+	}
+	/**
+	* Adds a column-to-column `on` constraint, joined with `and`.
+	*
+	* Accepts either a closure (for a nested group) or a column comparison in
+	* the `(first, second)` or `(first, operator, second)` form.
+	*
+	* @param first    The left-hand column or a nested closure.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	on(first, operator, second) {
+		return this.addOn("and", first, operator, second);
+	}
+	/**
+	* Adds a column-to-column `on` constraint, joined with `or`.
+	*
+	* @param first    The left-hand column or a nested closure.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	orOn(first, operator, second) {
+		return this.addOn("or", first, operator, second);
+	}
+	/**
+	* Adds a column-to-value constraint, joined with `and`.
+	*
+	* @param column   The column being compared.
+	* @param operator The comparison operator or the value when omitted.
+	* @param value    The value to compare against.
+	* @returns
+	*/
+	where(column, operator, value) {
+		return this.addWhere("and", column, operator, value);
+	}
+	/**
+	* Adds a column-to-value constraint, joined with `or`.
+	*
+	* @param column   The column being compared.
+	* @param operator The comparison operator or the value when omitted.
+	* @param value    The value to compare against.
+	* @returns
+	*/
+	orWhere(column, operator, value) {
+		return this.addWhere("or", column, operator, value);
+	}
+	/**
+	* Adds an `is null` constraint joined with `and`.
+	*
+	* @param column The column to test for null.
+	* @returns
+	*/
+	whereNull(column) {
+		this.constraints.push({
+			type: "null",
+			boolean: "and",
+			column,
+			not: false
+		});
+		return this;
+	}
+	/**
+	* Adds an `is null` constraint joined with `or`.
+	*
+	* @param column The column to test for null.
+	* @returns
+	*/
+	orWhereNull(column) {
+		this.constraints.push({
+			type: "null",
+			boolean: "or",
+			column,
+			not: false
+		});
+		return this;
+	}
+	/**
+	* Adds an `is not null` constraint joined with `and`.
+	*
+	* @param column The column to test for non-null.
+	* @returns
+	*/
+	whereNotNull(column) {
+		this.constraints.push({
+			type: "null",
+			boolean: "and",
+			column,
+			not: true
+		});
+		return this;
+	}
+	/**
+	* Adds an `is not null` constraint joined with `or`.
+	*
+	* @param column The column to test for non-null.
+	* @returns
+	*/
+	orWhereNotNull(column) {
+		this.constraints.push({
+			type: "null",
+			boolean: "or",
+			column,
+			not: true
+		});
+		return this;
+	}
+	/**
+	* Adds a raw constraint joined with `and`.
+	*
+	* @param sql      The raw SQL fragment (with `?` placeholders for bindings).
+	* @param bindings The values bound to the placeholders.
+	* @returns
+	*/
+	onRaw(sql, bindings = []) {
+		this.constraints.push({
+			type: "raw",
+			boolean: "and",
+			sql,
+			bindings
+		});
+		return this;
+	}
+	/**
+	* Adds a raw constraint joined with `or`.
+	*
+	* @param sql      The raw SQL fragment (with `?` placeholders for bindings).
+	* @param bindings The values bound to the placeholders.
+	* @returns
+	*/
+	orOnRaw(sql, bindings = []) {
+		this.constraints.push({
+			type: "raw",
+			boolean: "or",
+			sql,
+			bindings
+		});
+		return this;
+	}
+	/**
+	* Returns the accumulated constraints for this join clause.
+	*
+	* @returns
+	*/
+	getConstraints() {
+		return this.constraints;
+	}
+	addOn(boolean, first, operator, second) {
+		if (typeof first === "function") {
+			const nested = new JoinClause();
+			first(nested);
+			this.constraints.push({
+				type: "nested",
+				boolean,
+				constraints: nested.getConstraints()
+			});
+			return this;
+		}
+		const [resolvedOperator, resolvedSecond] = second === void 0 ? ["=", operator] : [operator, second];
+		if (typeof resolvedSecond !== "string") throw new Error("A join \"on\" constraint requires a second column.");
+		this.constraints.push({
+			type: "column",
+			boolean,
+			first,
+			operator: resolvedOperator ?? "=",
+			second: resolvedSecond
+		});
+		return this;
+	}
+	addWhere(boolean, column, operator, value) {
+		const [resolvedOperator, resolvedValue] = value === void 0 ? ["=", operator] : [operator, value];
+		this.constraints.push({
+			type: "value",
+			boolean,
+			column,
+			operator: resolvedOperator ?? "=",
+			value: resolvedValue
+		});
+		return this;
+	}
+};
+
 //#endregion
 //#region src/Exceptions/ModelNotFoundException.ts
 /**
@@ -4771,7 +5251,248 @@ var QueryBuilder = class QueryBuilder {
 		return this;
 	}
 	/**
-	* Adds a skip clause to the query for pagination. 
+	* Adds a join clause to the query.
+	*
+	* The `first`/`second` arguments are treated as raw database identifiers, so
+	* qualify them as `table.column` when needed. Pass a closure as `first` to
+	* build a compound `on` condition through a {@link JoinClause}.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @param type     The join type (defaults to `inner`).
+	* @returns
+	*/
+	join(table, first, operator, second, type = "inner") {
+		return this.addJoin(type, table, first, operator, second);
+	}
+	/**
+	* Adds an inner join clause to the query.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	innerJoin(table, first, operator, second) {
+		return this.addJoin("inner", table, first, operator, second);
+	}
+	/**
+	* Adds a left join clause to the query.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	leftJoin(table, first, operator, second) {
+		return this.addJoin("left", table, first, operator, second);
+	}
+	/**
+	* Adds a right join clause to the query.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	rightJoin(table, first, operator, second) {
+		return this.addJoin("right", table, first, operator, second);
+	}
+	/**
+	* Adds a cross join clause to the query.
+	*
+	* When a `first` column (or closure) is supplied the cross join is promoted
+	* to an inner join with the given constraints, mirroring Laravel's behaviour.
+	*
+	* @param table The table (or aliased table) to join.
+	* @param first Optional column or closure to constrain the join.
+	* @returns
+	*/
+	crossJoin(table, first) {
+		if (first === void 0) return this.addJoin("cross", table);
+		return this.addJoin("inner", table, first);
+	}
+	/**
+	* Adds a join clause that compares a column to a value.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The column being compared.
+	* @param operator The comparison operator.
+	* @param value    The value to compare against.
+	* @param type     The join type (defaults to `inner`).
+	* @returns
+	*/
+	joinWhere(table, first, operator, value, type = "inner") {
+		return this.addJoinWhere(type, table, first, operator, value);
+	}
+	/**
+	* Adds a left join clause that compares a column to a value.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The column being compared.
+	* @param operator The comparison operator.
+	* @param value    The value to compare against.
+	* @returns
+	*/
+	leftJoinWhere(table, first, operator, value) {
+		return this.addJoinWhere("left", table, first, operator, value);
+	}
+	/**
+	* Adds a right join clause that compares a column to a value.
+	*
+	* @param table    The table (or aliased table) to join.
+	* @param first    The column being compared.
+	* @param operator The comparison operator.
+	* @param value    The value to compare against.
+	* @returns
+	*/
+	rightJoinWhere(table, first, operator, value) {
+		return this.addJoinWhere("right", table, first, operator, value);
+	}
+	/**
+	* Adds a subquery join clause to the query.
+	*
+	* @param query    The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias    The alias assigned to the subquery.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @param type     The join type (defaults to `inner`).
+	* @returns
+	*/
+	joinSub(query, alias, first, operator, second, type = "inner") {
+		return this.addJoinSub(type, query, alias, first, operator, second);
+	}
+	/**
+	* Adds a subquery left join clause to the query.
+	*
+	* @param query    The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias    The alias assigned to the subquery.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	leftJoinSub(query, alias, first, operator, second) {
+		return this.addJoinSub("left", query, alias, first, operator, second);
+	}
+	/**
+	* Adds a subquery right join clause to the query.
+	*
+	* @param query    The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias    The alias assigned to the subquery.
+	* @param first    The left-hand column or a closure receiving a JoinClause.
+	* @param operator The comparison operator (defaults to `=`).
+	* @param second   The right-hand column.
+	* @returns
+	*/
+	rightJoinSub(query, alias, first, operator, second) {
+		return this.addJoinSub("right", query, alias, first, operator, second);
+	}
+	/**
+	* Adds a cross subquery join clause to the query.
+	*
+	* @param query The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias The alias assigned to the subquery.
+	* @returns
+	*/
+	crossJoinSub(query, alias) {
+		return this.addJoinSub("cross", query, alias);
+	}
+	/**
+	* Adds a lateral join clause to the query.
+	*
+	* @param query The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias The alias assigned to the subquery.
+	* @param type  The join type (defaults to `inner`).
+	* @returns
+	*/
+	joinLateral(query, alias, type = "inner") {
+		return this.addJoinSub(type, query, alias, void 0, void 0, void 0, true);
+	}
+	/**
+	* Adds a lateral left join clause to the query.
+	*
+	* @param query The subquery (a QueryBuilder instance or raw SQL string).
+	* @param alias The alias assigned to the subquery.
+	* @returns
+	*/
+	leftJoinLateral(query, alias) {
+		return this.addJoinSub("left", query, alias, void 0, void 0, void 0, true);
+	}
+	/**
+	* Builds a self-contained select specification used when this query is joined
+	* as a subquery by another query builder.
+	*
+	* @returns
+	*/
+	buildJoinSubquerySpec() {
+		const spec = this.tryBuildSelectSpec(this.buildWhere());
+		if (!spec) throw new require_relationship.UnsupportedAdapterFeatureException("Subquery join could not be compiled into an Arkorm select specification.", {
+			operation: "query.joinSub",
+			model: this.model.name
+		});
+		return spec;
+	}
+	guardJoinSupport() {
+		if (!this.adapter?.capabilities?.joins) throw new require_relationship.UnsupportedAdapterFeatureException("Join clauses are not supported by the current adapter.", {
+			operation: "join",
+			model: this.model.name,
+			meta: { feature: "joins" }
+		});
+	}
+	pushJoin(join) {
+		(this.queryJoins ??= []).push(join);
+	}
+	resolveJoinConstraints(first, operator, second) {
+		if (first === void 0) return [];
+		const clause = new JoinClause();
+		if (typeof first === "function") first(clause);
+		else clause.on(first, operator, second);
+		return clause.getConstraints();
+	}
+	resolveJoinSource(query) {
+		if (typeof query === "string") return { subquerySql: query };
+		return { subquery: query.buildJoinSubquerySpec() };
+	}
+	addJoin(type, table, first, operator, second) {
+		this.guardJoinSupport();
+		this.pushJoin({
+			type,
+			table,
+			constraints: this.resolveJoinConstraints(first, operator, second)
+		});
+		return this;
+	}
+	addJoinWhere(type, table, column, operator, value) {
+		this.guardJoinSupport();
+		const clause = new JoinClause();
+		clause.where(column, operator, value);
+		this.pushJoin({
+			type,
+			table,
+			constraints: clause.getConstraints()
+		});
+		return this;
+	}
+	addJoinSub(type, query, alias, first, operator, second, lateral = false) {
+		this.guardJoinSupport();
+		this.pushJoin({
+			type,
+			alias,
+			...this.resolveJoinSource(query),
+			...lateral ? { lateral: true } : {},
+			constraints: this.resolveJoinConstraints(first, operator, second)
+		});
+		return this;
+	}
+	/**
+	* Adds a skip clause to the query for pagination.
 	* This will overwrite any existing skip clause.
 	* 
 	* @param skip 
@@ -6026,6 +6747,7 @@ var QueryBuilder = class QueryBuilder {
 			columns,
 			distinct: this.queryDistinct || void 0,
 			groupBy: this.queryGroupBy ? [...this.queryGroupBy] : void 0,
+			joins: this.queryJoins ? [...this.queryJoins] : void 0,
 			where: condition,
 			orderBy,
 			limit: this.limitValue,
@@ -6042,6 +6764,7 @@ var QueryBuilder = class QueryBuilder {
 		if (this.hasRelationFilters() && this.canExecuteRelationFiltersInAdapter() && relationFilters === null) return null;
 		return {
 			target: this.buildQueryTarget(),
+			joins: this.queryJoins ? [...this.queryJoins] : void 0,
 			where: condition,
 			relationFilters: this.canExecuteRelationFiltersInAdapter() ? relationFilters ?? void 0 : void 0,
 			aggregate: { type: "count" }
@@ -8366,6 +9089,7 @@ exports.EnumBuilder = require_relationship.EnumBuilder;
 exports.ForeignKeyBuilder = require_relationship.ForeignKeyBuilder;
 exports.InitCommand = InitCommand;
 exports.InlineFactory = InlineFactory;
+exports.JoinClause = JoinClause;
 exports.KyselyDatabaseAdapter = KyselyDatabaseAdapter;
 exports.LengthAwarePaginator = require_relationship.LengthAwarePaginator;
 exports.MIGRATION_BRAND = MIGRATION_BRAND;