arkormx 2.10.2 → 2.11.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_relationship = require('./relationship-DWtfgLfh.cjs');
+const require_relationship = require('./relationship-IC-TAFyG.cjs');
 let pg = require("pg");
 let node_path = require("node:path");
 let module$1 = require("module");
@@ -65,7 +65,8 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 			rawWhere: true,
 			distinct: true,
 			groupBy: true,
-			joins: true
+			joins: true,
+			expressions: true
 		};
 	}
 	resolveConfiguredDatabaseName(connectionString) {
@@ -386,6 +387,13 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	}
 	buildSchemaColumnDefinition(table, column) {
 		const parts = [this.quoteIdentifier(column.map ?? column.name), this.resolveSchemaColumnType(table, column)];
+		if (column.generatedExpression) {
+			const storage = column.generatedStored === false ? "" : " stored";
+			parts.push(`generated always as (${column.generatedExpression})${storage}`);
+			if (column.unique) parts.push("unique");
+			if (!column.nullable && !column.primary) parts.push("not null");
+			return parts.join(" ");
+		}
 		if (this.shouldUseIdentity(column)) parts.push("generated by default as identity");
 		const defaultValue = this.resolveSchemaColumnDefault(column);
 		if (defaultValue && !this.shouldUseIdentity(column)) parts.push(`default ${defaultValue}`);
@@ -643,11 +651,16 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	}
 	buildSelectList(target, columns) {
 		if (!columns || columns.length === 0) return kysely.sql.raw("*");
-		return kysely.sql.join(columns.map(({ column, alias, raw, wildcard }) => {
+		return kysely.sql.join(columns.map(({ column, alias, raw, wildcard, expression }) => {
 			if (wildcard) return kysely.sql.raw("*");
+			if (expression) {
+				const compiled = this.buildExpression(target, expression);
+				const resultAlias = alias ?? column;
+				return resultAlias ? kysely.sql`${compiled} as ${kysely.sql.id(resultAlias)}` : compiled;
+			}
 			if (raw) {
-				const expression = kysely.sql.raw(column);
-				return alias ? kysely.sql`${expression} as ${kysely.sql.id(alias)}` : expression;
+				const rawExpression = kysely.sql.raw(column);
+				return alias ? kysely.sql`${rawExpression} as ${kysely.sql.id(alias)}` : rawExpression;
 			}
 			const mappedColumn = this.mapColumn(target, column);
 			const resultAlias = alias ?? column;
@@ -657,13 +670,18 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 	}
 	buildOrderBy(target, orderBy) {
 		if (!orderBy || orderBy.length === 0) return kysely.sql``;
-		return kysely.sql` order by ${kysely.sql.join(orderBy.map(({ column, direction }) => {
-			return kysely.sql`${kysely.sql.ref(this.mapColumn(target, column))} ${kysely.sql.raw(direction === "desc" ? "desc" : "asc")}`;
+		return kysely.sql` order by ${kysely.sql.join(orderBy.map(({ column, direction, expression }) => {
+			return kysely.sql`${expression ? this.buildExpression(target, expression) : kysely.sql.ref(this.mapColumn(target, column))} ${kysely.sql.raw(direction === "desc" ? "desc" : "asc")}`;
 		}), kysely.sql`, `)}`;
 	}
 	buildGroupBy(target, groupBy) {
 		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`, `)}`;
+		return kysely.sql` group by ${kysely.sql.join(groupBy.map((item) => {
+			if (typeof item === "string") return kysely.sql.ref(this.mapColumn(target, item));
+			if ("alias" in item) return kysely.sql.ref(item.alias);
+			if ("expression" in item) return this.buildExpression(target, item.expression);
+			return this.buildRawExpressionFragment(item.raw.sql, item.raw.bindings ?? []);
+		}), kysely.sql`, `)}`;
 	}
 	buildHavingClause(target, having) {
 		if (!having) return kysely.sql``;
@@ -812,6 +830,96 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		const contains = kysely.sql`${accessor} @> ${jsonValue}::jsonb`;
 		return condition.not ? kysely.sql`not (${contains})` : contains;
 	}
+	/**
+	* Compiles a serialized {@link ExpressionNode} into a parameterized SQL fragment.
+	* Shared by expression-backed select columns, `group by`, `order by`, and any
+	* boolean expression used as a `where`/`having` predicate.
+	*
+	* @param target
+	* @param node
+	* @returns
+	*/
+	buildExpression(target, node) {
+		switch (node.kind) {
+			case "column": return this.buildExpressionColumn(target, node.name);
+			case "value": return kysely.sql`${node.value}`;
+			case "raw": return this.buildRawExpressionFragment(node.sql, node.bindings);
+			case "json": return this.buildJsonValueExpression(target, node);
+			case "function": {
+				const args = node.args.map((arg) => this.buildExpression(target, arg));
+				return kysely.sql`${kysely.sql.raw(this.sanitizeFunctionName(node.name))}(${kysely.sql.join(args, kysely.sql`, `)})`;
+			}
+			case "case": {
+				const branches = node.cases.map((branch) => kysely.sql`when ${this.buildExpression(target, branch.when)} then ${this.buildExpression(target, branch.then)}`);
+				const elseClause = node.else ? kysely.sql` else ${this.buildExpression(target, node.else)}` : kysely.sql``;
+				return kysely.sql`case ${kysely.sql.join(branches, kysely.sql` `)}${elseClause} end`;
+			}
+			case "binary": return this.buildBinaryExpression(target, node);
+			case "in": {
+				const operand = this.buildExpression(target, node.operand);
+				const values = node.values.map((value) => this.buildExpression(target, value));
+				const list = values.length > 0 ? kysely.sql.join(values, kysely.sql`, `) : kysely.sql`null`;
+				return node.not ? kysely.sql`(${operand} not in (${list}))` : kysely.sql`(${operand} in (${list}))`;
+			}
+			case "null-check": {
+				const operand = this.buildExpression(target, node.operand);
+				return node.not ? kysely.sql`(${operand} is not null)` : kysely.sql`(${operand} is null)`;
+			}
+			case "aggregate": return this.buildAggregateExpression(target, node);
+			default: throw new require_relationship.ArkormException(`Unsupported expression node [${node.kind}].`);
+		}
+	}
+	buildExpressionColumn(target, name) {
+		if (name.includes(".")) return kysely.sql.ref(name);
+		return kysely.sql.ref(this.mapColumn(target, name));
+	}
+	buildBinaryExpression(target, node) {
+		const left = this.buildExpression(target, node.left);
+		const right = this.buildExpression(target, node.right);
+		switch (node.operator) {
+			case "like": return kysely.sql`(${left} like ${right})`;
+			case "ilike": return kysely.sql`(${left} ilike ${right})`;
+			case "not-like": return kysely.sql`(${left} not like ${right})`;
+			case "not-ilike": return kysely.sql`(${left} not ilike ${right})`;
+			case "and": return kysely.sql`(${left} and ${right})`;
+			case "or": return kysely.sql`(${left} or ${right})`;
+			default: return kysely.sql`(${left} ${kysely.sql.raw(node.operator)} ${right})`;
+		}
+	}
+	buildAggregateExpression(target, node) {
+		const argument = node.arg ? this.buildExpression(target, node.arg) : kysely.sql.raw("*");
+		const distinctKeyword = node.distinct ? kysely.sql`distinct ` : kysely.sql``;
+		let call = kysely.sql`${kysely.sql.raw(node.fn)}(${distinctKeyword}${argument})`;
+		if (node.filter) call = kysely.sql`${call} filter (where ${this.buildExpression(target, node.filter)})`;
+		if (node.fn === "sum" || node.fn === "avg") return kysely.sql`(${call})::double precision`;
+		if (node.fn === "count") return kysely.sql`(${call})::bigint`;
+		return call;
+	}
+	buildJsonValueExpression(target, node) {
+		const base = kysely.sql`${kysely.sql.ref(this.mapColumn(target, node.column))}::jsonb`;
+		let accessor;
+		if (node.path.length === 0) accessor = base;
+		else if (node.path.length === 1) accessor = kysely.sql`(${base} ->> ${node.path[0]})`;
+		else accessor = kysely.sql`(${base} #>> ${`{${node.path.join(",")}}`}::text[])`;
+		if (node.cast === "number") return kysely.sql`(${accessor})::numeric`;
+		if (node.cast === "boolean") return kysely.sql`(${accessor})::boolean`;
+		return accessor;
+	}
+	buildRawExpressionFragment(rawSql, bindings) {
+		const segments = rawSql.split("?");
+		if (segments.length !== bindings.length + 1) throw new require_relationship.ArkormException("Raw expression bindings do not match the number of placeholders.");
+		const parts = [];
+		segments.forEach((segment, index) => {
+			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``;
+		return kysely.sql`${kysely.sql.join(parts, kysely.sql``)}`;
+	}
+	sanitizeFunctionName(name) {
+		if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(name)) throw new require_relationship.ArkormException(`Unsupported SQL function name [${name}].`);
+		return name;
+	}
 	buildWhereCondition(target, condition) {
 		if (!condition) return kysely.sql`1 = 1`;
 		if (condition.type === "comparison") return this.buildComparisonCondition(target, condition);
@@ -821,6 +929,7 @@ var KyselyDatabaseAdapter = class KyselyDatabaseAdapter {
 		if (condition.type === "exists") return this.buildExistsCondition(condition);
 		if (condition.type === "full-text") return this.buildFullTextCondition(target, condition);
 		if (condition.type === "json") return this.buildJsonCondition(target, condition);
+		if (condition.type === "expression") return kysely.sql`${this.buildExpression(target, condition.expression)}`;
 		if (condition.type === "group") {
 			const group = condition;
 			const conditions = group.conditions.map((entry) => {
@@ -1693,6 +1802,7 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			rawWhere: false,
 			distinct: false,
 			groupBy: false,
+			expressions: false,
 			returning: false
 		};
 	}
@@ -1728,6 +1838,14 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 	}
 	toQuerySelect(columns) {
 		if (!columns || columns.length === 0) return void 0;
+		const expressionColumn = columns.find((column) => column.expression);
+		if (expressionColumn) throw new require_relationship.UnsupportedAdapterFeatureException("Expression select columns are not supported by the Prisma compatibility adapter; use a SQL-backed adapter.", {
+			operation: "adapter.select",
+			meta: {
+				feature: "expressions",
+				alias: expressionColumn.alias
+			}
+		});
 		const rawColumn = columns.find((column) => column.raw);
 		if (rawColumn) throw new require_relationship.UnsupportedAdapterFeatureException("Raw select expressions are not supported by the Prisma compatibility adapter; use a SQL-backed adapter or DB.raw().", {
 			operation: "adapter.select",
@@ -1745,6 +1863,10 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 	}
 	toQueryOrderBy(orderBy) {
 		if (!orderBy || orderBy.length === 0) return void 0;
+		if (orderBy.some((entry) => entry.expression)) throw new require_relationship.UnsupportedAdapterFeatureException("Order-by expressions are not supported by the Prisma compatibility adapter; use a SQL-backed adapter.", {
+			operation: "adapter.select",
+			meta: { feature: "expressions" }
+		});
 		return orderBy.map((entry) => ({ [entry.column]: entry.direction }));
 	}
 	toComparisonWhere(condition) {
@@ -3388,7 +3510,8 @@ var Migration = class {
 //#region src/cli/commands/MigrateCommand.ts
 /**
 * The MigrateCommand class implements the CLI command for applying migration
-* classes to the Prisma schema and running the Prisma workflow.
+* classes to the database or Prisma schema and running the Prisma workflow when
+* using the Prisma compatibility driver.
 *
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
@@ -3399,22 +3522,22 @@ var MigrateCommand = class extends _h3ravel_musket.Command {
 		this.signature = `migrate
         {name? : Migration class or file name}
         {--all : Run all migrations from the configured migrations directory}
-        {--deploy : Use prisma migrate deploy instead of migrate dev}
-        {--skip-generate : Skip prisma generate}
+        {--deploy : Use prisma migrate deploy instead of migrate dev (Prisma compatibility driver only)}
+        {--skip-generate : Skip prisma generate (Prisma compatibility driver only)}
         {--skip-migrate : Skip prisma migrate command}
         {--state-file= : Path to applied migration state file}
-        {--schema= : Explicit prisma schema path}
-        {--migration-name= : Name for prisma migrate dev}
+        {--schema= : Explicit prisma schema path (Prisma compatibility driver only)}
+        {--migration-name= : Name for prisma migrate dev (Prisma compatibility driver only)}
         {--create-database : Create the configured database without prompting}
     `;
-		this.description = "Apply migration classes to schema.prisma and run Prisma workflow";
+		this.description = "Apply migration classes to the database or schema.prisma and run Prisma workflow when using the Prisma compatibility driver";
 	}
 	/**
 	* Command handler for the migrate command.
 	* This method is responsible for orchestrating the migration
 	* process, including loading migration classes, applying them to
-	* the Prisma schema, and running the appropriate Prisma commands
-	* based on the provided options.
+	* the the database or Prisma schema, and running the appropriate Prisma commands
+	* when using the Prisma compatibility driver based on the provided options.
 	*
 	* @returns
 	*/
@@ -3623,10 +3746,10 @@ var MigrateFreshCommand = class extends _h3ravel_musket.Command {
 	constructor(..._args) {
 		super(..._args);
 		this.signature = `migrate:fresh
-        {--skip-generate : Skip prisma generate}
-        {--skip-migrate : Skip prisma database sync}
+        {--skip-generate : Skip prisma generate (Prisma compatibility driver only)}
+        {--skip-migrate : Skip prisma database sync (Prisma compatibility driver only)}
         {--state-file= : Path to applied migration state file}
-        {--schema= : Explicit prisma schema path}
+        {--schema= : Explicit prisma schema path (Prisma compatibility driver only)}
         {--create-database : Create the configured database without prompting}
     `;
 		this.description = "Reset the database and rerun all migration classes";
@@ -3781,12 +3904,12 @@ var MigrateRollbackCommand = class extends _h3ravel_musket.Command {
 		this.signature = `migrate:rollback
         {--step= : Number of latest applied migration classes to rollback}
         {--dry-run : Preview rollback targets without applying changes}
-        {--deploy : Use prisma migrate deploy instead of migrate dev}
-        {--skip-generate : Skip prisma generate}
-        {--skip-migrate : Skip prisma migrate command}
+        {--deploy : Use prisma migrate deploy instead of migrate dev (Prisma compatibility driver only)}
+        {--skip-generate : Skip prisma generate (Prisma compatibility driver only)}
+        {--skip-migrate : Skip prisma migrate command (Prisma compatibility driver only)}
         {--state-file= : Path to applied migration state file}
-        {--schema= : Explicit prisma schema path}
-        {--migration-name= : Name for prisma migrate dev}
+        {--schema= : Explicit prisma schema path (Prisma compatibility driver only)}
+        {--migration-name= : Name for prisma migrate dev (Prisma compatibility driver only)}
     `;
 		this.description = "Rollback migration classes from schema.prisma and run Prisma workflow";
 	}
@@ -3801,7 +3924,7 @@ var MigrateRollbackCommand = class extends _h3ravel_musket.Command {
 		const useDatabaseMigrations = require_relationship.supportsDatabaseMigrationExecution(adapter);
 		const persistedFeatures = require_relationship.resolvePersistedMetadataFeatures(this.app.getConfig("features"));
 		let appliedState = await require_relationship.readAppliedMigrationsStateFromStore(adapter, stateFilePath);
-		const stepOption = this.option("step");
+		const stepOption = this.option("step", 1);
 		const stepCount = stepOption == null ? void 0 : Number(stepOption);
 		if (stepCount != null && (!Number.isFinite(stepCount) || stepCount <= 0 || !Number.isInteger(stepCount))) return void this.error("Error: --step must be a positive integer.");
 		const targets = stepCount ? require_relationship.getLatestAppliedMigrations(appliedState, stepCount) : (() => {
@@ -4476,14 +4599,34 @@ var QueryBuilder = class QueryBuilder {
 		return Math.max(1, resolvedPage);
 	}
 	where(whereOrCallback) {
+		if (whereOrCallback instanceof require_relationship.Expression) return this.appendExpressionCondition("AND", whereOrCallback);
 		if (typeof whereOrCallback === "function") return this.appendNestedWhere("AND", whereOrCallback);
 		return this.addLogicalWhere("AND", whereOrCallback);
 	}
 	orWhere(whereOrCallback) {
+		if (whereOrCallback instanceof require_relationship.Expression) return this.appendExpressionCondition("OR", whereOrCallback);
 		if (typeof whereOrCallback === "function") return this.appendNestedWhere("OR", whereOrCallback);
 		return this.addLogicalWhere("OR", whereOrCallback);
 	}
 	/**
+	* Appends a boolean {@link Expression} as a where predicate. When the query is
+	* using the Prisma-like legacy where representation, the expression is merged in
+	* as a structured condition alongside it.
+	*/
+	appendExpressionCondition(boolean, expression) {
+		const condition = {
+			type: "expression",
+			expression: expression.toExpressionNode()
+		};
+		if (this.legacyWhere) {
+			const existing = this.tryBuildQueryCondition(this.legacyWhere);
+			this.legacyWhere = void 0;
+			if (existing) this.queryWhere = existing;
+		}
+		this.appendQueryCondition(boolean, condition);
+		return this;
+	}
+	/**
 	* Resolve a callback into a parenthesized group condition and append it.
 	*/
 	appendNestedWhere(boolean, callback) {
@@ -5133,15 +5276,17 @@ var QueryBuilder = class QueryBuilder {
 	whereIn(key, values) {
 		return this.where({ [key]: { in: values } });
 	}
-	/**
-	* Adds an orderBy clause to the query. This will overwrite any existing orderBy clause.
-	*
-	* @param orderBy
-	* @returns
-	*/
-	orderBy(orderBy) {
+	orderBy(orderByOrExpression, direction = "asc") {
 		this.randomOrderEnabled = false;
-		const normalized = this.normalizeQueryOrderBy(orderBy);
+		if (orderByOrExpression instanceof require_relationship.Expression) {
+			this.queryOrderBy = [...this.queryOrderBy ?? [], {
+				column: "",
+				direction,
+				expression: orderByOrExpression.toExpressionNode()
+			}];
+			return this;
+		}
+		const normalized = this.normalizeQueryOrderBy(orderByOrExpression);
 		if (!normalized) throw new require_relationship.UnsupportedAdapterFeatureException("Order clauses must use Arkorm-normalizable column directions.", {
 			operation: "orderBy",
 			model: this.model.name
@@ -5150,6 +5295,28 @@ var QueryBuilder = class QueryBuilder {
 		return this;
 	}
 	/**
+	* Appends a raw SQL `order by` fragment (with positional `?` bindings), useful
+	* for ordering by a computed expression the builder does not model directly.
+	*
+	* @param sql
+	* @param bindings
+	* @param direction
+	* @returns
+	*/
+	orderByRaw(sql, bindings = [], direction = "asc") {
+		this.randomOrderEnabled = false;
+		this.queryOrderBy = [...this.queryOrderBy ?? [], {
+			column: "",
+			direction,
+			expression: {
+				kind: "raw",
+				sql,
+				bindings
+			}
+		}];
+		return this;
+	}
+	/**
 	* Puts the query results in random order.
 	*
 	* @returns
@@ -5515,12 +5682,6 @@ var QueryBuilder = class QueryBuilder {
 	pipe(callback) {
 		return callback(this);
 	}
-	/**
-	* Adds a select clause to the query. This will overwrite any existing select clause.
-	*
-	* @param select
-	* @returns
-	*/
 	select(select) {
 		const normalized = this.normalizeQuerySelect(select);
 		if (normalized === null) throw new require_relationship.UnsupportedAdapterFeatureException("Select clauses must use Arkorm-normalizable column projections.", {
@@ -5530,12 +5691,6 @@ var QueryBuilder = class QueryBuilder {
 		this.querySelect = normalized;
 		return this;
 	}
-	/**
-	* Appends columns or expressions to the existing select clause.
-	*
-	* @param select
-	* @returns
-	*/
 	addSelect(select) {
 		const normalized = this.normalizeQuerySelect(select);
 		if (normalized === null) throw new require_relationship.UnsupportedAdapterFeatureException("Select clauses must use Arkorm-normalizable column projections.", {
@@ -5559,6 +5714,8 @@ var QueryBuilder = class QueryBuilder {
 		return this;
 	}
 	groupBy(...columns) {
+		const first = columns[0];
+		if (columns.length === 1 && this.isGroupByAggregateSpec(first)) return this.executeGroupByAggregate(first);
 		const normalized = Array.isArray(columns[0]) ? columns[0] : columns;
 		if (normalized.length === 0) throw new QueryConstraintException("groupBy requires at least one column.", {
 			operation: "groupBy",
@@ -5567,6 +5724,109 @@ var QueryBuilder = class QueryBuilder {
 		this.queryGroupBy = [...normalized];
 		return this;
 	}
+	/**
+	* Appends a raw SQL `group by` fragment (with positional `?` bindings), mirroring
+	* `whereRaw`/`havingRaw`. Combines with any columns/expressions already grouped.
+	*
+	* @param sql
+	* @param bindings
+	* @returns
+	*/
+	groupByRaw(sql, bindings = []) {
+		this.queryGroupBy = [...this.queryGroupBy ?? [], { raw: {
+			sql,
+			bindings
+		} }];
+		return this;
+	}
+	/**
+	* Resolves the recorded group-by sources into adapter {@link QueryGroupByItem}s.
+	* A bare string that matches a select-column alias is expanded to that column's
+	* underlying expression (group-by-alias); otherwise it is treated as a column.
+	*/
+	buildGroupByItems(selectColumns) {
+		if (!this.queryGroupBy || this.queryGroupBy.length === 0) return void 0;
+		const expressionAliases = /* @__PURE__ */ new Map();
+		selectColumns?.forEach((column) => {
+			if (column.expression && column.alias) expressionAliases.set(JSON.stringify(column.expression), column.alias);
+		});
+		const aliasNames = new Set(expressionAliases.values());
+		return this.queryGroupBy.map((source) => {
+			if (source instanceof require_relationship.Expression) {
+				const node = source.toExpressionNode();
+				const alias = expressionAliases.get(JSON.stringify(node));
+				return alias ? { alias } : { expression: node };
+			}
+			if (typeof source === "object") return { raw: source.raw };
+			return aliasNames.has(source) ? { alias: source } : source;
+		});
+	}
+	isGroupByAggregateSpec(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof require_relationship.Expression) && Array.isArray(value.by);
+	}
+	/**
+	* Executes the query and returns plain, un-hydrated rows keyed by their select
+	* alias — the natural shape for `select` + `groupBy` aggregate reports. Pass a
+	* row type to describe the projection.
+	*
+	* @returns
+	*/
+	async getRows() {
+		return await this.executeReadRows();
+	}
+	/**
+	* Runs a Prisma-style grouped aggregate and returns typed rows shaped as
+	* `{ <by columns>, _sum, _avg, _min, _max, _count }`.
+	*/
+	async executeGroupByAggregate(spec) {
+		const selectMap = {};
+		spec.by.forEach((column) => {
+			selectMap[column] = true;
+		});
+		const aggregates = [];
+		const register = (group, factory, map, numeric) => {
+			Object.keys(map).forEach((column) => {
+				if (!map[column]) return;
+				const alias = `${group}_${column}`;
+				selectMap[alias] = factory(column);
+				aggregates.push({
+					group,
+					column,
+					alias,
+					numeric
+				});
+			});
+		};
+		if (spec._sum) register("_sum", (column) => require_relationship.sum(column), spec._sum, true);
+		if (spec._avg) register("_avg", (column) => require_relationship.avg(column), spec._avg, true);
+		if (spec._min) register("_min", (column) => require_relationship.min(column), spec._min, false);
+		if (spec._max) register("_max", (column) => require_relationship.max(column), spec._max, false);
+		let countAllAlias;
+		if (spec._count === true) {
+			countAllAlias = "_count_all";
+			selectMap[countAllAlias] = require_relationship.count();
+		} else if (spec._count) register("_count", (column) => require_relationship.count(column), spec._count, true);
+		this.select(selectMap);
+		this.groupBy(spec.by);
+		return (await this.getRows()).map((row) => {
+			const result = {};
+			spec.by.forEach((column) => {
+				result[column] = row[column];
+			});
+			const grouped = {};
+			aggregates.forEach(({ group, column, alias, numeric }) => {
+				grouped[group] ??= {};
+				grouped[group][column] = numeric ? this.coerceNumeric(row[alias]) : row[alias];
+			});
+			Object.assign(result, grouped);
+			if (countAllAlias) result._count = this.coerceNumeric(row[countAllAlias]);
+			return result;
+		});
+	}
+	coerceNumeric(value) {
+		if (value === null || value === void 0) return null;
+		return Number(value);
+	}
 	appendHavingCondition(boolean, condition) {
 		if (!this.queryHaving) {
 			this.queryHaving = condition;
@@ -5587,12 +5847,35 @@ var QueryBuilder = class QueryBuilder {
 			value: hasOperator ? maybeValue : operatorOrValue
 		};
 	}
-	having(column, operatorOrValue, maybeValue) {
-		this.appendHavingCondition("AND", this.buildHavingComparison(operatorOrValue, maybeValue, column));
+	/**
+	* Resolves the three `having` call shapes into a condition: `having(column, …)`,
+	* `having(expression)` (a boolean expression predicate), and
+	* `having(expression, operator, value)` (compare an aggregate to a value).
+	*/
+	buildHavingCondition(columnOrExpression, operatorOrValue, maybeValue) {
+		if (columnOrExpression instanceof require_relationship.Expression) return {
+			type: "expression",
+			expression: (operatorOrValue === void 0 ? columnOrExpression : this.compareExpression(columnOrExpression, operatorOrValue, maybeValue)).toExpressionNode()
+		};
+		return this.buildHavingComparison(operatorOrValue, maybeValue, columnOrExpression);
+	}
+	compareExpression(expression, operator, value) {
+		switch (operator) {
+			case "=": return expression.eq(value);
+			case "!=": return expression.ne(value);
+			case ">": return expression.gt(value);
+			case ">=": return expression.gte(value);
+			case "<": return expression.lt(value);
+			case "<=": return expression.lte(value);
+			default: return expression.eq(value);
+		}
+	}
+	having(columnOrExpression, operatorOrValue, maybeValue) {
+		this.appendHavingCondition("AND", this.buildHavingCondition(columnOrExpression, operatorOrValue, maybeValue));
 		return this;
 	}
-	orHaving(column, operatorOrValue, maybeValue) {
-		this.appendHavingCondition("OR", this.buildHavingComparison(operatorOrValue, maybeValue, column));
+	orHaving(columnOrExpression, operatorOrValue, maybeValue) {
+		this.appendHavingCondition("OR", this.buildHavingCondition(columnOrExpression, operatorOrValue, maybeValue));
 		return this;
 	}
 	/**
@@ -6750,12 +7033,19 @@ var QueryBuilder = class QueryBuilder {
 		}
 		if (typeof select !== "object" || !select) return null;
 		const entries = Object.entries(select);
-		if (entries.some(([, value]) => value !== true && value !== false && value !== void 0 && typeof value !== "string")) return null;
-		const columns = entries.filter(([, value]) => value === true || typeof value === "string").map(([column, value]) => typeof value === "string" ? {
-			column,
-			alias: value,
-			raw: true
-		} : { column });
+		if (entries.some(([, value]) => value !== true && value !== false && value !== void 0 && typeof value !== "string" && !(value instanceof require_relationship.Expression))) return null;
+		const columns = entries.filter(([, value]) => value === true || typeof value === "string" || value instanceof require_relationship.Expression).map(([column, value]) => {
+			if (value instanceof require_relationship.Expression) return {
+				column,
+				alias: column,
+				expression: value.toExpressionNode()
+			};
+			return typeof value === "string" ? {
+				column,
+				alias: value,
+				raw: true
+			} : { column };
+		});
 		return columns.length > 0 ? columns : [];
 	}
 	normalizeQueryOrderBy(orderBy) {
@@ -6913,7 +7203,7 @@ var QueryBuilder = class QueryBuilder {
 					offset: normalizedQuery.offsetValue,
 					columns: normalizedQuery.querySelect ? [...normalizedQuery.querySelect] : void 0,
 					distinct: normalizedQuery.queryDistinct || void 0,
-					groupBy: normalizedQuery.queryGroupBy ? [...normalizedQuery.queryGroupBy] : void 0,
+					groupBy: normalizedQuery.queryGroupBy ? normalizedQuery.queryGroupBy.filter((source) => typeof source === "string") : void 0,
 					relationLoads: this.mergeRelationLoadPlans(normalizedQuery.queryRelationLoads ? this.cloneRelationLoads(normalizedQuery.queryRelationLoads) : void 0, this.mergeRelationLoadPlans(callbackRelationLoads, childRelationLoads))
 				});
 			}
@@ -7177,11 +7467,11 @@ var QueryBuilder = class QueryBuilder {
 		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 {
+		return this.expandComputedAttributes({
 			target: this.buildQueryTarget(),
 			columns,
 			distinct: this.queryDistinct || void 0,
-			groupBy: this.queryGroupBy ? [...this.queryGroupBy] : void 0,
+			groupBy: this.buildGroupByItems(columns ?? void 0),
 			having: this.queryHaving,
 			joins: this.queryJoins ? [...this.queryJoins] : void 0,
 			where: condition,
@@ -7191,7 +7481,86 @@ var QueryBuilder = class QueryBuilder {
 			relationLoads: this.queryRelationLoads,
 			relationFilters: this.canExecuteRelationFiltersInAdapter() ? relationFilters ?? void 0 : void 0,
 			relationAggregates: this.canExecuteRelationAggregatesInAdapter() ? relationAggregates ?? void 0 : void 0
+		});
+	}
+	/** Reads and caches the model's resolved `static computed` expression map. */
+	computedAttributes() {
+		const model = this.model;
+		return typeof model.getComputed === "function" ? model.getComputed() : {};
+	}
+	/**
+	* Expands references to `static computed` attribute names into their backing
+	* expressions across a select spec's columns, group by, order by, where, and
+	* having clauses. A no-op when the model declares no computed attributes.
+	*/
+	expandComputedAttributes(spec) {
+		const computed = this.computedAttributes();
+		if (Object.keys(computed).length === 0) return spec;
+		const columns = spec.columns?.map((column) => {
+			if (column.expression || column.raw || column.wildcard) return column;
+			const expression = computed[column.column];
+			return expression ? {
+				...column,
+				expression,
+				alias: column.alias ?? column.column
+			} : column;
+		});
+		const selectedComputedAliases = new Set(columns?.filter((column) => column.expression && column.alias).map((column) => column.alias));
+		return {
+			...spec,
+			columns,
+			groupBy: spec.groupBy?.map((item) => {
+				if (typeof item !== "string") return item;
+				const expression = computed[item];
+				if (!expression) return item;
+				return selectedComputedAliases.has(item) ? { alias: item } : { expression };
+			}),
+			orderBy: spec.orderBy?.map((clause) => {
+				if (clause.expression) return clause;
+				const expression = computed[clause.column];
+				return expression ? {
+					...clause,
+					expression
+				} : clause;
+			}),
+			where: spec.where ? this.expandComputedCondition(spec.where, computed) : spec.where,
+			having: spec.having ? this.expandComputedCondition(spec.having, computed) : spec.having
+		};
+	}
+	expandComputedCondition(condition, computed) {
+		if (condition.type === "comparison" && computed[condition.column]) return {
+			type: "expression",
+			expression: this.computedComparison(computed[condition.column], condition.operator, condition.value)
+		};
+		if (condition.type === "group") return {
+			...condition,
+			conditions: condition.conditions.map((entry) => this.expandComputedCondition(entry, computed))
 		};
+		if (condition.type === "not") return {
+			...condition,
+			condition: this.expandComputedCondition(condition.condition, computed)
+		};
+		return condition;
+	}
+	/** Converts a where comparison against a computed attribute into an expression. */
+	computedComparison(node, operator, value) {
+		const expression = require_relationship.fromExpressionNode(node);
+		const list = Array.isArray(value) ? value : [];
+		switch (operator) {
+			case "!=": return expression.ne(value).toExpressionNode();
+			case ">": return expression.gt(value).toExpressionNode();
+			case ">=": return expression.gte(value).toExpressionNode();
+			case "<": return expression.lt(value).toExpressionNode();
+			case "<=": return expression.lte(value).toExpressionNode();
+			case "in": return expression.in(list).toExpressionNode();
+			case "not-in": return expression.notIn(list).toExpressionNode();
+			case "is-null": return expression.isNull().toExpressionNode();
+			case "is-not-null": return expression.isNotNull().toExpressionNode();
+			case "contains": return expression.like(`%${String(value)}%`).toExpressionNode();
+			case "starts-with": return expression.like(`${String(value)}%`).toExpressionNode();
+			case "ends-with": return expression.like(`%${String(value)}`).toExpressionNode();
+			default: return expression.eq(value).toExpressionNode();
+		}
 	}
 	tryBuildAggregateSpec() {
 		const condition = this.buildQueryWhereCondition(false);
@@ -7691,6 +8060,9 @@ var Model = class Model {
 	static {
 		this.castMapCache = /* @__PURE__ */ new WeakMap();
 	}
+	static {
+		this.computedCache = /* @__PURE__ */ new WeakMap();
+	}
 	static {
 		this.emittedDeprecationWarnings = /* @__PURE__ */ new Set();
 	}
@@ -7841,6 +8213,19 @@ var Model = class Model {
 		return casts;
 	}
 	/**
+	* Resolves the model's `static computed` declarations into expression nodes,
+	* cached per class. Returns an empty map when no computed attributes exist.
+	*/
+	static getComputed() {
+		const cached = Model.computedCache.get(this);
+		if (cached) return cached;
+		const definitions = this.computed;
+		const resolved = {};
+		if (definitions) for (const [name, factory] of Object.entries(definitions)) resolved[name] = factory(require_relationship.expressionBuilder).toExpressionNode();
+		Model.computedCache.set(this, resolved);
+		return resolved;
+	}
+	/**
 	* Apply built-in persistence casts (currently `json` serialisation) to a raw
 	* attribute payload, without re-running arbitrary custom setters. Used by
 	* both instance `save()` and the query-builder insert/update paths so a JS
@@ -9697,18 +10082,22 @@ var PivotModel = class extends Model {
 };
 
 //#endregion
+exports.AggregateExpression = require_relationship.AggregateExpression;
 exports.Arkorm = Arkorm;
 exports.ArkormCollection = require_relationship.ArkormCollection;
 exports.ArkormException = require_relationship.ArkormException;
 exports.Arkormx = Arkormx;
 exports.Attribute = Attribute;
+exports.CaseExpression = require_relationship.CaseExpression;
 exports.CliApp = CliApp;
 exports.DB = DB;
 exports.EnumBuilder = require_relationship.EnumBuilder;
+exports.Expression = require_relationship.Expression;
 exports.ForeignKeyBuilder = require_relationship.ForeignKeyBuilder;
 exports.InitCommand = InitCommand;
 exports.InlineFactory = InlineFactory;
 exports.JoinClause = JoinClause;
+exports.JsonExpression = require_relationship.JsonExpression;
 exports.KyselyDatabaseAdapter = KyselyDatabaseAdapter;
 exports.LengthAwarePaginator = require_relationship.LengthAwarePaginator;
 exports.MIGRATION_BRAND = MIGRATION_BRAND;
@@ -9756,6 +10145,7 @@ exports.applyMigrationToDatabase = require_relationship.applyMigrationToDatabase
 exports.applyMigrationToPrismaSchema = require_relationship.applyMigrationToPrismaSchema;
 exports.applyOperationsToPersistedColumnMappingsState = require_relationship.applyOperationsToPersistedColumnMappingsState;
 exports.applyOperationsToPrismaSchema = require_relationship.applyOperationsToPrismaSchema;
+exports.avg = require_relationship.avg;
 exports.awaitConfiguredModelsRegistration = require_relationship.awaitConfiguredModelsRegistration;
 exports.bindAdapterToModels = require_relationship.bindAdapterToModels;
 exports.buildEnumBlock = require_relationship.buildEnumBlock;
@@ -9769,8 +10159,12 @@ exports.buildModelBlock = require_relationship.buildModelBlock;
 exports.buildPrimaryKeyLine = require_relationship.buildPrimaryKeyLine;
 exports.buildRelationLine = require_relationship.buildRelationLine;
 exports.buildUniqueConstraintLine = require_relationship.buildUniqueConstraintLine;
+exports.caseWhen = require_relationship.caseWhen;
+exports.coalesce = require_relationship.coalesce;
+exports.col = require_relationship.col;
 exports.computeMigrationChecksum = require_relationship.computeMigrationChecksum;
 exports.configureArkormRuntime = require_relationship.configureArkormRuntime;
+exports.count = require_relationship.count;
 exports.createEmptyAppliedMigrationsState = require_relationship.createEmptyAppliedMigrationsState;
 exports.createEmptyPersistedColumnMappingsState = require_relationship.createEmptyPersistedColumnMappingsState;
 exports.createKyselyAdapter = createKyselyAdapter;
@@ -9791,12 +10185,15 @@ exports.deriveSingularFieldName = require_relationship.deriveSingularFieldName;
 exports.emitRuntimeDebugEvent = require_relationship.emitRuntimeDebugEvent;
 exports.ensureArkormConfigLoading = require_relationship.ensureArkormConfigLoading;
 exports.escapeRegex = require_relationship.escapeRegex;
+exports.expressionBuilder = require_relationship.expressionBuilder;
 exports.findAppliedMigration = require_relationship.findAppliedMigration;
 exports.findEnumBlock = require_relationship.findEnumBlock;
 exports.findModelBlock = require_relationship.findModelBlock;
+exports.fn = require_relationship.fn;
 exports.formatDefaultValue = require_relationship.formatDefaultValue;
 exports.formatEnumDefaultValue = require_relationship.formatEnumDefaultValue;
 exports.formatRelationAction = require_relationship.formatRelationAction;
+exports.fromExpressionNode = require_relationship.fromExpressionNode;
 exports.generateMigrationFile = require_relationship.generateMigrationFile;
 exports.getActiveTransactionAdapter = require_relationship.getActiveTransactionAdapter;
 exports.getActiveTransactionClient = require_relationship.getActiveTransactionClient;
@@ -9828,6 +10225,7 @@ exports.isDelegateLike = require_relationship.isDelegateLike;
 exports.isMigrationApplied = require_relationship.isMigrationApplied;
 exports.isQuerySchemaLike = require_relationship.isQuerySchemaLike;
 exports.isTransactionCapableClient = require_relationship.isTransactionCapableClient;
+exports.json = require_relationship.json;
 exports.loadArkormConfig = require_relationship.loadArkormConfig;
 exports.loadFactoriesFrom = require_relationship.loadFactoriesFrom;
 exports.loadMigrationsFrom = require_relationship.loadMigrationsFrom;
@@ -9835,7 +10233,10 @@ exports.loadModelsFrom = require_relationship.loadModelsFrom;
 exports.loadSeedersFrom = require_relationship.loadSeedersFrom;
 exports.markMigrationApplied = require_relationship.markMigrationApplied;
 exports.markMigrationRun = require_relationship.markMigrationRun;
+exports.max = require_relationship.max;
+exports.min = require_relationship.min;
 exports.pad = require_relationship.pad;
+exports.raw = require_relationship.raw;
 exports.readAppliedMigrationsState = require_relationship.readAppliedMigrationsState;
 exports.readAppliedMigrationsStateFromStore = require_relationship.readAppliedMigrationsStateFromStore;
 exports.readPersistedColumnMappingsState = require_relationship.readPersistedColumnMappingsState;
@@ -9852,6 +10253,7 @@ exports.resetRuntimeRegistryForTests = require_relationship.resetRuntimeRegistry
 exports.resolveCast = resolveCast;
 exports.resolveColumnMappingsFilePath = require_relationship.resolveColumnMappingsFilePath;
 exports.resolveEnumName = require_relationship.resolveEnumName;
+exports.resolveGeneratedExpression = require_relationship.resolveGeneratedExpression;
 exports.resolveMigrationClassName = require_relationship.resolveMigrationClassName;
 exports.resolveMigrationStateFilePath = require_relationship.resolveMigrationStateFilePath;
 exports.resolvePersistedMetadataFeatures = require_relationship.resolvePersistedMetadataFeatures;
@@ -9862,6 +10264,7 @@ exports.runArkormTransaction = require_relationship.runArkormTransaction;
 exports.runMigrationWithPrisma = require_relationship.runMigrationWithPrisma;
 exports.runPrismaCommand = require_relationship.runPrismaCommand;
 exports.stripPrismaSchemaModelsAndEnums = require_relationship.stripPrismaSchemaModelsAndEnums;
+exports.sum = require_relationship.sum;
 exports.supportsDatabaseCreation = require_relationship.supportsDatabaseCreation;
 exports.supportsDatabaseMigrationExecution = require_relationship.supportsDatabaseMigrationExecution;
 exports.supportsDatabaseMigrationState = require_relationship.supportsDatabaseMigrationState;
@@ -9869,7 +10272,9 @@ exports.supportsDatabaseReset = require_relationship.supportsDatabaseReset;
 exports.syncPersistedColumnMappingsFromState = require_relationship.syncPersistedColumnMappingsFromState;
 exports.toMigrationFileSlug = require_relationship.toMigrationFileSlug;
 exports.toModelName = require_relationship.toModelName;
+exports.val = require_relationship.val;
 exports.validatePersistedMetadataFeaturesForMigrations = require_relationship.validatePersistedMetadataFeaturesForMigrations;
+exports.where = require_relationship.where;
 exports.writeAppliedMigrationsState = require_relationship.writeAppliedMigrationsState;
 exports.writeAppliedMigrationsStateToStore = require_relationship.writeAppliedMigrationsStateToStore;
 exports.writePersistedColumnMappingsState = require_relationship.writePersistedColumnMappingsState;