alepha 0.18.2 → 0.18.3

package/src/orm/core/services/ModelBuilder.ts

@@ -1,6 +1,7 @@
 import type { SQL } from "drizzle-orm";
 import type { EntityPrimitive } from "../primitives/$entity.ts";
 import type { SequencePrimitive } from "../primitives/$sequence.ts";
+import type { ViewPrimitive } from "../primitives/$view.ts";
 
 /**
  * Database-specific table configuration functions
@@ -41,6 +42,17 @@ export abstract class ModelBuilder {
     },
   ): void;
 
+  /**
+   * Build a view from a view primitive.
+   */
+  abstract buildView(
+    view: ViewPrimitive,
+    options: {
+      tables: Map<string, unknown>;
+      schema: string;
+    },
+  ): void;
+
   /**
    * Build a sequence from a sequence primitive.
    */
@@ -111,19 +123,17 @@ export abstract class ModelBuilder {
 
               // Use original camelCase property name for lookup
               if ((self as any)[indexDef.column]) {
-                if (indexDef.unique) {
-                  configs.push(
-                    builders
+                let idx = indexDef.unique
+                  ? builders
                       .uniqueIndex(indexName)
-                      .on((self as any)[indexDef.column]),
-                  );
-                } else {
-                  configs.push(
-                    builders
+                      .on((self as any)[indexDef.column])
+                  : builders
                       .index(indexName)
-                      .on((self as any)[indexDef.column]),
-                  );
+                      .on((self as any)[indexDef.column]);
+                if ("where" in indexDef && indexDef.where) {
+                  idx = (idx as any).where(indexDef.where);
                 }
+                configs.push(idx);
               }
             } else if ("columns" in indexDef) {
               const columnNames = indexDef.columns.map((col: any) =>
@@ -138,11 +148,13 @@ export abstract class ModelBuilder {
                 .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));
+                let idx = indexDef.unique
+                  ? builders.uniqueIndex(indexName).on(...cols)
+                  : builders.index(indexName).on(...cols);
+                if ("where" in indexDef && indexDef.where) {
+                  idx = (idx as any).where(indexDef.where);
                 }
+                configs.push(idx);
               }
             }
           }

package/src/orm/core/services/QueryManager.ts

@@ -12,6 +12,7 @@ import {
   arrayOverlaps,
   between,
   eq,
+  exists,
   gt,
   gte,
   ilike,
@@ -25,11 +26,13 @@ import {
   ne,
   not,
   notBetween,
+  notExists,
   notIlike,
   notInArray,
   notLike,
   or,
   type SQL,
+  type SQLWrapper,
   sql,
 } from "drizzle-orm";
 import type { PgColumn } from "drizzle-orm/pg-core";
@@ -154,6 +157,16 @@ export class QueryManager {
           }
         }
 
+        if (key === "exists") {
+          conditions.push(exists(operator as SQLWrapper));
+          continue;
+        }
+
+        if (key === "notExists") {
+          conditions.push(notExists(operator as SQLWrapper));
+          continue;
+        }
+
         if (operator) {
           const column = col(key);
           const sql = this.mapOperatorToSql(

package/src/orm/core/services/Repository.ts

@@ -12,7 +12,23 @@ import {
 } from "alepha";
 import { type DateTime, DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
-import { asc, desc, type SQL } from "drizzle-orm";
+import {
+  asc,
+  avg,
+  count,
+  desc,
+  and as drizzleAnd,
+  eq as drizzleEq,
+  gt,
+  gte,
+  lt,
+  lte,
+  max,
+  min,
+  ne,
+  type SQL,
+  sum,
+} from "drizzle-orm";
 import type {
   LockConfig,
   LockStrength,
@@ -41,6 +57,12 @@ import { DbNotNullError } from "../errors/DbNotNullError.ts";
 import { DbTableNotFoundError } from "../errors/DbTableNotFoundError.ts";
 import { DbVersionMismatchError } from "../errors/DbVersionMismatchError.ts";
 import { getAttrFields, type PgAttrField } from "../helpers/pgAttr.ts";
+import type {
+  AggregateOp,
+  AggregateQuery,
+  AggregateResult,
+  AggregateSelect,
+} from "../interfaces/AggregateQuery.ts";
 import type {
   PgQuery,
   PgQueryRelations,
@@ -55,6 +77,7 @@ import type {
   EntityPrimitive,
   SchemaToTableConfig,
 } from "../primitives/$entity.ts";
+import { DbCacheProvider } from "../providers/DbCacheProvider.ts";
 import {
   DatabaseProvider,
   type SQLLike,
@@ -72,6 +95,7 @@ export abstract class Repository<T extends TObject> {
   protected readonly relationManager = $inject(PgRelationManager);
   protected readonly queryManager = $inject(QueryManager);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly dbCache = new DbCacheProvider();
   protected readonly alepha = $inject(Alepha);
 
   static of<T extends TObject>(
@@ -88,7 +112,11 @@ export abstract class Repository<T extends TObject> {
   constructor(entity: EntityPrimitive<T>, provider = DatabaseProvider) {
     this.entity = entity;
     this.provider = this.alepha.inject(provider);
-    this.provider.registerEntity(entity as EntityPrimitive);
+    if ((entity as any).isView) {
+      this.provider.registerView(entity as any);
+    } else {
+      this.provider.registerEntity(entity as EntityPrimitive);
+    }
   }
 
   /**
@@ -120,6 +148,13 @@ export abstract class Repository<T extends TObject> {
     return this.entity.name;
   }
 
+  /**
+   * Whether this repository is backed by a view (read-only).
+   */
+  public get isReadOnly(): boolean {
+    return (this.entity as any).isView === true;
+  }
+
   /**
    * Getter for the database connection from the database provider.
    *
@@ -179,6 +214,17 @@ export abstract class Repository<T extends TObject> {
       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),
@@ -236,8 +282,10 @@ export abstract class Repository<T extends TObject> {
     ) => Promise<T>,
     config?: PgTransactionConfig,
   ): Promise<T> {
-    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 as any);
     }
 
@@ -310,6 +358,16 @@ export abstract class Repository<T extends TObject> {
     query: PgQueryRelations<T, R> = {},
     opts: StatementOptions = {},
   ): Promise<PgStatic<T, R>[]> {
+    // Check cache
+    if (opts.cache) {
+      const cacheKey = opts.cache.key ?? this.buildCacheKey("findMany", query);
+      const cached = await this.dbCache.get<PgStatic<T, R>[]>(
+        this.tableName,
+        cacheKey,
+      );
+      if (cached) return cached;
+    }
+
     await this.alepha.events.emit("repository:read:before", {
       tableName: this.tableName,
       query,
@@ -414,7 +472,21 @@ export abstract class Repository<T extends TObject> {
         entities: rows,
       });
 
-      return rows as PgStatic<T, R>[];
+      const result = rows as PgStatic<T, R>[];
+
+      // Store in cache
+      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");
     }
@@ -590,6 +662,7 @@ export abstract class Repository<T extends TObject> {
     data: Static<TObjectInsert<T>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
+    this.assertWritable();
     await this.alepha.events.emit("repository:create:before", {
       tableName: this.tableName,
       data,
@@ -601,6 +674,8 @@ export abstract class Repository<T extends TObject> {
         .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,
@@ -626,6 +701,7 @@ export abstract class Repository<T extends TObject> {
     values: Array<Static<TObjectInsert<T>>>,
     opts: StatementOptions & { batchSize?: number } = {},
   ): Promise<Static<T>[]> {
+    this.assertWritable();
     if (values.length === 0) {
       return [];
     }
@@ -648,6 +724,8 @@ export abstract class Repository<T extends TObject> {
         allEntities.push(...entities);
       }
 
+      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+
       await this.alepha.events.emit("repository:create:after", {
         tableName: this.tableName,
         data: values,
@@ -696,6 +774,7 @@ export abstract class Repository<T extends TObject> {
       set?: WithSQL<Static<TObjectUpdate<T>>>;
     } = {},
   ): Promise<Static<T>> {
+    this.assertWritable();
     await this.alepha.events.emit("repository:create:before", {
       tableName: this.tableName,
       data,
@@ -741,6 +820,8 @@ export abstract class Repository<T extends TObject> {
         .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,
@@ -763,6 +844,7 @@ export abstract class Repository<T extends TObject> {
     data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
+    this.assertWritable();
     await this.alepha.events.emit("repository:update:before", {
       tableName: this.tableName,
       where,
@@ -802,6 +884,8 @@ export abstract class Repository<T extends TObject> {
     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,
@@ -839,6 +923,7 @@ export abstract class Repository<T extends TObject> {
     entity: Static<T>,
     opts: StatementOptions = {},
   ): Promise<void> {
+    this.assertWritable();
     const row = entity as any;
 
     const id = row[this.id.key];
@@ -924,6 +1009,7 @@ export abstract class Repository<T extends TObject> {
     data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Array<number | string>> {
+    this.assertWritable();
     await this.alepha.events.emit("repository:update:before", {
       tableName: this.tableName,
       where,
@@ -950,6 +1036,8 @@ export abstract class Repository<T extends TObject> {
         .where(this.toSQL(where))
         .returning();
 
+      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+
       await this.alepha.events.emit("repository:update:after", {
         tableName: this.tableName,
         where,
@@ -971,6 +1059,7 @@ export abstract class Repository<T extends TObject> {
     where: PgQueryWhereOrSQL<T> = {},
     opts: StatementOptions = {},
   ): Promise<Array<number | string>> {
+    this.assertWritable();
     const deletedAt = this.deletedAt();
     if (deletedAt && !opts.force) {
       return await this.updateMany(
@@ -993,6 +1082,8 @@ export abstract class Repository<T extends TObject> {
         .returning({ id: (this.table as any)[this.id.key] });
       const ids = result.map((row) => row.id);
 
+      this.dbCache.invalidateTable(this.tableName).catch(() => {});
+
       await this.alepha.events.emit("repository:delete:after", {
         tableName: this.tableName,
         where,
@@ -1087,6 +1178,165 @@ export abstract class Repository<T extends TObject> {
 
   // -------------------------------------------------------------------------------------------------------------------
 
+  /**
+   * 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 } }>
+   * ```
+   */
+  public async aggregate<S extends AggregateSelect<T>>(
+    query: AggregateQuery<T, S>,
+    opts: StatementOptions = {},
+  ): Promise<AggregateResult<T, S>[]> {
+    const AGG_SEPARATOR = "___";
+
+    // Build flat select fields
+    const flatFields: Record<string, any> = {};
+    const aggFn = (op: AggregateOp, column: any) => {
+      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) as AggregateOp[]) {
+          if ((select as Record<string, boolean>)[op]) {
+            flatFields[`${key}${AGG_SEPARATOR}${op}`] = aggFn(
+              op,
+              this.col(key),
+            );
+          }
+        }
+      }
+    }
+
+    const db = opts.tx === null ? this.provider.db : (opts.tx ?? this.db);
+    let builder = db.select(flatFields).from(this.table as PgTable);
+
+    // WHERE
+    if (query.where) {
+      const where = this.withDeletedAt(query.where as any, opts);
+      builder = builder.where(this.toSQL(where)) as any;
+    }
+
+    // GROUP BY
+    if (query.groupBy) {
+      builder = builder.groupBy(
+        ...query.groupBy.map((key) => this.col(key as string)),
+      ) as any;
+    }
+
+    // HAVING
+    if (query.having) {
+      const havingConditions: SQL[] = [];
+      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 as AggregateOp, this.col(key));
+          for (const [cmp, val] of Object.entries(
+            comparisons as Record<string, number>,
+          )) {
+            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(drizzleEq(aggExpr, val));
+                break;
+              case "ne":
+                havingConditions.push(ne(aggExpr, val));
+                break;
+            }
+          }
+        }
+      }
+      if (havingConditions.length > 0) {
+        builder = builder.having(drizzleAnd(...havingConditions)!) as any;
+      }
+    }
+
+    // ORDER BY
+    if (query.orderBy) {
+      const clauses = this.queryManager.normalizeOrderBy(query.orderBy);
+      builder = builder.orderBy(
+        ...clauses.map((clause) => {
+          // Support dot notation: "amount.sum" → "amount___sum"
+          const colName = clause.column.includes(".")
+            ? clause.column.replace(".", AGG_SEPARATOR)
+            : clause.column;
+          const col = flatFields[colName];
+          if (!col) {
+            throw new AlephaError(
+              `Invalid orderBy column '${clause.column}' in aggregate query`,
+            );
+          }
+          return clause.direction === "desc" ? desc(col) : asc(col);
+        }),
+      ) as any;
+    }
+
+    // LIMIT / OFFSET
+    if (query.limit) {
+      builder = builder.limit(query.limit) as any;
+    }
+    if (query.offset) {
+      builder = builder.offset(query.offset) as any;
+    }
+
+    try {
+      const rows = await builder.execute();
+
+      // Re-nest flat results: { amount___sum: 500 } → { amount: { sum: 500 } }
+      return rows.map((row: any) => {
+        const result: Record<string, any> = {};
+        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 as AggregateResult<T, S>;
+      });
+    } catch (error) {
+      throw this.handleError(error, "Aggregate query has failed");
+    }
+  }
+
+  // -------------------------------------------------------------------------------------------------------------------
+
   // Error message patterns for different database errors
   protected errorPatterns = {
     // Unique constraint violations
@@ -1316,6 +1566,36 @@ export abstract class Repository<T extends TObject> {
     return entity as Static<T>;
   }
 
+  /**
+   * Throw if this repository is read-only (backed by a view).
+   */
+  protected assertWritable(): void {
+    if (this.isReadOnly) {
+      throw new AlephaError(
+        `Cannot write to view '${this.tableName}'. Views are read-only.`,
+      );
+    }
+  }
+
+  /**
+   * Refresh a materialized view. PostgreSQL only.
+   */
+  public async refresh(): Promise<void> {
+    if (!(this.entity as any).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.
+   */
+  protected buildCacheKey(method: string, query: any): string {
+    return `${method}:${JSON.stringify(query)}`;
+  }
+
   /**
    * Convert a where clause to SQL.
    */
@@ -1399,6 +1679,28 @@ export interface StatementOptions {
    * Force the current time.
    */
   now?: DateTime | string;
+
+  /**
+   * Cache configuration for query results.
+   *
+   * When set, results are stored in an in-memory cache keyed by query parameters.
+   * Any write to this table automatically invalidates all cached queries.
+   *
+   * @example
+   * ```ts
+   * await repo.findMany(query, { cache: { ttl: 60_000 } });
+   * ```
+   */
+  cache?: {
+    /**
+     * Time-to-live in milliseconds.
+     */
+    ttl?: number;
+    /**
+     * Custom cache key. If not provided, a key is derived from the query.
+     */
+    key?: string;
+  };
 }
 
 type WithSQL<T> = {

package/src/orm/core/services/SqliteModelBuilder.ts

@@ -16,20 +16,24 @@ import {
   type SQLiteColumnBuilderBase,
   type SQLiteTableWithColumns,
   sqliteTable,
+  sqliteView,
   unique,
   uniqueIndex,
 } from "drizzle-orm/sqlite-core";
 import {
   PG_CREATED_AT,
+  PG_GENERATED,
   PG_IDENTITY,
   PG_PRIMARY_KEY,
   PG_REF,
   PG_SERIAL,
   PG_UPDATED_AT,
+  type PgGeneratedOptions,
   type PgRefOptions,
 } from "../constants/PG_SYMBOLS.ts";
 import type { EntityPrimitive } from "../primitives/$entity.ts";
 import type { SequencePrimitive } from "../primitives/$sequence.ts";
+import type { ViewPrimitive } from "../primitives/$view.ts";
 import { ModelBuilder } from "./ModelBuilder.ts";
 
 export class SqliteModelBuilder extends ModelBuilder {
@@ -62,6 +66,33 @@ export class SqliteModelBuilder extends ModelBuilder {
     options.tables.set(tableName, table);
   }
 
+  public buildView(
+    view: ViewPrimitive,
+    options: {
+      tables: Map<string, unknown>;
+      schema: string;
+    },
+  ) {
+    const viewName = view.name;
+    if (options.tables.has(viewName)) {
+      return;
+    }
+
+    if (view.materialized) {
+      throw new AlephaError("SQLite does not support materialized views");
+    }
+
+    const columns = this.schemaToSqliteColumns(
+      viewName,
+      view.schema,
+      new Map(),
+      options.tables,
+    );
+
+    const drizzleView = sqliteView(viewName, columns).existing();
+    options.tables.set(viewName, drizzleView);
+  }
+
   public buildSequence(
     sequence: SequencePrimitive,
     options: {
@@ -151,6 +182,13 @@ export class SqliteModelBuilder extends ModelBuilder {
         }, config.actions);
       }
 
+      if (PG_GENERATED in value) {
+        const gen = value[PG_GENERATED] as PgGeneratedOptions;
+        col = col.generatedAlwaysAs(gen.expression, {
+          mode: gen.mode ?? "virtual",
+        });
+      }
+
       if (schema.required?.includes(key)) {
         col = col.notNull();
       }

package/src/orm/postgres/index.bun.ts

@@ -1,5 +1,5 @@
-import { $module, type Alepha, t } from "alepha";
-import { AlephaOrm, DatabaseProvider } from "alepha/orm";
+import { $module, type Alepha } from "alepha";
+import { AlephaOrm, DatabaseProvider, databaseEnvSchema } from "alepha/orm";
 import { BunPostgresProvider } from "./providers/BunPostgresProvider.ts";
 import { PglitePostgresProvider } from "./providers/PglitePostgresProvider.ts";
 import { PostgresProvider } from "./providers/PostgresProvider.ts";
@@ -8,6 +8,7 @@ import { PostgresModelBuilder } from "./services/PostgresModelBuilder.ts";
 export * from "./providers/BunPostgresProvider.ts";
 export * from "./providers/PglitePostgresProvider.ts";
 export * from "./providers/PostgresProvider.ts";
+export * from "./schemas/postgresEnvSchema.ts";
 export * from "./services/PostgresModelBuilder.ts";
 export * from "./types/byte.ts";
 
@@ -21,11 +22,7 @@ export const AlephaOrmPostgres = $module({
     PostgresModelBuilder,
   ],
   register: (alepha: Alepha) => {
-    const env = alepha.parseEnv(
-      t.object({
-        DATABASE_URL: t.optional(t.text()),
-      }),
-    );
+    const env = alepha.parseEnv(databaseEnvSchema);
 
     const url = env.DATABASE_URL;