alepha 0.9.4 → 0.9.5

package/postgres.d.ts

@@ -1,17 +1,17 @@
 import * as _alepha_core1 from "alepha";
-import { Alepha, AlephaError, Descriptor, KIND, Service, Static, TObject, TSchema as TSchema$1 } from "alepha";
-import * as drizzle_orm7 from "drizzle-orm";
+import { Alepha, AlephaError, Descriptor, KIND, Service, Static, TNull, TObject, TOptional, TSchema as TSchema$1, TUnion } from "alepha";
+import * as drizzle_orm6 from "drizzle-orm";
 import { BuildColumns, BuildExtraConfigColumns, SQL, SQLWrapper, TableConfig, sql } from "drizzle-orm";
 import * as pg$1 from "drizzle-orm/pg-core";
 import { AnyPgColumn, LockConfig, LockStrength, PgColumn, PgColumnBuilderBase, PgDatabase, PgInsertValue, PgSequenceOptions, PgTableExtraConfigValue, PgTableWithColumns, PgTransaction, PgTransactionConfig, SelectedFields, TableConfig as TableConfig$1, UpdateDeleteAction } from "drizzle-orm/pg-core";
-import { DateTimeProvider } from "alepha/datetime";
+import { DateTime, DateTimeProvider } from "alepha/datetime";
 import * as _alepha_logger1 from "alepha/logger";
 import * as _alepha_lock0 from "alepha/lock";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import * as _alepha_retry0 from "alepha/retry";
-import * as _sinclair_typebox1 from "@sinclair/typebox";
-import { Evaluate, IntegerOptions, Kind, NumberOptions, ObjectOptions, OptionalKind, Static as Static$1, StringOptions, TAdditionalProperties, TArray, TBoolean, TInteger, TIntersect, TNumber, TObject as TObject$1, TOptional, TOptionalWithFlag, TPick, TProperties, TReadonly, TRecord, TSchema as TSchema$2, TString } from "@sinclair/typebox";
+import * as _sinclair_typebox0 from "@sinclair/typebox";
+import { Evaluate, IntegerOptions, Kind, NumberOptions, ObjectOptions, OptionalKind, Static as Static$1, StringOptions, TAdditionalProperties, TArray, TBoolean, TInteger, TIntersect, TNumber, TObject as TObject$1, TOptional as TOptional$1, TOptionalWithFlag, TPick, TProperties, TReadonly, TRecord, TSchema as TSchema$2, TString } from "@sinclair/typebox";
 import { PgTransactionConfig as PgTransactionConfig$1 } from "drizzle-orm/pg-core/session";
 import * as DrizzleKit from "drizzle-kit/api";
 import { MigrationConfig } from "drizzle-orm/migrator";
@@ -65,11 +65,11 @@ interface PgRefOptions {
   };
 }
 //#endregion
-//#region src/interfaces/TInsertObject.d.ts
+//#region src/schemas/insertSchema.d.ts
 /**
  * Fork of the original typebox schema "TObject".
  */
-interface TInsertObject<T extends TObject$1> extends TSchema$2, ObjectOptions {
+interface TObjectInsert<T extends TObject$1> extends TSchema$2, ObjectOptions {
   [Kind]: "Object";
   static: ObjectStatic<{ [K in keyof T["properties"] as T["properties"][K] extends {
     [PG_DEFAULT]: any;
@@ -81,12 +81,39 @@ interface TInsertObject<T extends TObject$1> extends TSchema$2, ObjectOptions {
     [PG_DEFAULT]: any;
   } ? never : K]: T["properties"][K] };
 }
-type ReadonlyOptionalPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TReadonly<TSchema$2> ? T[K] extends TOptional<T[K]> ? K : never : never }[keyof T];
-type ReadonlyPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TReadonly<TSchema$2> ? T[K] extends TOptional<T[K]> ? never : K : never }[keyof T];
-type OptionalPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TOptional<TSchema$2> ? T[K] extends TReadonly<T[K]> ? never : K : never }[keyof T];
+type ReadonlyOptionalPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TReadonly<TSchema$2> ? T[K] extends TOptional$1<T[K]> ? K : never : never }[keyof T];
+type ReadonlyPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TReadonly<TSchema$2> ? T[K] extends TOptional$1<T[K]> ? never : K : never }[keyof T];
+type OptionalPropertyKeys<T extends TProperties> = { [K in keyof T]: T[K] extends TOptional$1<TSchema$2> ? T[K] extends TReadonly<T[K]> ? never : K : never }[keyof T];
 type RequiredPropertyKeys<T extends TProperties> = keyof Omit<T, ReadonlyOptionalPropertyKeys<T> | ReadonlyPropertyKeys<T> | OptionalPropertyKeys<T>>;
 type ObjectStaticProperties<T extends TProperties, R extends Record<keyof any, unknown>> = Evaluate<Readonly<Partial<Pick<R, ReadonlyOptionalPropertyKeys<T>>>> & Readonly<Pick<R, ReadonlyPropertyKeys<T>>> & Partial<Pick<R, OptionalPropertyKeys<T>>> & Required<Pick<R, RequiredPropertyKeys<T>>>>;
 type ObjectStatic<T extends TProperties, P extends unknown[]> = ObjectStaticProperties<T, { [K in keyof T]: Static$1<T[K], P> }>;
+declare const insertSchema: <T extends TObject$1>(obj: T) => TObjectInsert<T>;
+/**
+ * Enhance Typebox with a support of "Default" (PG_DEFAULT).
+ */
+type StaticInsert<T extends TObject$1> = StaticEntry<T> & StaticDefaultEntry<T>;
+type StaticDefaultEntry<T extends TObject$1> = { [K in keyof T["properties"] as T["properties"][K] extends {
+  [PG_DEFAULT]: any;
+} | {
+  [OptionalKind]: "Optional";
+} ? K : never]?: Static$1<T["properties"][K]> };
+type StaticEntry<T extends TObject$1> = { [K in keyof T["properties"] as T["properties"][K] extends {
+  [PG_DEFAULT]: any;
+} | {
+  [OptionalKind]: "Optional";
+} ? never : K]: Static$1<T["properties"][K]> };
+//#endregion
+//#region src/schemas/updateSchema.d.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.
+ *
+ * @example
+ * Before: { name?: string; age: number; }
+ * After:  { name?: string | null; age: number; }
+ */
+type TObjectUpdate<T extends TObject> = TObject<{ [K in keyof T["properties"]]: T["properties"][K] extends TOptional<infer U> ? TOptional<TUnion<[U, TNull]>> : T["properties"][K] }>;
 //#endregion
 //#region src/helpers/schemaToPgColumns.d.ts
 /**
@@ -107,7 +134,7 @@ declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSeria
   data: Buffer<ArrayBufferLike>;
   driverParam: unknown;
   enumValues: undefined;
-}> | pg$1.PgTimestampStringBuilderInitial<string> | pg$1.PgDateStringBuilderInitial<string> | pg$1.PgTextBuilderInitial<string, [string, ...string[]]> | pg$1.PgBooleanBuilderInitial<string> | drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+}> | pg$1.PgTimestampStringBuilderInitial<string> | pg$1.PgDateStringBuilderInitial<string> | pg$1.PgTextBuilderInitial<string, [string, ...string[]]> | pg$1.PgBooleanBuilderInitial<string> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -120,14 +147,14 @@ declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSeria
 }>, {
   [x: string]: unknown;
   [x: number]: unknown;
-}> | drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+}> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
   data: {};
   driverParam: string;
   enumValues: undefined;
-}>, {}> | drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+}>, {}> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -252,31 +279,215 @@ type FromSchema<T extends TObject> = { [key in keyof T["properties"]]: PgColumnB
 type PgTableWithColumnsAndSchema<T extends TableConfig, R extends TObject> = PgTableWithColumns<T> & {
   get $table(): PgTableWithColumns<T>;
   get $schema(): R;
-  get $insertSchema(): TInsertObject<R>;
+  get $insertSchema(): TObjectInsert<R>;
+  get $updateSchema(): TObjectUpdate<R>;
 };
-interface TableLike<T extends TObject = TObject> {
-  $schema: T;
-}
 //#endregion
 //#region src/descriptors/$entity.d.ts
 /**
- * Declare a new entity in the database.
- * This descriptor alone does not create the table, it only describes it.
- * It must be used with `$repository` to create the table and perform operations on it.
+ * Creates a database entity descriptor that defines table structure using TypeBox schemas.
+ *
+ * This descriptor provides a type-safe way to define database tables using JSON Schema
+ * syntax while generating the necessary database metadata for migrations and operations.
+ * It integrates with Drizzle ORM under the hood and works seamlessly with the $repository
+ * descriptor for complete database functionality.
+ *
+ * **Key Features**
+ *
+ * - **Type-Safe Schema Definition**: Uses TypeBox for full TypeScript type inference
+ * - **Automatic Table Generation**: Creates Drizzle ORM table structures automatically
+ * - **Index Management**: Supports single-column, multi-column, and unique indexes
+ * - **Constraint Support**: Foreign keys, unique constraints, and check constraints
+ * - **Audit Fields**: Built-in support for created_at, updated_at, deleted_at, and version fields
+ * - **Schema Validation**: Automatic insert/update schema generation with validation
+ *
+ * **Important Note**:
+ * This descriptor only defines the table structure - it does not create the physical
+ * database table. Use it with $repository to perform actual database operations,
+ * and run migrations to create the tables in your database.
+ *
+ * **Use Cases**
+ *
+ * Essential for defining database schema in type-safe applications:
+ * - User management and authentication tables
+ * - Business domain entities (products, orders, customers)
+ * - Audit and logging tables
+ * - Junction tables for many-to-many relationships
+ * - Configuration and settings tables
  *
- * This is a convenience function to create a table with a json schema.
- * For now, it creates a drizzle-orm table under the hood.
+ * @example
+ * **Basic entity with indexes:**
  * ```ts
  * import { $entity } from "alepha/postgres";
+ * import { pg, t } from "alepha";
  *
  * const User = $entity({
- *   name: "user",
+ *   name: "users",
  *   schema: t.object({
  *     id: pg.primaryKey(t.uuid()),
- *     name: t.string(),
- *     email: t.string(),
+ *     email: t.string({ format: "email" }),
+ *     username: t.string({ minLength: 3, maxLength: 30 }),
+ *     firstName: t.string(),
+ *     lastName: t.string(),
+ *     isActive: t.boolean({ default: true }),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt(),
+ *     deletedAt: pg.deletedAt()
+ *   }),
+ *   indexes: [
+ *     "email",              // Simple index on email
+ *     "username",           // Simple index on username
+ *     { column: "email", unique: true },  // Unique constraint on email
+ *     { columns: ["firstName", "lastName"] } // Composite index
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * **E-commerce product entity with relationships:**
+ * ```ts
+ * const Product = $entity({
+ *   name: "products",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     sku: t.string({ minLength: 3 }),
+ *     name: t.string({ minLength: 1, maxLength: 200 }),
+ *     description: t.optional(t.string()),
+ *     price: t.number({ minimum: 0 }),
+ *     categoryId: t.string({ format: "uuid" }),
+ *     inStock: t.boolean({ default: true }),
+ *     stockQuantity: t.integer({ minimum: 0, default: 0 }),
+ *     tags: t.optional(t.array(t.string())), // PostgreSQL array column
+ *     metadata: t.optional(t.record(t.string(), t.any())), // JSONB column
+ *     version: pg.version(),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt()
+ *   }),
+ *   indexes: [
+ *     { column: "sku", unique: true },        // Unique SKU
+ *     "categoryId",                           // Foreign key index
+ *     "inStock",                             // Filter frequently by stock status
+ *     { columns: ["categoryId", "inStock"] }, // Composite for category + stock queries
+ *     "createdAt"                            // For date-based queries
+ *   ],
+ *   foreignKeys: [
+ *     {
+ *       name: "fk_product_category",
+ *       columns: ["categoryId"],
+ *       foreignColumns: [Category.id] // Reference to Category entity
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * **Audit log entity with constraints:**
+ * ```ts
+ * const AuditLog = $entity({
+ *   name: "audit_logs",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     tableName: t.string(),
+ *     recordId: t.string(),
+ *     action: t.enum(["CREATE", "UPDATE", "DELETE"]),
+ *     userId: t.optional(t.string({ format: "uuid" })),
+ *     oldValues: t.optional(t.record(t.string(), t.any())),
+ *     newValues: t.optional(t.record(t.string(), t.any())),
+ *     timestamp: pg.createdAt(),
+ *     ipAddress: t.optional(t.string()),
+ *     userAgent: t.optional(t.string())
+ *   }),
+ *   indexes: [
+ *     "tableName",
+ *     "recordId",
+ *     "userId",
+ *     "action",
+ *     { columns: ["tableName", "recordId"] }, // Find all changes to a record
+ *     { columns: ["userId", "timestamp"] },   // User activity timeline
+ *     "timestamp"  // Time-based queries
+ *   ],
+ *   constraints: [
+ *     {
+ *       name: "valid_action_values",
+ *       columns: ["action"],
+ *       check: sql`action IN ('CREATE', 'UPDATE', 'DELETE')`
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * **Many-to-many junction table:**
+ * ```ts
+ * const UserRole = $entity({
+ *   name: "user_roles",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     userId: t.string({ format: "uuid" }),
+ *     roleId: t.string({ format: "uuid" }),
+ *     assignedBy: t.string({ format: "uuid" }),
+ *     assignedAt: pg.createdAt(),
+ *     expiresAt: t.optional(t.datetime())
+ *   }),
+ *   indexes: [
+ *     "userId",
+ *     "roleId",
+ *     "assignedBy",
+ *     { columns: ["userId", "roleId"], unique: true }, // Prevent duplicate assignments
+ *     "expiresAt" // For cleanup of expired roles
+ *   ],
+ *   foreignKeys: [
+ *     {
+ *       columns: ["userId"],
+ *       foreignColumns: [User.id]
+ *     },
+ *     {
+ *       columns: ["roleId"],
+ *       foreignColumns: [Role.id]
+ *     },
+ *     {
+ *       columns: ["assignedBy"],
+ *       foreignColumns: [User.id]
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * **Entity with custom Drizzle configuration:**
+ * ```ts
+ * const Order = $entity({
+ *   name: "orders",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     orderNumber: t.string(),
+ *     customerId: t.string({ format: "uuid" }),
+ *     status: t.enum(["pending", "processing", "shipped", "delivered"]),
+ *     totalAmount: t.number({ minimum: 0 }),
+ *     currency: t.string({ default: "USD" }),
+ *     notes: t.optional(t.string()),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt(),
+ *     version: pg.version()
  *   }),
- *   indexes: ["email"],
+ *   indexes: [
+ *     { column: "orderNumber", unique: true },
+ *     "customerId",
+ *     "status",
+ *     "createdAt",
+ *     { columns: ["customerId", "status"] }
+ *   ],
+ *   // Advanced Drizzle ORM configuration
+ *   config: (table) => [
+ *     // Custom index with specific options
+ *     index("idx_orders_amount_status")
+ *       .on(table.totalAmount, table.status)
+ *       .where(sql`status != 'cancelled'`), // Partial index
+ *
+ *     // Full-text search index (PostgreSQL specific)
+ *     index("idx_orders_search")
+ *       .using("gin", table.notes)
+ *   ]
  * });
  * ```
  *
@@ -288,52 +499,265 @@ declare const $entity: {
 };
 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.
-   * @example
-   * name: "user"
+   * The database table name that will be created for this entity.
+   *
+   * This name:
+   * - Must be unique within your database schema
+   * - Should follow your database naming conventions (typically snake_case)
+   * - Will be used in generated SQL queries and migrations
+   * - Should be descriptive of the entity's purpose
+   *
+   * **Naming Guidelines**:
+   * - Use plural nouns for table names ("users", "products", "orders")
+   * - Use snake_case for multi-word names ("user_profiles", "order_items")
+   * - Keep names concise but descriptive
+   * - Avoid SQL reserved words
+   *
+   * @example "users"
+   * @example "product_categories"
+   * @example "user_roles"
+   * @example "audit_logs"
    */
   name: TTableName;
   /**
-   * The schema of the table. This is a TypeBox schema that describes the columns and their types.
+   * TypeBox schema defining the table structure and column types.
+   *
+   * This schema:
+   * - Defines all table columns with their types and constraints
+   * - Provides full TypeScript type inference for the entity
+   * - Supports validation rules and default values
+   * - Enables automatic insert/update schema generation
+   * - Must include exactly one primary key field marked with `pg.primaryKey()`
+   *
+   * **Supported PostgreSQL Types**:
+   * - `pg.primaryKey(t.uuid())` - UUID primary key
+   * - `t.string()` - VARCHAR column
+   * - `t.integer()`, `t.number()` - Numeric columns
+   * - `t.boolean()` - Boolean column
+   * - `t.array(t.string())` - PostgreSQL array column
+   * - `t.record(t.string(), t.any())` - JSONB column
+   * - `pg.createdAt()`, `pg.updatedAt()`, `pg.deletedAt()` - Audit timestamps
+   * - `pg.version()` - Optimistic locking version field
+   *
+   * **Schema Best Practices**:
+   * - Always include a primary key
+   * - Use appropriate TypeBox constraints (minLength, format, etc.)
+   * - Add audit fields for trackability
+   * - Use optional fields for nullable columns
+   * - Include foreign key columns for relationships
+   *
    * @example
-   * schema: t.object({
-   *   id: t.uuid(),
-   *   name: t.string(),
-   *   email: t.string(),
-   *   phoneNumber: t.string(),
+   * ```ts
+   * t.object({
+   *   id: pg.primaryKey(t.uuid()),
+   *   email: t.string({ format: "email" }),
+   *   firstName: t.string({ minLength: 1, maxLength: 100 }),
+   *   lastName: t.string({ minLength: 1, maxLength: 100 }),
+   *   age: t.optional(t.integer({ minimum: 0, maximum: 150 })),
+   *   isActive: t.boolean({ default: true }),
+   *   preferences: t.optional(t.record(t.string(), t.any())),
+   *   tags: t.optional(t.array(t.string())),
+   *   createdAt: pg.createdAt(),
+   *   updatedAt: pg.updatedAt(),
+   *   version: pg.version()
    * })
+   * ```
    */
   schema: T;
   /**
-   * The indexes to create for the table. This can be a string or an object with the column name and options.
-   * @example
-   * indexes: ["name", { column: "email", unique: true }]
+   * Database indexes to create for query optimization.
+   *
+   * Indexes improve query performance but consume disk space and slow down writes.
+   * Choose indexes based on your actual query patterns and performance requirements.
+   *
+   * **Index Types**:
+   * - **Simple string**: Creates a single-column index
+   * - **Single column object**: Creates index on one column with options
+   * - **Multi-column object**: Creates composite index on multiple columns
+   *
+   * **Index Guidelines**:
+   * - Index frequently queried columns (WHERE, ORDER BY, JOIN conditions)
+   * - Create unique indexes for business constraints
+   * - Use composite indexes for multi-column queries
+   * - Index foreign key columns for join performance
+   * - Monitor index usage and remove unused indexes
+   *
+   * **Performance Considerations**:
+   * - Each index increases storage requirements
+   * - Indexes slow down INSERT/UPDATE/DELETE operations
+   * - PostgreSQL can use multiple indexes in complex queries
+   * - Partial indexes can be more efficient for filtered queries
+   *
+   * @example ["email", "createdAt", { column: "username", unique: true }]
+   * @example [{ columns: ["userId", "status"], name: "idx_user_status" }]
+   * @example ["categoryId", { columns: ["price", "inStock"] }]
    */
   indexes?: (Keys | {
+    /**
+     * Single column to index.
+     */
     column: Keys;
+    /**
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
     unique?: boolean;
+    /**
+     * Custom name for the index. If not provided, generates name automatically.
+     */
     name?: string;
   } | {
+    /**
+     * Multiple columns for composite index (order matters for query optimization).
+     */
     columns: Keys[];
+    /**
+     * Whether this should be a unique index (enforces uniqueness constraint).
+     */
     unique?: boolean;
+    /**
+     * Custom name for the index. If not provided, generates name automatically.
+     */
     name?: string;
   })[];
+  /**
+   * Foreign key constraints to maintain referential integrity.
+   *
+   * Foreign keys ensure that values in specified columns must exist in the referenced table.
+   * They prevent orphaned records and maintain database consistency.
+   *
+   * **Foreign Key Benefits**:
+   * - Prevents invalid references to non-existent records
+   * - Maintains data integrity automatically
+   * - Provides clear schema documentation of relationships
+   * - Enables cascade operations (DELETE, UPDATE)
+   *
+   * **Considerations**:
+   * - Foreign keys can impact performance on large tables
+   * - They prevent deletion of referenced records
+   * - Consider cascade options for related data cleanup
+   *
+   * @example
+   * ```ts
+   * foreignKeys: [
+   *   {
+   *     name: "fk_user_role",
+   *     columns: ["roleId"],
+   *     foreignColumns: [Role.id]
+   *   },
+   *   {
+   *     columns: ["createdBy"],
+   *     foreignColumns: [User.id]
+   *   }
+   * ]
+   * ```
+   */
   foreignKeys?: Array<{
+    /**
+     * Optional name for the foreign key constraint.
+     */
     name?: string;
+    /**
+     * Local columns that reference the foreign table.
+     */
     columns: Array<keyof Static$1<T>>;
+    /**
+     * Referenced columns in the foreign table.
+     */
     foreignColumns: Array<AnyPgColumn>;
   }>;
+  /**
+   * Additional table constraints for data validation.
+   *
+   * Constraints enforce business rules at the database level, providing
+   * an additional layer of data integrity beyond application validation.
+   *
+   * **Constraint Types**:
+   * - **Unique constraints**: Prevent duplicate values across columns
+   * - **Check constraints**: Enforce custom validation rules with SQL expressions
+   *
+   * **Use Cases**:
+   * - Enforce unique combinations of columns
+   * - Validate value ranges or patterns
+   * - Ensure consistent data states
+   * - Implement business rule validation
+   *
+   * @example
+   * ```ts
+   * constraints: [
+   *   {
+   *     name: "unique_user_email",
+   *     columns: ["email"],
+   *     unique: true
+   *   },
+   *   {
+   *     name: "valid_age_range",
+   *     columns: ["age"],
+   *     check: sql`age >= 0 AND age <= 150`
+   *   },
+   *   {
+   *     name: "unique_user_username_per_tenant",
+   *     columns: ["tenantId", "username"],
+   *     unique: true
+   *   }
+   * ]
+   * ```
+   */
   constraints?: Array<{
+    /**
+     * Columns involved in this constraint.
+     */
     columns: Array<keyof Static$1<T>>;
+    /**
+     * Optional name for the constraint.
+     */
     name?: string;
+    /**
+     * Whether this is a unique constraint.
+     */
     unique?: boolean | {};
+    /**
+     * SQL expression for check constraint validation.
+     */
     check?: SQL;
   }>;
   /**
-   * Extra configuration for the table. See drizzle-orm documentation for more details.
+   * Advanced Drizzle ORM configuration for complex table setups.
+   *
+   * This allows you to use advanced Drizzle ORM features that aren't covered
+   * by the simplified options above. Use this for:
+   * - Custom index types (GIN, GIST, etc.)
+   * - Partial indexes with WHERE clauses
+   * - Advanced constraint configurations
+   * - PostgreSQL-specific features
+   *
+   * **When to Use**:
+   * - Need PostgreSQL-specific index types
+   * - Require partial indexes for performance
+   * - Want fine-grained control over table creation
+   * - Using advanced PostgreSQL features
    *
-   * @param self The table descriptor.
-   * @returns The extra configuration for the table.
+   * See Drizzle ORM documentation for complete configuration options.
+   *
+   * @param self - The table columns available for configuration
+   * @returns Array of Drizzle table configuration objects
+   *
+   * @example
+   * ```ts
+   * config: (table) => [
+   *   // Partial index for active users only
+   *   index("idx_active_users_email")
+   *     .on(table.email)
+   *     .where(sql`is_active = true`),
+   *
+   *   // GIN index for full-text search
+   *   index("idx_content_search")
+   *     .using("gin", table.searchVector),
+   *
+   *   // Unique constraint with custom options
+   *   uniqueIndex("idx_unique_slug_per_tenant")
+   *     .on(table.tenantId, table.slug)
+   * ]
+   * ```
    */
   config?: (self: BuildExtraConfigColumns<string, FromSchema<T>, "pg">) => PgTableExtraConfigValue[];
 }
@@ -351,21 +775,6 @@ declare class PgError extends AlephaError {
   constructor(message: string, cause?: unknown);
 }
 //#endregion
-//#region src/helpers/nullToUndefined.d.ts
-/**
- * Replaces all null values in an object with undefined.
- * We need this for converting all nulls from Drizzle outputs.
- *
- * @param value - The object to be processed.
- * @return A new object with all null values replaced with undefined.
- */
-declare const nullToUndefined: <T extends object>(value: T) => NullToUndefined<T>;
-/**
- * Replaces all null values in an object with undefined.
- */
-type NullToUndefined<T> = T extends null ? undefined : T extends null | undefined | string | number | boolean | symbol | bigint | Function | Date | RegExp ? T : T extends Array<infer U> ? Array<NullToUndefined<U>> : T extends Map<infer K, infer V> ? Map<K, NullToUndefined<V>> : T extends Set<infer U> ? Set<NullToUndefined<U>> : T extends object ? { [K in keyof T]: NullToUndefined<T[K]> } : unknown;
-type NullifyIfOptional<T> = { [K in keyof T]: undefined extends T[K] ? T[K] | null : T[K] };
-//#endregion
 //#region src/helpers/pgAttr.d.ts
 /**
  * Type representation.
@@ -734,22 +1143,6 @@ interface FilterOperators<TValue> {
   arrayOverlaps?: TValue;
 }
 //#endregion
-//#region src/interfaces/InferInsert.d.ts
-/**
- * Enhance Typebox with a support of "Default" (PG_DEFAULT).
- */
-type InferInsert<T extends TObject$1> = StaticEntry<T> & StaticDefaultEntry<T>;
-type StaticDefaultEntry<T extends TObject$1> = { [K in keyof T["properties"] as T["properties"][K] extends {
-  [PG_DEFAULT]: any;
-} | {
-  [OptionalKind]: "Optional";
-} ? K : never]?: Static$1<T["properties"][K]> };
-type StaticEntry<T extends TObject$1> = { [K in keyof T["properties"] as T["properties"][K] extends {
-  [PG_DEFAULT]: any;
-} | {
-  [OptionalKind]: "Optional";
-} ? never : K]: Static$1<T["properties"][K]> };
-//#endregion
 //#region src/interfaces/PgQueryWhere.d.ts
 type PgQueryWhereOrSQL<T extends object> = SQLWrapper | PgQueryWhere<T>;
 type PgQueryWhere<T extends object> = { [Key in keyof T]?: FilterOperators<T[Key]> | T[Key] } & {
@@ -845,10 +1238,10 @@ declare abstract class PostgresProvider {
 }
 //#endregion
 //#region src/schemas/pageQuerySchema.d.ts
-declare const pageQuerySchema: _sinclair_typebox1.TObject<{
-  page: _sinclair_typebox1.TOptional<_sinclair_typebox1.TNumber>;
-  size: _sinclair_typebox1.TOptional<_sinclair_typebox1.TNumber>;
-  sort: _sinclair_typebox1.TOptional<_sinclair_typebox1.TString>;
+declare const pageQuerySchema: _sinclair_typebox0.TObject<{
+  page: _sinclair_typebox0.TOptional<_sinclair_typebox0.TNumber>;
+  size: _sinclair_typebox0.TOptional<_sinclair_typebox0.TNumber>;
+  sort: _sinclair_typebox0.TOptional<_sinclair_typebox0.TString>;
 }>;
 type PageQuery = Static<typeof pageQuerySchema>;
 //#endregion
@@ -870,8 +1263,6 @@ type TPage<T extends TObject$1 | TIntersect | TRecord> = TObject$1<{
     number: TInteger;
     size: TInteger;
     totalElements: TOptionalWithFlag<TInteger, true>;
-    queryDuration: TOptionalWithFlag<TInteger, true>;
-    countDuration: TOptionalWithFlag<TInteger, true>;
   }>;
 }>;
 type Page<T> = {
@@ -884,13 +1275,321 @@ type Page<T> = {
     number: number;
     size: number;
     totalElements?: number;
-    queryDuration?: number;
-    countDuration?: number;
   };
 };
 //#endregion
 //#region src/descriptors/$repository.d.ts
 /**
+ * Creates a repository descriptor for database operations on a defined entity.
+ *
+ * This descriptor provides a comprehensive, type-safe interface for performing all
+ * database operations on entities defined with $entity. It offers a rich set of
+ * CRUD operations, advanced querying capabilities, pagination, transactions, and
+ * built-in support for audit trails and soft deletes.
+ *
+ * **Key Features**
+ *
+ * - **Complete CRUD Operations**: Create, read, update, delete with full type safety
+ * - **Advanced Querying**: Complex WHERE conditions, sorting, pagination, and aggregations
+ * - **Transaction Support**: Database transactions for consistency and atomicity
+ * - **Soft Delete Support**: Built-in soft delete functionality with `pg.deletedAt()` fields
+ * - **Optimistic Locking**: Version-based conflict resolution with `pg.version()` fields
+ * - **Audit Trail Integration**: Automatic handling of `createdAt`, `updatedAt` timestamps
+ * - **Raw SQL Support**: Execute custom SQL queries when needed
+ * - **Pagination**: Built-in pagination with metadata and navigation
+ *
+ * **Important Requirements**
+ * - Must be used with an entity created by $entity
+ * - Entity schema must include exactly one primary key field
+ * - Database tables must be created via migrations before use
+ *
+ * **Use Cases**
+ *
+ * Essential for all database-driven applications:
+ * - User management and authentication systems
+ * - E-commerce product and order management
+ * - Content management and blogging platforms
+ * - Financial and accounting applications
+ * - Any application requiring persistent data storage
+ *
+ * @example
+ * **Basic repository with CRUD operations:**
+ * ```ts
+ * import { $entity, $repository } from "alepha/postgres";
+ * import { pg, t } from "alepha";
+ *
+ * // First, define the entity
+ * const User = $entity({
+ *   name: "users",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     email: t.string({ format: "email" }),
+ *     firstName: t.string(),
+ *     lastName: t.string(),
+ *     isActive: t.boolean({ default: true }),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt()
+ *   }),
+ *   indexes: [{ column: "email", unique: true }]
+ * });
+ *
+ * class UserService {
+ *   users = $repository({ table: User });
+ *
+ *   async createUser(userData: { email: string; firstName: string; lastName: string }) {
+ *     return await this.users.create({
+ *       id: generateUUID(),
+ *       email: userData.email,
+ *       firstName: userData.firstName,
+ *       lastName: userData.lastName,
+ *       isActive: true
+ *     });
+ *   }
+ *
+ *   async getUserByEmail(email: string) {
+ *     return await this.users.findOne({ email });
+ *   }
+ *
+ *   async updateUser(id: string, updates: { firstName?: string; lastName?: string }) {
+ *     return await this.users.updateById(id, updates);
+ *   }
+ *
+ *   async deactivateUser(id: string) {
+ *     return await this.users.updateById(id, { isActive: false });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Advanced querying and filtering:**
+ * ```ts
+ * const Product = $entity({
+ *   name: "products",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     name: t.string(),
+ *     price: t.number({ minimum: 0 }),
+ *     categoryId: t.string({ format: "uuid" }),
+ *     inStock: t.boolean(),
+ *     tags: t.optional(t.array(t.string())),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt()
+ *   }),
+ *   indexes: ["categoryId", "inStock", "price"]
+ * });
+ *
+ * class ProductService {
+ *   products = $repository({ table: Product });
+ *
+ *   async searchProducts(filters: {
+ *     categoryId?: string;
+ *     minPrice?: number;
+ *     maxPrice?: number;
+ *     inStock?: boolean;
+ *     searchTerm?: string;
+ *   }, page: number = 0, size: number = 20) {
+ *     const query = this.products.createQuery({
+ *       where: {
+ *         and: [
+ *           filters.categoryId ? { categoryId: filters.categoryId } : {},
+ *           filters.inStock !== undefined ? { inStock: filters.inStock } : {},
+ *           filters.minPrice ? { price: { gte: filters.minPrice } } : {},
+ *           filters.maxPrice ? { price: { lte: filters.maxPrice } } : {},
+ *           filters.searchTerm ? { name: { ilike: `%${filters.searchTerm}%` } } : {}
+ *         ]
+ *       },
+ *       sort: { createdAt: "desc" }
+ *     });
+ *
+ *     return await this.products.paginate({ page, size }, query, { count: true });
+ *   }
+ *
+ *   async getTopSellingProducts(limit: number = 10) {
+ *     // Custom SQL query for complex analytics
+ *     return await this.products.query(
+ *       (table, db) => db
+ *         .select({
+ *           id: table.id,
+ *           name: table.name,
+ *           price: table.price,
+ *           salesCount: sql<number>`COALESCE(sales.count, 0)`
+ *         })
+ *         .from(table)
+ *         .leftJoin(
+ *           sql`(
+ *             SELECT product_id, COUNT(*) as count
+ *             FROM order_items
+ *             WHERE created_at > NOW() - INTERVAL '30 days'
+ *             GROUP BY product_id
+ *           ) sales`,
+ *           sql`sales.product_id = ${table.id}`
+ *         )
+ *         .orderBy(sql`sales.count DESC NULLS LAST`)
+ *         .limit(limit)
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Transaction handling and data consistency:**
+ * ```ts
+ * class OrderService {
+ *   orders = $repository({ table: Order });
+ *   orderItems = $repository({ table: OrderItem });
+ *   products = $repository({ table: Product });
+ *
+ *   async createOrderWithItems(orderData: {
+ *     customerId: string;
+ *     items: Array<{ productId: string; quantity: number; price: number }>;
+ *   }) {
+ *     return await this.orders.transaction(async (tx) => {
+ *       // Create the order
+ *       const order = await this.orders.create({
+ *         id: generateUUID(),
+ *         customerId: orderData.customerId,
+ *         status: 'pending',
+ *         totalAmount: orderData.items.reduce((sum, item) => sum + (item.price * item.quantity), 0)
+ *       }, { tx });
+ *
+ *       // Create order items and update product inventory
+ *       for (const itemData of orderData.items) {
+ *         await this.orderItems.create({
+ *           id: generateUUID(),
+ *           orderId: order.id,
+ *           productId: itemData.productId,
+ *           quantity: itemData.quantity,
+ *           unitPrice: itemData.price
+ *         }, { tx });
+ *
+ *         // Update product inventory using optimistic locking
+ *         const product = await this.products.findById(itemData.productId, { tx });
+ *         if (product.stockQuantity < itemData.quantity) {
+ *           throw new Error(`Insufficient stock for product ${itemData.productId}`);
+ *         }
+ *
+ *         await this.products.save({
+ *           ...product,
+ *           stockQuantity: product.stockQuantity - itemData.quantity
+ *         }, { tx });
+ *       }
+ *
+ *       return order;
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Soft delete and audit trail:**
+ * ```ts
+ * const Document = $entity({
+ *   name: "documents",
+ *   schema: t.object({
+ *     id: pg.primaryKey(t.uuid()),
+ *     title: t.string(),
+ *     content: t.string(),
+ *     authorId: t.string({ format: "uuid" }),
+ *     version: pg.version(),
+ *     createdAt: pg.createdAt(),
+ *     updatedAt: pg.updatedAt(),
+ *     deletedAt: pg.deletedAt()  // Enables soft delete
+ *   })
+ * });
+ *
+ * class DocumentService {
+ *   documents = $repository({ table: Document });
+ *
+ *   async updateDocument(id: string, updates: { title?: string; content?: string }) {
+ *     // This uses optimistic locking via the version field
+ *     const document = await this.documents.findById(id);
+ *     return await this.documents.save({
+ *       ...document,
+ *       ...updates  // updatedAt will be set automatically
+ *     });
+ *   }
+ *
+ *   async softDeleteDocument(id: string) {
+ *     // Soft delete - sets deletedAt timestamp
+ *     await this.documents.deleteById(id);
+ *   }
+ *
+ *   async permanentDeleteDocument(id: string) {
+ *     // Hard delete - actually removes from database
+ *     await this.documents.deleteById(id, { force: true });
+ *   }
+ *
+ *   async getActiveDocuments() {
+ *     // Automatically excludes soft-deleted records
+ *     return await this.documents.find({
+ *       where: { authorId: { isNotNull: true } },
+ *       sort: { updatedAt: "desc" }
+ *     });
+ *   }
+ *
+ *   async getAllDocumentsIncludingDeleted() {
+ *     // Include soft-deleted records
+ *     return await this.documents.find({}, { force: true });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Complex filtering and aggregation:**
+ * ```ts
+ * class AnalyticsService {
+ *   users = $repository({ table: User });
+ *   orders = $repository({ table: Order });
+ *
+ *   async getUserStatistics(filters: {
+ *     startDate?: string;
+ *     endDate?: string;
+ *     isActive?: boolean;
+ *   }) {
+ *     const whereConditions = [];
+ *
+ *     if (filters.startDate) {
+ *       whereConditions.push({ createdAt: { gte: filters.startDate } });
+ *     }
+ *     if (filters.endDate) {
+ *       whereConditions.push({ createdAt: { lte: filters.endDate } });
+ *     }
+ *     if (filters.isActive !== undefined) {
+ *       whereConditions.push({ isActive: filters.isActive });
+ *     }
+ *
+ *     const totalUsers = await this.users.count({
+ *       and: whereConditions
+ *     });
+ *
+ *     const activeUsers = await this.users.count({
+ *       and: [...whereConditions, { isActive: true }]
+ *     });
+ *
+ *     // Complex aggregation query
+ *     const recentActivity = await this.users.query(
+ *       sql`
+ *         SELECT
+ *           DATE_TRUNC('day', created_at) as date,
+ *           COUNT(*) as new_users,
+ *           COUNT(*) FILTER (WHERE is_active = true) as active_users
+ *         FROM users
+ *         WHERE created_at >= NOW() - INTERVAL '30 days'
+ *         GROUP BY DATE_TRUNC('day', created_at)
+ *         ORDER BY date DESC
+ *       `
+ *     );
+ *
+ *     return {
+ *       totalUsers,
+ *       activeUsers,
+ *       inactiveUsers: totalUsers - activeUsers,
+ *       recentActivity
+ *     };
+ *   }
+ * }
+ * ```
+ *
  * @stability 3
  */
 declare const $repository: {
@@ -899,11 +1598,61 @@ declare const $repository: {
 };
 interface RepositoryDescriptorOptions<EntityTableConfig extends TableConfig, EntitySchema extends TObject$1> {
   /**
-   * The table to create the repository for.
+   * The entity table definition created with $entity.
+   *
+   * This table:
+   * - Must be created using the $entity descriptor
+   * - Defines the schema, indexes, and constraints for the repository
+   * - Provides type information for all repository operations
+   * - Must include exactly one primary key field
+   *
+   * The repository will automatically:
+   * - Generate typed CRUD operations based on the entity schema
+   * - Handle audit fields like createdAt, updatedAt, deletedAt
+   * - Support optimistic locking if version field is present
+   * - Provide soft delete functionality if deletedAt field exists
+   *
+   * **Entity Requirements**:
+   * - Must have been created with $entity descriptor
+   * - Schema must include a primary key field marked with `pg.primaryKey()`
+   * - Corresponding database table must exist (created via migrations)
+   *
+   * @example
+   * ```ts
+   * const User = $entity({
+   *   name: "users",
+   *   schema: t.object({
+   *     id: pg.primaryKey(t.uuid()),
+   *     email: t.string({ format: "email" }),
+   *     name: t.string()
+   *   })
+   * });
+   *
+   * const userRepository = $repository({ table: User });
+   * ```
    */
   table: PgTableWithColumnsAndSchema<EntityTableConfig, EntitySchema>;
   /**
-   * Override default provider.
+   * Override the default PostgreSQL database provider.
+   *
+   * By default, the repository will use the injected PostgresProvider from the
+   * dependency injection container. Use this option to:
+   * - Connect to a different database
+   * - Use a specific connection pool
+   * - Implement custom database behavior
+   * - Support multi-tenant architectures with database per tenant
+   *
+   * **Common Use Cases**:
+   * - Multi-database applications
+   * - Read replicas for query optimization
+   * - Different databases for different entity types
+   * - Testing with separate test databases
+   *
+   * @default Uses injected PostgresProvider
+   *
+   * @example ReadOnlyPostgresProvider
+   * @example TenantSpecificPostgresProvider
+   * @example TestDatabaseProvider
    */
   provider?: Service<PostgresProvider>;
 }
@@ -912,7 +1661,7 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
   readonly provider: PostgresProvider;
   protected readonly alepha: Alepha;
   readonly schema: EntitySchema;
-  readonly schemaInsert: TInsertObject<EntitySchema>;
+  readonly schemaInsert: TObjectInsert<EntitySchema>;
   /**
    * Represents the primary key of the table.
    * - Key is the name of the primary key column.
@@ -936,11 +1685,12 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
   /**
    * Getter for the database connection from the database provider.
    */
-  protected get db(): PgDatabase<any, Record<string, never>, drizzle_orm7.ExtractTablesWithRelations<Record<string, never>>>;
+  protected get db(): PgDatabase<any, Record<string, never>, drizzle_orm6.ExtractTablesWithRelations<Record<string, never>>>;
   /**
    * Execute a SQL query.
    */
   query<T extends TObject$1 = EntitySchema>(query: SQLLike | ((table: PgTableWithColumns<EntityTableConfig>, db: PgDatabase<any>) => SQLLike), schema?: T): Promise<Static$1<T>[]>;
+  protected mapRawFieldsToEntity(row: any[]): any;
   /**
    * Get a Drizzle column from the table by his name.
    *
@@ -960,10 +1710,10 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    *
    * @returns The SELECT query builder.
    */
-  protected select(opts?: StatementOptions): pg$1.PgSelectBase<string, Record<string, PgColumn<drizzle_orm7.ColumnBaseConfig<drizzle_orm7.ColumnDataType, string>, {}, {}>>, "single", Record<string, "not-null">, false, never, {
+  protected select(opts?: StatementOptions): pg$1.PgSelectBase<string, Record<string, PgColumn<drizzle_orm6.ColumnBaseConfig<drizzle_orm6.ColumnDataType, string>, {}, {}>>, "single", Record<string, "not-null">, false, never, {
     [x: string]: unknown;
   }[], {
-    [x: string]: PgColumn<drizzle_orm7.ColumnBaseConfig<drizzle_orm7.ColumnDataType, string>, {}, {}>;
+    [x: string]: PgColumn<drizzle_orm6.ColumnBaseConfig<drizzle_orm6.ColumnDataType, string>, {}, {}>;
   }>;
   protected selectDistinct(opts: StatementOptions | undefined, fields: SelectedFields): pg$1.PgSelectBase<string, SelectedFields, "partial", Record<string, "not-null">, false, never, {
     [x: string]: unknown;
@@ -1012,7 +1762,7 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    * Paginate entities.
    */
   paginate(pagination?: PageQuery, query?: PgQuery<EntitySchema>, opts?: StatementOptions & {
-    skipCount?: boolean;
+    count?: boolean;
   }): Promise<Page<Static$1<EntitySchema>>>;
   createQuery(query?: PgQuery<EntitySchema>): PgQuery<EntitySchema>;
   createQueryWhere(where?: PgQueryWhere<Static$1<EntitySchema>>): PgQueryWhere<Static$1<EntitySchema>>;
@@ -1023,7 +1773,7 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    * @param opts The options for creating the entity.
    * @returns The ID of the created entity.
    */
-  create(data: InferInsert<EntitySchema>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
+  create(data: StaticInsert<EntitySchema>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
   /**
    * Create many entities.
    *
@@ -1031,26 +1781,28 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    * @param opts The statement options.
    * @returns The created entities.
    */
-  createMany(values: Array<InferInsert<EntitySchema>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>[]>;
+  createMany(values: Array<StaticInsert<EntitySchema>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>[]>;
   /**
    * Find an entity and update it.
    */
-  updateOne(where: PgQueryWhereOrSQL<Static$1<EntitySchema>>, data: Partial<NullifyIfOptional<Static$1<EntitySchema>>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
+  updateOne(where: PgQueryWhereOrSQL<Static$1<EntitySchema>>, data: Partial<Static$1<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
   /**
    * Save a given entity.
    *
    * @example
    * ```ts
    * const entity = await repository.findById(1);
-   * entity.name = "New Name";
+   * entity.name = "New Name"; // update a field
+   * delete entity.description; // delete a field
    * await repository.save(entity);
    * ```
    *
    * Difference with `updateById/updateOne`:
    *
-   * - requires the entity to be fetched first
-   * - check pg.version() if present - optimistic locking
+   * - requires the entity to be fetched first (whole object is expected)
+   * - check pg.version() if present -> optimistic locking
    * - validate entity against schema
+   * - undefined values will be set to null, not ignored!
    *
    * @see {@link PostgresTypeProvider#version}
    * @see {@link PgVersionMismatchError}
@@ -1059,11 +1811,11 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
   /**
    * Find an entity by ID and update it.
    */
-  updateById(id: string | number, data: Partial<NullifyIfOptional<Static$1<EntitySchema>>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
+  updateById(id: string | number, data: Partial<Static$1<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<Static$1<EntitySchema>>;
   /**
    * Find many entities and update all of them.
    */
-  updateMany(where: PgQueryWhereOrSQL<Static$1<EntitySchema>>, data: Partial<NullifyIfOptional<Static$1<EntitySchema>>>, opts?: StatementOptions): Promise<void>;
+  updateMany(where: PgQueryWhereOrSQL<Static$1<EntitySchema>>, data: Partial<Static$1<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<void>;
   /**
    * Find many and delete all of them.
    */
@@ -1150,7 +1902,7 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    */
   protected getPrimaryKey(schema: TObject$1): {
     key: string;
-    col: PgColumn<drizzle_orm7.ColumnBaseConfig<drizzle_orm7.ColumnDataType, string>, {}, {}>;
+    col: PgColumn<drizzle_orm6.ColumnBaseConfig<drizzle_orm6.ColumnDataType, string>, {}, {}>;
     type: TSchema$2;
   };
 }
@@ -1173,10 +1925,238 @@ interface StatementOptions {
    * If true, ignore soft delete.
    */
   force?: boolean;
+  /**
+   * Force the current time.
+   */
+  now?: DateTime;
 }
 //#endregion
 //#region src/descriptors/$sequence.d.ts
 /**
+ * Creates a PostgreSQL sequence descriptor for generating unique numeric values.
+ *
+ * This descriptor provides a type-safe interface to PostgreSQL sequences, which are
+ * database objects that generate unique numeric identifiers. Sequences are commonly
+ * used for primary keys, order numbers, invoice numbers, and other cases where
+ * guaranteed unique, incrementing values are needed across concurrent operations.
+ *
+ * **Key Features**
+ *
+ * - **Thread-Safe**: PostgreSQL sequences are inherently thread-safe and handle concurrency
+ * - **Configurable Parameters**: Start value, increment, min/max bounds, and cycling behavior
+ * - **Automatic Creation**: Sequences are created automatically when first used
+ * - **Type Safety**: Full TypeScript support with numeric return types
+ * - **Performance**: Optimized for high-throughput ID generation
+ * - **Schema Support**: Works with PostgreSQL schemas for organization
+ *
+ * **Use Cases**
+ *
+ * Perfect for generating unique identifiers in concurrent environments:
+ * - Primary key generation (alternative to UUIDs)
+ * - Order numbers and invoice sequences
+ * - Ticket numbers and reference IDs
+ * - Version numbers and revision tracking
+ * - Batch numbers for processing workflows
+ * - Any scenario requiring guaranteed unique incrementing numbers
+ *
+ * @example
+ * **Basic sequence for order numbers:**
+ * ```ts
+ * import { $sequence } from "alepha/postgres";
+ *
+ * class OrderService {
+ *   orderNumbers = $sequence({
+ *     name: "order_numbers",
+ *     start: 1000,      // Start from order #1000
+ *     increment: 1      // Increment by 1 each time
+ *   });
+ *
+ *   async createOrder(orderData: OrderData) {
+ *     const orderNumber = await this.orderNumbers.next();
+ *
+ *     return await this.orders.create({
+ *       id: generateUUID(),
+ *       orderNumber,
+ *       ...orderData
+ *     });
+ *   }
+ *
+ *   async getCurrentOrderNumber() {
+ *     // Get the last generated number without incrementing
+ *     return await this.orderNumbers.current();
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Invoice numbering with yearly reset:**
+ * ```ts
+ * class InvoiceService {
+ *   // Separate sequence for each year
+ *   getInvoiceSequence(year: number) {
+ *     return $sequence({
+ *       name: `invoice_numbers_${year}`,
+ *       start: 1,
+ *       increment: 1
+ *     });
+ *   }
+ *
+ *   async generateInvoiceNumber(): Promise<string> {
+ *     const year = new Date().getFullYear();
+ *     const sequence = this.getInvoiceSequence(year);
+ *     const number = await sequence.next();
+ *
+ *     // Format as INV-2024-001, INV-2024-002, etc.
+ *     return `INV-${year}-${number.toString().padStart(3, '0')}`;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **High-performance ID generation with custom increments:**
+ * ```ts
+ * class TicketService {
+ *   // Generate ticket numbers in increments of 10 for better distribution
+ *   ticketSequence = $sequence({
+ *     name: "ticket_numbers",
+ *     start: 1000,
+ *     increment: 10,
+ *     min: 1000,
+ *     max: 999999,
+ *     cycle: false  // Don't cycle when max is reached
+ *   });
+ *
+ *   priorityTicketSequence = $sequence({
+ *     name: "priority_ticket_numbers",
+ *     start: 1,
+ *     increment: 1,
+ *     min: 1,
+ *     max: 999,
+ *     cycle: true   // Cycle when reaching max
+ *   });
+ *
+ *   async generateTicketNumber(isPriority: boolean = false): Promise<number> {
+ *     if (isPriority) {
+ *       return await this.priorityTicketSequence.next();
+ *     }
+ *     return await this.ticketSequence.next();
+ *   }
+ *
+ *   async getSequenceStatus() {
+ *     return {
+ *       currentTicketNumber: await this.ticketSequence.current(),
+ *       currentPriorityNumber: await this.priorityTicketSequence.current()
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Batch processing with sequence-based coordination:**
+ * ```ts
+ * class BatchProcessor {
+ *   batchSequence = $sequence({
+ *     name: "batch_numbers",
+ *     start: 1,
+ *     increment: 1
+ *   });
+ *
+ *   async processBatch(items: any[]) {
+ *     const batchNumber = await this.batchSequence.next();
+ *
+ *     console.log(`Starting batch processing #${batchNumber} with ${items.length} items`);
+ *
+ *     try {
+ *       // Process items with batch number for tracking
+ *       for (const item of items) {
+ *         await this.processItem(item, batchNumber);
+ *       }
+ *
+ *       await this.auditLogger.log({
+ *         event: 'batch_completed',
+ *         batchNumber,
+ *         itemCount: items.length,
+ *         timestamp: new Date()
+ *       });
+ *
+ *       return { batchNumber, processedCount: items.length };
+ *
+ *     } catch (error) {
+ *       await this.auditLogger.log({
+ *         event: 'batch_failed',
+ *         batchNumber,
+ *         error: error.message,
+ *         timestamp: new Date()
+ *       });
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   async processItem(item: any, batchNumber: number) {
+ *     // Associate item processing with batch number
+ *     await this.items.update(item.id, {
+ *       ...item.updates,
+ *       batchNumber,
+ *       processedAt: new Date()
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **Multi-tenant sequence management:**
+ * ```ts
+ * class TenantSequenceService {
+ *   // Create tenant-specific sequences
+ *   getTenantSequence(tenantId: string, sequenceType: string) {
+ *     return $sequence({
+ *       name: `${tenantId}_${sequenceType}_seq`,
+ *       start: 1,
+ *       increment: 1
+ *     });
+ *   }
+ *
+ *   async generateTenantOrderNumber(tenantId: string): Promise<string> {
+ *     const sequence = this.getTenantSequence(tenantId, 'orders');
+ *     const number = await sequence.next();
+ *
+ *     return `${tenantId.toUpperCase()}-ORD-${number.toString().padStart(6, '0')}`;
+ *   }
+ *
+ *   async generateTenantInvoiceNumber(tenantId: string): Promise<string> {
+ *     const sequence = this.getTenantSequence(tenantId, 'invoices');
+ *     const number = await sequence.next();
+ *
+ *     return `${tenantId.toUpperCase()}-INV-${number.toString().padStart(6, '0')}`;
+ *   }
+ *
+ *   async getTenantSequenceStatus(tenantId: string) {
+ *     const orderSeq = this.getTenantSequence(tenantId, 'orders');
+ *     const invoiceSeq = this.getTenantSequence(tenantId, 'invoices');
+ *
+ *     return {
+ *       tenant: tenantId,
+ *       sequences: {
+ *         orders: {
+ *           current: await orderSeq.current(),
+ *           next: await orderSeq.next()
+ *         },
+ *         invoices: {
+ *           current: await invoiceSeq.current()
+ *         }
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * **Important Notes**:
+ * - Sequences are created automatically when first used
+ * - PostgreSQL sequences are atomic and handle high concurrency
+ * - Sequence values are not rolled back in failed transactions
+ * - Consider the impact of max values and cycling behavior
+ * - Sequences are schema-scoped in PostgreSQL
+ *
  * @stability 1
  */
 declare const $sequence: {
@@ -1184,11 +2164,130 @@ declare const $sequence: {
   [KIND]: typeof SequenceDescriptor;
 };
 interface SequenceDescriptorOptions {
+  /**
+   * Name of the PostgreSQL sequence to create.
+   *
+   * This name:
+   * - Must be unique within the database schema
+   * - Should follow PostgreSQL identifier conventions
+   * - Will be used in generated SQL for sequence operations
+   * - Should be descriptive of the sequence's purpose
+   *
+   * If not provided, defaults to the property key where the sequence is declared.
+   *
+   * **Naming Guidelines**:
+   * - Use descriptive names like "order_numbers", "invoice_seq"
+   * - Include the purpose or entity type in the name
+   * - Consider adding "_seq" suffix for clarity
+   * - Use snake_case for consistency with PostgreSQL conventions
+   *
+   * @example "order_numbers"
+   * @example "invoice_sequence"
+   * @example "ticket_numbers_seq"
+   */
   name?: string;
+  /**
+   * The starting value for the sequence.
+   *
+   * This value:
+   * - Determines the first number that will be generated
+   * - Can be any integer within the sequence's range
+   * - Is useful for avoiding conflicts with existing data
+   * - Can be set higher for business reasons (e.g., starting invoices at 1000)
+   *
+   * **Common Patterns**:
+   * - Start at 1 for simple counters
+   * - Start at 1000+ for professional-looking numbers
+   * - Start at current max + 1 when migrating existing data
+   *
+   * @default 1
+   * @example 1     // Simple counter starting at 1
+   * @example 1000  // Professional numbering starting at 1000
+   * @example 10000 // Large starting number for established businesses
+   */
   start?: number;
+  /**
+   * The increment value for each call to next().
+   *
+   * This value:
+   * - Determines how much the sequence increases each time
+   * - Can be any positive or negative integer
+   * - Affects the gaps between generated numbers
+   * - Can be used for number distribution strategies
+   *
+   * **Use Cases**:
+   * - increment: 1 for consecutive numbering
+   * - increment: 10 for distributed numbering (leaves gaps for manual entries)
+   * - increment: -1 for countdown sequences
+   *
+   * @default 1
+   * @example 1   // Standard consecutive numbering
+   * @example 10  // Leave gaps between numbers
+   * @example 100 // Large gaps for special numbering schemes
+   */
   increment?: number;
+  /**
+   * The minimum value the sequence can generate.
+   *
+   * When the sequence reaches this value:
+   * - It cannot generate values below this minimum
+   * - Helps prevent negative numbers in contexts where they don't make sense
+   * - Works with cycling behavior to define the lower bound
+   *
+   * **Considerations**:
+   * - Set to 1 for positive-only sequences
+   * - Set to 0 if zero values are acceptable
+   * - Consider business rules about minimum valid numbers
+   *
+   * @example 1     // No zero or negative values
+   * @example 0     // Allow zero values
+   * @example 1000  // Maintain minimum professional appearance
+   */
   min?: number;
+  /**
+   * The maximum value the sequence can generate.
+   *
+   * When the sequence reaches this value:
+   * - It cannot generate values above this maximum
+   * - Behavior depends on the cycle option
+   * - Useful for preventing overflow or limiting number ranges
+   *
+   * **Planning Considerations**:
+   * - Consider the expected volume of your application
+   * - Account for business growth over time
+   * - Factor in any formatting constraints (e.g., fixed-width displays)
+   * - Remember that PostgreSQL sequences can handle very large numbers
+   *
+   * @example 999999    // Six-digit limit
+   * @example 2147483647 // Maximum 32-bit signed integer
+   * @example 9999      // Four-digit limit for display purposes
+   */
   max?: number;
+  /**
+   * Whether the sequence should cycle back to the minimum when it reaches the maximum.
+   *
+   * **cycle: true**:
+   * - When max is reached, next value will be the minimum value
+   * - Useful for scenarios where number reuse is acceptable
+   * - Common for temporary identifiers or rotating references
+   *
+   * **cycle: false (default)**:
+   * - When max is reached, further calls will fail with an error
+   * - Prevents unexpected number reuse
+   * - Better for permanent identifiers where uniqueness is critical
+   *
+   * **Use Cases for Cycling**:
+   * - Temporary ticket numbers that can be reused
+   * - Session IDs with limited lifetime
+   * - Batch numbers in rotating systems
+   *
+   * **Avoid Cycling For**:
+   * - Primary keys and permanent identifiers
+   * - Invoice numbers and financial references
+   * - Audit logs and compliance records
+   *
+   * @default false
+   */
   cycle?: boolean;
 }
 declare class SequenceDescriptor extends Descriptor<SequenceDescriptorOptions> {
@@ -1202,11 +2301,482 @@ declare class SequenceDescriptor extends Descriptor<SequenceDescriptorOptions> {
 //#endregion
 //#region src/descriptors/$transaction.d.ts
 /**
+ * Creates a transaction descriptor for database operations requiring atomicity and consistency.
+ *
+ * This descriptor provides a convenient way to wrap database operations in PostgreSQL
+ * transactions, ensuring ACID properties and automatic retry logic for version conflicts.
+ * It integrates seamlessly with the repository pattern and provides built-in handling
+ * for optimistic locking scenarios with automatic retry on version mismatches.
+ *
+ * **Key Features**
+ *
+ * - **ACID Compliance**: Full transaction support with commit/rollback functionality
+ * - **Automatic Retry Logic**: Built-in retry for optimistic locking conflicts
+ * - **Type Safety**: Full TypeScript support with generic parameters
+ * - **Isolation Levels**: Configurable transaction isolation levels
+ * - **Error Handling**: Automatic rollback on errors with proper error propagation
+ * - **Repository Integration**: Seamless integration with $repository operations
+ * - **Performance**: Efficient transaction management with connection reuse
+ *
+ * **Use Cases**
+ *
+ * Essential for operations requiring atomicity and consistency:
+ * - Financial transactions and accounting operations
+ * - Complex business workflows with multiple database operations
+ * - Data migrations and bulk operations
+ * - E-commerce order processing with inventory updates
+ * - User registration with related data creation
+ * - Audit trail creation with business operations
+ *
+ * @example
+ * **Basic transaction for financial operations:**
+ * ```ts
+ * import { $transaction } from "alepha/postgres";
+ *
+ * class BankingService {
+ *   transfer = $transaction({
+ *     handler: async (tx, fromAccountId: string, toAccountId: string, amount: number) => {
+ *       // All operations within this transaction are atomic
+ *       console.log(`Processing transfer: $${amount} from ${fromAccountId} to ${toAccountId}`);
+ *
+ *       // Get current account balances
+ *       const fromAccount = await this.accounts.findById(fromAccountId, { tx });
+ *       const toAccount = await this.accounts.findById(toAccountId, { tx });
+ *
+ *       // Validate sufficient balance
+ *       if (fromAccount.balance < amount) {
+ *         throw new Error(`Insufficient funds. Balance: $${fromAccount.balance}, Required: $${amount}`);
+ *       }
+ *
+ *       // Update account balances atomically
+ *       const updatedFromAccount = await this.accounts.updateById(
+ *         fromAccountId,
+ *         { balance: fromAccount.balance - amount },
+ *         { tx }
+ *       );
+ *
+ *       const updatedToAccount = await this.accounts.updateById(
+ *         toAccountId,
+ *         { balance: toAccount.balance + amount },
+ *         { tx }
+ *       );
+ *
+ *       // Create transaction record
+ *       const transactionRecord = await this.transactions.create({
+ *         id: generateUUID(),
+ *         fromAccountId,
+ *         toAccountId,
+ *         amount,
+ *         type: 'transfer',
+ *         status: 'completed',
+ *         processedAt: new Date().toISOString()
+ *       }, { tx });
+ *
+ *       console.log(`Transfer completed successfully: ${transactionRecord.id}`);
+ *
+ *       return {
+ *         transactionId: transactionRecord.id,
+ *         fromBalance: updatedFromAccount.balance,
+ *         toBalance: updatedToAccount.balance
+ *       };
+ *     }
+ *   });
+ *
+ *   async transferFunds(fromAccountId: string, toAccountId: string, amount: number) {
+ *     // This will automatically retry if there's a version mismatch (optimistic locking)
+ *     return await this.transfer.run(fromAccountId, toAccountId, amount);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * **E-commerce order processing with inventory management:**
+ * ```ts
+ * class OrderService {
+ *   processOrder = $transaction({
+ *     config: {
+ *       isolationLevel: 'serializable'  // Highest isolation for critical operations
+ *     },
+ *     handler: async (tx, orderData: {
+ *       customerId: string;
+ *       items: Array<{ productId: string; quantity: number; price: number }>;
+ *       shippingAddress: Address;
+ *       paymentMethodId: string;
+ *     }) => {
+ *       console.log(`Processing order for customer ${orderData.customerId}`);
+ *
+ *       let totalAmount = 0;
+ *       const orderItems = [];
+ *
+ *       // Process each item and update inventory atomically
+ *       for (const itemData of orderData.items) {
+ *         const product = await this.products.findById(itemData.productId, { tx });
+ *
+ *         // Check inventory availability
+ *         if (product.stockQuantity < itemData.quantity) {
+ *           throw new Error(`Insufficient stock for ${product.name}. Available: ${product.stockQuantity}, Requested: ${itemData.quantity}`);
+ *         }
+ *
+ *         // Update product inventory with optimistic locking
+ *         await this.products.save({
+ *           ...product,
+ *           stockQuantity: product.stockQuantity - itemData.quantity
+ *         }, { tx });
+ *
+ *         // Calculate totals
+ *         const lineTotal = itemData.price * itemData.quantity;
+ *         totalAmount += lineTotal;
+ *
+ *         orderItems.push({
+ *           id: generateUUID(),
+ *           productId: itemData.productId,
+ *           quantity: itemData.quantity,
+ *           unitPrice: itemData.price,
+ *           lineTotal
+ *         });
+ *       }
+ *
+ *       // Create the main order record
+ *       const order = await this.orders.create({
+ *         id: generateUUID(),
+ *         customerId: orderData.customerId,
+ *         status: 'pending',
+ *         totalAmount,
+ *         shippingAddress: orderData.shippingAddress,
+ *         createdAt: new Date().toISOString()
+ *       }, { tx });
+ *
+ *       // Create order items
+ *       for (const itemData of orderItems) {
+ *         await this.orderItems.create({
+ *           ...itemData,
+ *           orderId: order.id
+ *         }, { tx });
+ *       }
+ *
+ *       // Process payment
+ *       const paymentResult = await this.paymentService.processPayment({
+ *         orderId: order.id,
+ *         amount: totalAmount,
+ *         paymentMethodId: orderData.paymentMethodId,
+ *         customerId: orderData.customerId
+ *       }, { tx });
+ *
+ *       if (!paymentResult.success) {
+ *         throw new Error(`Payment failed: ${paymentResult.error}`);
+ *       }
+ *
+ *       // Update order status
+ *       const completedOrder = await this.orders.updateById(
+ *         order.id,
+ *         {
+ *           status: 'paid',
+ *           paymentId: paymentResult.paymentId,
+ *           paidAt: new Date().toISOString()
+ *         },
+ *         { tx }
+ *       );
+ *
+ *       console.log(`Order processed successfully: ${order.id}`);
+ *
+ *       return {
+ *         orderId: order.id,
+ *         totalAmount,
+ *         paymentId: paymentResult.paymentId,
+ *         itemCount: orderItems.length
+ *       };
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **User registration with related data creation:**
+ * ```ts
+ * class UserService {
+ *   registerUser = $transaction({
+ *     handler: async (tx, registrationData: {
+ *       email: string;
+ *       password: string;
+ *       profile: {
+ *         firstName: string;
+ *         lastName: string;
+ *         dateOfBirth: string;
+ *       };
+ *       preferences: {
+ *         notifications: boolean;
+ *         newsletter: boolean;
+ *       };
+ *     }) => {
+ *       console.log(`Registering new user: ${registrationData.email}`);
+ *
+ *       // Check if email already exists
+ *       const existingUser = await this.users.find(
+ *         { where: { email: registrationData.email } },
+ *         { tx }
+ *       );
+ *
+ *       if (existingUser.length > 0) {
+ *         throw new Error(`User with email ${registrationData.email} already exists`);
+ *       }
+ *
+ *       // Hash password
+ *       const hashedPassword = await this.hashPassword(registrationData.password);
+ *
+ *       // Create user record
+ *       const user = await this.users.create({
+ *         id: generateUUID(),
+ *         email: registrationData.email,
+ *         passwordHash: hashedPassword,
+ *         isActive: true,
+ *         emailVerified: false
+ *       }, { tx });
+ *
+ *       // Create user profile
+ *       const profile = await this.userProfiles.create({
+ *         id: generateUUID(),
+ *         userId: user.id,
+ *         firstName: registrationData.profile.firstName,
+ *         lastName: registrationData.profile.lastName,
+ *         dateOfBirth: registrationData.profile.dateOfBirth
+ *       }, { tx });
+ *
+ *       // Create user preferences
+ *       const preferences = await this.userPreferences.create({
+ *         id: generateUUID(),
+ *         userId: user.id,
+ *         notifications: registrationData.preferences.notifications,
+ *         newsletter: registrationData.preferences.newsletter
+ *       }, { tx });
+ *
+ *       // Create audit log entry
+ *       await this.auditLogs.create({
+ *         id: generateUUID(),
+ *         userId: user.id,
+ *         action: 'user_registered',
+ *         details: { email: user.email },
+ *         timestamp: new Date().toISOString()
+ *       }, { tx });
+ *
+ *       console.log(`User registration completed: ${user.id}`);
+ *
+ *       return {
+ *         userId: user.id,
+ *         email: user.email,
+ *         profile: {
+ *           firstName: profile.firstName,
+ *           lastName: profile.lastName
+ *         }
+ *       };
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Data migration with progress tracking:**
+ * ```ts
+ * class MigrationService {
+ *   migrateUserData = $transaction({
+ *     config: {
+ *       isolationLevel: 'read_committed',
+ *       accessMode: 'read_write'
+ *     },
+ *     handler: async (tx, batchSize: number = 1000) => {
+ *       console.log(`Starting data migration with batch size ${batchSize}`);
+ *
+ *       let totalMigrated = 0;
+ *       let hasMore = true;
+ *       let offset = 0;
+ *
+ *       while (hasMore) {
+ *         // Get batch of users to migrate
+ *         const users = await this.legacyUsers.find({
+ *           limit: batchSize,
+ *           offset,
+ *           sort: { id: 'asc' }
+ *         }, { tx });
+ *
+ *         if (users.length === 0) {
+ *           hasMore = false;
+ *           break;
+ *         }
+ *
+ *         // Process each user in the batch
+ *         for (const legacyUser of users) {
+ *           try {
+ *             // Transform legacy data to new format
+ *             const newUser = {
+ *               id: generateUUID(),
+ *               email: legacyUser.email_address,
+ *               firstName: legacyUser.first_name,
+ *               lastName: legacyUser.last_name,
+ *               createdAt: legacyUser.created_date,
+ *               isActive: legacyUser.status === 'active'
+ *             };
+ *
+ *             // Create new user record
+ *             await this.users.create(newUser, { tx });
+ *
+ *             // Mark legacy user as migrated
+ *             await this.legacyUsers.updateById(
+ *               legacyUser.id,
+ *               {
+ *                 migrated: true,
+ *                 migratedAt: new Date().toISOString(),
+ *                 newUserId: newUser.id
+ *               },
+ *               { tx }
+ *             );
+ *
+ *             totalMigrated++;
+ *
+ *           } catch (error) {
+ *             console.error(`Failed to migrate user ${legacyUser.id}:`, error.message);
+ *
+ *             // Log failed migration
+ *             await this.migrationErrors.create({
+ *               id: generateUUID(),
+ *               legacyUserId: legacyUser.id,
+ *               error: error.message,
+ *               attemptedAt: new Date().toISOString()
+ *             }, { tx });
+ *           }
+ *         }
+ *
+ *         offset += batchSize;
+ *         console.log(`Migrated ${totalMigrated} users so far...`);
+ *       }
+ *
+ *       // Update migration status
+ *       await this.migrationStatus.updateById(
+ *         'user_migration',
+ *         {
+ *           totalMigrated,
+ *           completedAt: new Date().toISOString(),
+ *           status: 'completed'
+ *         },
+ *         { tx }
+ *       );
+ *
+ *       console.log(`Migration completed. Total migrated: ${totalMigrated}`);
+ *
+ *       return { totalMigrated };
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * **Important Notes**:
+ * - All operations within the transaction handler are atomic
+ * - Automatic retry on `PgVersionMismatchError` for optimistic locking
+ * - Pass `{ tx }` option to all repository operations within the transaction
+ * - Transactions are automatically rolled back on any unhandled error
+ * - Use appropriate isolation levels based on your consistency requirements
+ *
  * @stability 2
  */
 declare const $transaction: <T extends any[], R>(opts: TransactionDescriptorOptions<T, R>) => _alepha_retry0.RetryDescriptorFn<(...args: T) => Promise<R>>;
 interface TransactionDescriptorOptions<T extends any[], R> {
+  /**
+   * Transaction handler function that contains all database operations to be executed atomically.
+   *
+   * This function:
+   * - Receives a transaction object as the first parameter
+   * - Should pass the transaction to all repository operations via `{ tx }` option
+   * - All operations within are automatically rolled back if any error occurs
+   * - Has access to the full Alepha dependency injection container
+   * - Will be automatically retried if a `PgVersionMismatchError` occurs
+   *
+   * **Transaction Guidelines**:
+   * - Keep transactions as short as possible to minimize lock contention
+   * - Always pass the `tx` parameter to repository operations
+   * - Handle expected business errors gracefully
+   * - Log important operations for debugging and audit trails
+   * - Consider the impact of long-running transactions on performance
+   *
+   * **Error Handling**:
+   * - Throwing any error will automatically roll back the transaction
+   * - `PgVersionMismatchError` triggers automatic retry logic
+   * - Other database errors will be propagated after rollback
+   * - Use try-catch within the handler for business-specific error handling
+   *
+   * @param tx - The PostgreSQL transaction object to use for all database operations
+   * @param ...args - Additional arguments passed to the transaction function
+   * @returns Promise resolving to the transaction result
+   *
+   * @example
+   * ```ts
+   * handler: async (tx, orderId: string, newStatus: string) => {
+   *   // Get the current order (with transaction)
+   *   const order = await this.orders.findById(orderId, { tx });
+   *
+   *   // Validate business rules
+   *   if (!this.isValidStatusTransition(order.status, newStatus)) {
+   *     throw new Error(`Invalid status transition: ${order.status} -> ${newStatus}`);
+   *   }
+   *
+   *   // Update order status (with transaction)
+   *   const updatedOrder = await this.orders.updateById(
+   *     orderId,
+   *     { status: newStatus },
+   *     { tx }
+   *   );
+   *
+   *   // Create audit log (with transaction)
+   *   await this.auditLogs.create({
+   *     id: generateUUID(),
+   *     entityId: orderId,
+   *     action: 'status_change',
+   *     oldValue: order.status,
+   *     newValue: newStatus,
+   *     timestamp: new Date().toISOString()
+   *   }, { tx });
+   *
+   *   return updatedOrder;
+   * }
+   * ```
+   */
   handler: (tx: PgTransaction<any, any, any>, ...args: T) => Promise<R>;
+  /**
+   * PostgreSQL transaction configuration options.
+   *
+   * This allows you to customize transaction behavior including:
+   * - **Isolation Level**: Controls visibility of concurrent transaction changes
+   * - **Access Mode**: Whether the transaction is read-only or read-write
+   * - **Deferrable**: For serializable transactions, allows deferring to avoid conflicts
+   *
+   * **Isolation Levels**:
+   * - **read_uncommitted**: Lowest isolation, allows dirty reads (rarely used)
+   * - **read_committed**: Default level, prevents dirty reads
+   * - **repeatable_read**: Prevents dirty and non-repeatable reads
+   * - **serializable**: Highest isolation, full ACID compliance
+   *
+   * **Access Modes**:
+   * - **read_write**: Default, allows both read and write operations
+   * - **read_only**: Only allows read operations, can provide performance benefits
+   *
+   * **When to Use Different Isolation Levels**:
+   * - **read_committed**: Most common operations, good balance of consistency and performance
+   * - **repeatable_read**: When you need consistent reads throughout the transaction
+   * - **serializable**: Critical financial operations, when absolute consistency is required
+   *
+   * @example
+   * ```ts
+   * config: {
+   *   isolationLevel: 'serializable',  // Highest consistency for financial operations
+   *   accessMode: 'read_write'
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * config: {
+   *   isolationLevel: 'read_committed', // Default level for most operations
+   *   accessMode: 'read_only'          // Performance optimization for read-only operations
+   * }
+   * ```
+   */
   config?: PgTransactionConfig$1;
 }
 type TransactionContext = PgTransaction<any, any, any>;
@@ -1435,7 +3005,7 @@ declare class PostgresTypeProvider {
    * This is used to mark rows as deleted without actually removing them from the database.
    * The column is nullable - NULL means not deleted, timestamp means deleted.
    */
-  readonly deletedAt: (options?: StringOptions) => PgAttr<_sinclair_typebox1.TOptional<TString>, typeof PG_DELETED_AT>;
+  readonly deletedAt: (options?: StringOptions) => PgAttr<_sinclair_typebox0.TOptional<TString>, typeof PG_DELETED_AT>;
   /**
    * Creates a reference to another table or schema. Basically a foreign key.
    */
@@ -1443,14 +3013,6 @@ declare class PostgresTypeProvider {
     onUpdate?: UpdateDeleteAction$1;
     onDelete?: UpdateDeleteAction$1;
   }) => PgAttr<T, PgRef>;
-  /**
-   * Convert a schema to a schema for INSERT operations.
-   * It means that:
-   * - All pg.default() will be optional
-   *
-   * @internal
-   */
-  readonly insert: <T extends TObject$1>(obj: T) => TInsertObject<T>;
   /**
    * Creates a page schema for a given object schema.
    * It's used by {@link RepositoryDescriptor#paginate} method.
@@ -1463,13 +3025,13 @@ declare const pg: PostgresTypeProvider;
 /**
  * @deprecated Use `pg.primaryKey()` instead.
  */
-declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<_sinclair_typebox1.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
+declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<_sinclair_typebox0.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
 //#endregion
 //#region src/types/schema.d.ts
 /**
  * Postgres schema type.
  */
-declare const schema: <TDocument extends TSchema$2>(name: string, document: TDocument) => drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+declare const schema: <TDocument extends TSchema$2>(name: string, document: TDocument) => drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -1525,5 +3087,5 @@ declare const schema: <TDocument extends TSchema$2>(name: string, document: TDoc
  */
 declare const AlephaPostgres: _alepha_core1.Service<_alepha_core1.Module>;
 //#endregion
-export { $entity, $repository, $sequence, $transaction, AlephaPostgres, DrizzleKitProvider, Entity, EntityDescriptorOptions, FilterOperators, FromSchema, NodePostgresProvider, NodePostgresProviderOptions, NullToUndefined, NullifyIfOptional, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_IDENTITY, PG_PRIMARY_KEY, PG_REF, PG_SCHEMA, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Page, PageQuery, PgDefault, PgEntityNotFoundError, PgIdentityOptions, PgPrimaryKey, PgQuery, PgQueryResult, PgQueryWhere, PgQueryWhereOrSQL, PgRef, PgRefOptions, PgSymbolKeys, PgSymbols, PgTableConfig, PgTableWithColumnsAndSchema, PostgresProvider, PostgresTypeProvider, RepositoryDescriptor, RepositoryDescriptorOptions, RepositoryProvider, SQLLike, SequenceDescriptor, SequenceDescriptorOptions, StatementOptions, TInsertObject, TPage, TableLike, TransactionContext, TransactionDescriptorOptions, camelToSnakeCase, drizzle_orm7 as drizzle, legacyIdSchema, mapFieldToColumn, mapStringToColumn, nullToUndefined, pageQuerySchema, pageSchema, pg, schema, schemaToPgColumns, sql };
+export { $entity, $repository, $sequence, $transaction, AlephaPostgres, DrizzleKitProvider, Entity, EntityDescriptorOptions, FilterOperators, FromSchema, NodePostgresProvider, NodePostgresProviderOptions, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_IDENTITY, PG_PRIMARY_KEY, PG_REF, PG_SCHEMA, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Page, PageQuery, PgDefault, PgEntityNotFoundError, PgIdentityOptions, PgPrimaryKey, PgQuery, PgQueryResult, PgQueryWhere, PgQueryWhereOrSQL, PgRef, PgRefOptions, PgSymbolKeys, PgSymbols, PgTableConfig, PgTableWithColumnsAndSchema, PostgresProvider, PostgresTypeProvider, RepositoryDescriptor, RepositoryDescriptorOptions, RepositoryProvider, SQLLike, SequenceDescriptor, SequenceDescriptorOptions, StatementOptions, StaticDefaultEntry, StaticEntry, StaticInsert, TObjectInsert, TPage, TransactionContext, TransactionDescriptorOptions, camelToSnakeCase, drizzle_orm6 as drizzle, insertSchema, legacyIdSchema, mapFieldToColumn, mapStringToColumn, pageQuerySchema, pageSchema, pg, schema, schemaToPgColumns, sql };
 //# sourceMappingURL=index.d.ts.map