arkormx 2.10.2 → 2.11.0

package/dist/cli.mjs

@@ -363,6 +363,419 @@ var PrimaryKeyGenerationPlanner = class {
 	}
 };
 
+//#endregion
+//#region src/Expression.ts
+/**
+* A composable SQL expression. Instances are immutable — every operator returns a
+* new expression — and are accepted by `select`, `where`, `groupBy`, `orderBy`,
+* `having`, and the aggregate helpers. Adapters compile the underlying node tree.
+*/
+var Expression = class Expression {
+	/**
+	* Type guard for values that came out of the expression builder.
+	*/
+	static isExpression(value) {
+		return value instanceof Expression;
+	}
+	eq(value) {
+		return binary("=", this, coerceValue(value));
+	}
+	ne(value) {
+		return binary("!=", this, coerceValue(value));
+	}
+	gt(value) {
+		return binary(">", this, coerceValue(value));
+	}
+	gte(value) {
+		return binary(">=", this, coerceValue(value));
+	}
+	lt(value) {
+		return binary("<", this, coerceValue(value));
+	}
+	lte(value) {
+		return binary("<=", this, coerceValue(value));
+	}
+	like(value) {
+		return binary("like", this, coerceValue(value));
+	}
+	ilike(value) {
+		return binary("ilike", this, coerceValue(value));
+	}
+	notLike(value) {
+		return binary("not-like", this, coerceValue(value));
+	}
+	notIlike(value) {
+		return binary("not-ilike", this, coerceValue(value));
+	}
+	in(values) {
+		return new NodeExpression({
+			kind: "in",
+			operand: this.toExpressionNode(),
+			values: values.map((value) => coerceValue(value).toExpressionNode()),
+			not: false
+		});
+	}
+	notIn(values) {
+		return new NodeExpression({
+			kind: "in",
+			operand: this.toExpressionNode(),
+			values: values.map((value) => coerceValue(value).toExpressionNode()),
+			not: true
+		});
+	}
+	isNull() {
+		return new NodeExpression({
+			kind: "null-check",
+			operand: this.toExpressionNode(),
+			not: false
+		});
+	}
+	isNotNull() {
+		return new NodeExpression({
+			kind: "null-check",
+			operand: this.toExpressionNode(),
+			not: true
+		});
+	}
+	and(other) {
+		return binary("and", this, other);
+	}
+	or(other) {
+		return binary("or", this, other);
+	}
+	plus(value) {
+		return binary("+", this, coerceValue(value));
+	}
+	minus(value) {
+		return binary("-", this, coerceValue(value));
+	}
+	times(value) {
+		return binary("*", this, coerceValue(value));
+	}
+	dividedBy(value) {
+		return binary("/", this, coerceValue(value));
+	}
+};
+/**
+* Concrete expression backed by a pre-built node.
+*/
+var NodeExpression = class extends Expression {
+	constructor(node) {
+		super();
+		this.node = node;
+	}
+	toExpressionNode() {
+		return this.node;
+	}
+};
+/**
+* Fluent `CASE … WHEN … THEN … ELSE … END` builder. Immutable.
+*/
+var CaseExpression = class CaseExpression extends Expression {
+	constructor(branches, elseExpr) {
+		super();
+		this.branches = branches;
+		this.elseExpr = elseExpr;
+	}
+	when(condition, result) {
+		return new CaseExpression([...this.branches, {
+			when: condition,
+			then: coerceValue(result)
+		}], this.elseExpr);
+	}
+	else(result) {
+		return new CaseExpression(this.branches, coerceValue(result));
+	}
+	toExpressionNode() {
+		return {
+			kind: "case",
+			cases: this.branches.map((branch) => ({
+				when: branch.when.toExpressionNode(),
+				then: branch.then.toExpressionNode()
+			})),
+			else: this.elseExpr?.toExpressionNode()
+		};
+	}
+};
+/**
+* JSON-path value extraction (`metadata ->> 'billType'`), with optional casts.
+*/
+var JsonExpression = class JsonExpression extends Expression {
+	constructor(column, path, castTo) {
+		super();
+		this.column = column;
+		this.path = path;
+		this.castTo = castTo;
+	}
+	asText() {
+		return new JsonExpression(this.column, this.path, "text");
+	}
+	asNumber() {
+		return new JsonExpression(this.column, this.path, "number");
+	}
+	asBoolean() {
+		return new JsonExpression(this.column, this.path, "boolean");
+	}
+	toExpressionNode() {
+		return {
+			kind: "json",
+			column: this.column,
+			path: this.path,
+			cast: this.castTo
+		};
+	}
+};
+/**
+* Aggregate expression (`sum`, `count`, `avg`, `min`, `max`) with optional filter.
+*/
+var AggregateExpression = class AggregateExpression extends Expression {
+	constructor(fn, arg, options = {}) {
+		super();
+		this.fn = fn;
+		this.arg = arg;
+		this.options = options;
+	}
+	/**
+	* Restricts the aggregate to rows matching `predicate` (`FILTER (WHERE …)`).
+	*/
+	filter(predicate) {
+		return new AggregateExpression(this.fn, this.arg, {
+			...this.options,
+			filterExpr: predicate
+		});
+	}
+	distinct() {
+		return new AggregateExpression(this.fn, this.arg, {
+			...this.options,
+			distinct: true
+		});
+	}
+	toExpressionNode() {
+		return {
+			kind: "aggregate",
+			fn: this.fn,
+			arg: this.arg?.toExpressionNode(),
+			distinct: this.options.distinct,
+			filter: this.options.filterExpr?.toExpressionNode()
+		};
+	}
+};
+const binary = (operator, left, right) => new NodeExpression({
+	kind: "binary",
+	operator,
+	left: left.toExpressionNode(),
+	right: right.toExpressionNode()
+});
+/**
+* Coerces a raw value into a bound-literal expression; passes expressions through.
+*/
+const coerceValue = (value) => {
+	if (value instanceof Expression) return value;
+	return new NodeExpression({
+		kind: "value",
+		value
+	});
+};
+/**
+* Coerces a bare string into a column reference; passes expressions through.
+*/
+const coerceColumn = (value) => {
+	if (value instanceof Expression) return value;
+	if (typeof value === "string") return col(value);
+	return coerceValue(value);
+};
+/**
+* A typed column reference. Supports joined `table.column` syntax.
+*/
+const col = (name) => new NodeExpression({
+	kind: "column",
+	name
+});
+/**
+* A bound literal value (parameterized, never interpolated).
+*/
+const val = (value) => new NodeExpression({
+	kind: "value",
+	value
+});
+/**
+* Raw SQL escape hatch with positional `?` bindings.
+*/
+const raw = (sql, bindings = []) => new NodeExpression({
+	kind: "raw",
+	sql,
+	bindings
+});
+/**
+* Starts a `CASE WHEN condition THEN result` expression.
+*/
+const caseWhen = (condition, result) => new CaseExpression([{
+	when: condition,
+	then: coerceValue(result)
+}]);
+/**
+* `COALESCE(a, b, …)` — first non-null argument. Bare strings are columns.
+*/
+const coalesce = (...args) => new NodeExpression({
+	kind: "function",
+	name: "coalesce",
+	args: args.map((arg) => coerceColumn(arg).toExpressionNode())
+});
+/**
+* An arbitrary SQL function call. Bare-string arguments are treated as columns.
+*/
+const fn = (name, ...args) => new NodeExpression({
+	kind: "function",
+	name,
+	args: args.map((arg) => coerceColumn(arg).toExpressionNode())
+});
+/**
+* JSON value extraction: `json('metadata', 'billType')` => `metadata ->> 'billType'`.
+*/
+const json = (column, ...path) => new JsonExpression(column, path.map(String));
+/**
+* `SUM(expr)`; a bare-string argument is treated as a column.
+*/
+const sum = (arg) => new AggregateExpression("sum", coerceColumn(arg));
+/**
+* `AVG(expr)`; a bare-string argument is treated as a column.
+*/
+const avg = (arg) => new AggregateExpression("avg", coerceColumn(arg));
+/**
+* `MIN(expr)`; a bare-string argument is treated as a column.
+*/
+const min = (arg) => new AggregateExpression("min", coerceColumn(arg));
+/**
+* `MAX(expr)`; a bare-string argument is treated as a column.
+*/
+const max = (arg) => new AggregateExpression("max", coerceColumn(arg));
+/**
+* `COUNT(expr)` — or `COUNT(*)` when called without an argument.
+*/
+const count = (arg) => new AggregateExpression("count", arg === void 0 ? void 0 : coerceColumn(arg));
+const EXPRESSION_OPERATORS = {
+	"=": "=",
+	"==": "=",
+	"!=": "!=",
+	"<>": "!=",
+	">": ">",
+	">=": ">=",
+	"<": "<",
+	"<=": "<=",
+	like: "like",
+	ilike: "ilike",
+	"not like": "not-like",
+	"not ilike": "not-ilike"
+};
+/**
+* Builds a comparison predicate: `where('createdAt', '>=', boundary)`. Handy as an
+* inline predicate for `caseWhen`, `having`, and aggregate `.filter(…)`.
+*/
+const where = (column, operator, value) => {
+	const normalized = EXPRESSION_OPERATORS[operator];
+	if (!normalized) throw new Error(`Unsupported expression operator [${operator}].`);
+	return binary(normalized, col(column), coerceValue(value));
+};
+/**
+* The expression-builder namespace passed to `static computed` factories, so a
+* model can declare a virtual attribute as `category: (e) => e.coalesce(…)`.
+*/
+const expressionBuilder = {
+	col,
+	val,
+	raw,
+	caseWhen,
+	coalesce,
+	fn,
+	json,
+	sum,
+	avg,
+	min,
+	max,
+	count,
+	where
+};
+
+//#endregion
+//#region src/helpers/generated-column.ts
+/**
+* Resolves a generated-column expression into raw Postgres SQL. Generated columns
+* cannot carry bind parameters (they must be immutable), so literal values are
+* inlined and aggregates are rejected.
+*/
+const resolveGeneratedExpression = (expression) => {
+	if (typeof expression === "string") return expression;
+	return expressionNodeToSql(expression(expressionBuilder).toExpressionNode());
+};
+const quoteIdentifier = (name) => name.split(".").map((part) => `"${part.replace(/"/g, "\"\"")}"`).join(".");
+const quoteLiteral = (value) => {
+	if (value === null || value === void 0) return "null";
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (value instanceof Date) return `'${value.toISOString()}'`;
+	return `'${String(value).replace(/'/g, "''")}'`;
+};
+const BINARY_OPERATORS = {
+	"=": "=",
+	"!=": "!=",
+	">": ">",
+	">=": ">=",
+	"<": "<",
+	"<=": "<=",
+	like: "like",
+	ilike: "ilike",
+	"not-like": "not like",
+	"not-ilike": "not ilike",
+	and: "and",
+	or: "or",
+	"+": "+",
+	"-": "-",
+	"*": "*",
+	"/": "/"
+};
+const FUNCTION_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const jsonAccessorSql = (node) => {
+	const base = `${quoteIdentifier(node.column)}::jsonb`;
+	let accessor;
+	if (node.path.length === 0) accessor = base;
+	else if (node.path.length === 1) accessor = `(${base} ->> ${quoteLiteral(node.path[0])})`;
+	else accessor = `(${base} #>> '{${node.path.join(",")}}'::text[])`;
+	if (node.cast === "number") return `(${accessor})::numeric`;
+	if (node.cast === "boolean") return `(${accessor})::boolean`;
+	return accessor;
+};
+const expressionNodeToSql = (node) => {
+	switch (node.kind) {
+		case "column": return quoteIdentifier(node.name);
+		case "value": return quoteLiteral(node.value);
+		case "raw": return inlineRawSql(node.sql, node.bindings);
+		case "json": return jsonAccessorSql(node);
+		case "function":
+			if (!FUNCTION_NAME.test(node.name)) throw new ArkormException(`Unsupported SQL function name [${node.name}].`);
+			return `${node.name}(${node.args.map(expressionNodeToSql).join(", ")})`;
+		case "case": return `case ${node.cases.map((branch) => `when ${expressionNodeToSql(branch.when)} then ${expressionNodeToSql(branch.then)}`).join(" ")}${node.else ? ` else ${expressionNodeToSql(node.else)}` : ""} end`;
+		case "binary": {
+			const operator = BINARY_OPERATORS[node.operator];
+			return `(${expressionNodeToSql(node.left)} ${operator} ${expressionNodeToSql(node.right)})`;
+		}
+		case "in": {
+			const values = node.values.map(expressionNodeToSql).join(", ");
+			return `(${expressionNodeToSql(node.operand)} ${node.not ? "not in" : "in"} (${values}))`;
+		}
+		case "null-check": return `(${expressionNodeToSql(node.operand)} is ${node.not ? "not null" : "null"})`;
+		case "aggregate": throw new ArkormException("Aggregate expressions are not allowed in generated columns.");
+		default: throw new ArkormException(`Unsupported expression node [${node.kind}].`);
+	}
+};
+const inlineRawSql = (sql, bindings) => {
+	const segments = sql.split("?");
+	if (segments.length !== bindings.length + 1) throw new ArkormException("Raw expression bindings do not match the number of placeholders.");
+	return segments.reduce((accumulator, segment, index) => {
+		const binding = index < bindings.length ? quoteLiteral(bindings[index]) : "";
+		return accumulator + segment + binding;
+	}, "");
+};
+
 //#endregion
 //#region src/database/TableBuilder.ts
 const PRISMA_ENUM_MEMBER_REGEX$1 = /^[A-Za-z][A-Za-z0-9_]*$/;
@@ -666,6 +1079,30 @@ var TableBuilder = class {
 		return this.column(name, "dateTime", options);
 	}
 	/**
+	* Defines a database-computed column (`GENERATED ALWAYS AS (…) STORED`). The
+	* expression may be a raw SQL string or an expression-builder factory, and must
+	* be immutable and reference only the row's own columns. Combine with
+	* {@link index} to index the generated value.
+	*
+	* @example
+	* table.generated('category', "case when metadata->>'kind' = 'a' then 'x' else 'y' end", {
+	*   type: 'text',
+	* })
+	* table.generated('total', (e) => e.col('price').times(e.col('quantity')), { type: 'integer' })
+	*
+	* @param name        The generated column name.
+	* @param expression  The SQL expression string, or a builder factory.
+	* @param options     Column type (default `text`), `stored` flag, and nullability.
+	* @returns
+	*/
+	generated(name, expression, options = {}) {
+		return this.column(name, options.type ?? "text", {
+			generatedExpression: resolveGeneratedExpression(expression),
+			generatedStored: options.stored ?? true,
+			nullable: options.nullable
+		});
+	}
+	/**
 	* Defines colonns for a polymorphic relationship in the table.
 	*
 	* @param name    The base name for the polymorphic relationship columns.
@@ -1001,6 +1438,8 @@ var TableBuilder = class {
 			updatedAt: options.updatedAt,
 			precision: options.precision,
 			scale: options.scale,
+			generatedExpression: options.generatedExpression,
+			generatedStored: options.generatedStored,
 			primaryKeyGeneration: options.primaryKeyGeneration
 		});
 		const column = this.columns[this.columns.length - 1];
@@ -1384,6 +1823,10 @@ const buildFieldLine = (column) => {
 	const mapped = typeof column.map === "string" && column.map.trim().length > 0 ? ` @map("${column.map.replace(/"/g, "\\\"")}")` : "";
 	const updatedAt = column.updatedAt ? " @updatedAt" : "";
 	const nativeType = column.type === "decimal" ? ` @db.Decimal(${column.precision ?? 8}, ${column.scale ?? 2})` : "";
+	if (column.generatedExpression) {
+		const escaped = column.generatedExpression.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+		return `  ${column.name} ${scalar}${nullable}${unique} @default(dbgenerated("${escaped}"))${mapped}${nativeType}`;
+	}
 	const defaultValue = column.type === "enum" ? formatEnumDefaultValue(column.default) : column.primaryKeyGeneration?.prismaDefault ?? formatDefaultValue(column.default);
 	const defaultSuffix = defaultValue ? ` ${defaultValue}` : "";
 	return `  ${column.name} ${scalar}${nullable}${primary}${unique}${defaultSuffix}${updatedAt}${mapped}${nativeType}`;
@@ -2816,6 +3259,7 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 			rawWhere: false,
 			distinct: false,
 			groupBy: false,
+			expressions: false,
 			returning: false
 		};
 	}
@@ -2851,6 +3295,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 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 UnsupportedAdapterFeatureException("Raw select expressions are not supported by the Prisma compatibility adapter; use a SQL-backed adapter or DB.raw().", {
 			operation: "adapter.select",
@@ -2868,6 +3320,10 @@ var PrismaDatabaseAdapter = class PrismaDatabaseAdapter {
 	}
 	toQueryOrderBy(orderBy) {
 		if (!orderBy || orderBy.length === 0) return void 0;
+		if (orderBy.some((entry) => entry.expression)) throw new 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) {
@@ -4242,7 +4698,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
@@ -4253,22 +4710,22 @@ var MigrateCommand = class extends 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
 	*/
@@ -4477,10 +4934,10 @@ var MigrateFreshCommand = class extends 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";
@@ -4635,12 +5092,12 @@ var MigrateRollbackCommand = class extends 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";
 	}
@@ -4655,7 +5112,7 @@ var MigrateRollbackCommand = class extends Command {
 		const useDatabaseMigrations = supportsDatabaseMigrationExecution(adapter);
 		const persistedFeatures = resolvePersistedMetadataFeatures(this.app.getConfig("features"));
 		let appliedState = await 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 ? getLatestAppliedMigrations(appliedState, stepCount) : (() => {