alepha 0.10.5 → 0.10.7

package/postgres.d.ts

@@ -1,16 +1,16 @@
 import * as _alepha_core1 from "alepha";
 import { Alepha, AlephaError, Descriptor, KIND, Service, Static, TArray, TBigInt, TBoolean, TInteger, TNull, TNumber, TNumberOptions, TObject, TObjectOptions, TOptional, TOptionalAdd, TRecord, TSchema as TSchema$1, TString, TStringOptions, TUnion } from "alepha";
-import * as drizzle_orm7 from "drizzle-orm";
+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, AnyPgTable, LockConfig, LockStrength, PgColumn, PgColumnBuilderBase, PgDatabase, PgInsertValue, PgSequenceOptions, PgTableExtraConfigValue, PgTableWithColumns, PgTransaction, PgTransactionConfig, SelectedFields, TableConfig as TableConfig$1, UpdateDeleteAction } from "drizzle-orm/pg-core";
+import { AnyPgColumn, AnyPgTable, LockConfig, LockStrength, PgColumn, PgColumnBuilderBase, PgDatabase, PgInsertValue, PgSelectBase, PgSequenceOptions, PgTableExtraConfigValue, PgTableWithColumns, PgTransaction, PgTransactionConfig, TableConfig as TableConfig$1, UpdateDeleteAction } from "drizzle-orm/pg-core";
 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 typebox1 from "typebox";
+import * as typebox0 from "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";
@@ -84,11 +84,11 @@ interface PgRefOptions {
  * Before: { name: string; age: number(default=0); }
  * After:  { name: string; age?: number; }
  */
-type TObjectInsert<T extends TObject> = TObject<{ [K in keyof T["properties"]]: T["properties"][K] extends {
+type TObjectInsert<T$1 extends TObject> = TObject<{ [K in keyof T$1["properties"]]: T$1["properties"][K] extends {
   [PG_DEFAULT]: any;
 } | {
   "~optional": true;
-} ? TOptional<T["properties"][K]> : T["properties"][K] }>;
+} ? TOptional<T$1["properties"][K]> : T$1["properties"][K] }>;
 declare const insertSchema: <T extends TObject>(obj: T) => TObjectInsert<T>;
 //#endregion
 //#region src/schemas/updateSchema.d.ts
@@ -101,7 +101,7 @@ declare const insertSchema: <T extends TObject>(obj: T) => TObjectInsert<T>;
  * 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] }>;
+type TObjectUpdate<T$1 extends TObject> = TObject<{ [K in keyof T$1["properties"]]: T$1["properties"][K] extends TOptional<infer U> ? TOptional<TUnion<[U, TNull]>> : T$1["properties"][K] }>;
 declare const updateSchema: <T extends TObject>(schema: T) => TObjectUpdate<T>;
 //#endregion
 //#region src/helpers/schemaToPgColumns.d.ts
@@ -116,14 +116,14 @@ declare const schemaToPgColumns: <T extends TObject>(schema: T) => FromSchema<T>
  * @param value The value of the field.
  * @returns The PG column.
  */
-declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSerialBuilderInitial<string> | pg$1.PgIntegerBuilderInitial<string> | drizzle_orm7.IsIdentity<pg$1.PgBigInt64BuilderInitial<"">, "byDefault"> | drizzle_orm7.IsIdentity<pg$1.PgBigInt64BuilderInitial<"">, "always"> | pg$1.PgBigInt53BuilderInitial<string> | pg$1.PgNumericBuilderInitial<string> | pg$1.PgTimestampBuilderInitial<string> | pg$1.PgUUIDBuilderInitial<string> | pg$1.PgCustomColumnBuilder<{
+declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSerialBuilderInitial<string> | pg$1.PgIntegerBuilderInitial<string> | drizzle_orm6.IsIdentity<pg$1.PgBigInt64BuilderInitial<"">, "byDefault"> | drizzle_orm6.IsIdentity<pg$1.PgBigInt64BuilderInitial<"">, "always"> | pg$1.PgBigInt53BuilderInitial<string> | pg$1.PgNumericBuilderInitial<string> | pg$1.PgDateStringBuilderInitial<string> | pg$1.PgUUIDBuilderInitial<string> | pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
   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.PgTextBuilderInitial<string, [string, ...string[]]> | pg$1.PgBooleanBuilderInitial<string> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -138,14 +138,14 @@ declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSeria
   [x: string]: unknown;
   [x: number]: unknown;
   [x: symbol]: unknown;
-}> | drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+}> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
   data: Record<string, unknown>;
   driverParam: string;
   enumValues: undefined;
-}>, Record<string, unknown>> | drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+}>, Record<string, unknown>> | drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -251,27 +251,28 @@ declare const mapFieldToColumn: (name: string, value: TSchema$1) => pg$1.PgSeria
  * @param key The key of the field.
  * @param value The value of the field.
  */
-declare const mapStringToColumn: (key: string, value: TSchema$1) => pg$1.PgUUIDBuilderInitial<string> | pg$1.PgCustomColumnBuilder<{
+declare const mapStringToColumn: (key: string, value: TSchema$1) => pg$1.PgDateStringBuilderInitial<string> | pg$1.PgUUIDBuilderInitial<string> | pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
   data: Buffer<ArrayBufferLike>;
   driverParam: unknown;
   enumValues: undefined;
-}> | pg$1.PgTimestampStringBuilderInitial<string> | pg$1.PgDateStringBuilderInitial<string> | pg$1.PgTextBuilderInitial<string, [string, ...string[]]>;
+}> | pg$1.PgTimestampStringBuilderInitial<string> | pg$1.PgTextBuilderInitial<string, [string, ...string[]]>;
 declare const camelToSnakeCase: (str: string) => string;
 /**
  * Convert a schema to columns.
  */
-type FromSchema<T extends TObject> = { [key in keyof T["properties"]]: PgColumnBuilderBase };
+type FromSchema<T$1 extends TObject> = { [key in keyof T$1["properties"]]: PgColumnBuilderBase };
 /**
  * A table with columns and schema.
  */
-type PgTableWithColumnsAndSchema<T extends TableConfig, R extends TObject> = PgTableWithColumns<T> & {
-  get $table(): PgTableWithColumns<T>;
-  get $schema(): R;
-  get $insertSchema(): TObjectInsert<R>;
-  get $updateSchema(): TObjectUpdate<R>;
+type PgTableWithColumnsAndSchema<T$1 extends TableConfig, R$1 extends TObject> = PgTableWithColumns<T$1> & {
+  get $table(): PgTableWithColumns<T$1>;
+  get $schema(): R$1;
+  get $insertSchema(): TObjectInsert<R$1>;
+  get $updateSchema(): TObjectUpdate<R$1>;
+  alias: (alias: string) => PgTableWithColumnsAndSchema<T$1, R$1>;
 };
 //#endregion
 //#region src/descriptors/$entity.d.ts
@@ -481,107 +482,22 @@ type PgTableWithColumnsAndSchema<T extends TableConfig, R extends TObject> = PgT
  *   ]
  * });
  * ```
- *
- * @stability 2
  */
 declare const $entity: {
   <TTableName extends string, TSchema extends TObject, TColumnsMap extends FromSchema<TSchema>>(options: EntityDescriptorOptions<TTableName, TSchema>): PgTableWithColumnsAndSchema<PgTableConfig<TTableName, TSchema, TColumnsMap>, TSchema>;
   [KIND]: string;
 };
-interface EntityDescriptorOptions<TTableName extends string, T extends TObject, Keys = keyof Static<T>> {
+interface EntityDescriptorOptions<TTableName$1 extends string, T$1 extends TObject, Keys = keyof Static<T$1>> {
   /**
    * 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;
+  name: TTableName$1;
   /**
    * 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.text()` - VARCHAR column
-   * - `t.integer()`, `t.number()` - Numeric columns
-   * - `t.boolean()` - Boolean column
-   * - `t.array(t.text())` - PostgreSQL array column
-   * - `t.record(t.text(), 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
-   * ```ts
-   * t.object({
-   *   id: pg.primaryKey(t.uuid()),
-   *   email: t.text({ format: "email" }),
-   *   firstName: t.text({ minLength: 1, maxLength: 100 }),
-   *   lastName: t.text({ minLength: 1, maxLength: 100 }),
-   *   age: t.optional(t.integer({ minimum: 0, maximum: 150 })),
-   *   isActive: t.boolean({ default: true }),
-   *   preferences: t.optional(t.record(t.text(), t.any())),
-   *   tags: t.optional(t.array(t.text())),
-   *   createdAt: pg.createdAt(),
-   *   updatedAt: pg.updatedAt(),
-   *   version: pg.version()
-   * })
-   * ```
    */
-  schema: T;
+  schema: T$1;
   /**
    * 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 | {
     /**
@@ -612,35 +528,6 @@ interface EntityDescriptorOptions<TTableName extends string, T extends TObject,
   })[];
   /**
    * 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<{
     /**
@@ -650,7 +537,7 @@ interface EntityDescriptorOptions<TTableName extends string, T extends TObject,
     /**
      * Local columns that reference the foreign table.
      */
-    columns: Array<keyof Static<T>>;
+    columns: Array<keyof Static<T$1>>;
     /**
      * Referenced columns in the foreign table.
      */
@@ -697,7 +584,7 @@ interface EntityDescriptorOptions<TTableName extends string, T extends TObject,
     /**
      * Columns involved in this constraint.
      */
-    columns: Array<keyof Static<T>>;
+    columns: Array<keyof Static<T$1>>;
     /**
      * Optional name for the constraint.
      */
@@ -750,13 +637,13 @@ interface EntityDescriptorOptions<TTableName extends string, T extends TObject,
    * ]
    * ```
    */
-  config?: (self: BuildExtraConfigColumns<string, FromSchema<T>, "pg">) => PgTableExtraConfigValue[];
+  config?: (self: BuildExtraConfigColumns<string, FromSchema<T$1>, "pg">) => PgTableExtraConfigValue[];
 }
-type Entity<T extends TObject> = PgTableWithColumnsAndSchema<PgTableConfig<string, T, FromSchema<T>>, T>;
-type PgTableConfig<TTableName extends string, TSchema extends TObject, TColumnsMap extends FromSchema<TSchema>> = {
-  name: TTableName;
+type Entity<T$1 extends TObject> = PgTableWithColumnsAndSchema<PgTableConfig<string, T$1, FromSchema<T$1>>, T$1>;
+type PgTableConfig<TTableName$1 extends string, TSchema$2 extends TObject, TColumnsMap$1 extends FromSchema<TSchema$2>> = {
+  name: TTableName$1;
   schema: any;
-  columns: BuildColumns<TTableName, TColumnsMap, "pg">;
+  columns: BuildColumns<TTableName$1, TColumnsMap$1, "pg">;
   dialect: "pg";
 };
 //#endregion
@@ -766,39 +653,6 @@ declare class PgError extends AlephaError {
   constructor(message: string, cause?: unknown);
 }
 //#endregion
-//#region src/helpers/pgAttr.d.ts
-/**
- * Decorates a typebox schema with a Postgres attribute.
- *
- * > It's just a fancy way to add Symbols to a field.
- *
- * @example
- * ```ts
- * import { t } from "alepha";
- * import { PG_UPDATED_AT } from "../constants/PG_SYMBOLS";
- *
- * export const updatedAtSchema = pgAttr(
- *   t.datetime(), PG_UPDATED_AT,
- * );
- * ```
- */
-declare const pgAttr: <T extends TSchema$1, Attr extends PgSymbolKeys>(type: T, attr: Attr, value?: PgSymbols[Attr]) => PgAttr<T, Attr>;
-/**
- * Retrieves the fields of a schema that have a specific attribute.
- */
-declare const getAttrFields: (schema: TObject, name: PgSymbolKeys) => PgAttrField[];
-/**
- * Type representation.
- */
-type PgAttr<T extends TSchema$1, TAttr extends PgSymbolKeys> = T & { [K in TAttr]: PgSymbols[K] };
-interface PgAttrField {
-  key: string;
-  type: TSchema$1;
-  data: any;
-  nested?: any[];
-  one?: boolean;
-}
-//#endregion
 //#region src/interfaces/FilterOperators.d.ts
 interface FilterOperators<TValue> {
   /**
@@ -1155,8 +1009,55 @@ interface FilterOperators<TValue> {
   arrayOverlaps?: TValue;
 }
 //#endregion
+//#region src/interfaces/PgQuery.d.ts
+/**
+ * Order direction for sorting
+ */
+type OrderDirection = "asc" | "desc";
+/**
+ * Single order by clause with column and direction
+ */
+interface OrderByClause<T$1> {
+  column: keyof T$1;
+  direction?: OrderDirection;
+}
+/**
+ * Order by parameter - supports 3 modes:
+ * 1. String: orderBy: "name" (defaults to ASC)
+ * 2. Single object: orderBy: { column: "name", direction: "desc" }
+ * 3. Array: orderBy: [{ column: "name", direction: "asc" }, { column: "age", direction: "desc" }]
+ */
+type OrderBy<T$1> = keyof T$1 | OrderByClause<T$1> | Array<OrderByClause<T$1>>;
+/**
+ * Generic query interface for PostgreSQL entities
+ */
+interface PgQuery<T$1 extends TObject = TObject> {
+  distinct?: (keyof Static<T$1>)[];
+  columns?: (keyof Static<T$1>)[];
+  where?: PgQueryWhereOrSQL<T$1>;
+  limit?: number;
+  offset?: number;
+  orderBy?: OrderBy<Static<T$1>>;
+  groupBy?: (keyof Static<T$1>)[];
+}
+type PgStatic<T$1 extends TObject, Relations extends PgRelationMap<T$1>> = Static<T$1> & { [K in keyof Relations]: Static<Relations[K]["join"]["$schema"]> & (Relations[K]["with"] extends PgRelationMap<TObject> ? PgStatic<Relations[K]["join"]["$schema"], Relations[K]["with"]> : {}) };
+interface PgQueryRelations<T$1 extends TObject = TObject, Relations extends PgRelationMap<T$1> | undefined = undefined> extends PgQuery<T$1> {
+  with?: Relations;
+  where?: PgQueryWhereOrSQL<T$1, Relations>;
+}
+type PgRelationMap<Base extends TObject> = Record<string, PgRelation<Base>>;
+type PgRelation<Base extends TObject> = {
+  type?: "left" | "inner" | "right";
+  join: PgTableWithColumnsAndSchema<any, TObject>;
+  on: SQLWrapper | [keyof Static<Base>, PgColumn];
+  with?: PgRelationMap<TObject>;
+};
+//#endregion
 //#region src/interfaces/PgQueryWhere.d.ts
-type PgQueryWhere<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperators<Static<T>[Key]> | Static<T>[Key] } & {
+type PgQueryWhere<T$1 extends TObject, Relations extends PgRelationMap<TObject> | undefined = undefined> = (PgQueryWhereOperators<T$1> & PgQueryWhereConditions<T$1>) | (PgQueryWhereRelations<Relations> & PgQueryWhereOperators<T$1> & PgQueryWhereConditions<T$1, Relations>);
+type PgQueryWhereOrSQL<T$1 extends TObject, Relations extends PgRelationMap<TObject> | undefined = undefined> = SQLWrapper | PgQueryWhere<T$1, Relations>;
+type PgQueryWhereOperators<T$1 extends TObject> = { [Key in keyof Static<T$1>]?: FilterOperators<Static<T$1>[Key]> | Static<T$1>[Key] | (Static<T$1>[Key] extends object ? NestedJsonbQuery<Static<T$1>[Key]> : never) };
+type PgQueryWhereConditions<T$1 extends TObject, Relations extends PgRelationMap<TObject> | undefined = undefined> = {
   /**
    * Combine a list of conditions with the `and` operator. Conditions
    * that are equal `undefined` are automatically ignored.
@@ -1173,7 +1074,7 @@ type PgQueryWhere<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperat
    *   )
    * ```
    */
-  and?: Array<PgQueryWhereOrSQL<T>>;
+  and?: Array<PgQueryWhereOrSQL<T$1, Relations>>;
   /**
    * Combine a list of conditions with the `or` operator. Conditions
    * that are equal `undefined` are automatically ignored.
@@ -1190,7 +1091,7 @@ type PgQueryWhere<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperat
    *   )
    * ```
    */
-  or?: Array<PgQueryWhereOrSQL<T>>;
+  or?: Array<PgQueryWhereOrSQL<T$1, Relations>>;
   /**
    * Negate the meaning of an expression using the `not` keyword.
    *
@@ -1202,7 +1103,7 @@ type PgQueryWhere<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperat
    *   .where(not(inArray(cars.make, ['GM', 'Ford'])))
    * ```
    */
-  not?: PgQueryWhereOrSQL<T>;
+  not?: PgQueryWhereOrSQL<T$1, Relations>;
   /**
    * Test whether a subquery evaluates to have any rows.
    *
@@ -1225,88 +1126,29 @@ type PgQueryWhere<T extends TObject> = { [Key in keyof Static<T>]?: FilterOperat
    */
   exists?: SQLWrapper;
 };
-type PgQueryWhereOrSQL<T extends TObject> = SQLWrapper | PgQueryWhere<T>;
-type PgQueryWhereWithManyOrSQL<T extends TObject> = SQLWrapper | PgQueryWhereWithMany<T>;
-type PgQueryWhereWithMany<T extends TObject> = PgQueryWhere<RemoveManyRelations<T>> & ExtractManyRelations<T>;
-type RelField = {
-  [PG_MANY]: any;
-} | {
-  [PG_ONE]: any;
-};
-type ExtractManyRelations<T extends TObject> = { [K in keyof T["properties"] as T["properties"][K] extends RelField ? T["properties"][K] extends TArray ? T["properties"][K]["items"] extends TObject ? K : never : never : T["properties"][K] extends TObject ? K : never]?: PgQueryWhere<T["properties"][K] extends TArray ? T["properties"][K]["items"] extends TObject ? T["properties"][K]["items"] : TObject : T["properties"][K] extends TObject ? T["properties"][K] : TObject> };
-type RemoveManyRelations<T extends TObject> = TObject<{ [K in keyof T["properties"] as T["properties"][K] extends RelField ? never : K]: T["properties"][K] }>;
-type PgQueryWithMap<T extends TObject> = { [K in keyof T["properties"] as T["properties"][K] extends RelField ? K : never]?: T["properties"][K] extends TArray ? T["properties"][K]["items"] extends TObject ? PgQueryWithMany<T["properties"][K]["items"]> : never : T["properties"][K] extends TObject ? PgQueryWithOne<T["properties"][K]> : T["properties"][K] extends PgAttr<PgAttr<TOptionalAdd<infer U>, PgOne>, PgDefault> ? U extends TObject ? PgQueryWithOne<U> : never : never };
-type PgQueryWithOne<T extends TObject> = true | {
-  columns?: (keyof Static<T>)[];
-  relations?: PgQueryWithMap<T>;
-};
-type PgQueryWithMany<T extends TObject> = true | {
-  limit?: number;
-  columns?: (keyof Static<T>)[];
-  relations?: PgQueryWithMap<T>;
-};
-//#endregion
-//#region src/interfaces/PgQuery.d.ts
-/**
- * Order direction for sorting
- */
-type OrderDirection = "asc" | "desc";
-/**
- * Single order by clause with column and direction
- */
-interface OrderByClause<T> {
-  column: keyof T;
-  direction?: OrderDirection;
-}
+type PgQueryWhereRelations<Relations extends PgRelationMap<TObject> | undefined = undefined> = Relations extends PgRelationMap<TObject> ? { [K in keyof Relations]?: PgQueryWhere<Relations[K]["join"]["$schema"], Relations[K]["with"]> } : {};
 /**
- * Order by parameter - supports 3 modes:
- * 1. String: orderBy: "name" (defaults to ASC)
- * 2. Single object: orderBy: { column: "name", direction: "desc" }
- * 3. Array: orderBy: [{ column: "name", direction: "asc" }, { column: "age", direction: "desc" }]
+ * Recursively allow nested queries for JSONB object/array types
  */
-type OrderBy<T> = keyof T | OrderByClause<T> | Array<OrderByClause<T>>;
-interface PgQuery<T extends TObject = TObject> {
-  distinct?: boolean;
-  where?: PgQueryWhereWithMany<T> | SQLWrapper;
-  limit?: number;
-  offset?: number;
-  orderBy?: OrderBy<Static<T>>;
-  groupBy?: (keyof Static<T>)[];
-  relations?: PgQueryWithMap<T>;
-}
-//#endregion
-//#region src/providers/drivers/PostgresProvider.d.ts
-type SQLLike = SQLWrapper | string;
-declare abstract class PostgresProvider {
-  protected readonly alepha: Alepha;
-  abstract get db(): PgDatabase<any>;
-  readonly dialect: "postgres" | "sqlite";
-  get schema(): string;
-  execute<T extends TObject | undefined>(query: SQLLike, schema?: T): Promise<Array<T extends TObject ? Static<T> : any>>;
-  protected mapResult<T extends TObject = any>(result: Array<any>, schema?: T): Array<T extends TObject ? Static<T> : any>;
-}
-//#endregion
-//#region src/schemas/pageQuerySchema.d.ts
-declare const pageQuerySchema: typebox1.TObject<{
-  page: typebox1.TOptional<typebox1.TInteger>;
-  size: typebox1.TOptional<typebox1.TInteger>;
-  sort: typebox1.TOptional<typebox1.TString>;
-}>;
-type PageQuery = Static<typeof pageQuerySchema>;
+type NestedJsonbQuery<T$1> = T$1 extends object ? T$1 extends Array<infer U> ? U extends object ? { [K in keyof U]?: FilterOperators<U[K]> | U[K] } : FilterOperators<U> | U : { [K in keyof T$1]?: FilterOperators<T$1[K]> | T$1[K] | (T$1[K] extends object ? NestedJsonbQuery<T$1[K]> : never) } : FilterOperators<T$1> | T$1;
 //#endregion
 //#region src/schemas/pageSchema.d.ts
 /**
  * Create a pagination schema for the given object schema.
  *
+ * > use `pg.page` directly.
+ *
  * @example
+ * ```ts
  * const userSchema = t.object({ id: t.int(), name: t.text() });
- * const pagedUserSchema = pageSchema(userSchema);
+ * const userPageSchema = pageSchema(userSchema);
+ * ```
  *
  * @see {@link $repository#paginate}
  */
 declare const pageSchema: <T extends TObject | TRecord>(objectSchema: T, options?: TObjectOptions) => TPage<T>;
-type TPage<T extends TObject | TRecord> = TObject<{
-  content: TArray<T>;
+type TPage<T$1 extends TObject | TRecord> = TObject<{
+  content: TArray<T$1>;
   can: TObject<{
     next: TBoolean;
     previous: TBoolean;
@@ -1317,22 +1159,244 @@ type TPage<T extends TObject | TRecord> = TObject<{
     totalElements: TOptionalAdd<TInteger>;
   }>;
 }>;
-type Page<T> = {
-  content: T[];
+/**
+ * Opinionated type definition for a paginated response.
+ *
+ * @example
+ * ```ts
+ * const page = {
+ *   content: [ ... ]
+ *   can: {
+ *     next: true,
+ *     previous: false
+ *   },
+ *   page: {
+ *     number: 0,
+ *     size: 10,
+ *     totalElements: 1200
+ *   }
+ * }
+ * ```
+ */
+type Page<T$1> = {
+  /**
+   * Array of items on the current page.
+   */
+  content: T$1[];
   can: {
+    /**
+     * Indicates if there is a next page.
+     */
     next: boolean;
+    /**
+     * Indicates if there is a previous page.
+     */
     previous: boolean;
   };
   page: {
+    /**
+     * Page number, starting from 0.
+     */
     number: number;
+    /**
+     * Number of items per page.
+     */
     size: number;
+    /**
+     * Requires `count: true` in the paginate options.
+     */
     totalElements?: number;
   };
 };
 //#endregion
+//#region src/helpers/PgJsonQueryManager.d.ts
+/**
+ * Manages JSONB query generation for nested object and array queries in PostgreSQL.
+ * This class handles complex nested queries using PostgreSQL's JSONB operators.
+ */
+declare class PgJsonQueryManager {
+  /**
+   * Check if a query contains nested JSONB queries.
+   * A nested query is when the value is an object with operator keys.
+   */
+  hasNestedQuery(where: PgQueryWhere<TObject>): boolean;
+  /**
+   * Build a JSONB query condition for nested object queries.
+   * Supports deep nesting like: { profile: { contact: { email: { eq: "test@example.com" } } } }
+   *
+   * @param column The JSONB column
+   * @param path The path to the nested property (e.g., ['profile', 'contact', 'email'])
+   * @param operator The filter operator (e.g., { eq: "test@example.com" })
+   * @returns SQL condition
+   */
+  buildJsonbCondition(column: PgColumn, path: string[], operator: FilterOperators<any>): SQL | undefined;
+  /**
+   * Build JSONB array query conditions.
+   * Supports queries like: { addresses: { city: { eq: "Wonderland" } } }
+   * which translates to: EXISTS (SELECT 1 FROM jsonb_array_elements(addresses) elem WHERE elem->>'city' = 'Wonderland')
+   */
+  buildJsonbArrayCondition(column: PgColumn, path: string[], arrayPath: string, operator: FilterOperators<any>): SQL | undefined;
+  /**
+   * Apply a filter operator to a JSONB value.
+   */
+  private applyOperatorToJsonValue;
+  /**
+   * Parse a nested query object and extract the path and operator.
+   * For example: { profile: { contact: { email: { eq: "test@example.com" } } } }
+   * Returns: { path: ['profile', 'contact', 'email'], operator: { eq: "test@example.com" } }
+   */
+  parseNestedQuery(nestedQuery: any, currentPath?: string[]): Array<{
+    path: string[];
+    operator: FilterOperators<any>;
+  }>;
+  /**
+   * Determine if a property is a JSONB column based on the schema.
+   * A column is JSONB if it's defined as an object or array in the TypeBox schema.
+   */
+  isJsonbColumn(schema: TObject, columnName: string): boolean;
+  /**
+   * Check if an array property contains primitive types (string, number, boolean, etc.)
+   * rather than objects. Primitive arrays should use native Drizzle operators.
+   * @returns true if the array contains primitives, false if it contains objects
+   */
+  isPrimitiveArray(schema: TObject, columnName: string): boolean;
+  /**
+   * Check if a nested path points to an array property.
+   */
+  isArrayProperty(schema: TObject, path: string[]): boolean;
+}
+//#endregion
+//#region src/helpers/PgQueryManager.d.ts
+declare class PgQueryManager {
+  protected readonly jsonQueryManager: PgJsonQueryManager;
+  /**
+   * Convert a query object to a SQL query.
+   */
+  toSQL(query: PgQueryWhereOrSQL<TObject>, options: {
+    schema: TObject;
+    col: (key: string) => PgColumn;
+    joins?: PgJoin[];
+  }): SQL | undefined;
+  /**
+   * Build a JSONB query for nested object/array queries.
+   */
+  protected buildJsonbQuery(column: PgColumn, nestedQuery: any, schema: TObject, columnName: string): SQL | undefined;
+  /**
+   * Map a filter operator to a SQL query.
+   */
+  mapOperatorToSql(operator: FilterOperators<any> | any, column: PgColumn): SQL | undefined;
+  /**
+   * Parse pagination sort string to orderBy format.
+   * Format: "firstName,-lastName" -> [{ column: "firstName", direction: "asc" }, { column: "lastName", direction: "desc" }]
+   * - Columns separated by comma
+   * - Prefix with '-' for DESC direction
+   *
+   * @param sort Pagination sort string
+   * @returns OrderBy array or single object
+   */
+  parsePaginationSort(sort: string): Array<{
+    column: string;
+    direction: "asc" | "desc";
+  }> | {
+    column: string;
+    direction: "asc" | "desc";
+  };
+  /**
+   * Normalize orderBy parameter to array format.
+   * Supports 3 modes:
+   * 1. String: "name" -> [{ column: "name", direction: "asc" }]
+   * 2. Object: { column: "name", direction: "desc" } -> [{ column: "name", direction: "desc" }]
+   * 3. Array: [{ column: "name" }, { column: "age", direction: "desc" }] -> normalized array
+   *
+   * @param orderBy The orderBy parameter
+   * @returns Normalized array of order by clauses
+   */
+  normalizeOrderBy(orderBy: any): Array<{
+    column: string;
+    direction: "asc" | "desc";
+  }>;
+  /**
+   * Create a pagination object.
+   *
+   * @param entities The entities to paginate.
+   * @param limit The limit of the pagination.
+   * @param offset The offset of the pagination.
+   */
+  createPagination<T>(entities: T[], limit?: number, offset?: number): Page<T>;
+}
+interface PgJoin {
+  table: string;
+  schema: TObject;
+  key: string;
+  col: (key: string) => PgColumn;
+  parent?: string;
+}
+//#endregion
+//#region src/helpers/PgRelationManager.d.ts
+declare class PgRelationManager {
+  buildJoins(builder: PgSelectBase<any, any, any>, joins: Array<PgJoin>, withRelations: PgRelationMap<TObject>, table: PgTableWithColumnsAndSchema<any, any>, parentKey?: string): void;
+  mapRowWithJoins(record: Record<string, unknown>, row: Record<string, unknown>, schema: TObject, joins: PgJoin[], parentKey?: string): Record<string, unknown>;
+  /**
+   * Check if all values in an object are null (indicates a left join with no match)
+   */
+  private isAllNull;
+}
+//#endregion
+//#region src/helpers/pgAttr.d.ts
+/**
+ * Decorates a typebox schema with a Postgres attribute.
+ *
+ * > It's just a fancy way to add Symbols to a field.
+ *
+ * @example
+ * ```ts
+ * import { t } from "alepha";
+ * import { PG_UPDATED_AT } from "../constants/PG_SYMBOLS";
+ *
+ * export const updatedAtSchema = pgAttr(
+ *   t.datetime(), PG_UPDATED_AT,
+ * );
+ * ```
+ */
+declare const pgAttr: <T extends TSchema$1, Attr extends PgSymbolKeys>(type: T, attr: Attr, value?: PgSymbols[Attr]) => PgAttr<T, Attr>;
+/**
+ * Retrieves the fields of a schema that have a specific attribute.
+ */
+declare const getAttrFields: (schema: TObject, name: PgSymbolKeys) => PgAttrField[];
+/**
+ * Type representation.
+ */
+type PgAttr<T$1 extends TSchema$1, TAttr extends PgSymbolKeys> = T$1 & { [K in TAttr]: PgSymbols[K] };
+interface PgAttrField {
+  key: string;
+  type: TSchema$1;
+  data: any;
+  nested?: any[];
+  one?: boolean;
+}
+//#endregion
+//#region src/providers/drivers/PostgresProvider.d.ts
+type SQLLike = SQLWrapper | string;
+declare abstract class PostgresProvider {
+  protected readonly alepha: Alepha;
+  abstract get db(): PgDatabase<any>;
+  readonly dialect: "postgres" | "sqlite";
+  get schema(): string;
+  execute<T extends TObject | undefined>(query: SQLLike, schema?: T): Promise<Array<T extends TObject ? Static<T> : any>>;
+  protected mapResult<T extends TObject = any>(result: Array<any>, schema?: T): Array<T extends TObject ? Static<T> : any>;
+}
+//#endregion
+//#region src/schemas/pageQuerySchema.d.ts
+declare const pageQuerySchema: typebox0.TObject<{
+  page: typebox0.TOptional<typebox0.TInteger>;
+  size: typebox0.TOptional<typebox0.TInteger>;
+  sort: typebox0.TOptional<typebox0.TString>;
+}>;
+type PageQuery = Static<typeof pageQuerySchema>;
+//#endregion
 //#region src/descriptors/$repository.d.ts
 /**
- * Creates a repository descriptor for database operations on a defined entity.
+ * Creates a repository 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
@@ -1355,15 +1419,6 @@ type Page<T> = {
  * - 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
@@ -1371,14 +1426,14 @@ type Page<T> = {
  * import { pg, t } from "alepha";
  *
  * // First, define the entity
- * const User = $entity({
+ * const users = $entity({
  *   name: "users",
  *   schema: t.object({
  *     id: pg.primaryKey(t.uuid()),
  *     email: t.text({ format: "email" }),
  *     firstName: t.text(),
  *     lastName: t.text(),
- *     isActive: t.boolean({ default: true }),
+ *     isActive: pg.default(t.boolean(), true),
  *     createdAt: pg.createdAt(),
  *     updatedAt: pg.updatedAt()
  *   }),
@@ -1386,15 +1441,14 @@ type Page<T> = {
  * });
  *
  * class UserService {
- *   users = $repository({ table: User });
+ *   users = $repository(users);
  *
  *   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
+ *       lastName: userData.lastName
  *     });
  *   }
  *
@@ -1416,7 +1470,7 @@ declare const $repository: {
   <EntityTableConfig extends TableConfig, EntitySchema extends TObject>(optionsOrTable: RepositoryDescriptorOptions<EntityTableConfig, EntitySchema> | PgTableWithColumnsAndSchema<EntityTableConfig, EntitySchema>): RepositoryDescriptor<EntityTableConfig, EntitySchema>;
   [KIND]: typeof RepositoryDescriptor;
 };
-interface RepositoryDescriptorOptions<EntityTableConfig extends TableConfig, EntitySchema extends TObject> {
+interface RepositoryDescriptorOptions<EntityTableConfig$1 extends TableConfig, EntitySchema$1 extends TObject> {
   /**
    * The entity table definition created with $entity.
    *
@@ -1451,7 +1505,7 @@ interface RepositoryDescriptorOptions<EntityTableConfig extends TableConfig, Ent
    * const userRepository = $repository({ table: User });
    * ```
    */
-  table: PgTableWithColumnsAndSchema<EntityTableConfig, EntitySchema>;
+  table: PgTableWithColumnsAndSchema<EntityTableConfig$1, EntitySchema$1>;
   /**
    * Override the default PostgreSQL database provider.
    *
@@ -1476,12 +1530,14 @@ interface RepositoryDescriptorOptions<EntityTableConfig extends TableConfig, Ent
    */
   provider?: Service<PostgresProvider>;
 }
-declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, EntitySchema extends TObject> extends Descriptor<RepositoryDescriptorOptions<EntityTableConfig, EntitySchema>> {
+declare class RepositoryDescriptor<EntityTableConfig$1 extends TableConfig, EntitySchema$1 extends TObject> extends Descriptor<RepositoryDescriptorOptions<EntityTableConfig$1, EntitySchema$1>> {
+  protected readonly pgRelationManager: PgRelationManager;
+  protected readonly pgQueryManager: PgQueryManager;
   protected readonly dateTimeProvider: DateTimeProvider;
   protected readonly alepha: Alepha;
   readonly provider: PostgresProvider;
-  readonly schema: EntitySchema;
-  readonly schemaInsert: TObjectInsert<EntitySchema>;
+  readonly schema: EntitySchema$1;
+  readonly schemaInsert: TObjectInsert<EntitySchema$1>;
   /**
    * Represents the primary key of the table.
    * - Key is the name of the primary key column.
@@ -1491,13 +1547,13 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    */
   readonly id: {
     type: TSchema$1;
-    key: keyof EntitySchema["properties"];
+    key: keyof EntitySchema$1["properties"];
     col: PgColumn;
   };
   /**
    * Get Drizzle table object.
    */
-  get table(): PgTableWithColumns<EntityTableConfig>;
+  get table(): PgTableWithColumns<EntityTableConfig$1>;
   /**
    * Get SQL table name. (from Drizzle table object)
    */
@@ -1505,87 +1561,97 @@ 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.
+   *
+   * This method allows executing raw SQL queries against the database.
+   * This is by far the easiest way to run custom queries that are not covered by the repository's built-in methods!
+   *
+   * You must use the `sql` tagged template function from Drizzle ORM to create the query. https://orm.drizzle.team/docs/sql
+   *
+   * @example
+   * ```ts
+   * const users = $entity({ ... });
+   * const result = await repository.query(sql`SELECT * FROM ${users} WHERE ${users.age} > ${18}`, users.$schema);
+   * ```
+   */
+  query<T extends TObject = EntitySchema$1>(query: SQLLike | ((table: PgTableWithColumns<EntityTableConfig$1>, db: PgDatabase<any>) => SQLLike), schema?: T): Promise<Static<T>[]>;
+  /**
+   * Map raw database fields to entity fields. (handles column name differences)
    */
-  query<T extends TObject = EntitySchema>(query: SQLLike | ((table: PgTableWithColumns<EntityTableConfig>, db: PgDatabase<any>) => SQLLike), schema?: T): Promise<Static<T>[]>;
-  protected mapRawFieldsToEntity(row: any[]): any;
+  protected mapRawFieldsToEntity(row: Record<string, unknown>): any;
   /**
    * Get a Drizzle column from the table by his name.
-   *
-   * @param name - The name of the column to get.
-   * @returns The column from the table.
    */
-  protected col(name: keyof PgTableWithColumns<EntityTableConfig>["_"]["columns"]): PgColumn;
+  protected col(name: keyof PgTableWithColumns<EntityTableConfig$1>["_"]["columns"]): PgColumn;
   /**
    * Run a transaction.
-   *
-   * @param transaction
-   * @param config
    */
   transaction<T>(transaction: (tx: PgTransaction<any, Record<string, any>, any>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
   /**
    * Start a SELECT query on the table.
-   *
-   * @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;
+  /**
+   * Start a SELECT DISTINCT query on the table.
+   */
+  protected selectDistinct(opts?: StatementOptions, columns?: (keyof Static<EntitySchema$1>)[]): pg$1.PgSelectBase<string, Record<string, any>, "partial", Record<string, "not-null">, false, never, {
+    [x: string]: any;
   }[], {
-    [x: string]: never;
+    [x: string]: any;
   }>;
   /**
    * Start an INSERT query on the table.
-   *
-   * @returns The INSERT query builder.
    */
-  protected insert(opts?: StatementOptions): pg$1.PgInsertBuilder<PgTableWithColumns<EntityTableConfig>, any, false>;
+  protected insert(opts?: StatementOptions): pg$1.PgInsertBuilder<PgTableWithColumns<EntityTableConfig$1>, any, false>;
   /**
    * Start an UPDATE query on the table.
-   *
-   * @returns The UPDATE query builder.
    */
-  protected update(opts?: StatementOptions): pg$1.PgUpdateBuilder<PgTableWithColumns<EntityTableConfig>, any>;
+  protected update(opts?: StatementOptions): pg$1.PgUpdateBuilder<PgTableWithColumns<EntityTableConfig$1>, any>;
   /**
    * Start a DELETE query on the table.
-   *
-   * @returns The DELETE query builder.
    */
-  protected delete(opts?: StatementOptions): pg$1.PgDeleteBase<PgTableWithColumns<EntityTableConfig>, any, undefined, undefined, false, never>;
+  protected delete(opts?: StatementOptions): pg$1.PgDeleteBase<PgTableWithColumns<EntityTableConfig$1>, any, undefined, undefined, false, never>;
   /**
-   * Find entities.
+   * Create a Drizzle `select` query based on a JSON query object.
    *
-   * @param query The find query.
-   * @param opts The statement options.
-   * @returns The found entities.
+   * > This method is the base for `find`, `findOne`, `findById`, and `paginate`.
    */
-  find(query?: PgQuery<EntitySchema>, opts?: StatementOptions): Promise<Static<EntitySchema>[]>;
+  find<R extends PgRelationMap<EntitySchema$1>>(query?: PgQueryRelations<EntitySchema$1, R>, opts?: StatementOptions): Promise<PgStatic<EntitySchema$1, R>[]>;
   /**
    * Find a single entity.
+   */
+  findOne<R extends PgRelationMap<EntitySchema$1>>(query: Pick<PgQueryRelations<EntitySchema$1, R>, "with" | "where">, opts?: StatementOptions): Promise<PgStatic<EntitySchema$1, R>>;
+  /**
+   * Find entities with pagination.
    *
-   * @param where The where clause.
-   * @param opts The statement options.
-   * @returns The found entity.
+   * It uses the same parameters as `find()`, but adds pagination metadata to the response.
+   *
+   * > Pagination CAN also do a count query to get the total number of elements.
    */
-  findOne<T extends EntitySchema = EntitySchema>(where: PgQueryWhereOrSQL<T>, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  paginate<R extends PgRelationMap<EntitySchema$1>>(pagination?: PageQuery, query?: PgQueryRelations<EntitySchema$1, R>, opts?: StatementOptions & {
+    count?: boolean;
+  }): Promise<Page<PgStatic<EntitySchema$1, R>>>;
   /**
    * Find an entity by ID.
+   *
+   * This is a convenience method for `findOne` with a where clause on the primary key.
+   * If you need more complex queries, use `findOne` instead.
    */
-  findById(id: string | number, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  findById(id: string | number, opts?: StatementOptions): Promise<Static<EntitySchema$1>>;
   /**
-   * Paginate entities.
+   * Helper to create a type-safe query object.
    */
-  paginate(pagination?: PageQuery, query?: PgQuery<EntitySchema>, opts?: StatementOptions & {
-    count?: boolean;
-  }): Promise<Page<Static<EntitySchema>>>;
-  createQuery(query?: PgQuery<EntitySchema>): PgQuery<EntitySchema>;
-  createQueryWhere(where?: PgQueryWhere<EntitySchema>): PgQueryWhere<EntitySchema>;
+  createQuery(): PgQuery<EntitySchema$1>;
+  /**
+   * Helper to create a type-safe where clause.
+   */
+  createQueryWhere(): PgQueryWhere<EntitySchema$1>;
   /**
    * Create an entity.
    *
@@ -1593,7 +1659,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: Static<TObjectInsert<EntitySchema>>, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  create(data: Static<TObjectInsert<EntitySchema$1>>, opts?: StatementOptions): Promise<Static<EntitySchema$1>>;
   /**
    * Create many entities.
    *
@@ -1601,11 +1667,11 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    * @param opts The statement options.
    * @returns The created entities.
    */
-  createMany(values: Array<Static<TObjectInsert<EntitySchema>>>, opts?: StatementOptions): Promise<Static<EntitySchema>[]>;
+  createMany(values: Array<Static<TObjectInsert<EntitySchema$1>>>, opts?: StatementOptions): Promise<Static<EntitySchema$1>[]>;
   /**
    * Find an entity and update it.
    */
-  updateOne(where: PgQueryWhereOrSQL<EntitySchema>, data: Partial<Static<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  updateOne(where: PgQueryWhereOrSQL<EntitySchema$1>, data: Partial<Static<TObjectUpdate<EntitySchema$1>>>, opts?: StatementOptions): Promise<Static<EntitySchema$1>>;
   /**
    * Save a given entity.
    *
@@ -1627,19 +1693,19 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    * @see {@link PostgresTypeProvider#version}
    * @see {@link PgVersionMismatchError}
    */
-  save(entity: Static<EntitySchema>, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  save(entity: Static<EntitySchema$1>, opts?: StatementOptions): Promise<Static<EntitySchema$1>>;
   /**
    * Find an entity by ID and update it.
    */
-  updateById(id: string | number, data: Partial<Static<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<Static<EntitySchema>>;
+  updateById(id: string | number, data: Partial<Static<TObjectUpdate<EntitySchema$1>>>, opts?: StatementOptions): Promise<Static<EntitySchema$1>>;
   /**
    * Find many entities and update all of them.
    */
-  updateMany(where: PgQueryWhereOrSQL<EntitySchema>, data: Partial<Static<TObjectUpdate<EntitySchema>>>, opts?: StatementOptions): Promise<void>;
+  updateMany(where: PgQueryWhereOrSQL<EntitySchema$1>, data: Partial<Static<TObjectUpdate<EntitySchema$1>>>, opts?: StatementOptions): Promise<void>;
   /**
    * Find many and delete all of them.
    */
-  deleteMany(where?: PgQueryWhereOrSQL<EntitySchema>, opts?: StatementOptions): Promise<void>;
+  deleteMany(where?: PgQueryWhereOrSQL<EntitySchema$1>, opts?: StatementOptions): Promise<void>;
   /**
    * Delete all entities.
    */
@@ -1649,11 +1715,11 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    *
    * You must fetch the entity first in order to delete it.
    */
-  destroy(entity: Static<EntitySchema>, opts?: StatementOptions): Promise<void>;
+  destroy(entity: Static<EntitySchema$1>, opts?: StatementOptions): Promise<void>;
   /**
    * Find an entity and delete it.
    */
-  deleteOne(where?: PgQueryWhereOrSQL<EntitySchema>, opts?: StatementOptions): Promise<void>;
+  deleteOne(where?: PgQueryWhereOrSQL<EntitySchema$1>, opts?: StatementOptions): Promise<void>;
   /**
    * Find an entity by ID and delete it.
    */
@@ -1661,87 +1727,45 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
   /**
    * Count entities.
    */
-  count(where?: PgQueryWhereOrSQL<EntitySchema>, opts?: StatementOptions): Promise<number>;
+  count(where?: PgQueryWhereOrSQL<EntitySchema$1>, opts?: StatementOptions): Promise<number>;
   protected conflictMessagePattern: string;
   protected handleError(error: unknown, message: string): PgError;
-  protected withDeletedAt(where: PgQueryWhereOrSQL<EntitySchema>, opts?: {
+  protected withDeletedAt(where: PgQueryWhereOrSQL<EntitySchema$1>, opts?: {
     force?: boolean;
-  }): PgQueryWhereOrSQL<EntitySchema>;
-  protected get organization(): undefined;
+  }): PgQueryWhereOrSQL<EntitySchema$1>;
   protected deletedAt(): PgAttrField | undefined;
   /**
-   * Convert a query object to a SQL query.
-   *
-   * @param query The query object.
-   * @param schema The schema to use.
-   * @param col The column to use.
-   */
-  protected jsonQueryToSql(query: PgQueryWhereOrSQL<EntitySchema>, schema?: TObject, col?: (key: string) => PgColumn): SQL | undefined;
-  /**
-   * Map a filter operator to a SQL query.
-   *
-   * @param operator
-   * @param column
-   * @protected
+   * Convert something to valid Pg Insert Value.
    */
-  protected mapOperatorToSql(operator: FilterOperators<any> | any, column: PgColumn): SQL | undefined;
+  protected cast(data: any, insert: boolean): PgInsertValue<PgTableWithColumns<EntityTableConfig$1>>;
   /**
-   * Create a pagination object.
+   * Transform a row from the database into a clean entity.
    *
-   * @param entities The entities to paginate.
-   * @param limit The limit of the pagination.
-   * @param offset The offset of the pagination.
+   * - Validate against schema
+   * - Replace all null values by undefined
+   * - Fix date-time and date fields to ISO strings
+   * - Cast BigInt to string
    */
-  protected createPagination(entities: Static<EntitySchema>[], limit?: number, offset?: number): Page<Static<EntitySchema>>;
+  protected clean<T extends TObject = EntitySchema$1>(row: Record<string, unknown>, schema?: T): Static<T>;
   /**
-   * Convert something to valid Pg Insert Value.
+   * Clean a row with joins recursively
    */
-  protected cast(data: any, insert: boolean): PgInsertValue<PgTableWithColumns<EntityTableConfig>>;
+  protected cleanWithJoins<T extends TObject = EntitySchema$1>(row: Record<string, unknown>, schema: T, joins: PgJoin[], parentPath?: string): Static<T>;
   /**
-   * Clean a row. Remove all null values.
-   *
-   * @param row The row to clean.
-   * @param schema The schema to use.
-   * @returns The cleaned row.
+   * Build a schema that includes all join properties recursively
    */
-  protected clean<T extends TObject = EntitySchema>(row: any, schema?: T): Static<T>;
+  protected buildSchemaWithJoins(baseSchema: TObject, joins: PgJoin[], parentPath?: string): TObject;
   /**
-   * Parse pagination sort string to orderBy format.
-   * Format: "firstName,-lastName" -> [{ column: "firstName", direction: "asc" }, { column: "lastName", direction: "desc" }]
-   * - Columns separated by comma
-   * - Prefix with '-' for DESC direction
-   *
-   * @param sort Pagination sort string
-   * @returns OrderBy array or single object
+   * Convert a where clause to SQL.
    */
-  protected parsePaginationSort(sort: string): Array<{
-    column: string;
-    direction: "asc" | "desc";
-  }> | {
-    column: string;
-    direction: "asc" | "desc";
-  };
-  /**
-   * Normalize orderBy parameter to array format.
-   * Supports 3 modes:
-   * 1. String: "name" -> [{ column: "name", direction: "asc" }]
-   * 2. Object: { column: "name", direction: "desc" } -> [{ column: "name", direction: "desc" }]
-   * 3. Array: [{ column: "name" }, { column: "age", direction: "desc" }] -> normalized array
-   *
-   * @param orderBy The orderBy parameter
-   * @returns Normalized array of order by clauses
-   */
-  protected normalizeOrderBy(orderBy: any): Array<{
-    column: string;
-    direction: "asc" | "desc";
-  }>;
+  protected toSQL(where: PgQueryWhereOrSQL<EntitySchema$1>, joins?: PgJoin[]): SQL | undefined;
   /**
    * Get the where clause for an ID.
    *
    * @param id The ID to get the where clause for.
    * @returns The where clause for the ID.
    */
-  protected getWhereId(id: string | number): PgQueryWhereOrSQL<EntitySchema>;
+  protected getWhereId(id: string | number): PgQueryWhere<EntitySchema$1>;
   /**
    * Find a primary key in the schema.
    *
@@ -1750,7 +1774,7 @@ declare class RepositoryDescriptor<EntityTableConfig extends TableConfig, Entity
    */
   protected getPrimaryKey(schema: TObject): {
     key: string;
-    col: PgColumn<drizzle_orm7.ColumnBaseConfig<drizzle_orm7.ColumnDataType, string>, {}, {}>;
+    col: PgColumn<drizzle_orm6.ColumnBaseConfig<drizzle_orm6.ColumnDataType, string>, {}, {}>;
     type: TSchema$1;
   };
 }
@@ -2164,7 +2188,7 @@ declare class SequenceDescriptor extends Descriptor<SequenceDescriptorOptions> {
  * - Use appropriate isolation levels based on your consistency requirements
  */
 declare const $transaction: <T extends any[], R>(opts: TransactionDescriptorOptions<T, R>) => _alepha_retry0.RetryDescriptorFn<(...args: T) => Promise<R>>;
-interface TransactionDescriptorOptions<T extends any[], R> {
+interface TransactionDescriptorOptions<T$1 extends any[], R$1> {
   /**
    * Transaction handler function that contains all database operations to be executed atomically.
    *
@@ -2224,7 +2248,7 @@ interface TransactionDescriptorOptions<T extends any[], R> {
    * }
    * ```
    */
-  handler: (tx: PgTransaction<any, any, any>, ...args: T) => Promise<R>;
+  handler: (tx: PgTransaction<any, any, any>, ...args: T$1) => Promise<R$1>;
   /**
    * PostgreSQL transaction configuration options.
    *
@@ -2268,6 +2292,12 @@ interface TransactionDescriptorOptions<T extends any[], R> {
 }
 type TransactionContext = PgTransaction<any, any, any>;
 //#endregion
+//#region src/errors/PgConflictError.d.ts
+declare class PgConflictError extends PgError {
+  readonly name = "PgConflictError";
+  readonly status = 409;
+}
+//#endregion
 //#region src/errors/PgEntityNotFoundError.d.ts
 declare class PgEntityNotFoundError extends PgError {
   readonly name = "EntityNotFoundError";
@@ -2275,6 +2305,23 @@ declare class PgEntityNotFoundError extends PgError {
   constructor(entityName: string);
 }
 //#endregion
+//#region src/errors/PgMigrationError.d.ts
+declare class PgMigrationError extends PgError {
+  readonly name = "PgMigrationError";
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/errors/PgVersionMismatchError.d.ts
+/**
+ * Error thrown when there is a version mismatch.
+ * It's thrown by {@link RepositoryDescriptor#save} when the updated entity version does not match the one in the database.
+ * This is used for optimistic concurrency control.
+ */
+declare class PgVersionMismatchError extends PgError {
+  readonly name = "PgVersionMismatchError";
+  constructor(table: string, id: any);
+}
+//#endregion
 //#region src/providers/RepositoryProvider.d.ts
 declare class RepositoryProvider {
   protected readonly log: _alepha_logger1.Logger;
@@ -2480,7 +2527,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?: TStringOptions) => PgAttr<typebox1.TOptional<TString>, typeof PG_DELETED_AT>;
+  readonly deletedAt: (options?: TStringOptions) => PgAttr<typebox0.TOptional<TString>, typeof PG_DELETED_AT>;
   /**
    * Creates a reference to another table or schema. Basically a foreign key.
    */
@@ -2502,13 +2549,13 @@ declare const pg: PostgresTypeProvider;
 /**
  * @deprecated Use `pg.primaryKey()` instead.
  */
-declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<typebox1.TInteger, typeof PG_PRIMARY_KEY>, typeof PG_SERIAL>, typeof PG_DEFAULT>;
+declare const legacyIdSchema: PgAttr<PgAttr<PgAttr<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$1>(name: string, document: TDocument) => drizzle_orm7.$Type<pg$1.PgCustomColumnBuilder<{
+declare const schema: <TDocument extends TSchema$1>(name: string, document: TDocument) => drizzle_orm6.$Type<pg$1.PgCustomColumnBuilder<{
   name: string;
   dataType: "custom";
   columnType: "PgCustomColumn";
@@ -2560,5 +2607,5 @@ declare const schema: <TDocument extends TSchema$1>(name: string, document: TDoc
  */
 declare const AlephaPostgres: _alepha_core1.Service<_alepha_core1.Module<{}>>;
 //#endregion
-export { $entity, $repository, $sequence, $transaction, AlephaPostgres, DrizzleKitProvider, Entity, EntityDescriptorOptions, ExtractManyRelations, FilterOperators, FromSchema, NodePostgresProvider, NodePostgresProviderOptions, OrderBy, OrderByClause, OrderDirection, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_IDENTITY, PG_MANY, PG_ONE, PG_PRIMARY_KEY, PG_REF, PG_SCHEMA, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Page, PageQuery, PgAttr, PgAttrField, PgDefault, PgEntityNotFoundError, PgIdentityOptions, PgMany, PgManyOptions, PgOne, PgPrimaryKey, PgQuery, PgQueryWhere, PgQueryWhereOrSQL, PgQueryWhereWithMany, PgQueryWhereWithManyOrSQL, PgQueryWithMany, PgQueryWithMap, PgQueryWithOne, PgRef, PgRefOptions, PgSymbolKeys, PgSymbols, PgTableConfig, PgTableWithColumnsAndSchema, PostgresProvider, PostgresTypeProvider, RelField, RemoveManyRelations, RepositoryDescriptor, RepositoryDescriptorOptions, RepositoryProvider, SQLLike, SequenceDescriptor, SequenceDescriptorOptions, StatementOptions, TObjectInsert, TObjectUpdate, TPage, TransactionContext, TransactionDescriptorOptions, camelToSnakeCase, drizzle_orm7 as drizzle, getAttrFields, insertSchema, legacyIdSchema, mapFieldToColumn, mapStringToColumn, pageQuerySchema, pageSchema, pg, pgAttr, schema, schemaToPgColumns, sql, updateSchema };
+export { $entity, $repository, $sequence, $transaction, AlephaPostgres, DrizzleKitProvider, Entity, EntityDescriptorOptions, FilterOperators, FromSchema, NodePostgresProvider, NodePostgresProviderOptions, OrderBy, OrderByClause, OrderDirection, PG_CREATED_AT, PG_DEFAULT, PG_DELETED_AT, PG_IDENTITY, PG_MANY, PG_ONE, PG_PRIMARY_KEY, PG_REF, PG_SCHEMA, PG_SERIAL, PG_UPDATED_AT, PG_VERSION, Page, PageQuery, PgAttr, PgAttrField, PgConflictError, PgDefault, PgEntityNotFoundError, PgError, PgIdentityOptions, PgMany, PgManyOptions, PgMigrationError, PgOne, PgPrimaryKey, PgQuery, PgQueryRelations, PgQueryWhere, PgQueryWhereOrSQL, PgRef, PgRefOptions, PgRelation, PgRelationMap, PgStatic, PgSymbolKeys, PgSymbols, PgTableConfig, PgTableWithColumnsAndSchema, PgVersionMismatchError, PostgresProvider, PostgresTypeProvider, RepositoryDescriptor, RepositoryDescriptorOptions, RepositoryProvider, SQLLike, SequenceDescriptor, SequenceDescriptorOptions, StatementOptions, TObjectInsert, TObjectUpdate, TPage, TransactionContext, TransactionDescriptorOptions, camelToSnakeCase, drizzle_orm6 as drizzle, getAttrFields, insertSchema, legacyIdSchema, mapFieldToColumn, mapStringToColumn, pageQuerySchema, pageSchema, pg, pgAttr, schema, schemaToPgColumns, sql, updateSchema };
 //# sourceMappingURL=index.d.ts.map