metal-orm 1.0.59 → 1.0.60

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -3540,6 +3540,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3540
3540
  /**
3541
3541
  * Applies an alias to the root FROM table.
3542
3542
  * @param alias - Alias to apply
3543
+ * @example
3544
+ * const qb = new SelectQueryBuilder(userTable).as('u');
3543
3545
  */
3544
3546
  as(alias: string): SelectQueryBuilder<T, TTable>;
3545
3547
  /**
@@ -3567,6 +3569,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3567
3569
  * Can be called with column names or a projection object.
3568
3570
  * @param args - Column names or projection object
3569
3571
  * @returns New query builder instance with selected columns
3572
+ * @example
3573
+ * // Select specific columns
3574
+ * qb.select('id', 'name', 'email');
3575
+ * @example
3576
+ * // Select with aliases and expressions
3577
+ * qb.select({
3578
+ * id: userTable.columns.id,
3579
+ * fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
3580
+ * });
3570
3581
  */
3571
3582
  select<K extends keyof TTable['columns'] & string>(...args: K[]): SelectQueryBuilder<T, TTable>;
3572
3583
  select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
@@ -3574,6 +3585,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3574
3585
  * Selects raw column expressions
3575
3586
  * @param cols - Column expressions as strings
3576
3587
  * @returns New query builder instance with raw column selections
3588
+ * @example
3589
+ * qb.selectRaw('COUNT(*) as total', 'UPPER(name) as upper_name');
3577
3590
  */
3578
3591
  selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable>;
3579
3592
  /**
@@ -3582,6 +3595,12 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3582
3595
  * @param query - Query builder or query node for the CTE
3583
3596
  * @param columns - Optional column names for the CTE
3584
3597
  * @returns New query builder instance with the CTE
3598
+ * @example
3599
+ * const recentUsers = new SelectQueryBuilder(userTable)
3600
+ * .where(gt(userTable.columns.createdAt, subDays(now(), 30)));
3601
+ * const qb = new SelectQueryBuilder(userTable)
3602
+ * .with('recent_users', recentUsers)
3603
+ * .from('recent_users');
3585
3604
  */
3586
3605
  with<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
3587
3606
  /**
@@ -3590,6 +3609,19 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3590
3609
  * @param query - Query builder or query node for the CTE
3591
3610
  * @param columns - Optional column names for the CTE
3592
3611
  * @returns New query builder instance with the recursive CTE
3612
+ * @example
3613
+ * // Base case: select root nodes
3614
+ * const baseQuery = new SelectQueryBuilder(orgTable)
3615
+ * .where(eq(orgTable.columns.parentId, 1));
3616
+ * // Recursive case: join with the CTE itself
3617
+ * const recursiveQuery = new SelectQueryBuilder(orgTable)
3618
+ * .join('org_hierarchy', 'oh', eq(orgTable.columns.parentId, col('oh.id')));
3619
+ * // Combine base and recursive parts
3620
+ * const orgHierarchy = baseQuery.union(recursiveQuery);
3621
+ * // Use in main query
3622
+ * const qb = new SelectQueryBuilder(orgTable)
3623
+ * .withRecursive('org_hierarchy', orgHierarchy)
3624
+ * .from('org_hierarchy');
3593
3625
  */
3594
3626
  withRecursive<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
3595
3627
  /**
@@ -3598,6 +3630,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3598
3630
  * @param alias - Alias for the derived table
3599
3631
  * @param columnAliases - Optional column alias list
3600
3632
  * @returns New query builder instance with updated FROM
3633
+ * @example
3634
+ * const subquery = new SelectQueryBuilder(userTable)
3635
+ * .select('id', 'name')
3636
+ * .where(gt(userTable.columns.score, 100));
3637
+ * qb.fromSubquery(subquery, 'high_scorers', ['userId', 'userName']);
3601
3638
  */
3602
3639
  fromSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3603
3640
  /**
@@ -3606,6 +3643,13 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3606
3643
  * @param args - Optional function arguments
3607
3644
  * @param alias - Optional alias for the function table
3608
3645
  * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
3646
+ * @example
3647
+ * qb.fromFunctionTable(
3648
+ * 'generate_series',
3649
+ * [literal(1), literal(10), literal(1)],
3650
+ * 'series',
3651
+ * { columnAliases: ['value'] }
3652
+ * );
3609
3653
  */
3610
3654
  fromFunctionTable(name: string, args?: OperandNode[], alias?: string, options?: {
3611
3655
  lateral?: boolean;
@@ -3618,6 +3662,12 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3618
3662
  * @param alias - Alias for the subquery column
3619
3663
  * @param sub - Query builder or query node for the subquery
3620
3664
  * @returns New query builder instance with the subquery selection
3665
+ * @example
3666
+ * const postCount = new SelectQueryBuilder(postTable)
3667
+ * .select(count(postTable.columns.id))
3668
+ * .where(eq(postTable.columns.userId, col('u.id')));
3669
+ * qb.select('id', 'name')
3670
+ * .selectSubquery('postCount', postCount);
3621
3671
  */
3622
3672
  selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3623
3673
  /**
@@ -3628,6 +3678,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3628
3678
  * @param joinKind - Join kind (defaults to INNER)
3629
3679
  * @param columnAliases - Optional column alias list for the derived table
3630
3680
  * @returns New query builder instance with the derived-table join
3681
+ * @example
3682
+ * const activeUsers = new SelectQueryBuilder(userTable)
3683
+ * .where(eq(userTable.columns.active, true));
3684
+ * qb.joinSubquery(
3685
+ * activeUsers,
3686
+ * 'au',
3687
+ * eq(col('t.userId'), col('au.id')),
3688
+ * JOIN_KINDS.LEFT
3689
+ * );
3631
3690
  */
3632
3691
  joinSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3633
3692
  /**
@@ -3638,6 +3697,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3638
3697
  * @param condition - Join condition expression
3639
3698
  * @param joinKind - Kind of join (defaults to INNER)
3640
3699
  * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
3700
+ * @example
3701
+ * qb.joinFunctionTable(
3702
+ * 'generate_series',
3703
+ * [literal(1), literal(10)],
3704
+ * 'gs',
3705
+ * eq(col('t.value'), col('gs.value')),
3706
+ * JOIN_KINDS.INNER,
3707
+ * { columnAliases: ['value'] }
3708
+ * );
3641
3709
  */
3642
3710
  joinFunctionTable(name: string, args: OperandNode[], alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, options?: {
3643
3711
  lateral?: boolean;
@@ -3650,6 +3718,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3650
3718
  * @param table - Table to join
3651
3719
  * @param condition - Join condition expression
3652
3720
  * @returns New query builder instance with the INNER JOIN
3721
+ * @example
3722
+ * qb.innerJoin(
3723
+ * postTable,
3724
+ * eq(userTable.columns.id, postTable.columns.userId)
3725
+ * );
3653
3726
  */
3654
3727
  innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3655
3728
  /**
@@ -3657,6 +3730,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3657
3730
  * @param table - Table to join
3658
3731
  * @param condition - Join condition expression
3659
3732
  * @returns New query builder instance with the LEFT JOIN
3733
+ * @example
3734
+ * qb.leftJoin(
3735
+ * postTable,
3736
+ * eq(userTable.columns.id, postTable.columns.userId)
3737
+ * );
3660
3738
  */
3661
3739
  leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3662
3740
  /**
@@ -3664,6 +3742,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3664
3742
  * @param table - Table to join
3665
3743
  * @param condition - Join condition expression
3666
3744
  * @returns New query builder instance with the RIGHT JOIN
3745
+ * @example
3746
+ * qb.rightJoin(
3747
+ * postTable,
3748
+ * eq(userTable.columns.id, postTable.columns.userId)
3749
+ * );
3667
3750
  */
3668
3751
  rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3669
3752
  /**
@@ -3671,6 +3754,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3671
3754
  * @param relationName - Name of the relationship to match
3672
3755
  * @param predicate - Optional predicate expression
3673
3756
  * @returns New query builder instance with the relationship match
3757
+ * @example
3758
+ * qb.match('posts', eq(postTable.columns.published, true));
3674
3759
  */
3675
3760
  match<K extends keyof TTable['relations'] & string>(relationName: K, predicate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3676
3761
  /**
@@ -3679,6 +3764,10 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3679
3764
  * @param joinKind - Type of join (defaults to INNER)
3680
3765
  * @param extraCondition - Optional additional join condition
3681
3766
  * @returns New query builder instance with the relationship join
3767
+ * @example
3768
+ * qb.joinRelation('posts', JOIN_KINDS.LEFT);
3769
+ * @example
3770
+ * qb.joinRelation('posts', JOIN_KINDS.INNER, eq(postTable.columns.published, true));
3682
3771
  */
3683
3772
  joinRelation<K extends keyof TTable['relations'] & string>(relationName: K, joinKind?: JoinKind, extraCondition?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3684
3773
  /**
@@ -3686,6 +3775,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3686
3775
  * @param relationName - Name of the relationship to include
3687
3776
  * @param options - Optional include options
3688
3777
  * @returns New query builder instance with the relationship inclusion
3778
+ * @example
3779
+ * qb.include('posts');
3780
+ * @example
3781
+ * qb.include('posts', { columns: ['id', 'title', 'published'] });
3782
+ * @example
3783
+ * qb.include('posts', {
3784
+ * columns: ['id', 'title'],
3785
+ * where: eq(postTable.columns.published, true)
3786
+ * });
3689
3787
  */
3690
3788
  include<K extends keyof TTable['relations'] & string>(relationName: K, options?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
3691
3789
  /**
@@ -3693,16 +3791,28 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3693
3791
  * @param relationName - Name of the relation to include lazily
3694
3792
  * @param options - Optional include options for lazy loading
3695
3793
  * @returns New query builder instance with lazy relation inclusion
3794
+ * @example
3795
+ * const qb = new SelectQueryBuilder(userTable).includeLazy('posts');
3796
+ * const users = await qb.execute(session);
3797
+ * // Access posts later - they will be loaded on demand
3798
+ * const posts = await users[0].posts;
3696
3799
  */
3697
3800
  includeLazy<K extends keyof RelationMap<TTable>>(relationName: K, options?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
3698
3801
  /**
3699
3802
  * Convenience alias for including only specific columns from a relation.
3803
+ * @example
3804
+ * qb.includePick('posts', ['id', 'title', 'createdAt']);
3700
3805
  */
3701
3806
  includePick<K extends keyof TTable['relations'] & string, C extends RelationTargetColumns<TTable['relations'][K]>>(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable>;
3702
3807
  /**
3703
3808
  * Selects columns for the root table and relations from an array of entries
3704
3809
  * @param config - Configuration array for deep column selection
3705
3810
  * @returns New query builder instance with deep column selections
3811
+ * @example
3812
+ * qb.selectColumnsDeep([
3813
+ * { type: 'root', columns: ['id', 'name'] },
3814
+ * { type: 'relation', relationName: 'posts', columns: ['id', 'title'] }
3815
+ * ]);
3706
3816
  */
3707
3817
  selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable>;
3708
3818
  /**
@@ -3724,6 +3834,10 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3724
3834
  * Executes the query and returns hydrated results
3725
3835
  * @param ctx - ORM session context
3726
3836
  * @returns Promise of entity instances
3837
+ * @example
3838
+ * const users = await qb.select('id', 'name')
3839
+ * .where(eq(userTable.columns.active, true))
3840
+ * .execute(session);
3727
3841
  */
3728
3842
  execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]>;
3729
3843
  /**
@@ -3751,24 +3865,42 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3751
3865
  * @param execCtx - Execution context
3752
3866
  * @param hydCtx - Hydration context
3753
3867
  * @returns Promise of entity instances
3868
+ * @example
3869
+ * const execCtx = new ExecutionContext(session);
3870
+ * const hydCtx = new HydrationContext();
3871
+ * const users = await qb.executeWithContexts(execCtx, hydCtx);
3754
3872
  */
3755
3873
  executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]>;
3756
3874
  /**
3757
3875
  * Adds a WHERE condition to the query
3758
3876
  * @param expr - Expression for the WHERE clause
3759
3877
  * @returns New query builder instance with the WHERE condition
3878
+ * @example
3879
+ * qb.where(eq(userTable.columns.id, 1));
3880
+ * @example
3881
+ * qb.where(and(
3882
+ * eq(userTable.columns.active, true),
3883
+ * gt(userTable.columns.createdAt, subDays(now(), 30))
3884
+ * ));
3760
3885
  */
3761
3886
  where(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
3762
3887
  /**
3763
3888
  * Adds a GROUP BY clause to the query
3764
3889
  * @param term - Column definition or ordering term to group by
3765
3890
  * @returns New query builder instance with the GROUP BY clause
3891
+ * @example
3892
+ * qb.select('departmentId', count(userTable.columns.id))
3893
+ * .groupBy(userTable.columns.departmentId);
3766
3894
  */
3767
3895
  groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable>;
3768
3896
  /**
3769
3897
  * Adds a HAVING condition to the query
3770
3898
  * @param expr - Expression for the HAVING clause
3771
3899
  * @returns New query builder instance with the HAVING condition
3900
+ * @example
3901
+ * qb.select('departmentId', count(userTable.columns.id))
3902
+ * .groupBy(userTable.columns.departmentId)
3903
+ * .having(gt(count(userTable.columns.id), 5));
3772
3904
  */
3773
3905
  having(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
3774
3906
  /**
@@ -3789,54 +3921,95 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3789
3921
  * Adds a DISTINCT clause to the query
3790
3922
  * @param cols - Columns to make distinct
3791
3923
  * @returns New query builder instance with the DISTINCT clause
3924
+ * @example
3925
+ * qb.distinct(userTable.columns.email);
3926
+ * @example
3927
+ * qb.distinct(userTable.columns.firstName, userTable.columns.lastName);
3792
3928
  */
3793
3929
  distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable>;
3794
3930
  /**
3795
3931
  * Adds a LIMIT clause to the query
3796
3932
  * @param n - Maximum number of rows to return
3797
3933
  * @returns New query builder instance with the LIMIT clause
3934
+ * @example
3935
+ * qb.limit(10);
3936
+ * @example
3937
+ * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
3798
3938
  */
3799
3939
  limit(n: number): SelectQueryBuilder<T, TTable>;
3800
3940
  /**
3801
3941
  * Adds an OFFSET clause to the query
3802
3942
  * @param n - Number of rows to skip
3803
3943
  * @returns New query builder instance with the OFFSET clause
3944
+ * @example
3945
+ * qb.offset(10);
3946
+ * @example
3947
+ * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
3804
3948
  */
3805
3949
  offset(n: number): SelectQueryBuilder<T, TTable>;
3806
3950
  /**
3807
3951
  * Combines this query with another using UNION
3808
3952
  * @param query - Query to union with
3809
3953
  * @returns New query builder instance with the set operation
3954
+ * @example
3955
+ * const activeUsers = new SelectQueryBuilder(userTable)
3956
+ * .where(eq(userTable.columns.active, true));
3957
+ * const inactiveUsers = new SelectQueryBuilder(userTable)
3958
+ * .where(eq(userTable.columns.active, false));
3959
+ * qb.union(activeUsers).union(inactiveUsers);
3810
3960
  */
3811
3961
  union<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3812
3962
  /**
3813
3963
  * Combines this query with another using UNION ALL
3814
3964
  * @param query - Query to union with
3815
3965
  * @returns New query builder instance with the set operation
3966
+ * @example
3967
+ * const q1 = new SelectQueryBuilder(userTable).where(gt(userTable.columns.score, 80));
3968
+ * const q2 = new SelectQueryBuilder(userTable).where(lt(userTable.columns.score, 20));
3969
+ * qb.unionAll(q1).unionAll(q2);
3816
3970
  */
3817
3971
  unionAll<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3818
3972
  /**
3819
3973
  * Combines this query with another using INTERSECT
3820
3974
  * @param query - Query to intersect with
3821
3975
  * @returns New query builder instance with the set operation
3976
+ * @example
3977
+ * const activeUsers = new SelectQueryBuilder(userTable)
3978
+ * .where(eq(userTable.columns.active, true));
3979
+ * const premiumUsers = new SelectQueryBuilder(userTable)
3980
+ * .where(eq(userTable.columns.premium, true));
3981
+ * qb.intersect(activeUsers).intersect(premiumUsers);
3822
3982
  */
3823
3983
  intersect<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3824
3984
  /**
3825
3985
  * Combines this query with another using EXCEPT
3826
3986
  * @param query - Query to subtract
3827
3987
  * @returns New query builder instance with the set operation
3988
+ * @example
3989
+ * const allUsers = new SelectQueryBuilder(userTable);
3990
+ * const inactiveUsers = new SelectQueryBuilder(userTable)
3991
+ * .where(eq(userTable.columns.active, false));
3992
+ * qb.except(allUsers).except(inactiveUsers); // Only active users
3828
3993
  */
3829
3994
  except<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3830
3995
  /**
3831
3996
  * Adds a WHERE EXISTS condition to the query
3832
3997
  * @param subquery - Subquery to check for existence
3833
3998
  * @returns New query builder instance with the WHERE EXISTS condition
3999
+ * @example
4000
+ * const postsQuery = new SelectQueryBuilder(postTable)
4001
+ * .where(eq(postTable.columns.userId, col('u.id')));
4002
+ * qb.whereExists(postsQuery);
3834
4003
  */
3835
4004
  whereExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3836
4005
  /**
3837
4006
  * Adds a WHERE NOT EXISTS condition to the query
3838
4007
  * @param subquery - Subquery to check for non-existence
3839
4008
  * @returns New query builder instance with the WHERE NOT EXISTS condition
4009
+ * @example
4010
+ * const postsQuery = new SelectQueryBuilder(postTable)
4011
+ * .where(eq(postTable.columns.userId, col('u.id')));
4012
+ * qb.whereNotExists(postsQuery); // Users without posts
3840
4013
  */
3841
4014
  whereNotExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3842
4015
  /**
@@ -3863,22 +4036,39 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
3863
4036
  * Compiles the query to SQL for a specific dialect
3864
4037
  * @param dialect - Database dialect to compile for
3865
4038
  * @returns Compiled query with SQL and parameters
4039
+ * @example
4040
+ * const compiled = qb.select('id', 'name')
4041
+ * .where(eq(userTable.columns.active, true))
4042
+ * .compile('postgres');
4043
+ * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
3866
4044
  */
3867
4045
  compile(dialect: SelectDialectInput): CompiledQuery;
3868
4046
  /**
3869
4047
  * Converts the query to SQL string for a specific dialect
3870
4048
  * @param dialect - Database dialect to generate SQL for
3871
4049
  * @returns SQL string representation of the query
4050
+ * @example
4051
+ * const sql = qb.select('id', 'name')
4052
+ * .where(eq(userTable.columns.active, true))
4053
+ * .toSql('postgres');
4054
+ * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
3872
4055
  */
3873
4056
  toSql(dialect: SelectDialectInput): string;
3874
4057
  /**
3875
4058
  * Gets the hydration plan for the query
3876
4059
  * @returns Hydration plan or undefined if none exists
4060
+ * @example
4061
+ * const plan = qb.include('posts').getHydrationPlan();
4062
+ * console.log(plan?.relations); // Information about included relations
3877
4063
  */
3878
4064
  getHydrationPlan(): HydrationPlan | undefined;
3879
4065
  /**
3880
4066
  * Gets the Abstract Syntax Tree (AST) representation of the query
3881
4067
  * @returns Query AST with hydration applied
4068
+ * @example
4069
+ * const ast = qb.select('id', 'name').getAST();
4070
+ * console.log(ast.columns); // Array of column nodes
4071
+ * console.log(ast.from); // From clause information
3882
4072
  */
3883
4073
  getAST(): SelectQueryNode;
3884
4074
  }
@@ -4277,6 +4467,68 @@ declare class DeleteQueryBuilder<T> {
4277
4467
  getAST(): DeleteQueryNode;
4278
4468
  }
4279
4469
 
4470
+ /**
4471
+ * Represents a target for query operations, which can be either a table definition
4472
+ * or an entity constructor. This type allows flexible targeting of database tables
4473
+ * through either direct table definitions or entity classes decorated with ORM metadata.
4474
+ *
4475
+ * @template TTable - The table definition type, defaults to TableDef
4476
+ */
4477
+ type QueryTarget<TTable extends TableDef = TableDef> = TTable | EntityConstructor;
4478
+
4479
+ /**
4480
+ * Creates a SELECT query builder for the specified table or entity.
4481
+ *
4482
+ * @template TTable - The table definition type
4483
+ * @param target - The table definition or entity constructor to query from
4484
+ * @returns A new SelectQueryBuilder instance for building SELECT queries
4485
+ *
4486
+ * @example
4487
+ * ```typescript
4488
+ * const query = selectFrom(UserTable).select('id', 'name');
4489
+ * ```
4490
+ */
4491
+ declare const selectFrom: <TTable extends TableDef>(target: QueryTarget<TTable>) => SelectQueryBuilder<unknown, TTable>;
4492
+ /**
4493
+ * Creates an INSERT query builder for the specified table or entity.
4494
+ *
4495
+ * @template TTable - The table definition type
4496
+ * @param target - The table definition or entity constructor to insert into
4497
+ * @returns A new InsertQueryBuilder instance for building INSERT queries
4498
+ *
4499
+ * @example
4500
+ * ```typescript
4501
+ * const query = insertInto(UserTable).values({ name: 'John', email: 'john@example.com' });
4502
+ * ```
4503
+ */
4504
+ declare const insertInto: <TTable extends TableDef>(target: QueryTarget<TTable>) => InsertQueryBuilder<unknown>;
4505
+ /**
4506
+ * Creates an UPDATE query builder for the specified table or entity.
4507
+ *
4508
+ * @template TTable - The table definition type
4509
+ * @param target - The table definition or entity constructor to update
4510
+ * @returns A new UpdateQueryBuilder instance for building UPDATE queries
4511
+ *
4512
+ * @example
4513
+ * ```typescript
4514
+ * const query = update(UserTable).set({ name: 'Jane' }).where(eq(UserTable.id, 1));
4515
+ * ```
4516
+ */
4517
+ declare const update: <TTable extends TableDef>(target: QueryTarget<TTable>) => UpdateQueryBuilder<unknown>;
4518
+ /**
4519
+ * Creates a DELETE query builder for the specified table or entity.
4520
+ *
4521
+ * @template TTable - The table definition type
4522
+ * @param target - The table definition or entity constructor to delete from
4523
+ * @returns A new DeleteQueryBuilder instance for building DELETE queries
4524
+ *
4525
+ * @example
4526
+ * ```typescript
4527
+ * const query = deleteFrom(UserTable).where(eq(UserTable.id, 1));
4528
+ * ```
4529
+ */
4530
+ declare const deleteFrom: <TTable extends TableDef>(target: QueryTarget<TTable>) => DeleteQueryBuilder<unknown>;
4531
+
4280
4532
  /**
4281
4533
  * Strategy interface for compiling pagination clauses.
4282
4534
  * Allows dialects to customize how pagination (LIMIT/OFFSET, ROWS FETCH, etc.) is generated.
@@ -6158,4 +6410,4 @@ type PooledExecutorFactoryOptions<TConn> = {
6158
6410
  */
6159
6411
  declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
6160
6412
 
6161
- export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };
6413
+ export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };