metal-orm 1.0.59 → 1.0.62

package/dist/index.d.cts

@@ -3509,7 +3509,7 @@ type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
  * @typeParam T - Result type for projections (unused)
  * @typeParam TTable - Table definition being queried
  */
-declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef> {
+declare class SelectQueryBuilder<T = EntityInstance<any>, TTable extends TableDef = TableDef> {
     private readonly env;
     private readonly context;
     private readonly columnSelector;
@@ -3522,6 +3522,7 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
     private readonly relationFacet;
     private readonly lazyRelations;
     private readonly lazyRelationOptions;
+    private readonly entityConstructor?;
     /**
      * Creates a new SelectQueryBuilder instance
      * @param table - Table definition to query
@@ -3529,7 +3530,7 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param hydration - Optional hydration manager
      * @param dependencies - Optional query builder dependencies
      */
-    constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>, lazyRelationOptions?: Map<string, RelationIncludeOptions>);
+    constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>, lazyRelationOptions?: Map<string, RelationIncludeOptions>, entityConstructor?: EntityConstructor<any>);
     /**
      * Creates a new SelectQueryBuilder instance with updated context and lazy relations
      * @param context - Updated query context
@@ -3540,6 +3541,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
     /**
      * Applies an alias to the root FROM table.
      * @param alias - Alias to apply
+     * @example
+     * const qb = new SelectQueryBuilder(userTable).as('u');
      */
     as(alias: string): SelectQueryBuilder<T, TTable>;
     /**
@@ -3567,6 +3570,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * Can be called with column names or a projection object.
      * @param args - Column names or projection object
      * @returns New query builder instance with selected columns
+     * @example
+     * // Select specific columns
+     * qb.select('id', 'name', 'email');
+     * @example
+     * // Select with aliases and expressions
+     * qb.select({
+     *   id: userTable.columns.id,
+     *   fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
+     * });
      */
     select<K extends keyof TTable['columns'] & string>(...args: K[]): SelectQueryBuilder<T, TTable>;
     select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
@@ -3574,6 +3586,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * Selects raw column expressions
      * @param cols - Column expressions as strings
      * @returns New query builder instance with raw column selections
+     * @example
+     * qb.selectRaw('COUNT(*) as total', 'UPPER(name) as upper_name');
      */
     selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable>;
     /**
@@ -3582,6 +3596,12 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param query - Query builder or query node for the CTE
      * @param columns - Optional column names for the CTE
      * @returns New query builder instance with the CTE
+     * @example
+     * const recentUsers = new SelectQueryBuilder(userTable)
+     *   .where(gt(userTable.columns.createdAt, subDays(now(), 30)));
+     * const qb = new SelectQueryBuilder(userTable)
+     *   .with('recent_users', recentUsers)
+     *   .from('recent_users');
      */
     with<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
     /**
@@ -3590,6 +3610,19 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param query - Query builder or query node for the CTE
      * @param columns - Optional column names for the CTE
      * @returns New query builder instance with the recursive CTE
+     * @example
+     * // Base case: select root nodes
+     * const baseQuery = new SelectQueryBuilder(orgTable)
+     *   .where(eq(orgTable.columns.parentId, 1));
+     * // Recursive case: join with the CTE itself
+     * const recursiveQuery = new SelectQueryBuilder(orgTable)
+     *   .join('org_hierarchy', 'oh', eq(orgTable.columns.parentId, col('oh.id')));
+     * // Combine base and recursive parts
+     * const orgHierarchy = baseQuery.union(recursiveQuery);
+     * // Use in main query
+     * const qb = new SelectQueryBuilder(orgTable)
+     *   .withRecursive('org_hierarchy', orgHierarchy)
+     *   .from('org_hierarchy');
      */
     withRecursive<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
     /**
@@ -3598,6 +3631,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param alias - Alias for the derived table
      * @param columnAliases - Optional column alias list
      * @returns New query builder instance with updated FROM
+     * @example
+     * const subquery = new SelectQueryBuilder(userTable)
+     *   .select('id', 'name')
+     *   .where(gt(userTable.columns.score, 100));
+     * qb.fromSubquery(subquery, 'high_scorers', ['userId', 'userName']);
      */
     fromSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
     /**
@@ -3606,6 +3644,13 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param args - Optional function arguments
      * @param alias - Optional alias for the function table
      * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
+     * @example
+     * qb.fromFunctionTable(
+     *   'generate_series',
+     *   [literal(1), literal(10), literal(1)],
+     *   'series',
+     *   { columnAliases: ['value'] }
+     * );
      */
     fromFunctionTable(name: string, args?: OperandNode[], alias?: string, options?: {
         lateral?: boolean;
@@ -3618,6 +3663,12 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param alias - Alias for the subquery column
      * @param sub - Query builder or query node for the subquery
      * @returns New query builder instance with the subquery selection
+     * @example
+     * const postCount = new SelectQueryBuilder(postTable)
+     *   .select(count(postTable.columns.id))
+     *   .where(eq(postTable.columns.userId, col('u.id')));
+     * qb.select('id', 'name')
+     *   .selectSubquery('postCount', postCount);
      */
     selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3628,6 +3679,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param joinKind - Join kind (defaults to INNER)
      * @param columnAliases - Optional column alias list for the derived table
      * @returns New query builder instance with the derived-table join
+     * @example
+     * const activeUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.active, true));
+     * qb.joinSubquery(
+     *   activeUsers,
+     *   'au',
+     *   eq(col('t.userId'), col('au.id')),
+     *   JOIN_KINDS.LEFT
+     * );
      */
     joinSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
     /**
@@ -3638,6 +3698,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param condition - Join condition expression
      * @param joinKind - Kind of join (defaults to INNER)
      * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
+     * @example
+     * qb.joinFunctionTable(
+     *   'generate_series',
+     *   [literal(1), literal(10)],
+     *   'gs',
+     *   eq(col('t.value'), col('gs.value')),
+     *   JOIN_KINDS.INNER,
+     *   { columnAliases: ['value'] }
+     * );
      */
     joinFunctionTable(name: string, args: OperandNode[], alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, options?: {
         lateral?: boolean;
@@ -3650,6 +3719,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param table - Table to join
      * @param condition - Join condition expression
      * @returns New query builder instance with the INNER JOIN
+     * @example
+     * qb.innerJoin(
+     *   postTable,
+     *   eq(userTable.columns.id, postTable.columns.userId)
+     * );
      */
     innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3657,6 +3731,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param table - Table to join
      * @param condition - Join condition expression
      * @returns New query builder instance with the LEFT JOIN
+     * @example
+     * qb.leftJoin(
+     *   postTable,
+     *   eq(userTable.columns.id, postTable.columns.userId)
+     * );
      */
     leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3664,6 +3743,11 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param table - Table to join
      * @param condition - Join condition expression
      * @returns New query builder instance with the RIGHT JOIN
+     * @example
+     * qb.rightJoin(
+     *   postTable,
+     *   eq(userTable.columns.id, postTable.columns.userId)
+     * );
      */
     rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3671,6 +3755,8 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param relationName - Name of the relationship to match
      * @param predicate - Optional predicate expression
      * @returns New query builder instance with the relationship match
+     * @example
+     * qb.match('posts', eq(postTable.columns.published, true));
      */
     match<K extends keyof TTable['relations'] & string>(relationName: K, predicate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3679,6 +3765,10 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param joinKind - Type of join (defaults to INNER)
      * @param extraCondition - Optional additional join condition
      * @returns New query builder instance with the relationship join
+     * @example
+     * qb.joinRelation('posts', JOIN_KINDS.LEFT);
+     * @example
+     * qb.joinRelation('posts', JOIN_KINDS.INNER, eq(postTable.columns.published, true));
      */
     joinRelation<K extends keyof TTable['relations'] & string>(relationName: K, joinKind?: JoinKind, extraCondition?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3686,6 +3776,15 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param relationName - Name of the relationship to include
      * @param options - Optional include options
      * @returns New query builder instance with the relationship inclusion
+     * @example
+     * qb.include('posts');
+     * @example
+     * qb.include('posts', { columns: ['id', 'title', 'published'] });
+     * @example
+     * qb.include('posts', {
+     *   columns: ['id', 'title'],
+     *   where: eq(postTable.columns.published, true)
+     * });
      */
     include<K extends keyof TTable['relations'] & string>(relationName: K, options?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
     /**
@@ -3693,16 +3792,28 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param relationName - Name of the relation to include lazily
      * @param options - Optional include options for lazy loading
      * @returns New query builder instance with lazy relation inclusion
+     * @example
+     * const qb = new SelectQueryBuilder(userTable).includeLazy('posts');
+     * const users = await qb.execute(session);
+     * // Access posts later - they will be loaded on demand
+     * const posts = await users[0].posts;
      */
     includeLazy<K extends keyof RelationMap<TTable>>(relationName: K, options?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
     /**
      * Convenience alias for including only specific columns from a relation.
+     * @example
+     * qb.includePick('posts', ['id', 'title', 'createdAt']);
      */
     includePick<K extends keyof TTable['relations'] & string, C extends RelationTargetColumns<TTable['relations'][K]>>(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable>;
     /**
      * Selects columns for the root table and relations from an array of entries
      * @param config - Configuration array for deep column selection
      * @returns New query builder instance with deep column selections
+     * @example
+     * qb.selectColumnsDeep([
+     *   { type: 'root', columns: ['id', 'name'] },
+     *   { type: 'relation', relationName: 'posts', columns: ['id', 'title'] }
+     * ]);
      */
     selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable>;
     /**
@@ -3721,11 +3832,49 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      */
     getTable(): TTable;
     /**
-     * Executes the query and returns hydrated results
+     * Ensures that if no columns are selected, all columns from the table are selected by default.
+     */
+    private ensureDefaultSelection;
+    /**
+     * Executes the query and returns hydrated results.
+     * If the builder was created with an entity constructor (e.g. via selectFromEntity),
+     * this will automatically return fully materialized entity instances.
+     *
      * @param ctx - ORM session context
-     * @returns Promise of entity instances
+     * @returns Promise of entity instances (or objects if generic T is not an entity)
+     * @example
+     * const users = await selectFromEntity(User).execute(session);
+     * // users is User[]
+     * users[0] instanceof User; // true
+     */
+    execute(ctx: OrmSession): Promise<T[]>;
+    /**
+     * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.
+     * Use this if you want raw data even when using selectFromEntity.
+     *
+     * @param ctx - ORM session context
+     * @returns Promise of plain entity instances
+     * @example
+     * const rows = await selectFromEntity(User).executePlain(session);
+     * // rows is EntityInstance<UserTable>[] (plain objects)
+     * rows[0] instanceof User; // false
      */
-    execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]>;
+    executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]>;
+    /**
+     * Executes the query and returns results as real class instances.
+     * Unlike execute(), this returns actual instances of the decorated entity class
+     * with working methods and proper instanceof checks.
+     * @param entityClass - The entity class constructor
+     * @param ctx - ORM session context
+     * @returns Promise of entity class instances
+     * @example
+     * const users = await selectFromEntity(User)
+     *   .include('posts')
+     *   .executeAs(User, session);
+     * users[0] instanceof User; // true!
+     * users[0].getFullName();   // works!
+     */
+    executeAs<TEntity extends object>(entityClass: EntityConstructor<TEntity>, ctx: OrmSession): Promise<TEntity[]>;
     /**
      * Executes a count query for the current builder without LIMIT/OFFSET clauses.
      *
@@ -3743,7 +3892,7 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
         page: number;
         pageSize: number;
     }): Promise<{
-        items: EntityInstance<TTable>[];
+        items: T[];
         totalItems: number;
     }>;
     /**
@@ -3751,24 +3900,42 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param execCtx - Execution context
      * @param hydCtx - Hydration context
      * @returns Promise of entity instances
+     * @example
+     * const execCtx = new ExecutionContext(session);
+     * const hydCtx = new HydrationContext();
+     * const users = await qb.executeWithContexts(execCtx, hydCtx);
      */
-    executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]>;
+    executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<T[]>;
     /**
      * Adds a WHERE condition to the query
      * @param expr - Expression for the WHERE clause
      * @returns New query builder instance with the WHERE condition
+     * @example
+     * qb.where(eq(userTable.columns.id, 1));
+     * @example
+     * qb.where(and(
+     *   eq(userTable.columns.active, true),
+     *   gt(userTable.columns.createdAt, subDays(now(), 30))
+     * ));
      */
     where(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a GROUP BY clause to the query
      * @param term - Column definition or ordering term to group by
      * @returns New query builder instance with the GROUP BY clause
+     * @example
+     * qb.select('departmentId', count(userTable.columns.id))
+     *   .groupBy(userTable.columns.departmentId);
      */
     groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a HAVING condition to the query
      * @param expr - Expression for the HAVING clause
      * @returns New query builder instance with the HAVING condition
+     * @example
+     * qb.select('departmentId', count(userTable.columns.id))
+     *   .groupBy(userTable.columns.departmentId)
+     *   .having(gt(count(userTable.columns.id), 5));
      */
     having(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3789,54 +3956,95 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * Adds a DISTINCT clause to the query
      * @param cols - Columns to make distinct
      * @returns New query builder instance with the DISTINCT clause
+     * @example
+     * qb.distinct(userTable.columns.email);
+     * @example
+     * qb.distinct(userTable.columns.firstName, userTable.columns.lastName);
      */
     distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a LIMIT clause to the query
      * @param n - Maximum number of rows to return
      * @returns New query builder instance with the LIMIT clause
+     * @example
+     * qb.limit(10);
+     * @example
+     * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
      */
     limit(n: number): SelectQueryBuilder<T, TTable>;
     /**
      * Adds an OFFSET clause to the query
      * @param n - Number of rows to skip
      * @returns New query builder instance with the OFFSET clause
+     * @example
+     * qb.offset(10);
+     * @example
+     * qb.limit(20).offset(40); // Pagination: page 3 with 20 items per page
      */
     offset(n: number): SelectQueryBuilder<T, TTable>;
     /**
      * Combines this query with another using UNION
      * @param query - Query to union with
      * @returns New query builder instance with the set operation
+     * @example
+     * const activeUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.active, true));
+     * const inactiveUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.active, false));
+     * qb.union(activeUsers).union(inactiveUsers);
      */
     union<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Combines this query with another using UNION ALL
      * @param query - Query to union with
      * @returns New query builder instance with the set operation
+     * @example
+     * const q1 = new SelectQueryBuilder(userTable).where(gt(userTable.columns.score, 80));
+     * const q2 = new SelectQueryBuilder(userTable).where(lt(userTable.columns.score, 20));
+     * qb.unionAll(q1).unionAll(q2);
      */
     unionAll<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Combines this query with another using INTERSECT
      * @param query - Query to intersect with
      * @returns New query builder instance with the set operation
+     * @example
+     * const activeUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.active, true));
+     * const premiumUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.premium, true));
+     * qb.intersect(activeUsers).intersect(premiumUsers);
      */
     intersect<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Combines this query with another using EXCEPT
      * @param query - Query to subtract
      * @returns New query builder instance with the set operation
+     * @example
+     * const allUsers = new SelectQueryBuilder(userTable);
+     * const inactiveUsers = new SelectQueryBuilder(userTable)
+     *   .where(eq(userTable.columns.active, false));
+     * qb.except(allUsers).except(inactiveUsers); // Only active users
      */
     except<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a WHERE EXISTS condition to the query
      * @param subquery - Subquery to check for existence
      * @returns New query builder instance with the WHERE EXISTS condition
+     * @example
+     * const postsQuery = new SelectQueryBuilder(postTable)
+     *   .where(eq(postTable.columns.userId, col('u.id')));
+     * qb.whereExists(postsQuery);
      */
     whereExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
      * Adds a WHERE NOT EXISTS condition to the query
      * @param subquery - Subquery to check for non-existence
      * @returns New query builder instance with the WHERE NOT EXISTS condition
+     * @example
+     * const postsQuery = new SelectQueryBuilder(postTable)
+     *   .where(eq(postTable.columns.userId, col('u.id')));
+     * qb.whereNotExists(postsQuery); // Users without posts
      */
     whereNotExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
@@ -3863,22 +4071,39 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * Compiles the query to SQL for a specific dialect
      * @param dialect - Database dialect to compile for
      * @returns Compiled query with SQL and parameters
+     * @example
+     * const compiled = qb.select('id', 'name')
+     *   .where(eq(userTable.columns.active, true))
+     *   .compile('postgres');
+     * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
      */
     compile(dialect: SelectDialectInput): CompiledQuery;
     /**
      * Converts the query to SQL string for a specific dialect
      * @param dialect - Database dialect to generate SQL for
      * @returns SQL string representation of the query
+     * @example
+     * const sql = qb.select('id', 'name')
+     *   .where(eq(userTable.columns.active, true))
+     *   .toSql('postgres');
+     * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
      */
     toSql(dialect: SelectDialectInput): string;
     /**
      * Gets the hydration plan for the query
      * @returns Hydration plan or undefined if none exists
+     * @example
+     * const plan = qb.include('posts').getHydrationPlan();
+     * console.log(plan?.relations); // Information about included relations
      */
     getHydrationPlan(): HydrationPlan | undefined;
     /**
      * Gets the Abstract Syntax Tree (AST) representation of the query
      * @returns Query AST with hydration applied
+     * @example
+     * const ast = qb.select('id', 'name').getAST();
+     * console.log(ast.columns); // Array of column nodes
+     * console.log(ast.from); // From clause information
      */
     getAST(): SelectQueryNode;
 }
@@ -4277,6 +4502,68 @@ declare class DeleteQueryBuilder<T> {
     getAST(): DeleteQueryNode;
 }
 
+/**
+ * Represents a target for query operations, which can be either a table definition
+ * or an entity constructor. This type allows flexible targeting of database tables
+ * through either direct table definitions or entity classes decorated with ORM metadata.
+ *
+ * @template TTable - The table definition type, defaults to TableDef
+ */
+type QueryTarget<TTable extends TableDef = TableDef> = TTable | EntityConstructor;
+
+/**
+ * Creates a SELECT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to query from
+ * @returns A new SelectQueryBuilder instance for building SELECT queries
+ *
+ * @example
+ * ```typescript
+ * const query = selectFrom(UserTable).select('id', 'name');
+ * ```
+ */
+declare const selectFrom: <TTable extends TableDef>(target: QueryTarget<TTable>) => SelectQueryBuilder<unknown, TTable>;
+/**
+ * Creates an INSERT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to insert into
+ * @returns A new InsertQueryBuilder instance for building INSERT queries
+ *
+ * @example
+ * ```typescript
+ * const query = insertInto(UserTable).values({ name: 'John', email: 'john@example.com' });
+ * ```
+ */
+declare const insertInto: <TTable extends TableDef>(target: QueryTarget<TTable>) => InsertQueryBuilder<unknown>;
+/**
+ * Creates an UPDATE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to update
+ * @returns A new UpdateQueryBuilder instance for building UPDATE queries
+ *
+ * @example
+ * ```typescript
+ * const query = update(UserTable).set({ name: 'Jane' }).where(eq(UserTable.id, 1));
+ * ```
+ */
+declare const update: <TTable extends TableDef>(target: QueryTarget<TTable>) => UpdateQueryBuilder<unknown>;
+/**
+ * Creates a DELETE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to delete from
+ * @returns A new DeleteQueryBuilder instance for building DELETE queries
+ *
+ * @example
+ * ```typescript
+ * const query = deleteFrom(UserTable).where(eq(UserTable.id, 1));
+ * ```
+ */
+declare const deleteFrom: <TTable extends TableDef>(target: QueryTarget<TTable>) => DeleteQueryBuilder<unknown>;
+
 /**
  * Strategy interface for compiling pagination clauses.
  * Allows dialects to customize how pagination (LIMIT/OFFSET, ROWS FETCH, etc.) is generated.
@@ -5966,7 +6253,7 @@ type EntityTable<TEntity extends object> = Omit<TableDef<{
         [K in RelationKeys<TEntity>]: NonNullable<TEntity[K]> extends HasManyCollection<infer TChild> ? HasManyRelation<EntityTable<NonNullable<TChild> & object>> : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget, infer TPivot> ? BelongsToManyRelation<EntityTable<NonNullable<TTarget> & object>, TPivot extends object ? EntityTable<NonNullable<TPivot> & object> : TableDef> : NonNullable<TEntity[K]> extends HasOneReference<infer TChild> ? HasOneRelation<EntityTable<NonNullable<TChild> & object>> : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent> ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>> : NonNullable<TEntity[K]> extends object ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>> : never;
     };
 };
-declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => SelectQueryBuilder<unknown, EntityTable<TEntity>>;
+declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => SelectQueryBuilder<TEntity, EntityTable<TEntity>>;
 /**
  * Public API: opt-in ergonomic entity reference (decorator-level).
  *
@@ -5995,6 +6282,85 @@ interface DecoratorMetadataBag {
  */
 declare const getDecoratorMetadata: (ctor: object) => DecoratorMetadataBag | undefined;
 
+/**
+ * Strategy interface for materializing entity instances (Open/Closed Principle).
+ */
+interface EntityMaterializationStrategy {
+    /**
+     * Creates an instance of the entity class and populates it with data.
+     * @param ctor - The entity constructor
+     * @param data - The raw data to populate
+     * @returns The materialized entity instance
+     */
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
+}
+/**
+ * Default strategy: Uses Object.create() to create instance without calling constructor.
+ * Safe for classes with required constructor parameters.
+ */
+declare class PrototypeMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
+}
+/**
+ * Alternative strategy: Calls default constructor then assigns properties.
+ * Use when class constructor initializes important state.
+ */
+declare class ConstructorMaterializationStrategy implements EntityMaterializationStrategy {
+    materialize<T>(ctor: EntityConstructor<T>, data: Record<string, unknown>): T;
+}
+/**
+ * Interface for materializing query results into real entity class instances.
+ */
+interface EntityMaterializer {
+    /**
+     * Materializes a single row into a real entity instance.
+     * @param entityClass - The entity constructor
+     * @param row - The raw data row
+     * @returns The materialized entity instance
+     */
+    materialize<T>(entityClass: EntityConstructor<T>, row: Record<string, unknown>): T;
+    /**
+     * Materializes multiple rows into real entity instances.
+     * @param entityClass - The entity constructor
+     * @param rows - The raw data rows
+     * @returns Array of materialized entity instances
+     */
+    materializeMany<T>(entityClass: EntityConstructor<T>, rows: Record<string, unknown>[]): T[];
+}
+/**
+ * Default implementation of EntityMaterializer.
+ * Converts query results into actual class instances with working methods.
+ *
+ * @example
+ * const materializer = new DefaultEntityMaterializer();
+ * const users = materializer.materializeMany(User, queryResults);
+ * users[0] instanceof User; // true
+ * users[0].getFullName();   // works!
+ */
+declare class DefaultEntityMaterializer implements EntityMaterializer {
+    private readonly strategy;
+    constructor(strategy?: EntityMaterializationStrategy);
+    materialize<T>(ctor: EntityConstructor<T>, row: Record<string, unknown>): T;
+    materializeMany<T>(ctor: EntityConstructor<T>, rows: Record<string, unknown>[]): T[];
+    /**
+     * Recursively materializes nested relation data.
+     */
+    private materializeRelations;
+    /**
+     * Simple heuristic to check if an object looks like an entity.
+     */
+    private isEntityLike;
+}
+/**
+ * Convenience function to materialize query results as real class instances.
+ *
+ * @example
+ * const results = await selectFromEntity(User).execute(session);
+ * const users = materializeAs(User, results);
+ * users[0] instanceof User; // true!
+ */
+declare const materializeAs: <TEntity extends object>(ctor: EntityConstructor<TEntity>, results: Record<string, unknown>[]) => TEntity[];
+
 type PoolOptions = {
     /** Maximum number of live resources (idle + leased). */
     max: number;
@@ -6158,4 +6524,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-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 };
+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, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, 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, PrototypeMaterializationStrategy, 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, materializeAs, 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 };