arkormx 2.10.2 → 2.11.0

package/dist/{relationship-DWtfgLfh.cjs → relationship-IC-TAFyG.cjs}

@@ -1126,6 +1126,423 @@ 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);
+};
+/**
+* Rebuilds an {@link Expression} around an already-serialized node.
+*/
+const fromExpressionNode = (node) => new NodeExpression(node);
+/**
+* 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_]*$/;
@@ -1429,6 +1846,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.
@@ -1764,6 +2205,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];
@@ -2147,6 +2590,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}`;
@@ -6025,6 +6472,12 @@ var MorphToRelation = class extends Relation {
 };
 
 //#endregion
+Object.defineProperty(exports, 'AggregateExpression', {
+  enumerable: true,
+  get: function () {
+    return AggregateExpression;
+  }
+});
 Object.defineProperty(exports, 'ArkormCollection', {
   enumerable: true,
   get: function () {
@@ -6049,12 +6502,24 @@ Object.defineProperty(exports, 'BelongsToRelation', {
     return BelongsToRelation;
   }
 });
+Object.defineProperty(exports, 'CaseExpression', {
+  enumerable: true,
+  get: function () {
+    return CaseExpression;
+  }
+});
 Object.defineProperty(exports, 'EnumBuilder', {
   enumerable: true,
   get: function () {
     return EnumBuilder;
   }
 });
+Object.defineProperty(exports, 'Expression', {
+  enumerable: true,
+  get: function () {
+    return Expression;
+  }
+});
 Object.defineProperty(exports, 'ForeignKeyBuilder', {
   enumerable: true,
   get: function () {
@@ -6085,6 +6550,12 @@ Object.defineProperty(exports, 'HasOneThroughRelation', {
     return HasOneThroughRelation;
   }
 });
+Object.defineProperty(exports, 'JsonExpression', {
+  enumerable: true,
+  get: function () {
+    return JsonExpression;
+  }
+});
 Object.defineProperty(exports, 'LengthAwarePaginator', {
   enumerable: true,
   get: function () {
@@ -6265,6 +6736,12 @@ Object.defineProperty(exports, 'applyOperationsToPrismaSchema', {
     return applyOperationsToPrismaSchema;
   }
 });
+Object.defineProperty(exports, 'avg', {
+  enumerable: true,
+  get: function () {
+    return avg;
+  }
+});
 Object.defineProperty(exports, 'awaitConfiguredModelsRegistration', {
   enumerable: true,
   get: function () {
@@ -6343,6 +6820,24 @@ Object.defineProperty(exports, 'buildUniqueConstraintLine', {
     return buildUniqueConstraintLine;
   }
 });
+Object.defineProperty(exports, 'caseWhen', {
+  enumerable: true,
+  get: function () {
+    return caseWhen;
+  }
+});
+Object.defineProperty(exports, 'coalesce', {
+  enumerable: true,
+  get: function () {
+    return coalesce;
+  }
+});
+Object.defineProperty(exports, 'col', {
+  enumerable: true,
+  get: function () {
+    return col;
+  }
+});
 Object.defineProperty(exports, 'computeMigrationChecksum', {
   enumerable: true,
   get: function () {
@@ -6355,6 +6850,12 @@ Object.defineProperty(exports, 'configureArkormRuntime', {
     return configureArkormRuntime;
   }
 });
+Object.defineProperty(exports, 'count', {
+  enumerable: true,
+  get: function () {
+    return count;
+  }
+});
 Object.defineProperty(exports, 'createEmptyAppliedMigrationsState', {
   enumerable: true,
   get: function () {
@@ -6439,6 +6940,12 @@ Object.defineProperty(exports, 'escapeRegex', {
     return escapeRegex;
   }
 });
+Object.defineProperty(exports, 'expressionBuilder', {
+  enumerable: true,
+  get: function () {
+    return expressionBuilder;
+  }
+});
 Object.defineProperty(exports, 'findAppliedMigration', {
   enumerable: true,
   get: function () {
@@ -6457,6 +6964,12 @@ Object.defineProperty(exports, 'findModelBlock', {
     return findModelBlock;
   }
 });
+Object.defineProperty(exports, 'fn', {
+  enumerable: true,
+  get: function () {
+    return fn;
+  }
+});
 Object.defineProperty(exports, 'formatDefaultValue', {
   enumerable: true,
   get: function () {
@@ -6475,6 +6988,12 @@ Object.defineProperty(exports, 'formatRelationAction', {
     return formatRelationAction;
   }
 });
+Object.defineProperty(exports, 'fromExpressionNode', {
+  enumerable: true,
+  get: function () {
+    return fromExpressionNode;
+  }
+});
 Object.defineProperty(exports, 'generateMigrationFile', {
   enumerable: true,
   get: function () {
@@ -6649,6 +7168,12 @@ Object.defineProperty(exports, 'isTransactionCapableClient', {
     return isTransactionCapableClient;
   }
 });
+Object.defineProperty(exports, 'json', {
+  enumerable: true,
+  get: function () {
+    return json;
+  }
+});
 Object.defineProperty(exports, 'loadArkormConfig', {
   enumerable: true,
   get: function () {
@@ -6691,12 +7216,30 @@ Object.defineProperty(exports, 'markMigrationRun', {
     return markMigrationRun;
   }
 });
+Object.defineProperty(exports, 'max', {
+  enumerable: true,
+  get: function () {
+    return max;
+  }
+});
+Object.defineProperty(exports, 'min', {
+  enumerable: true,
+  get: function () {
+    return min;
+  }
+});
 Object.defineProperty(exports, 'pad', {
   enumerable: true,
   get: function () {
     return pad;
   }
 });
+Object.defineProperty(exports, 'raw', {
+  enumerable: true,
+  get: function () {
+    return raw;
+  }
+});
 Object.defineProperty(exports, 'readAppliedMigrationsState', {
   enumerable: true,
   get: function () {
@@ -6787,6 +7330,12 @@ Object.defineProperty(exports, 'resolveEnumName', {
     return resolveEnumName;
   }
 });
+Object.defineProperty(exports, 'resolveGeneratedExpression', {
+  enumerable: true,
+  get: function () {
+    return resolveGeneratedExpression;
+  }
+});
 Object.defineProperty(exports, 'resolveMigrationClassName', {
   enumerable: true,
   get: function () {
@@ -6835,6 +7384,12 @@ Object.defineProperty(exports, 'stripPrismaSchemaModelsAndEnums', {
     return stripPrismaSchemaModelsAndEnums;
   }
 });
+Object.defineProperty(exports, 'sum', {
+  enumerable: true,
+  get: function () {
+    return sum;
+  }
+});
 Object.defineProperty(exports, 'supportsDatabaseCreation', {
   enumerable: true,
   get: function () {
@@ -6877,12 +7432,24 @@ Object.defineProperty(exports, 'toModelName', {
     return toModelName;
   }
 });
+Object.defineProperty(exports, 'val', {
+  enumerable: true,
+  get: function () {
+    return val;
+  }
+});
 Object.defineProperty(exports, 'validatePersistedMetadataFeaturesForMigrations', {
   enumerable: true,
   get: function () {
     return validatePersistedMetadataFeaturesForMigrations;
   }
 });
+Object.defineProperty(exports, 'where', {
+  enumerable: true,
+  get: function () {
+    return where;
+  }
+});
 Object.defineProperty(exports, 'writeAppliedMigrationsState', {
   enumerable: true,
   get: function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkormx",
-  "version": "2.10.2",
+  "version": "2.11.0",
   "description": "Modern TypeScript-first ORM for Node.js.",
   "keywords": [
     "orm",