alepha 0.18.2 → 0.18.3

package/dist/orm/core/index.bun.js

@@ -3,13 +3,13 @@ import { $atom, $context, $env, $hook, $inject, $mode, $module, $use, Alepha, Al
 import { AlephaDateTime, DateTimeProvider } from "alepha/datetime";
 import { alias, customType } from "drizzle-orm/pg-core";
 import * as drizzle from "drizzle-orm";
-import { and, arrayContained, arrayContains, arrayOverlaps, asc, between, desc, eq, getTableName, gt, gte, ilike, inArray, isNotNull, isNull, isSQLWrapper, like, lt, lte, ne, not, notBetween, notIlike, notInArray, notLike, or, sql, sql as sql$1 } from "drizzle-orm";
+import { and, arrayContained, arrayContains, arrayOverlaps, asc, avg, between, count, desc, eq, exists, getTableName, gt, gte, ilike, inArray, isNotNull, isNull, isSQLWrapper, like, lt, lte, max, min, ne, not, notBetween, notExists, notIlike, notInArray, notLike, or, sql, sql as sql$1, sum } from "drizzle-orm";
 import { mkdir, stat } from "node:fs/promises";
 import { $logger } from "alepha/logger";
 import { dirname } from "node:path";
 import { randomUUID } from "node:crypto";
 import * as pg from "drizzle-orm/sqlite-core";
-import { check, foreignKey, index, sqliteTable, unique, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { check, foreignKey, index, sqliteTable, sqliteView, unique, uniqueIndex } from "drizzle-orm/sqlite-core";
 import { isSQLWrapper as isSQLWrapper$1 } from "drizzle-orm/sql/sql";
 
 export * from "drizzle-orm/pg-core"
@@ -59,6 +59,7 @@ const PG_VERSION = Symbol.for("Alepha.Postgres.Version");
 const PG_IDENTITY = Symbol.for("Alepha.Postgres.Identity");
 const PG_ENUM = Symbol.for("Alepha.Postgres.Enum");
 const PG_REF = Symbol.for("Alepha.Postgres.Ref");
+const PG_GENERATED = Symbol.for("Alepha.Postgres.Generated");
 /**
 * @deprecated Use `PG_IDENTITY` instead.
 */
@@ -81,6 +82,7 @@ const insertSchema = (obj) => {
 	const newProperties = {};
 	for (const key in obj.properties) {
 		const prop = obj.properties[key];
+		if (PG_GENERATED in prop) continue;
 		if (PG_DEFAULT in prop) newProperties[key] = t.optional(prop);
 		else newProperties[key] = prop;
 	}
@@ -93,6 +95,7 @@ const updateSchema = (schema) => {
 	const newProperties = {};
 	for (const key in schema.properties) {
 		const prop = schema.properties[key];
+		if (PG_GENERATED in prop) continue;
 		if (t.schema.isOptional(prop)) newProperties[key] = t.optional(t.union([prop, t.raw.Null()]));
 		else newProperties[key] = prop;
 	}
@@ -166,6 +169,26 @@ var DbError = class extends AlephaError {
 	}
 };
 
+//#endregion
+//#region ../../src/orm/core/schemas/databaseEnvSchema.ts
+/**
+* Base database environment schema.
+*
+* Defines the `DATABASE_URL` connection string used by all ORM providers
+* to determine the database driver and connection target.
+*
+* Supported URL formats:
+* - `sqlite://:memory:` or `sqlite://./path/to/db` — SQLite (Node.js or Bun)
+* - `postgres://user:password@host:port/database` — PostgreSQL (Node.js or Bun)
+* - `pglite://:memory:` or `pglite://./path` — PGlite (embedded Postgres)
+* - `d1://BINDING_NAME` — Cloudflare D1
+* - `hyperdrive://BINDING_NAME` — Cloudflare Hyperdrive
+*/
+const databaseEnvSchema = t.object({
+	DATABASE_URL: t.optional(t.text()),
+	DATABASE_SYNC: t.optional(t.boolean())
+});
+
 //#endregion
 //#region ../../src/orm/core/providers/DrizzleKitProvider.ts
 var DrizzleKitProvider = class {
@@ -291,6 +314,32 @@ var DrizzleKitProvider = class {
 		}
 		return models;
 	}
+	/**
+	* Preview schema push without executing any statements.
+	*
+	* Returns the SQL statements that would be executed, warnings, and
+	* whether data loss would occur. Does NOT execute any SQL.
+	*/
+	async dryRunPush(provider) {
+		const kit = this.importDrizzleKit();
+		const models = this.getModels(provider);
+		if (Object.keys(models).length === 0) return {
+			statements: [],
+			warnings: [],
+			hasDataLoss: false
+		};
+		let result;
+		if (provider.dialect === "sqlite") result = await this.muteSpinner(() => kit.pushSQLiteSchema(models, provider.db));
+		else {
+			const wrappedDb = this.wrapDbForDrizzleKit(provider.db);
+			result = await this.muteSpinner(() => kit.pushSchema(models, wrappedDb, [provider.schema]));
+		}
+		return {
+			statements: result.statementsToExecute,
+			warnings: result.warnings,
+			hasDataLoss: result.hasDataLoss
+		};
+	}
 	async pushSqlite(kit, models, provider) {
 		const result = await this.muteSpinner(() => kit.pushSQLiteSchema(models, provider.db));
 		await this.runPushResult(result, provider);
@@ -418,6 +467,14 @@ var DatabaseProvider = class {
 		return this.dialect;
 	}
 	/**
+	* Whether this driver supports SQL-level transactions (BEGIN/COMMIT/ROLLBACK).
+	*
+	* Drivers that do not (e.g. PGlite, Cloudflare D1) should override to `false`.
+	*/
+	get supportsTransactions() {
+		return true;
+	}
+	/**
 	* Raw database connection handle (e.g. DatabaseSync, bun:sqlite Database).
 	* Override in providers that expose native connections for introspection.
 	*/
@@ -475,6 +532,9 @@ var DatabaseProvider = class {
 		this.entityPrimitives.push(entity);
 		this.builder.buildTable(entity, this);
 	}
+	registerView(view) {
+		this.builder.buildView(view, this);
+	}
 	registerSequence(sequence) {
 		this.sequencePrimitives.push(sequence);
 		this.builder.buildSequence(sequence, this);
@@ -509,6 +569,7 @@ var DatabaseProvider = class {
 	*/
 	async transactional(fn, config) {
 		if (this.alepha.get("alepha.orm.tx")) return fn();
+		if (!this.supportsTransactions) return fn();
 		return this.db.transaction(async (tx) => {
 			this.alepha.store.set("alepha.orm.tx", tx, { skipEvents: true });
 			try {
@@ -519,7 +580,13 @@ var DatabaseProvider = class {
 		}, config);
 	}
 	async run(statement, schema) {
-		return (await this.execute(statement)).map((row) => this.alepha.codec.decode(schema, row));
+		const result = await this.execute(statement);
+		if (result == null) return [];
+		if (!Array.isArray(result)) {
+			this.log.error("Unexpected query result format", { result });
+			throw new DbError("Unexpected query result format, expected array of rows");
+		}
+		return result.map((row) => this.alepha.codec.decode(schema, row));
 	}
 	/**
 	* Get migrations folder path - can be overridden
@@ -549,10 +616,17 @@ var DatabaseProvider = class {
 			this.log.debug(`Migrate from '${migrationsFolder}' directory ...`);
 			await this.executeMigrations(migrationsFolder);
 			this.log.info("Migration OK");
-		} else try {
-			await this.kit.synchronize(this);
-		} catch (error) {
-			throw new DbError(`Failed to synchronize ${this.dialect} database schema`, error);
+		} else {
+			const { DATABASE_SYNC } = this.alepha.parseEnv(databaseEnvSchema);
+			if (DATABASE_SYNC === false) {
+				this.log.info("Database synchronization disabled (DATABASE_SYNC=false)");
+				return;
+			}
+			try {
+				await this.kit.synchronize(this);
+			} catch (error) {
+				throw new DbError(`Failed to synchronize ${this.dialect} database schema`, error);
+			}
 		}
 	}
 	/**
@@ -629,14 +703,20 @@ var ModelBuilder = class {
 					if ("column" in indexDef) {
 						const columnName = this.toColumnName(indexDef.column);
 						const indexName = indexDef.name || `${entity.name}_${columnName}_idx`;
-						if (self[indexDef.column]) if (indexDef.unique) configs.push(builders.uniqueIndex(indexName).on(self[indexDef.column]));
-						else configs.push(builders.index(indexName).on(self[indexDef.column]));
+						if (self[indexDef.column]) {
+							let idx = indexDef.unique ? builders.uniqueIndex(indexName).on(self[indexDef.column]) : builders.index(indexName).on(self[indexDef.column]);
+							if ("where" in indexDef && indexDef.where) idx = idx.where(indexDef.where);
+							configs.push(idx);
+						}
 					} else if ("columns" in indexDef) {
 						const columnNames = indexDef.columns.map((col) => this.toColumnName(col));
 						const indexName = indexDef.name || `${entity.name}_${columnNames.join("_")}_idx`;
 						const cols = indexDef.columns.map((col) => self[col]).filter(Boolean);
-						if (cols.length === indexDef.columns.length) if (indexDef.unique) configs.push(builders.uniqueIndex(indexName).on(...cols));
-						else configs.push(builders.index(indexName).on(...cols));
+						if (cols.length === indexDef.columns.length) {
+							let idx = indexDef.unique ? builders.uniqueIndex(indexName).on(...cols) : builders.index(indexName).on(...cols);
+							if ("where" in indexDef && indexDef.where) idx = idx.where(indexDef.where);
+							configs.push(idx);
+						}
 					}
 				}
 			}
@@ -695,6 +775,13 @@ var SqliteModelBuilder = class extends ModelBuilder {
 		const table = sqliteTable(tableName, this.schemaToSqliteColumns(tableName, entity.schema, options.enums, options.tables), this.getTableConfig(entity, options.tables));
 		options.tables.set(tableName, table);
 	}
+	buildView(view, options) {
+		const viewName = view.name;
+		if (options.tables.has(viewName)) return;
+		if (view.materialized) throw new AlephaError("SQLite does not support materialized views");
+		const drizzleView = sqliteView(viewName, this.schemaToSqliteColumns(viewName, view.schema, /* @__PURE__ */ new Map(), options.tables)).existing();
+		options.tables.set(viewName, drizzleView);
+	}
 	buildSequence(sequence, options) {
 		throw new AlephaError("SQLite does not support sequences");
 	}
@@ -733,6 +820,10 @@ var SqliteModelBuilder = class extends ModelBuilder {
 					return target;
 				}, config.actions);
 			}
+			if (PG_GENERATED in value) {
+				const gen = value[PG_GENERATED];
+				col = col.generatedAlwaysAs(gen.expression, { mode: gen.mode ?? "virtual" });
+			}
 			if (schema.required?.includes(key)) col = col.notNull();
 			return {
 				...columns,
@@ -816,7 +907,7 @@ var SqliteModelBuilder = class extends ModelBuilder {
 
 //#endregion
 //#region ../../src/orm/core/providers/drivers/BunSqliteProvider.ts
-const envSchema = t.object({ DATABASE_URL: t.optional(t.text()) });
+const envSchema = databaseEnvSchema;
 /**
 * Configuration options for the Bun SQLite database provider.
 */
@@ -947,6 +1038,17 @@ var CloudflareD1Provider = class extends DatabaseProvider {
 		const { rows } = await this.db.run(query);
 		return rows;
 	}
+	/**
+	* D1 does not support SQL-level transactions (BEGIN/COMMIT/ROLLBACK).
+	* It rejects these statements and requires the JS `batch()` API for atomic
+	* multi-statement operations instead.
+	*
+	* @see https://developers.cloudflare.com/d1/worker-api/d1-database/#batch-statements
+	* @see https://github.com/drizzle-team/drizzle-orm/issues/2463
+	*/
+	get supportsTransactions() {
+		return false;
+	}
 	onStart = $hook({
 		on: "start",
 		handler: async () => {
@@ -1278,6 +1380,54 @@ const getAttrFields = (schema, name) => {
 	return fields;
 };
 
+//#endregion
+//#region ../../src/orm/core/providers/DbCacheProvider.ts
+/**
+* Database query cache using a simple in-memory Map.
+*
+* Uses `{tableName}:{cacheKey}` as the storage key.
+* Provides per-table invalidation for write-through cache busting.
+*
+* This is intentionally self-contained (no external cache dependencies)
+* so the ORM module does not force `AlephaCache` on all consumers.
+*/
+var DbCacheProvider = class {
+	store = /* @__PURE__ */ new Map();
+	storeKey(tableName, cacheKey) {
+		return `${tableName}:${cacheKey}`;
+	}
+	/**
+	* Get a cached query result.
+	*/
+	async get(tableName, cacheKey) {
+		const key = this.storeKey(tableName, cacheKey);
+		const entry = this.store.get(key);
+		if (!entry) return void 0;
+		if (entry.expiresAt && Date.now() > entry.expiresAt) {
+			this.store.delete(key);
+			return;
+		}
+		return entry.value;
+	}
+	/**
+	* Store a query result in the cache.
+	*/
+	async set(tableName, cacheKey, value, ttl) {
+		const key = this.storeKey(tableName, cacheKey);
+		this.store.set(key, {
+			value,
+			expiresAt: ttl ? Date.now() + ttl : void 0
+		});
+	}
+	/**
+	* Invalidate all cached queries for a table.
+	*/
+	async invalidateTable(tableName) {
+		const prefix = `${tableName}:`;
+		for (const key of this.store.keys()) if (key.startsWith(prefix)) this.store.delete(key);
+	}
+};
+
 //#endregion
 //#region ../../src/orm/core/services/PgRelationManager.ts
 var PgRelationManager = class {
@@ -1402,6 +1552,14 @@ var QueryManager = class {
 					});
 					if (where) return not(where);
 				}
+				if (key === "exists") {
+					conditions.push(exists(operator));
+					continue;
+				}
+				if (key === "notExists") {
+					conditions.push(notExists(operator));
+					continue;
+				}
 				if (operator) {
 					const column = col(key);
 					const sql = this.mapOperatorToSql(operator, column, schema, key, options.dialect);
@@ -1581,6 +1739,7 @@ var Repository = class Repository {
 	relationManager = $inject(PgRelationManager);
 	queryManager = $inject(QueryManager);
 	dateTimeProvider = $inject(DateTimeProvider);
+	dbCache = new DbCacheProvider();
 	alepha = $inject(Alepha);
 	static of(entity, provider = DatabaseProvider) {
 		return class InlineRepository extends Repository {
@@ -1592,7 +1751,8 @@ var Repository = class Repository {
 	constructor(entity, provider = DatabaseProvider) {
 		this.entity = entity;
 		this.provider = this.alepha.inject(provider);
-		this.provider.registerEntity(entity);
+		if (entity.isView) this.provider.registerView(entity);
+		else this.provider.registerEntity(entity);
 	}
 	/**
 	* Represents the primary key of the table.
@@ -1617,6 +1777,12 @@ var Repository = class Repository {
 		return this.entity.name;
 	}
 	/**
+	* Whether this repository is backed by a view (read-only).
+	*/
+	get isReadOnly() {
+		return this.entity.isView === true;
+	}
+	/**
 	* Getter for the database connection from the database provider.
 	*
 	* Automatically picks up a transaction from `alepha.store` if one was set
@@ -1656,6 +1822,8 @@ var Repository = class Repository {
 		} catch (error) {
 			throw this.handleError(error, "Custom query has failed");
 		}
+		if (rows == null) return [];
+		if (!Array.isArray(rows)) throw new DbError("Invalid query result. Expected an array of rows, but got: " + JSON.stringify(rows));
 		return rows.map((it) => {
 			return this.clean(this.mapRawFieldsToEntity(it), schema ?? this.entity.schema);
 		});
@@ -1689,8 +1857,8 @@ var Repository = class Repository {
 	* Run a transaction.
 	*/
 	async transaction(transaction, config) {
-		if (this.provider.driver === "pglite") {
-			this.log.warn("Transactions are not supported with pglite driver");
+		if (!this.provider.supportsTransactions) {
+			this.log.warn(`Transactions are not supported with ${this.provider.driver} driver`);
 			return await transaction(null);
 		}
 		this.log.debug(`Starting transaction on table ${this.tableName}`);
@@ -1736,6 +1904,11 @@ var Repository = class Repository {
 	* > This method is the base for `find`, `findOne`, `findById`, and `paginate`.
 	*/
 	async findMany(query = {}, opts = {}) {
+		if (opts.cache) {
+			const cacheKey = opts.cache.key ?? this.buildCacheKey("findMany", query);
+			const cached = await this.dbCache.get(this.tableName, cacheKey);
+			if (cached) return cached;
+		}
 		await this.alepha.events.emit("repository:read:before", {
 			tableName: this.tableName,
 			query
@@ -1783,7 +1956,12 @@ var Repository = class Repository {
 				query,
 				entities: rows
 			});
-			return rows;
+			const result = rows;
+			if (opts.cache) {
+				const cacheKey = opts.cache.key ?? this.buildCacheKey("findMany", query);
+				await this.dbCache.set(this.tableName, cacheKey, result, opts.cache.ttl);
+			}
+			return result;
 		} catch (error) {
 			throw this.handleError(error, "Query select has failed");
 		}
@@ -1883,12 +2061,14 @@ var Repository = class Repository {
 	* @returns The ID of the created entity.
 	*/
 	async create(data, opts = {}) {
+		this.assertWritable();
 		await this.alepha.events.emit("repository:create:before", {
 			tableName: this.tableName,
 			data
 		});
 		try {
 			const entity = await this.rawInsert(opts).values(this.cast(data ?? {}, true)).returning(this.table).then(([it]) => this.clean(it, this.entity.schema));
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:create:after", {
 				tableName: this.tableName,
 				data,
@@ -1909,6 +2089,7 @@ var Repository = class Repository {
 	* @returns The created entities.
 	*/
 	async createMany(values, opts = {}) {
+		this.assertWritable();
 		if (values.length === 0) return [];
 		await this.alepha.events.emit("repository:create:before", {
 			tableName: this.tableName,
@@ -1922,6 +2103,7 @@ var Repository = class Repository {
 				const entities = await this.rawInsert(opts).values(batch.map((data) => this.cast(data, true))).returning(this.table).then((rows) => rows.map((it) => this.clean(it, this.entity.schema)));
 				allEntities.push(...entities);
 			}
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:create:after", {
 				tableName: this.tableName,
 				data: values,
@@ -1962,6 +2144,7 @@ var Repository = class Repository {
 	* ```
 	*/
 	async upsert(data, opts = {}) {
+		this.assertWritable();
 		await this.alepha.events.emit("repository:create:before", {
 			tableName: this.tableName,
 			data
@@ -1982,6 +2165,7 @@ var Repository = class Repository {
 				target: targetColumns,
 				set: setData
 			}).returning(this.table).then(([it]) => this.clean(it, this.entity.schema));
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:create:after", {
 				tableName: this.tableName,
 				data,
@@ -1996,6 +2180,7 @@ var Repository = class Repository {
 	* Find an entity and update it.
 	*/
 	async updateOne(where, data, opts = {}) {
+		this.assertWritable();
 		await this.alepha.events.emit("repository:update:before", {
 			tableName: this.tableName,
 			where,
@@ -2013,6 +2198,7 @@ var Repository = class Repository {
 		if (!response[0]) throw new DbEntityNotFoundError(this.tableName);
 		try {
 			const entity = this.clean(response[0], this.entity.schema);
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:update:after", {
 				tableName: this.tableName,
 				where,
@@ -2045,6 +2231,7 @@ var Repository = class Repository {
 	* @see {@link DbVersionMismatchError}
 	*/
 	async save(entity, opts = {}) {
+		this.assertWritable();
 		const row = entity;
 		const id = row[this.id.key];
 		if (id == null) throw new AlephaError("Cannot save entity without ID - missing primary key in value");
@@ -2082,6 +2269,7 @@ var Repository = class Repository {
 	* Find many entities and update all of them.
 	*/
 	async updateMany(where, data, opts = {}) {
+		this.assertWritable();
 		await this.alepha.events.emit("repository:update:before", {
 			tableName: this.tableName,
 			where,
@@ -2093,6 +2281,7 @@ var Repository = class Repository {
 		data = this.cast(data, false);
 		try {
 			const entities = await this.rawUpdate(opts).set(data).where(this.toSQL(where)).returning();
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:update:after", {
 				tableName: this.tableName,
 				where,
@@ -2109,6 +2298,7 @@ var Repository = class Repository {
 	* @returns Array of deleted entity IDs
 	*/
 	async deleteMany(where = {}, opts = {}) {
+		this.assertWritable();
 		const deletedAt = this.deletedAt();
 		if (deletedAt && !opts.force) return await this.updateMany(where, { [deletedAt.key]: opts.now ?? this.dateTimeProvider.nowISOString() }, opts);
 		await this.alepha.events.emit("repository:delete:before", {
@@ -2117,6 +2307,7 @@ var Repository = class Repository {
 		});
 		try {
 			const ids = (await this.rawDelete(opts).where(this.toSQL(where)).returning({ id: this.table[this.id.key] })).map((row) => row.id);
+			this.dbCache.invalidateTable(this.tableName).catch(() => {});
 			await this.alepha.events.emit("repository:delete:after", {
 				tableName: this.tableName,
 				where,
@@ -2176,6 +2367,97 @@ var Repository = class Repository {
 		where = this.withDeletedAt(where, opts);
 		return (opts.tx === null ? this.provider.db : opts.tx ?? this.db).$count(this.table, this.toSQL(where));
 	}
+	/**
+	* Execute an aggregate query with type-safe select, groupBy, and having.
+	*
+	* @example
+	* ```ts
+	* const result = await repo.aggregate({
+	*   select: { category: true, amount: { sum: true, avg: true } },
+	*   groupBy: ["category"],
+	*   having: { amount: { sum: { gt: 100 } } },
+	*   orderBy: { column: "amount.sum", direction: "desc" },
+	* });
+	* // result: Array<{ category: string; amount: { sum: number; avg: number } }>
+	* ```
+	*/
+	async aggregate(query, opts = {}) {
+		const AGG_SEPARATOR = "___";
+		const flatFields = {};
+		const aggFn = (op, column) => {
+			switch (op) {
+				case "count": return count(column);
+				case "sum": return sum(column);
+				case "avg": return avg(column);
+				case "min": return min(column);
+				case "max": return max(column);
+			}
+		};
+		for (const [key, select] of Object.entries(query.select)) if (select === true) flatFields[key] = this.col(key);
+		else if (typeof select === "object" && select !== null) {
+			for (const op of Object.keys(select)) if (select[op]) flatFields[`${key}${AGG_SEPARATOR}${op}`] = aggFn(op, this.col(key));
+		}
+		let builder = (opts.tx === null ? this.provider.db : opts.tx ?? this.db).select(flatFields).from(this.table);
+		if (query.where) {
+			const where = this.withDeletedAt(query.where, opts);
+			builder = builder.where(this.toSQL(where));
+		}
+		if (query.groupBy) builder = builder.groupBy(...query.groupBy.map((key) => this.col(key)));
+		if (query.having) {
+			const havingConditions = [];
+			for (const [key, ops] of Object.entries(query.having)) {
+				if (!ops || typeof ops !== "object") continue;
+				for (const [op, comparisons] of Object.entries(ops)) {
+					if (!comparisons || typeof comparisons !== "object") continue;
+					const aggExpr = aggFn(op, this.col(key));
+					for (const [cmp, val] of Object.entries(comparisons)) switch (cmp) {
+						case "gt":
+							havingConditions.push(gt(aggExpr, val));
+							break;
+						case "gte":
+							havingConditions.push(gte(aggExpr, val));
+							break;
+						case "lt":
+							havingConditions.push(lt(aggExpr, val));
+							break;
+						case "lte":
+							havingConditions.push(lte(aggExpr, val));
+							break;
+						case "eq":
+							havingConditions.push(eq(aggExpr, val));
+							break;
+						case "ne":
+							havingConditions.push(ne(aggExpr, val));
+							break;
+					}
+				}
+			}
+			if (havingConditions.length > 0) builder = builder.having(and(...havingConditions));
+		}
+		if (query.orderBy) {
+			const clauses = this.queryManager.normalizeOrderBy(query.orderBy);
+			builder = builder.orderBy(...clauses.map((clause) => {
+				const col = flatFields[clause.column.includes(".") ? clause.column.replace(".", AGG_SEPARATOR) : clause.column];
+				if (!col) throw new AlephaError(`Invalid orderBy column '${clause.column}' in aggregate query`);
+				return clause.direction === "desc" ? desc(col) : asc(col);
+			}));
+		}
+		if (query.limit) builder = builder.limit(query.limit);
+		if (query.offset) builder = builder.offset(query.offset);
+		try {
+			return (await builder.execute()).map((row) => {
+				const result = {};
+				for (const [flatKey, value] of Object.entries(row)) if (flatKey.includes(AGG_SEPARATOR)) {
+					const [col, op] = flatKey.split(AGG_SEPARATOR);
+					if (!result[col]) result[col] = {};
+					result[col][op] = value != null ? Number(value) : 0;
+				} else result[flatKey] = value;
+				return result;
+			});
+		} catch (error) {
+			throw this.handleError(error, "Aggregate query has failed");
+		}
+	}
 	errorPatterns = {
 		conflict: ["duplicate key value violates unique constraint", "UNIQUE constraint failed"],
 		foreignKey: ["violates foreign key constraint", "FOREIGN KEY constraint failed"],
@@ -2251,6 +2533,25 @@ var Repository = class Repository {
 		return entity;
 	}
 	/**
+	* Throw if this repository is read-only (backed by a view).
+	*/
+	assertWritable() {
+		if (this.isReadOnly) throw new AlephaError(`Cannot write to view '${this.tableName}'. Views are read-only.`);
+	}
+	/**
+	* Refresh a materialized view. PostgreSQL only.
+	*/
+	async refresh() {
+		if (!this.entity.materialized) throw new AlephaError(`Cannot refresh '${this.tableName}'. Only materialized views support refresh.`);
+		await this.provider.execute(`REFRESH MATERIALIZED VIEW ${this.tableName}`);
+	}
+	/**
+	* Build a cache key from method name and query parameters.
+	*/
+	buildCacheKey(method, query) {
+		return `${method}:${JSON.stringify(query)}`;
+	}
+	/**
 	* Convert a where clause to SQL.
 	*/
 	toSQL(where, joins) {
@@ -2697,6 +2998,59 @@ function buildQueryString(where) {
 	return parts.join("&");
 }
 
+//#endregion
+//#region ../../src/orm/core/primitives/$view.ts
+/**
+* Creates a database view primitive from a TypeBox schema and SQL query.
+*
+* Views are read-only: Repository blocks all write operations.
+*
+* @example
+* ```ts
+* import { t } from "alepha";
+* import { $view } from "alepha/orm";
+* import { sql } from "drizzle-orm";
+*
+* const userSummary = $view({
+*   name: "user_summary",
+*   schema: t.object({
+*     id: t.uuid(),
+*     fullName: t.text(),
+*     orderCount: t.integer(),
+*   }),
+*   query: sql`SELECT u.id, u.first_name || ' ' || u.last_name AS full_name, COUNT(o.id) AS order_count FROM users u LEFT JOIN orders o ON o.user_id = u.id GROUP BY u.id`,
+* });
+*
+* // Materialized view (PostgreSQL only)
+* const monthlyStats = $view({
+*   name: "monthly_stats",
+*   schema: t.object({ ... }),
+*   query: sql`...`,
+*   materialized: true,
+* });
+* ```
+*/
+const $view = (options) => {
+	return new ViewPrimitive(options);
+};
+var ViewPrimitive = class {
+	options;
+	isView = true;
+	constructor(options) {
+		this.options = options;
+	}
+	get name() {
+		return this.options.name;
+	}
+	get schema() {
+		return this.options.schema;
+	}
+	get materialized() {
+		return this.options.materialized ?? false;
+	}
+};
+$view[KIND] = ViewPrimitive;
+
 //#endregion
 //#region ../../src/orm/core/providers/DatabaseTypeProvider.ts
 var DatabaseTypeProvider = class {
@@ -2817,7 +3171,7 @@ const legacyIdSchema = pgAttr(pgAttr(pgAttr(t.integer(), PG_PRIMARY_KEY), PG_SER
 //#endregion
 //#region ../../src/orm/core/primitives/$repository.ts
 /**
-* Get the repository for the given entity.
+* Get the repository for the given entity or view.
 */
 const $repository = (entity) => {
 	const { alepha } = $context();
@@ -2917,11 +3271,13 @@ var index_bun_exports = /* @__PURE__ */ __exportAll({
 	$seed: () => $seed,
 	$sequence: () => $sequence,
 	$transactional: () => $transactional,
+	$view: () => $view,
 	AlephaOrm: () => AlephaOrm,
 	BunSqliteProvider: () => BunSqliteProvider,
 	CloudflareD1Provider: () => CloudflareD1Provider,
 	DatabaseProvider: () => DatabaseProvider,
 	DatabaseTypeProvider: () => DatabaseTypeProvider,
+	DbCacheProvider: () => DbCacheProvider,
 	DbColumnNotFoundError: () => DbColumnNotFoundError,
 	DbConflictError: () => DbConflictError,
 	DbConnectionError: () => DbConnectionError,
@@ -2940,6 +3296,7 @@ var index_bun_exports = /* @__PURE__ */ __exportAll({
 	PG_DEFAULT: () => PG_DEFAULT,
 	PG_DELETED_AT: () => PG_DELETED_AT,
 	PG_ENUM: () => PG_ENUM,
+	PG_GENERATED: () => PG_GENERATED,
 	PG_IDENTITY: () => PG_IDENTITY,
 	PG_PRIMARY_KEY: () => PG_PRIMARY_KEY,
 	PG_REF: () => PG_REF,
@@ -2950,8 +3307,10 @@ var index_bun_exports = /* @__PURE__ */ __exportAll({
 	RepositoryProvider: () => RepositoryProvider,
 	SequencePrimitive: () => SequencePrimitive,
 	SqliteProvider: () => SqliteProvider,
+	ViewPrimitive: () => ViewPrimitive,
 	buildQueryString: () => buildQueryString,
 	bunSqliteOptions: () => bunSqliteOptions,
+	databaseEnvSchema: () => databaseEnvSchema,
 	db: () => db,
 	drizzle: () => drizzle,
 	getAttrFields: () => getAttrFields,
@@ -2982,7 +3341,7 @@ const AlephaOrm = $module({
 		QueryManager
 	],
 	register: (alepha) => {
-		const env = alepha.parseEnv(t.object({ DATABASE_URL: t.optional(t.text()) }));
+		const env = alepha.parseEnv(databaseEnvSchema);
 		alepha.with(DrizzleKitProvider);
 		alepha.with(RepositoryProvider);
 		const url = env.DATABASE_URL;
@@ -3004,5 +3363,5 @@ const AlephaOrm = $module({
 });
 
 //#endregion
-export { $entity, $repository, $seed, $sequence, $transactional, AlephaOrm, BunSqliteProvider, CloudflareD1Provider, DatabaseProvider, DatabaseTypeProvider, DbColumnNotFoundError, DbConflictError, DbConnectionError, DbDeadlockError, DbEntityNotFoundError, DbError, DbForeignKeyError, DbMigrationError, DbNotNullError, DbTableNotFoundError, DbVersionMismatchError, DrizzleKitProvider, EntityPrimitive, ModelBuilder, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_ENUM, PG_IDENTITY, PG_PRIMARY_KEY, PG_REF, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Repository, RepositoryProvider, SequencePrimitive, SqliteProvider, buildQueryString, bunSqliteOptions, db, drizzle, getAttrFields, insertSchema, legacyIdSchema, pageQuerySchema, pageSchema, parseQueryString, pgAttr, schema, sql, updateSchema };
+export { $entity, $repository, $seed, $sequence, $transactional, $view, AlephaOrm, BunSqliteProvider, CloudflareD1Provider, DatabaseProvider, DatabaseTypeProvider, DbCacheProvider, DbColumnNotFoundError, DbConflictError, DbConnectionError, DbDeadlockError, DbEntityNotFoundError, DbError, DbForeignKeyError, DbMigrationError, DbNotNullError, DbTableNotFoundError, DbVersionMismatchError, DrizzleKitProvider, EntityPrimitive, ModelBuilder, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_ENUM, PG_GENERATED, PG_IDENTITY, PG_PRIMARY_KEY, PG_REF, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Repository, RepositoryProvider, SequencePrimitive, SqliteProvider, ViewPrimitive, buildQueryString, bunSqliteOptions, databaseEnvSchema, db, drizzle, getAttrFields, insertSchema, legacyIdSchema, pageQuerySchema, pageSchema, parseQueryString, pgAttr, schema, sql, updateSchema };
 //# sourceMappingURL=index.bun.js.map