alepha 0.8.0 → 0.8.1

package/postgres.d.ts

@@ -1,26 +1,26 @@
-import * as _alepha_core56 from "alepha";
-import * as _alepha_core20 from "alepha";
-import * as _alepha_core22 from "alepha";
+import * as _alepha_core55 from "alepha";
+import * as _alepha_core19 from "alepha";
+import * as _alepha_core21 from "alepha";
 import { Alepha, KIND, Module, OPTIONS, Static, TObject, TSchema as TSchema$1 } from "alepha";
 import * as drizzle_orm3 from "drizzle-orm";
 import * as drizzle_orm8 from "drizzle-orm";
 import * as drizzle_orm2 from "drizzle-orm";
 import * as drizzle from "drizzle-orm";
 import { BuildColumns, BuildExtraConfigColumns, SQL, SQLWrapper, TableConfig, sql } from "drizzle-orm";
-import * as _alepha_lock45 from "alepha/lock";
+import * as _alepha_lock44 from "alepha/lock";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import * as pg$1 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core13 from "drizzle-orm/pg-core";
 import * as drizzle_orm_pg_core1 from "drizzle-orm/pg-core";
 import { AnyPgColumn, AnyPgTable, LockConfig, LockStrength, PgColumn, PgColumnBuilderBase, PgDatabase, PgInsertValue, PgSequenceOptions, PgTableExtraConfigValue, PgTableWithColumns, PgTransaction, PgTransactionConfig, TableConfig as TableConfig$1, UpdateDeleteAction } from "drizzle-orm/pg-core";
-import * as _alepha_retry19 from "alepha/retry";
-import * as _sinclair_typebox75 from "@sinclair/typebox";
+import * as _alepha_retry81 from "alepha/retry";
+import * as _sinclair_typebox74 from "@sinclair/typebox";
+import * as _sinclair_typebox89 from "@sinclair/typebox";
 import * as _sinclair_typebox85 from "@sinclair/typebox";
-import * as _sinclair_typebox88 from "@sinclair/typebox";
 import * as _sinclair_typebox82 from "@sinclair/typebox";
-import * as _sinclair_typebox58 from "@sinclair/typebox";
-import * as _sinclair_typebox49 from "@sinclair/typebox";
+import * as _sinclair_typebox57 from "@sinclair/typebox";
+import * as _sinclair_typebox48 from "@sinclair/typebox";
 import { Evaluate, IntegerOptions, Kind, NumberOptions, ObjectOptions, OptionalKind, Static as Static$1, StringOptions, TAdditionalProperties, TArray, TBoolean, TInteger, TIntersect, TObject as TObject$1, TOptional, TOptionalWithFlag, TPick, TProperties, TReadonly, TRecord, TSchema as TSchema$2 } from "@sinclair/typebox";
 import { PgTransactionConfig as PgTransactionConfig$1 } from "drizzle-orm/pg-core/session";
 import * as DrizzleKit from "drizzle-kit/api";
@@ -778,10 +778,10 @@ declare abstract class PostgresProvider {
 //# sourceMappingURL=PostgresProvider.d.ts.map
 //#endregion
 //#region src/schemas/pageQuerySchema.d.ts
-declare const pageQuerySchema: _sinclair_typebox75.TObject<{
-  page: _sinclair_typebox75.TOptional<_sinclair_typebox75.TNumber>;
-  size: _sinclair_typebox75.TOptional<_sinclair_typebox75.TNumber>;
-  sort: _sinclair_typebox75.TOptional<_sinclair_typebox75.TString>;
+declare const pageQuerySchema: _sinclair_typebox74.TObject<{
+  page: _sinclair_typebox74.TOptional<_sinclair_typebox74.TNumber>;
+  size: _sinclair_typebox74.TOptional<_sinclair_typebox74.TNumber>;
+  sort: _sinclair_typebox74.TOptional<_sinclair_typebox74.TString>;
 }>;
 type PageQuery = Static<typeof pageQuerySchema>;
 //# sourceMappingURL=pageQuerySchema.d.ts.map
@@ -1130,6 +1130,12 @@ declare const PG_SCHEMA: unique symbol;
 
 //#endregion
 //#region src/descriptors/$db.d.ts
+/**
+ * @experimental
+ */
+declare const $db: <T extends {
+  [key: string]: TableLike;
+}>(options?: DbDescriptorOptions<T>) => DbDescriptor<T>;
 type DbDescriptorOptions<T extends {
   [key: string]: TableLike;
 }> = {
@@ -1138,12 +1144,13 @@ type DbDescriptorOptions<T extends {
 type DbDescriptor<T extends {
   [key: string]: TableLike;
 }> = { [key in keyof T]: Repository<any, T[key]["$schema"]> } & Pick<PostgresProvider, "execute">;
-declare const $db: <T extends {
-  [key: string]: TableLike;
-}>(options?: DbDescriptorOptions<T>) => DbDescriptor<T>;
 //# sourceMappingURL=$db.d.ts.map
 //#endregion
 //#region src/descriptors/$entity.d.ts
+/**
+ * Creates a table descriptor for drizzle-orm.
+ */
+declare const $entity: <TTableName extends string, TSchema extends TObject$1, TColumnsMap extends FromSchema<TSchema>>(options: EntityDescriptorOptions<TTableName, TSchema>) => PgTableWithColumnsAndSchema<PgTableConfig<TTableName, TSchema, TColumnsMap>, TSchema>;
 interface EntityDescriptorOptions<TTableName extends string, T extends TObject$1, Keys = keyof Static$1<T>> {
   /**
    * The name of the table. This is the name that will be used in the database.
@@ -1200,10 +1207,6 @@ interface EntityDescriptorOptions<TTableName extends string, T extends TObject$1
    */
   config?: (self: BuildExtraConfigColumns<string, FromSchema<T>, "pg">) => PgTableExtraConfigValue[];
 }
-/**
- * Creates a table descriptor for drizzle-orm.
- */
-declare const $entity: <TTableName extends string, TSchema extends TObject$1, TColumnsMap extends FromSchema<TSchema>>(options: EntityDescriptorOptions<TTableName, TSchema>) => PgTableWithColumnsAndSchema<PgTableConfig<TTableName, TSchema, TColumnsMap>, TSchema>;
 type Entity<T extends TObject$1> = PgTableWithColumnsAndSchema<PgTableConfig<string, T, FromSchema<T>>, T>;
 /**
  * Create a table with a json schema.
@@ -1222,6 +1225,13 @@ type PgTableConfig<TTableName extends string, TSchema extends TObject$1, TColumn
 //# sourceMappingURL=$entity.d.ts.map
 //#endregion
 //#region src/descriptors/$repository.d.ts
+/**
+ *
+ */
+declare const $repository: {
+  <TEntity extends TableConfig, TSchema extends TObject>(optionsOrTable: RepositoryDescriptorOptions<TEntity, TSchema> | PgTableWithColumnsAndSchema<TEntity, TSchema>): Repository<PgTableWithColumnsAndSchema<TEntity, TSchema>, TSchema>;
+  [KIND]: string;
+};
 interface RepositoryDescriptorOptions<TEntity extends TableConfig, TSchema extends TObject> {
   /**
    * The table to create the repository for.
@@ -1232,17 +1242,14 @@ interface RepositoryDescriptorOptions<TEntity extends TableConfig, TSchema exten
    */
   provider?: () => PostgresProvider;
 }
-/**
- * @param optionsOrTable
- */
-declare const $repository: {
-  <TEntity extends TableConfig, TSchema extends TObject>(optionsOrTable: RepositoryDescriptorOptions<TEntity, TSchema> | PgTableWithColumnsAndSchema<TEntity, TSchema>): Repository<PgTableWithColumnsAndSchema<TEntity, TSchema>, TSchema>;
-  [KIND]: string;
-};
 //# sourceMappingURL=$repository.d.ts.map
 //#endregion
 //#region src/descriptors/$sequence.d.ts
 declare const KEY = "SEQUENCE";
+declare const $sequence: {
+  (options?: SequenceDescriptorOptions): SequenceDescriptor;
+  [KIND]: string;
+};
 interface SequenceDescriptorOptions {
   name?: string;
   start?: number;
@@ -1258,18 +1265,17 @@ interface SequenceDescriptor {
   next(): Promise<number>;
   current(): Promise<number>;
 }
-declare const $sequence: {
-  (options?: SequenceDescriptorOptions): SequenceDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/descriptors/$transaction.d.ts
+/**
+ *
+ */
+declare const $transaction: <T extends any[], R>(opts: TransactionDescriptorOptions<T, R>) => _alepha_retry81.RetryDescriptor<(...args: T) => Promise<R>>;
 interface TransactionDescriptorOptions<T extends any[], R> {
   handler: (tx: PgTransaction<any, any, any>, ...args: T) => Promise<R>;
   config?: PgTransactionConfig$1;
 }
 type TransactionContext = PgTransaction<any, any, any>;
-declare const $transaction: <T extends any[], R>(opts: TransactionDescriptorOptions<T, R>) => _alepha_retry19.RetryDescriptor<(...args: T) => Promise<R>>;
 //# sourceMappingURL=$transaction.d.ts.map
 //#endregion
 //#region src/errors/EntityNotFoundError.d.ts
@@ -1282,12 +1288,12 @@ declare class EntityNotFoundError extends Error {
 //#endregion
 //#region src/providers/RepositoryDescriptorProvider.d.ts
 declare class RepositoryDescriptorProvider {
-  protected readonly log: _alepha_core56.Logger;
+  protected readonly log: _alepha_core55.Logger;
   protected readonly alepha: Alepha;
   protected readonly repositories: Array<Repository<any, TObject$1>>;
   constructor();
   clearRepositories(): Promise<void>;
-  protected readonly configure: _alepha_core56.HookDescriptor<"configure">;
+  protected readonly configure: _alepha_core55.HookDescriptor<"configure">;
   /**
    * Get all repositories.
    *
@@ -1321,7 +1327,7 @@ declare class RepositoryDescriptorProvider {
 //#endregion
 //#region src/providers/DrizzleKitProvider.d.ts
 declare class DrizzleKitProvider {
-  protected readonly log: _alepha_core20.Logger;
+  protected readonly log: _alepha_core19.Logger;
   protected readonly alepha: Alepha;
   protected readonly repositoryProvider: RepositoryDescriptorProvider;
   push(provider: PostgresProvider, schema?: string): Promise<void>;
@@ -1360,37 +1366,37 @@ declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 declare const envSchema: TObject$1<{
-  PG_HOST: _alepha_core22.TOptional<_alepha_core22.TString>;
-  PG_USERNAME: _alepha_core22.TOptional<_alepha_core22.TString>;
-  PG_DATABASE: _alepha_core22.TOptional<_alepha_core22.TString>;
-  PG_PASSWORD: _alepha_core22.TOptional<_alepha_core22.TString>;
-  PG_PORT: _alepha_core22.TOptional<_alepha_core22.TNumber>;
-  DATABASE_URL: _alepha_core22.TOptional<_alepha_core22.TString>;
-  DATABASE_MIGRATIONS_FOLDER: _alepha_core22.TString;
+  PG_HOST: _alepha_core21.TOptional<_alepha_core21.TString>;
+  PG_USERNAME: _alepha_core21.TOptional<_alepha_core21.TString>;
+  PG_DATABASE: _alepha_core21.TOptional<_alepha_core21.TString>;
+  PG_PASSWORD: _alepha_core21.TOptional<_alepha_core21.TString>;
+  PG_PORT: _alepha_core21.TOptional<_alepha_core21.TNumber>;
+  DATABASE_URL: _alepha_core21.TOptional<_alepha_core21.TString>;
+  DATABASE_MIGRATIONS_FOLDER: _alepha_core21.TString;
   /**
    * The schema to use.
    * Accept a string.
    */
-  POSTGRES_SCHEMA: _alepha_core22.TOptional<_alepha_core22.TString>;
+  POSTGRES_SCHEMA: _alepha_core21.TOptional<_alepha_core21.TString>;
   /**
    * Synchronize the database schema with the models.
    * Accept a boolean or a postgres schema name.
    *
    * @default false
    */
-  POSTGRES_SYNCHRONIZE: _alepha_core22.TOptional<_alepha_core22.TBoolean>;
+  POSTGRES_SYNCHRONIZE: _alepha_core21.TOptional<_alepha_core21.TBoolean>;
   /**
    * Push the schema to the database.
    *
    * @default false
    */
-  POSTGRES_PUSH_SCHEMA: _alepha_core22.TOptional<_alepha_core22.TBoolean>;
+  POSTGRES_PUSH_SCHEMA: _alepha_core21.TOptional<_alepha_core21.TBoolean>;
   /**
    * Reject unauthorized SSL connections.
    *
    * @default false
    */
-  POSTGRES_REJECT_UNAUTHORIZED: _alepha_core22.TBoolean;
+  POSTGRES_REJECT_UNAUTHORIZED: _alepha_core21.TBoolean;
 }>;
 interface NodePostgresProviderState {
   client: postgres.Sql;
@@ -1398,7 +1404,7 @@ interface NodePostgresProviderState {
 }
 declare class NodePostgresProvider extends PostgresProvider {
   readonly dialect = "postgres";
-  protected readonly log: _alepha_core22.Logger;
+  protected readonly log: _alepha_core21.Logger;
   protected readonly env: {
     DATABASE_URL?: string | undefined;
     PG_HOST?: string | undefined;
@@ -1420,8 +1426,8 @@ declare class NodePostgresProvider extends PostgresProvider {
    */
   protected testingSchemaName?: string;
   get db(): PostgresJsDatabase;
-  protected readonly configure: _alepha_core22.HookDescriptor<"start">;
-  protected readonly stop: _alepha_core22.HookDescriptor<"stop">;
+  protected readonly configure: _alepha_core21.HookDescriptor<"start">;
+  protected readonly stop: _alepha_core21.HookDescriptor<"stop">;
   /**
    * Get Postgres schema.
    */
@@ -1429,7 +1435,7 @@ declare class NodePostgresProvider extends PostgresProvider {
   execute<T extends TObject$1 = any>(query: SQLLike, schema?: T): Promise<Array<T extends TObject$1 ? Static<T> : any>>;
   connect(): Promise<void>;
   close(): Promise<void>;
-  protected migrate: _alepha_lock45.LockDescriptor<() => Promise<void>>;
+  protected migrate: _alepha_lock44.LockDescriptor<() => Promise<void>>;
   protected createClient(): NodePostgresProviderState;
   protected getMigrationOptions(): MigrationConfig;
   protected getClientOptions(): postgres.Options<any>;
@@ -1444,7 +1450,7 @@ declare class NodePostgresProvider extends PostgresProvider {
 type PgAttr<T extends TSchema$1, TAttr extends PgSymbolKeys> = T & { [K in TAttr]: PgSymbols[K] };
 //#endregion
 //#region src/schemas/createdAtSchema.d.ts
-declare const createdAtSchema: PgAttr<PgAttr<_sinclair_typebox85.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+declare const createdAtSchema: PgAttr<PgAttr<_sinclair_typebox89.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
 //# sourceMappingURL=createdAtSchema.d.ts.map
 
 //#endregion
@@ -1452,7 +1458,7 @@ declare const createdAtSchema: PgAttr<PgAttr<_sinclair_typebox85.TString, typeof
 /**
  * @deprecated Use `pg.primaryKey()` instead.
  */
-declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<_sinclair_typebox88.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
+declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<_sinclair_typebox85.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
 //# sourceMappingURL=legacyIdSchema.d.ts.map
 //#endregion
 //#region src/schemas/updatedAtSchema.d.ts
@@ -1467,9 +1473,9 @@ declare const updatedAtSchema: PgAttr<PgAttr<_sinclair_typebox82.TString, typeof
  * Add some common SQL properties to an object.
  */
 declare const entitySchema: TObject$1<{
-  id: PgAttr<PgAttr<PgAttr<_sinclair_typebox58.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
-  createdAt: PgAttr<PgAttr<_sinclair_typebox58.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
-  updatedAt: PgAttr<PgAttr<_sinclair_typebox58.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+  id: PgAttr<PgAttr<PgAttr<_sinclair_typebox57.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
+  createdAt: PgAttr<PgAttr<_sinclair_typebox57.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+  updatedAt: PgAttr<PgAttr<_sinclair_typebox57.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
 }>;
 /**
  * TypeBox Entity Type.
@@ -1504,19 +1510,19 @@ declare class PostgresTypeProvider {
   /**
    * Creates a primary key with an identity column.
    */
-  readonly identityPrimaryKey: (identity?: PgIdentityOptions, options?: IntegerOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox49.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
+  readonly identityPrimaryKey: (identity?: PgIdentityOptions, options?: IntegerOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox48.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
   /**
    * Creates a primary key with a big identity column. (default)
    */
-  readonly bigIdentityPrimaryKey: (identity?: PgIdentityOptions, options?: NumberOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox49.TNumber, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
+  readonly bigIdentityPrimaryKey: (identity?: PgIdentityOptions, options?: NumberOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox48.TNumber, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
   /**
    * Creates a primary key with a UUID column.
    */
-  readonly uuidPrimaryKey: () => PgAttr<PgAttr<_sinclair_typebox49.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
+  readonly uuidPrimaryKey: () => PgAttr<PgAttr<_sinclair_typebox48.TString, typeof PG_PRIMARY_KEY>, typeof PG_DEFAULT>;
   /**
    * @alias bigIdentityPrimaryKey
    */
-  readonly primaryKey: (identity?: PgIdentityOptions, options?: NumberOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox49.TNumber, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
+  readonly primaryKey: (identity?: PgIdentityOptions, options?: NumberOptions) => PgAttr<PgAttr<PgAttr<_sinclair_typebox48.TNumber, typeof PG_PRIMARY_KEY>, typeof PG_IDENTITY>, typeof PG_DEFAULT>;
   /**
    * Wrap a schema with "default" attribute.
    * This is used to set a default value for a column in the database.
@@ -1527,15 +1533,15 @@ declare class PostgresTypeProvider {
    * This is used to track the version of a row in the database.
    * You can use it for optimistic concurrency control.
    */
-  readonly version: (options?: IntegerOptions) => PgAttr<PgAttr<_sinclair_typebox49.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
+  readonly version: (options?: IntegerOptions) => PgAttr<PgAttr<_sinclair_typebox48.TInteger, typeof PG_VERSION>, typeof PG_DEFAULT>;
   /**
    * Creates a column Created At. So just a datetime column with a default value of the current timestamp.
    */
-  readonly createdAt: (options?: StringOptions) => PgAttr<PgAttr<_sinclair_typebox49.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
+  readonly createdAt: (options?: StringOptions) => PgAttr<PgAttr<_sinclair_typebox48.TString, typeof PG_CREATED_AT>, typeof PG_DEFAULT>;
   /**
    * Creates a column Updated At. Like createdAt, but it is updated on every update of the row.
    */
-  readonly updatedAt: (options?: StringOptions) => PgAttr<PgAttr<_sinclair_typebox49.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
+  readonly updatedAt: (options?: StringOptions) => PgAttr<PgAttr<_sinclair_typebox48.TString, typeof PG_UPDATED_AT>, typeof PG_DEFAULT>;
   /**
    * @deprecated Build your own entity schema.
    */
@@ -1600,6 +1606,132 @@ declare const schema: <TDocument extends TSchema$2>(name: string, document: TDoc
 declare module "alepha" {
   function $inject<T extends TableConfig, R extends TObject>(type: PgTableWithColumnsAndSchema<T, R>): Repository<PgTableWithColumnsAndSchema<T, R>, R>;
 }
+/**
+ * Provides PostgreSQL and SQLite database integration with type-safe ORM capabilities through Drizzle.
+ *
+ * The postgres module enables declarative database operations using descriptors like `$entity`, `$repository`,
+ * and `$db` on class properties. It offers automatic schema generation, type-safe queries, transactions,
+ * and database migrations with support for both PostgreSQL and SQLite backends.
+ *
+ * **Key Features:**
+ * - Declarative entity definition with `$entity` descriptor
+ * - Type-safe repository pattern with `$repository` descriptor
+ * - Database connection management with `$db` descriptor
+ * - Automatic schema migrations and type generation
+ * - Transaction support with `$transaction` descriptor
+ * - Sequence management with `$sequence` descriptor
+ * - Full TypeScript integration with compile-time type checking
+ *
+ * **Basic Usage:**
+ * ```ts
+ * import { Alepha, run, t } from "alepha";
+ * import { AlephaPostgres, $entity, $repository, pg } from "alepha/postgres";
+ *
+ * // Define database entities
+ * const user = $entity({
+ *   name: "users",
+ *   schema: t.object({
+ *     id: pg.primaryKey(),
+ *     createdAt: pg.createdAt(),
+ *     name: t.string(),
+ *     email: t.string(),
+ *     age: t.optional(t.integer()),
+ *   }),
+ * });
+ *
+ * const post = $entity({
+ *   name: "posts",
+ *   schema: t.object({
+ *     id: pg.primaryKey(),
+ *     createdAt: pg.createdAt(),
+ *     title: t.string(),
+ *     content: t.string(),
+ *     authorId: pg.references(t.uint(), () => user.id),
+ *   }),
+ * });
+ *
+ * class Database {
+ *   users = $repository(user);
+ *   posts = $repository(post);
+ * }
+ *
+ * const alepha = Alepha.create()
+ *   .with(AlephaPostgres)
+ *   .with(Database);
+ *
+ * run(alepha);
+ * ```
+ *
+ * **Repository Operations:**
+ * ```ts
+ * class UserService {
+ *   users = $repository(user);
+ *
+ *   async createUser(userData: { name: string; email: string }) {
+ *     return await this.users.create(userData);
+ *   }
+ *
+ *   async findUserByEmail(email: string) {
+ *     return await this.users.findFirst({
+ *       where: { email },
+ *     });
+ *   }
+ *
+ *   async getUsersWithPosts() {
+ *     return await this.users.find({
+ *       with: { posts: true },
+ *       limit: 10,
+ *     });
+ *   }
+ *
+ *   async updateUser(id: number, updates: Partial<{ name: string; age: number }>) {
+ *     return await this.users.update(id, updates);
+ *   }
+ * }
+ * ```
+ *
+ * **Advanced Database Operations:**
+ * ```ts
+ * import { $db, $transaction } from "alepha/postgres";
+ *
+ * class AdvancedDatabase {
+ *   db = $db({
+ *     entities: { user, post },
+ *   });
+ *
+ *   createUserWithPost = $transaction(async () => {
+ *     const newUser = await this.db.users.create({
+ *       name: "John Doe",
+ *       email: "john@example.com",
+ *     });
+ *
+ *     const newPost = await this.db.posts.create({
+ *       title: "My First Post",
+ *       content: "Hello world!",
+ *       authorId: newUser.id,
+ *     });
+ *
+ *     return { user: newUser, post: newPost };
+ *   });
+ *
+ *   async rawQuery() {
+ *     // Execute raw SQL queries
+ *     return await this.db.execute(sql`
+ *       SELECT users.name, COUNT(posts.id) as post_count
+ *       FROM users
+ *       LEFT JOIN posts ON users.id = posts.author_id
+ *       GROUP BY users.id, users.name
+ *     `);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link $entity}
+ * @see {@link $repository}
+ * @see {@link $db}
+ * @see {@link $transaction}
+ * @module alepha.postgres
+ */
 declare class AlephaPostgres implements Module {
   readonly name = "alepha.postgres";
   readonly env: {

package/queue/redis.d.ts

@@ -17,8 +17,6 @@ declare class RedisQueueProvider implements QueueProvider {
 //#region src/index.d.ts
 // ---------------------------------------------------------------------------------------------------------------------
 /**
-* Alepha Queue Redis Module
-*
 * Plugin for Alepha Queue that provides Redis queue capabilities.
 *
 * @see {@link RedisQueueProvider}

package/queue.d.ts

@@ -31,7 +31,7 @@ declare abstract class QueueProvider {
 //#region src/descriptors/$queue.d.ts
 declare const KEY$1 = "QUEUE";
 /**
- * Queue descriptor.
+ * Create a new queue.
  */
 declare const $queue: {
   <T extends QueueMessageSchema>(options: QueueDescriptorOptions<T>): QueueDescriptor<T>;
@@ -192,11 +192,97 @@ declare class QueueDescriptorProvider {
 //#endregion
 //#region src/index.d.ts
 /**
- * Alepha Queue Module
+ * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
  *
- * Generic interface for queueing.
- * Gives you the ability to create queues and consumers.
- * This module provides only a memory implementation of the queue provider.
+ * The queue module enables reliable background job processing and message passing using the `$queue` descriptor
+ * on class properties. It supports schema validation, automatic retries, and multiple queue backends for
+ * building scalable, decoupled applications with robust error handling.
+ *
+ * **Key Features:**
+ * - Declarative queue definition with `$queue` descriptor
+ * - Schema validation for message payloads and headers
+ * - Built-in message handlers with automatic processing
+ * - Multiple queue backends (memory, Redis, etc.)
+ * - Type-safe message publishing and consumption
+ * - Automatic retry mechanisms and error handling
+ *
+ * **Basic Usage:**
+ * ```ts
+ * import { Alepha, run, t } from "alepha";
+ * import { AlephaQueue, $queue } from "alepha/queue";
+ *
+ * class EmailService {
+ *   sendEmail = $queue({
+ *     name: "emails",
+ *     schema: {
+ *       payload: t.object({
+ *         to: t.string(),
+ *         subject: t.string(),
+ *         body: t.string(),
+ *       }),
+ *     },
+ *     handler: async ({ payload }) => {
+ *       // Process the email
+ *       await sendEmailViaProvider(payload.to, payload.subject, payload.body);
+ *       console.log(`Email sent to ${payload.to}`);
+ *     },
+ *   });
+ * }
+ *
+ * const alepha = Alepha.create()
+ *   .with(AlephaQueue)
+ *   .with(EmailService);
+ *
+ * run(alepha);
+ * ```
+ *
+ * **Queue Operations:**
+ * ```ts
+ * class NotificationService {
+ *   notifications = $queue({
+ *     name: "notifications",
+ *     provider: "memory",
+ *     schema: {
+ *       payload: t.object({
+ *         userId: t.string(),
+ *         message: t.string(),
+ *         type: t.union([t.literal("info"), t.literal("warning"), t.literal("error")]),
+ *       }),
+ *     },
+ *     handler: async ({ payload }) => {
+ *       await sendNotification(payload.userId, payload.message, payload.type);
+ *     },
+ *   });
+ *
+ *   async notifyUser(userId: string, message: string, type: "info" | "warning" | "error") {
+ *     // Push message to queue
+ *     await this.notifications.push({ userId, message, type });
+ *   }
+ * }
+ * ```
+ *
+ * **Batch Processing:**
+ * ```ts
+ * class BatchProcessor {
+ *   processTasks = $queue({
+ *     name: "batch-tasks",
+ *     schema: {
+ *       payload: t.object({
+ *         taskId: t.string(),
+ *         data: t.any(),
+ *       }),
+ *     },
+ *     handler: async ({ payload }) => {
+ *       await processTask(payload.taskId, payload.data);
+ *     },
+ *   });
+ *
+ *   async submitBatch(tasks: Array<{ taskId: string; data: any }>) {
+ *     // Push multiple messages at once
+ *     await this.processTasks.push(...tasks);
+ *   }
+ * }
+ * ```
  *
  * @see {@link $queue}
  * @see {@link $consumer}

package/react/auth.d.ts

@@ -12,6 +12,13 @@ import * as _sinclair_typebox2 from "@sinclair/typebox";
 
 //#region src/descriptors/$auth.d.ts
 declare const KEY = "AUTH";
+/**
+ *
+ */
+declare const $auth: {
+  (options: AuthDescriptorOptions): AuthDescriptor;
+  [KIND]: string;
+};
 type AccessToken = string;
 interface AuthDescriptorOptions {
   name?: string;
@@ -30,10 +37,6 @@ interface AuthDescriptor {
   [OPTIONS]: AuthDescriptorOptions;
   jwks: () => string;
 }
-declare const $auth: {
-  (options: AuthDescriptorOptions): AuthDescriptor;
-  [KIND]: string;
-};
 //#endregion
 //#region src/providers/ReactAuthProvider.d.ts
 declare class ReactAuthProvider {
@@ -185,8 +188,6 @@ declare module "alepha/react" {
   }
 }
 /**
- * Alepha React Authentication Module
- *
  * The ReactAuthModule provides authentication services for React applications.
  *
  * @see {@link ReactAuthProvider}

package/react/head.d.ts

@@ -76,7 +76,7 @@ declare module "alepha/react" {
   }
 }
 /**
- * Alepha React Head Module
+ * Fill `<head>` server & client side.
  *
  * @see {@link ServerHeadProvider}
  * @module alepha.react.head