alepha 0.18.2 → 0.18.3

package/src/orm/core/index.shared-server.ts

@@ -13,10 +13,12 @@ export * from "./primitives/$repository.ts";
 export * from "./primitives/$seed.ts";
 export * from "./primitives/$sequence.ts";
 export * from "./primitives/$transactional.ts";
+export * from "./providers/DbCacheProvider.ts";
 export * from "./providers/DrizzleKitProvider.ts";
 export * from "./providers/drivers/CloudflareD1Provider.ts";
 export * from "./providers/drivers/DatabaseProvider.ts";
 export * from "./providers/RepositoryProvider.ts";
+export * from "./schemas/databaseEnvSchema.ts";
 export * from "./schemas/insertSchema.ts";
 export * from "./schemas/updateSchema.ts";
 export * from "./services/ModelBuilder.ts";

package/src/orm/core/index.shared.ts

@@ -13,9 +13,11 @@ export * from "./errors/DbNotNullError.ts";
 export * from "./errors/DbTableNotFoundError.ts";
 export * from "./helpers/parseQueryString.ts";
 export * from "./helpers/pgAttr.ts";
+export * from "./interfaces/AggregateQuery.ts";
 export * from "./interfaces/FilterOperators.ts";
 export * from "./interfaces/PgQuery.ts";
 export * from "./interfaces/PgQueryWhere.ts";
 export * from "./primitives/$entity.ts";
+export * from "./primitives/$view.ts";
 export * from "./providers/DatabaseTypeProvider.ts";
 export * from "./schemas/legacyIdSchema.ts";

package/src/orm/core/index.ts

@@ -1,15 +1,17 @@
-import { $module, type Alepha, t } from "alepha";
+import { $module, type Alepha } from "alepha";
 import { AlephaDateTime } from "alepha/datetime";
 import type { PgTransaction } from "drizzle-orm/pg-core";
 import { DbMigrationMode } from "./modes/DbMigrationMode.ts";
 import { $entity } from "./primitives/$entity.ts";
 import { $sequence } from "./primitives/$sequence.ts";
+import { $view } from "./primitives/$view.ts";
 import { DrizzleKitProvider } from "./providers/DrizzleKitProvider.ts";
 import { BunSqliteProvider } from "./providers/drivers/BunSqliteProvider.ts";
 import { CloudflareD1Provider } from "./providers/drivers/CloudflareD1Provider.ts";
 import { DatabaseProvider } from "./providers/drivers/DatabaseProvider.ts";
 import { NodeSqliteProvider } from "./providers/drivers/NodeSqliteProvider.ts";
 import { RepositoryProvider } from "./providers/RepositoryProvider.ts";
+import { databaseEnvSchema } from "./schemas/databaseEnvSchema.ts";
 import { PgRelationManager } from "./services/PgRelationManager.ts";
 import { QueryManager } from "./services/QueryManager.ts";
 import { Repository } from "./services/Repository.ts";
@@ -100,7 +102,7 @@ export const SqliteProvider = NodeSqliteProvider;
 
 export const AlephaOrm = $module({
   name: "alepha.orm",
-  primitives: [$sequence, $entity],
+  primitives: [$sequence, $entity, $view],
   services: [
     AlephaDateTime,
     DatabaseProvider,
@@ -116,11 +118,7 @@ export const AlephaOrm = $module({
     DbMigrationMode,
   ],
   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;
     const isBun = alepha.isBun();

package/src/orm/core/interfaces/AggregateQuery.ts

@@ -0,0 +1,103 @@
+import type { Static, TObject } from "alepha";
+import type { PgQueryWhereOrSQL } from "./PgQueryWhere.ts";
+
+export type AggregateOp = "count" | "sum" | "avg" | "min" | "max";
+
+/**
+ * Select definition for aggregate queries.
+ * - `true` means select the column value as-is (used for groupBy columns).
+ * - `{ sum: true, avg: true, ... }` means compute those aggregations.
+ */
+export type AggregateColumnSelect = true | Partial<Record<AggregateOp, true>>;
+
+export type AggregateSelect<T extends TObject> = {
+  [K in keyof Static<T>]?: AggregateColumnSelect;
+};
+
+/**
+ * Maps a single column's select definition to its result type.
+ * - `true` → original column type
+ * - `{ sum: true, avg: true }` → `{ sum: number; avg: number }`
+ */
+export type AggregateColumnResult<TValue, TSelect> = TSelect extends true
+  ? TValue
+  : {
+      [Op in AggregateOp as TSelect extends Record<Op, true>
+        ? Op
+        : never]: number;
+    };
+
+/**
+ * Result type for an aggregate query.
+ */
+export type AggregateResult<T extends TObject, S extends AggregateSelect<T>> = {
+  [K in keyof S & keyof Static<T>]: AggregateColumnResult<
+    Static<T>[K],
+    NonNullable<S[K]>
+  >;
+};
+
+/**
+ * HAVING clause for aggregate queries.
+ * Only applies to columns with aggregate operations (not `true`).
+ */
+export type AggregateHaving<T extends TObject, S extends AggregateSelect<T>> = {
+  [K in keyof S & keyof Static<T>]?: S[K] extends true
+    ? never
+    : {
+        [Op in AggregateOp as S[K] extends Record<Op, true> ? Op : never]?: {
+          gt?: number;
+          gte?: number;
+          lt?: number;
+          lte?: number;
+          eq?: number;
+          ne?: number;
+        };
+      };
+};
+
+/**
+ * Full aggregate query definition.
+ */
+export interface AggregateQuery<
+  T extends TObject,
+  S extends AggregateSelect<T>,
+> {
+  /**
+   * Columns and aggregate operations to select.
+   */
+  select: S;
+
+  /**
+   * WHERE clause to filter rows before aggregation.
+   */
+  where?: PgQueryWhereOrSQL<T>;
+
+  /**
+   * Columns to group by.
+   */
+  groupBy?: (keyof Static<T>)[];
+
+  /**
+   * HAVING clause to filter groups after aggregation.
+   */
+  having?: AggregateHaving<T, S>;
+
+  /**
+   * Order results. Supports dot notation for aggregate columns (e.g. "amount.sum").
+   */
+  orderBy?:
+    | string
+    | { column: string; direction: "asc" | "desc" }
+    | Array<{ column: string; direction: "asc" | "desc" }>;
+
+  /**
+   * Limit the number of results.
+   */
+  limit?: number;
+
+  /**
+   * Offset for pagination.
+   */
+  offset?: number;
+}

package/src/orm/core/interfaces/PgQueryWhere.ts

@@ -97,6 +97,13 @@ type PgQueryWhereConditions<
    * @see notExists for the inverse of this test
    */
   exists?: SQLWrapper;
+
+  /**
+   * Test whether a subquery evaluates to have no rows.
+   *
+   * @see exists for the inverse of this test
+   */
+  notExists?: SQLWrapper;
 };
 
 type PgQueryWhereRelations<

package/src/orm/core/primitives/$entity.ts

@@ -67,6 +67,10 @@ export interface EntityPrimitiveOptions<
          * Custom name for the index. If not provided, generates name automatically.
          */
         name?: string;
+        /**
+         * Partial index condition. Only rows matching this SQL expression are indexed.
+         */
+        where?: SQL;
       }
     | {
         /**
@@ -81,6 +85,10 @@ export interface EntityPrimitiveOptions<
          * Custom name for the index. If not provided, generates name automatically.
          */
         name?: string;
+        /**
+         * Partial index condition. Only rows matching this SQL expression are indexed.
+         */
+        where?: SQL;
       }
   )[];
 

package/src/orm/core/primitives/$repository.ts

@@ -2,14 +2,17 @@ import { $context, $inject, type TObject } from "alepha";
 import { RepositoryProvider } from "../providers/RepositoryProvider.ts";
 import type { Repository } from "../services/Repository.ts";
 import type { EntityPrimitive } from "./$entity.ts";
+import type { ViewPrimitive } from "./$view.ts";
 
 /**
- * Get the repository for the given entity.
+ * Get the repository for the given entity or view.
  */
 export const $repository = <T extends TObject>(
-  entity: EntityPrimitive<T>,
+  entity: EntityPrimitive<T> | ViewPrimitive<T>,
 ): Repository<T> => {
   const { alepha } = $context();
   const repositoryProvider = alepha.inject(RepositoryProvider);
-  return $inject(repositoryProvider.createClassRepository(entity));
+  return $inject(
+    repositoryProvider.createClassRepository(entity as EntityPrimitive<T>),
+  );
 };

package/src/orm/core/primitives/$view.ts

@@ -0,0 +1,88 @@
+import { KIND, type TObject } from "alepha";
+import type { SQL } from "drizzle-orm";
+
+/**
+ * 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,
+ * });
+ * ```
+ */
+export const $view = <TSchema extends TObject>(
+  options: ViewPrimitiveOptions<TSchema>,
+): ViewPrimitive<TSchema> => {
+  return new ViewPrimitive<TSchema>(options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface ViewPrimitiveOptions<T extends TObject> {
+  /**
+   * The database view name.
+   */
+  name: string;
+
+  /**
+   * TypeBox schema defining the view's columns.
+   */
+  schema: T;
+
+  /**
+   * SQL query that defines the view.
+   */
+  query: SQL;
+
+  /**
+   * Whether this is a materialized view (PostgreSQL only).
+   * Materialized views store results on disk and can be refreshed.
+   */
+  materialized?: boolean;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class ViewPrimitive<T extends TObject = TObject> {
+  public readonly options: ViewPrimitiveOptions<T>;
+  public readonly isView = true;
+
+  constructor(options: ViewPrimitiveOptions<T>) {
+    this.options = options;
+  }
+
+  get name(): string {
+    return this.options.name;
+  }
+
+  get schema(): T {
+    return this.options.schema;
+  }
+
+  get materialized(): boolean {
+    return this.options.materialized ?? false;
+  }
+}
+
+$view[KIND] = ViewPrimitive;

package/src/orm/core/providers/DbCacheProvider.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+export class DbCacheProvider {
+  protected readonly store = new Map<
+    string,
+    { value: unknown; expiresAt?: number }
+  >();
+
+  protected storeKey(tableName: string, cacheKey: string): string {
+    return `${tableName}:${cacheKey}`;
+  }
+
+  /**
+   * Get a cached query result.
+   */
+  public async get<T>(
+    tableName: string,
+    cacheKey: string,
+  ): Promise<T | undefined> {
+    const key = this.storeKey(tableName, cacheKey);
+    const entry = this.store.get(key);
+
+    if (!entry) return undefined;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  /**
+   * Store a query result in the cache.
+   */
+  public async set<T>(
+    tableName: string,
+    cacheKey: string,
+    value: T,
+    ttl?: number,
+  ): Promise<void> {
+    const key = this.storeKey(tableName, cacheKey);
+    this.store.set(key, {
+      value,
+      expiresAt: ttl ? Date.now() + ttl : undefined,
+    });
+  }
+
+  /**
+   * Invalidate all cached queries for a table.
+   */
+  public async invalidateTable(tableName: string): Promise<void> {
+    const prefix = `${tableName}:`;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key);
+      }
+    }
+  }
+}

package/src/orm/core/providers/DrizzleKitProvider.ts

@@ -203,6 +203,48 @@ export class DrizzleKitProvider {
     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.
+   */
+  public async dryRunPush(provider: DatabaseProvider): Promise<{
+    statements: string[];
+    warnings: string[];
+    hasDataLoss: boolean;
+  }> {
+    const kit = this.importDrizzleKit();
+    const models = this.getModels(provider);
+
+    if (Object.keys(models).length === 0) {
+      return { statements: [], warnings: [], hasDataLoss: false };
+    }
+
+    let result: {
+      statementsToExecute: string[];
+      warnings: string[];
+      hasDataLoss: boolean;
+    };
+
+    if (provider.dialect === "sqlite") {
+      result = await this.muteSpinner(() =>
+        kit.pushSQLiteSchema(models, provider.db as any),
+      );
+    } 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,
+    };
+  }
+
   // -------------------------------------------------------------------------------------------------------------------
 
   protected async pushSqlite(

package/src/orm/core/providers/drivers/BunSqliteProvider.ts

@@ -13,14 +13,13 @@ import {
 } from "alepha";
 import type { BunSQLiteDatabase } from "drizzle-orm/bun-sqlite";
 import type { PgDatabase } from "drizzle-orm/pg-core";
+import { databaseEnvSchema } from "../../schemas/databaseEnvSchema.ts";
 import { SqliteModelBuilder } from "../../services/SqliteModelBuilder.ts";
 import { DatabaseProvider, type SQLLike } from "./DatabaseProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-const envSchema = t.object({
-  DATABASE_URL: t.optional(t.text()),
-});
+const envSchema = databaseEnvSchema;
 
 /**
  * Configuration options for the Bun SQLite database provider.

package/src/orm/core/providers/drivers/CloudflareD1Provider.ts

@@ -88,6 +88,18 @@ export class CloudflareD1Provider extends DatabaseProvider {
     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
+   */
+  public override get supportsTransactions(): boolean {
+    return false;
+  }
+
   protected readonly onStart = $hook({
     on: "start",
     handler: async () => {

package/src/orm/core/providers/drivers/DatabaseProvider.ts

@@ -21,6 +21,8 @@ import type {
   SchemaToTableConfig,
 } from "../../primitives/$entity.ts";
 import type { SequencePrimitive } from "../../primitives/$sequence.ts";
+import type { ViewPrimitive } from "../../primitives/$view.ts";
+import { databaseEnvSchema } from "../../schemas/databaseEnvSchema.ts";
 import type { ModelBuilder } from "../../services/ModelBuilder.ts";
 import { DrizzleKitProvider } from "../DrizzleKitProvider.ts";
 
@@ -51,6 +53,15 @@ export abstract class DatabaseProvider {
     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`.
+   */
+  public get supportsTransactions(): boolean {
+    return true;
+  }
+
   /**
    * Raw database connection handle (e.g. DatabaseSync, bun:sqlite Database).
    * Override in providers that expose native connections for introspection.
@@ -143,6 +154,10 @@ export abstract class DatabaseProvider {
     this.builder.buildTable(entity, this);
   }
 
+  public registerView(view: ViewPrimitive) {
+    this.builder.buildView(view, this);
+  }
+
   public registerSequence(sequence: SequencePrimitive) {
     this.sequencePrimitives.push(sequence);
     this.builder.buildSequence(sequence, this);
@@ -197,6 +212,10 @@ export abstract class DatabaseProvider {
       return fn();
     }
 
+    if (!this.supportsTransactions) {
+      return fn();
+    }
+
     return this.db.transaction(async (tx) => {
       this.alepha.store.set("alepha.orm.tx", tx as PgTransaction<any>, {
         skipEvents: true,
@@ -218,6 +237,18 @@ export abstract class DatabaseProvider {
     schema: T,
   ): Promise<Array<Static<T>>> {
     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));
   }
 
@@ -263,6 +294,14 @@ export abstract class DatabaseProvider {
       await this.executeMigrations(migrationsFolder);
       this.log.info("Migration OK");
     } 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) {

package/src/orm/core/providers/drivers/NodeSqliteProvider.ts

@@ -13,6 +13,7 @@ import {
   t,
 } from "alepha";
 import type { PgDatabase } from "drizzle-orm/pg-core";
+import { databaseEnvSchema } from "../../schemas/databaseEnvSchema.ts";
 import { SqliteModelBuilder } from "../../services/SqliteModelBuilder.ts";
 import { DatabaseProvider, type SQLLike } from "./DatabaseProvider.ts";
 
@@ -39,9 +40,7 @@ import { DatabaseProvider, type SQLLike } from "./DatabaseProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-const envSchema = t.object({
-  DATABASE_URL: t.optional(t.text()),
-});
+const envSchema = databaseEnvSchema;
 
 /**
  * Configuration options for the Node.js SQLite database provider.

package/src/orm/core/schemas/databaseEnvSchema.ts

@@ -0,0 +1,31 @@
+import { type Static, t } from "alepha";
+
+/**
+ * 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
+ */
+export const databaseEnvSchema = t.object({
+  DATABASE_URL: t.optional(t.text()),
+
+  /**
+   * Enable or disable push-based schema synchronization (drizzle-kit push).
+   *
+   * Defaults to `true` in development and test, `false` in production.
+   * Set to `false` in development to skip automatic schema sync
+   * (e.g. when managing migrations manually).
+   */
+  DATABASE_SYNC: t.optional(t.boolean()),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof databaseEnvSchema>> {}
+}

package/src/orm/core/schemas/insertSchema.ts

@@ -1,18 +1,23 @@
 import type { TObject, TOptional } from "alepha";
 import { t } from "alepha";
-import { PG_DEFAULT } from "../constants/PG_SYMBOLS.ts";
+import { PG_DEFAULT, PG_GENERATED } from "../constants/PG_SYMBOLS.ts";
 import { schema } from "../types/schema.ts";
 
 /**
  * Transforms a TObject schema for insert operations.
  * All default properties at the root level are made optional.
+ * Generated columns are excluded entirely.
  *
  * @example
- * Before: { name: string; age: number(default=0); }
+ * Before: { name: string; age: number(default=0); fullName: generated }
  * After:  { name: string; age?: number; }
  */
 export type TObjectInsert<T extends TObject> = TObject<{
-  [K in keyof T["properties"]]: T["properties"][K] extends
+  [K in keyof T["properties"] as T["properties"][K] extends {
+    [PG_GENERATED]: any;
+  }
+    ? never
+    : K]: T["properties"][K] extends
     | { [PG_DEFAULT]: any }
     | { "~optional": true }
     ? TOptional<T["properties"][K]>
@@ -25,6 +30,11 @@ export const insertSchema = <T extends TObject>(obj: T): TObjectInsert<T> => {
   for (const key in obj.properties) {
     const prop = obj.properties[key];
 
+    // Skip generated columns — they are computed by the database
+    if (PG_GENERATED in prop) {
+      continue;
+    }
+
     if (PG_DEFAULT in prop) {
       newProperties[key] = t.optional(prop);
     } else {

package/src/orm/core/schemas/updateSchema.ts

@@ -5,18 +5,23 @@ import {
   type TUnion,
   t,
 } from "alepha";
+import { PG_GENERATED } from "../constants/PG_SYMBOLS.ts";
 
 /**
  * Transforms a TObject schema for update operations.
  * All optional properties at the root level are made nullable (i.e., `T | null`).
- * This allows an API endpoint to explicitly accept `null` to clear an optional field in the database.
+ * Generated columns are excluded entirely.
  *
  * @example
- * Before: { name?: string; age: number; }
+ * Before: { name?: string; age: number; fullName: generated }
  * After:  { name?: string | null; age: number; }
  */
 export type TObjectUpdate<T extends TObject> = TObject<{
-  [K in keyof T["properties"]]: T["properties"][K] extends TOptional<infer U>
+  [K in keyof T["properties"] as T["properties"][K] extends {
+    [PG_GENERATED]: any;
+  }
+    ? never
+    : K]: T["properties"][K] extends TOptional<infer U>
     ? TOptional<TUnion<[U, TNull]>>
     : T["properties"][K];
 }>;
@@ -28,6 +33,12 @@ export const updateSchema = <T extends TObject>(
 
   for (const key in schema.properties) {
     const prop = schema.properties[key];
+
+    // Skip generated columns — they are computed by the database
+    if (PG_GENERATED in prop) {
+      continue;
+    }
+
     if (t.schema.isOptional(prop)) {
       newProperties[key] = t.optional(t.union([prop, t.raw.Null()]));
     } else {