arkormx 2.6.1 → 2.8.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_relationship = require('./relationship-CxCQj_Pg.cjs');
+const require_relationship = require('./relationship-WiXlopzY.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 
@@ -4914,6 +5635,56 @@ var QueryBuilder = class QueryBuilder {
 		if (!model) throw new ModelNotFoundException(this.model.name, "Record not found.");
 		return model;
 	}
+	/**
+	* Returns the first record matching the given attributes or instantiates a
+	* new, unpersisted model populated with the merged attributes and values.
+	*
+	* @param attributes
+	* @param values
+	* @returns
+	*/
+	async firstOrNew(attributes, values = {}) {
+		const existing = await this.clone().where(attributes).first();
+		if (existing) return existing;
+		const ModelConstructor = this.model;
+		return new ModelConstructor({
+			...attributes,
+			...values
+		});
+	}
+	/**
+	* Returns the first record matching the given attributes or creates and
+	* persists a new record populated with the merged attributes and values.
+	*
+	* @param attributes
+	* @param values
+	* @returns
+	*/
+	async firstOrCreate(attributes, values = {}) {
+		const existing = await this.clone().where(attributes).first();
+		if (existing) return existing;
+		return await this.create({
+			...attributes,
+			...values
+		});
+	}
+	async firstOr(columnsOrCallback, maybeCallback) {
+		const callback = typeof columnsOrCallback === "function" ? columnsOrCallback : maybeCallback;
+		if (!callback) throw new QueryConstraintException("firstOr requires a fallback callback.", {
+			operation: "firstOr",
+			model: this.model.name
+		});
+		if (Array.isArray(columnsOrCallback) && columnsOrCallback.length > 0) {
+			const select = columnsOrCallback.reduce((all, column) => {
+				all[column] = true;
+				return all;
+			}, {});
+			this.select(select);
+		}
+		const found = await this.first();
+		if (found) return found;
+		return callback();
+	}
 	async find(value, key) {
 		const resolvedKey = key ?? this.model.getPrimaryKey();
 		return this.where({ [resolvedKey]: value }).first();
@@ -5123,6 +5894,23 @@ var QueryBuilder = class QueryBuilder {
 		}
 		return await this.clone().where(attributes).update(resolvedValues) != null;
 	}
+	/**
+	* Update the first record matching the given attributes, or create a new
+	* record populated with the merged attributes and values when none exists.
+	*
+	* @param attributes
+	* @param values
+	* @returns
+	*/
+	async updateOrCreate(attributes, values = {}) {
+		const existing = await this.clone().where(attributes).first();
+		if (!existing) return await this.create({
+			...attributes,
+			...values
+		});
+		if (Object.keys(values).length === 0) return existing;
+		return await this.clone().where(attributes).update(values);
+	}
 	shouldFallbackUpdateOrInsertUpsert(error) {
 		if (!(error instanceof QueryExecutionException)) return false;
 		const cause = error.cause;
@@ -5174,13 +5962,25 @@ var QueryBuilder = class QueryBuilder {
 		if (!this.isUniqueWhere(where) && directSpec && typeof adapter.deleteFirst === "function") {
 			const deleted = await adapter.deleteFirst(directSpec);
 			if (!deleted) return null;
-			return this.model.hydrate(deleted);
+			return this.hydrateDeleted(deleted);
 		}
 		const uniqueWhere = await this.resolveUniqueWhere(where, false);
 		if (!uniqueWhere) return null;
 		const deleted = await this.executeDeleteRow(uniqueWhere, false);
 		if (!deleted) return null;
-		return this.model.hydrate(deleted);
+		return this.hydrateDeleted(deleted);
+	}
+	/**
+	* Hydrate a row that was just deleted, marking the resulting model as no
+	* longer existing in the database.
+	*
+	* @param attributes
+	* @returns
+	*/
+	hydrateDeleted(attributes) {
+		const model = this.model.hydrate(attributes);
+		model.exists = false;
+		return model;
 	}
 	/**
 	* Deletes the first record matching the current query constraints and throws
@@ -6026,6 +6826,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 +6843,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" }
@@ -6547,9 +7349,12 @@ var Model = class Model {
 		this.hidden = [];
 		this.visible = [];
 		this.appends = [];
+		this.exists = false;
+		this.wasRecentlyCreated = false;
 		this.attributes = {};
 		this.original = {};
 		this.changes = {};
+		this.previous = {};
 		this.touchedAttributes = /* @__PURE__ */ new Set();
 		this.fill(attributes);
 		return new Proxy(this, {
@@ -6909,6 +7714,68 @@ var Model = class Model {
 		return this.query().scope(name, ...args);
 	}
 	/**
+	* Start a query constrained by the given where clause.
+	*
+	* @param this
+	* @param where
+	* @returns
+	*/
+	static where(where) {
+		return this.query().where(where);
+	}
+	/**
+	* Retrieve all records for the model.
+	*
+	* @param this
+	* @returns
+	*/
+	static async all() {
+		return await this.query().get();
+	}
+	/**
+	* Create and persist a new record, returning the hydrated model instance.
+	*
+	* @param this
+	* @param data
+	* @returns
+	*/
+	static async create(data) {
+		return await this.query().create(data);
+	}
+	/**
+	* Insert new records or update existing records by one or more unique keys.
+	*
+	* @param this
+	* @param values
+	* @param uniqueBy
+	* @param update
+	* @returns
+	*/
+	static async upsert(values, uniqueBy, update = null) {
+		return await this.query().upsert(values, uniqueBy, update);
+	}
+	/**
+	* Delete records by their primary key(s), dispatching model events for each
+	* matched record. Returns the number of records deleted.
+	*
+	* @param this
+	* @param ids
+	* @returns
+	*/
+	static async destroy(ids) {
+		const constructor = this;
+		const identifiers = (Array.isArray(ids) ? ids : [ids]).filter((identifier, index, all) => all.indexOf(identifier) === index);
+		const primaryKey = constructor.getPrimaryKey();
+		let deleted = 0;
+		for (const identifier of identifiers) {
+			const model = await constructor.query().where({ [primaryKey]: identifier }).first();
+			if (!model) continue;
+			await model.delete();
+			deleted += 1;
+		}
+		return deleted;
+	}
+	/**
 	* Get the soft delete configuration for the model, including whether 
 	* soft deletes are enabled and the name of the deleted at column.
 	* 
@@ -6931,6 +7798,7 @@ var Model = class Model {
 		const model = new this(attributes);
 		model.syncOriginal();
 		model.syncChanges({});
+		model.exists = true;
 		return model;
 	}
 	/**
@@ -6941,7 +7809,8 @@ var Model = class Model {
 	* @returns 
 	*/
 	static hydrateMany(attributes) {
-		return attributes.map((attribute) => new this(attribute));
+		const constructor = this;
+		return attributes.map((attribute) => constructor.hydrate(attribute));
 	}
 	/**
 	* Hydrate a model instance and dispatch the retrieved lifecycle event.
@@ -6989,6 +7858,11 @@ var Model = class Model {
 			return false;
 		}
 	}
+	async updateOrFail(attributes) {
+		const primaryKey = this.constructor.getPrimaryKey();
+		if (this.getAttribute(primaryKey) == null) throw new require_relationship.ArkormException(primaryKey === "id" ? "Cannot update a model without an id." : `Cannot update a model without a [${primaryKey}] value.`);
+		return await this.fill(attributes).saveOrFail();
+	}
 	getAttribute(key) {
 		const attributeMutator = this.resolveAttributeMutator(key);
 		const mutator = this.resolveGetMutator(key);
@@ -7012,29 +7886,35 @@ var Model = class Model {
 		return this;
 	}
 	/**
-	* Save the model to the database. 
-	* If the model has an identifier (id), it will perform an update. 
-	* Otherwise, it will perform a create.
-	* 
-	* @returns 
+	* Save the model to the database.
+	* If the model already exists in the database it performs an update;
+	* otherwise it performs an insert. Existence is tracked through the
+	* `exists` flag rather than the presence of a primary-key value, so a model
+	* built with an explicit primary key still inserts on its first save.
+	*
+	* @returns
 	*/
 	async save() {
 		const constructor = this.constructor;
 		const primaryKey = constructor.getPrimaryKey();
-		const identifier = this.getAttribute(primaryKey);
 		const previousOriginal = this.getOriginal();
-		if (identifier == null) {
+		if (!this.exists) {
 			await Model.dispatchEvent(constructor, "saving", this);
 			await Model.dispatchEvent(constructor, "creating", this);
 			const payload = this.normalizePersistenceAttributes(this.getRawAttributes());
 			const model = await constructor.query().create(payload);
 			this.fill(model.getRawAttributes());
 			this.syncChanges(previousOriginal);
+			this.syncPrevious(previousOriginal);
 			this.syncOriginal();
+			this.exists = true;
+			this.wasRecentlyCreated = true;
 			await Model.dispatchEvent(constructor, "created", this);
 			await Model.dispatchEvent(constructor, "saved", this);
 			return this;
 		}
+		const identifier = this.getAttribute(primaryKey);
+		if (identifier == null) throw new require_relationship.ArkormException(primaryKey === "id" ? "Cannot update an existing model without an id." : `Cannot update an existing model without a [${primaryKey}] value.`);
 		await Model.dispatchEvent(constructor, "saving", this);
 		await Model.dispatchEvent(constructor, "updating", this);
 		const payload = this.normalizePersistenceAttributes(this.getDirtyAttributes());
@@ -7042,6 +7922,7 @@ var Model = class Model {
 		const model = await constructor.query().where({ [primaryKey]: identifier }).update(payload);
 		this.fill(model.getRawAttributes());
 		this.syncChanges(previousOriginal);
+		this.syncPrevious(previousOriginal);
 		this.syncOriginal();
 		await Model.dispatchEvent(constructor, "updated", this);
 		await Model.dispatchEvent(constructor, "saved", this);
@@ -7056,6 +7937,15 @@ var Model = class Model {
 		return await Model.withoutEvents(() => this.save());
 	}
 	/**
+	* Save the model within a transaction, rolling back and rethrowing if the
+	* operation fails. Unlike update(), this never swallows errors.
+	*
+	* @returns
+	*/
+	async saveOrFail() {
+		return await this.constructor.transaction(async () => await this.save());
+	}
+	/**
 	* Delete the model from the database. 
 	* If soft deletes are enabled, it will perform a soft delete by 
 	* setting the deleted at column to the current date. 
@@ -7083,6 +7973,7 @@ var Model = class Model {
 		this.fill(deleted.getRawAttributes());
 		this.syncChanges(previousOriginal);
 		this.syncOriginal();
+		this.exists = false;
 		await Model.dispatchEvent(constructor, "deleted", this);
 		return this;
 	}
@@ -7095,6 +7986,15 @@ var Model = class Model {
 		return await Model.withoutEvents(() => this.delete());
 	}
 	/**
+	* Delete the model within a transaction, rolling back and rethrowing if the
+	* operation fails.
+	*
+	* @returns
+	*/
+	async deleteOrFail() {
+		return await this.constructor.transaction(async () => await this.delete());
+	}
+	/**
 	* Permanently delete the model from the database, regardless of whether soft 
 	* deletes are enabled.
 	* 
@@ -7112,6 +8012,7 @@ var Model = class Model {
 		this.fill(deleted.getRawAttributes());
 		this.syncChanges(previousOriginal);
 		this.syncOriginal();
+		this.exists = false;
 		await Model.dispatchEvent(constructor, "deleted", this);
 		await Model.dispatchEvent(constructor, "forceDeleted", this);
 		return this;
@@ -7266,6 +8167,25 @@ var Model = class Model {
 		return keyList.some((key) => Object.prototype.hasOwnProperty.call(this.changes, key));
 	}
 	/**
+	* Get the attributes that were changed during the last successful
+	* persistence operation.
+	*
+	* @returns
+	*/
+	getChanges() {
+		return Object.entries(this.changes).reduce((all, [key, value]) => {
+			all[key] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+	}
+	getPrevious(key) {
+		if (typeof key === "string") return Model.cloneAttributeValue(this.previous[key]);
+		return Object.entries(this.previous).reduce((all, [previousKey, value]) => {
+			all[previousKey] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+	}
+	/**
 	* Convert the model instance to a plain object, applying visibility 
 	* rules, appends, and mutators.
 	* 
@@ -7682,6 +8602,18 @@ var Model = class Model {
 		}, {});
 	}
 	/**
+	* Capture the attribute snapshot that was persisted before the most recent
+	* save so it can be read back via getPrevious().
+	*
+	* @param previousOriginal
+	*/
+	syncPrevious(previousOriginal) {
+		this.previous = Object.entries(previousOriginal).reduce((all, [key, value]) => {
+			all[key] = Model.cloneAttributeValue(value);
+			return all;
+		}, {});
+	}
+	/**
 	* Resolve lifecycle state for the provided model class.
 	*
 	* @param modelClass
@@ -8366,6 +9298,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;