metal-orm 1.0.16 → 1.0.18

package/dist/{select-BKZrMRCQ.d.ts → select-BuMpVcVt.d.ts}

@@ -1,7 +1,7 @@
 /**
  * Supported column data types for database schema definitions
  */
-type ColumnType = 'INT' | 'INTEGER' | 'BIGINT' | 'VARCHAR' | 'TEXT' | 'JSON' | 'ENUM' | 'DECIMAL' | 'FLOAT' | 'DOUBLE' | 'UUID' | 'DATE' | 'DATETIME' | 'TIMESTAMP' | 'TIMESTAMPTZ' | 'BOOLEAN' | 'int' | 'integer' | 'bigint' | 'varchar' | 'text' | 'json' | 'enum' | 'decimal' | 'float' | 'double' | 'uuid' | 'date' | 'datetime' | 'timestamp' | 'timestamptz' | 'boolean';
+type ColumnType = 'INT' | 'INTEGER' | 'BIGINT' | 'VARCHAR' | 'TEXT' | 'JSON' | 'ENUM' | 'DECIMAL' | 'FLOAT' | 'DOUBLE' | 'UUID' | 'BINARY' | 'VARBINARY' | 'BLOB' | 'BYTEA' | 'DATE' | 'DATETIME' | 'TIMESTAMP' | 'TIMESTAMPTZ' | 'BOOLEAN' | 'int' | 'integer' | 'bigint' | 'varchar' | 'text' | 'json' | 'enum' | 'decimal' | 'float' | 'double' | 'uuid' | 'binary' | 'varbinary' | 'blob' | 'bytea' | 'date' | 'datetime' | 'timestamp' | 'timestamptz' | 'boolean';
 type ReferentialAction = 'NO ACTION' | 'RESTRICT' | 'CASCADE' | 'SET NULL' | 'SET DEFAULT';
 interface RawDefaultValue {
     raw: string;
@@ -83,6 +83,22 @@ declare const col: {
      * Creates a UUID column definition
      */
     uuid: () => ColumnDef<"UUID">;
+    /**
+     * Creates a binary large object column definition
+     */
+    blob: () => ColumnDef<"BLOB">;
+    /**
+     * Creates a fixed-length binary column definition
+     */
+    binary: (length?: number) => ColumnDef<"BINARY">;
+    /**
+     * Creates a variable-length binary column definition
+     */
+    varbinary: (length?: number) => ColumnDef<"VARBINARY">;
+    /**
+     * Creates a Postgres bytea column definition
+     */
+    bytea: () => ColumnDef<"BYTEA">;
     /**
      * Creates a timestamp column definition
      */
@@ -348,10 +364,14 @@ interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDe
  */
 declare const defineTable: <T extends Record<string, ColumnDef>>(name: string, columns: T, relations?: Record<string, RelationDef>, hooks?: TableHooks, options?: TableOptions) => TableDef<T>;
 
+/**
+ * Resolves a relation definition to its target table type.
+ */
+type RelationTargetTable<TRel extends RelationDef> = TRel extends HasManyRelation<infer TTarget> ? TTarget : TRel extends HasOneRelation<infer TTarget> ? TTarget : TRel extends BelongsToRelation<infer TTarget> ? TTarget : TRel extends BelongsToManyRelation<infer TTarget> ? TTarget : never;
 /**
  * Maps a ColumnDef to its TypeScript type representation
  */
-type ColumnToTs<T extends ColumnDef> = T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number : T['type'] extends 'BIGINT' | 'bigint' ? number | bigint : T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number : T['type'] extends 'BOOLEAN' | 'boolean' ? boolean : T['type'] extends 'JSON' | 'json' ? unknown : T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string : string;
+type ColumnToTs<T extends ColumnDef> = T['type'] extends 'INT' | 'INTEGER' | 'int' | 'integer' ? number : T['type'] extends 'BIGINT' | 'bigint' ? number | bigint : T['type'] extends 'DECIMAL' | 'decimal' | 'FLOAT' | 'float' | 'DOUBLE' | 'double' ? number : T['type'] extends 'BOOLEAN' | 'boolean' ? boolean : T['type'] extends 'JSON' | 'json' ? unknown : T['type'] extends 'BLOB' | 'blob' | 'BINARY' | 'binary' | 'VARBINARY' | 'varbinary' | 'BYTEA' | 'bytea' ? Buffer : T['type'] extends 'DATE' | 'date' | 'DATETIME' | 'datetime' | 'TIMESTAMP' | 'timestamp' | 'TIMESTAMPTZ' | 'timestamptz' ? string : string;
 /**
  * Infers a row shape from a table definition
  */
@@ -530,6 +550,8 @@ interface ColumnNode {
     name: string;
     /** Optional alias for the column */
     alias?: string;
+    /** Optional scope marker (e.g., 'outer' for correlated references) */
+    scope?: 'outer' | 'default';
 }
 /**
  * AST node representing a function call
@@ -544,6 +566,12 @@ interface FunctionNode {
     args: OperandNode[];
     /** Optional alias for the function result */
     alias?: string;
+    /** Optional ORDER BY clause used by aggregations like GROUP_CONCAT */
+    orderBy?: OrderByNode[];
+    /** Optional separator argument used by GROUP_CONCAT-like functions */
+    separator?: OperandNode;
+    /** Optional DISTINCT modifier */
+    distinct?: boolean;
 }
 /**
  * AST node representing a JSON path expression
@@ -690,7 +718,7 @@ interface JoinNode {
     /** Type of join (INNER, LEFT, RIGHT, etc.) */
     kind: JoinKind;
     /** Table to join */
-    table: TableNode | FunctionTableNode;
+    table: TableSourceNode;
     /** Join condition expression */
     condition: ExpressionNode;
     /** Optional metadata for non-SQL concerns (e.g., relation name) */
@@ -729,6 +757,19 @@ interface FunctionTableNode {
     /** Optional column aliases */
     columnAliases?: string[];
 }
+/**
+ * AST node representing a derived table (subquery with an alias)
+ */
+interface DerivedTableNode {
+    type: 'DerivedTable';
+    /** Subquery providing the rows */
+    query: SelectQueryNode;
+    /** Required alias for the derived table */
+    alias: string;
+    /** Optional column aliases */
+    columnAliases?: string[];
+}
+type TableSourceNode = TableNode | FunctionTableNode | DerivedTableNode;
 /**
  * AST node representing an ORDER BY clause
  */
@@ -775,7 +816,7 @@ interface SelectQueryNode {
     /** Optional CTEs (WITH clauses) */
     ctes?: CommonTableExpressionNode[];
     /** FROM clause table (either a Table or a FunctionTable) */
-    from: TableNode | FunctionTableNode;
+    from: TableSourceNode;
     /** SELECT clause columns */
     columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
     /** JOIN clauses */
@@ -893,6 +934,8 @@ interface HydrationMetadata {
 interface FunctionRenderContext {
     node: FunctionNode;
     compiledArgs: string[];
+    /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
+    compileOperand: (operand: OperandNode) => string;
 }
 type FunctionRenderer = (ctx: FunctionRenderContext) => string;
 interface FunctionStrategy {
@@ -1106,6 +1149,12 @@ declare class SelectQueryState {
      * @returns New SelectQueryState with added join
      */
     withJoin(join: JoinNode): SelectQueryState;
+    /**
+     * Replaces the FROM clause.
+     * @param from - Table source for the FROM clause
+     * @returns New SelectQueryState with updated FROM
+     */
+    withFrom(from: TableSourceNode): SelectQueryState;
     /**
      * Adds a WHERE clause to the query
      * @param predicate - WHERE predicate expression
@@ -1342,6 +1391,12 @@ declare class QueryAstService {
      * @returns Updated query state with set operation
      */
     withSetOperation(operator: SetOperationKind, query: SelectQueryNode): SelectQueryState;
+    /**
+     * Replaces the FROM clause for the current query.
+     * @param from - Table source to use in the FROM clause
+     * @returns Updated query state with new FROM
+     */
+    withFrom(from: TableSourceNode): SelectQueryState;
     /**
      * Selects a subquery as a column
      * @param alias - Alias for the subquery
@@ -1483,7 +1538,7 @@ declare class RelationService {
      * @param ast - Query AST to modify
      * @returns Modified query AST with relation correlation
      */
-    applyRelationCorrelation(relationName: string, ast: SelectQueryNode): SelectQueryNode;
+    applyRelationCorrelation(relationName: string, ast: SelectQueryNode, additionalCorrelation?: ExpressionNode): SelectQueryNode;
     /**
      * Creates a join node for a relation
      * @param state - Current query state
@@ -1514,6 +1569,7 @@ declare class RelationService {
      * @returns QueryAstService instance
      */
     private astService;
+    private rootTableName;
 }
 
 /**
@@ -1587,6 +1643,101 @@ type EntityConstructor = new (...args: any[]) => any;
 type EntityOrTableTarget = EntityConstructor | TableDef;
 type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
+/**
+ * Entity status enum representing the lifecycle state of an entity
+ */
+declare enum EntityStatus {
+    /** Entity is newly created and not yet persisted */
+    New = "new",
+    /** Entity is managed by the ORM and synchronized with the database */
+    Managed = "managed",
+    /** Entity has been modified but not yet persisted */
+    Dirty = "dirty",
+    /** Entity has been marked for removal */
+    Removed = "removed",
+    /** Entity is detached from the ORM context */
+    Detached = "detached"
+}
+/**
+ * Represents an entity being tracked by the ORM
+ */
+interface TrackedEntity {
+    /** The table definition this entity belongs to */
+    table: TableDef;
+    /** The actual entity instance */
+    entity: any;
+    /** Primary key value of the entity */
+    pk: string | number | null;
+    /** Current status of the entity */
+    status: EntityStatus;
+    /** Original values of the entity when it was loaded */
+    original: Record<string, any> | null;
+}
+/**
+ * Type representing a key for relation navigation
+ */
+type RelationKey = string;
+/**
+ * Represents a change operation on a relation
+ * @typeParam T - Type of the related entity
+ */
+type RelationChange<T> = {
+    kind: 'add';
+    entity: T;
+} | {
+    kind: 'attach';
+    entity: T;
+} | {
+    kind: 'remove';
+    entity: T;
+} | {
+    kind: 'detach';
+    entity: T;
+};
+/**
+ * Represents a relation change entry in the unit of work
+ */
+interface RelationChangeEntry {
+    /** Root entity that owns the relation */
+    root: any;
+    /** Key of the relation being changed */
+    relationKey: RelationKey;
+    /** Table definition of the root entity */
+    rootTable: TableDef;
+    /** Name of the relation */
+    relationName: string;
+    /** Relation definition */
+    relation: RelationDef;
+    /** The change being applied */
+    change: RelationChange<any>;
+}
+/**
+ * Represents a domain event that can be emitted by entities
+ * @typeParam TType - Type of the event (string literal)
+ */
+interface DomainEvent<TType extends string = string> {
+    /** Type identifier for the event */
+    readonly type: TType;
+    /** Timestamp when the event occurred */
+    readonly occurredAt?: Date;
+}
+/**
+ * Type representing any domain event
+ */
+type AnyDomainEvent = DomainEvent<string>;
+/**
+ * Type representing ORM-specific domain events
+ */
+type OrmDomainEvent = AnyDomainEvent;
+/**
+ * Interface for entities that can emit domain events
+ * @typeParam E - Type of domain events this entity can emit
+ */
+interface HasDomainEvents<E extends DomainEvent = AnyDomainEvent> {
+    /** Array of domain events emitted by this entity */
+    domainEvents?: E[];
+}
+
 /**
  * Strategy interface for converting database names to TypeScript identifiers
  */
@@ -1596,7 +1747,7 @@ interface NamingStrategy {
      * @param table - Table node, function table node, or name
      * @returns Valid TypeScript identifier
      */
-    tableToSymbol(table: TableNode | FunctionTableNode | string): string;
+    tableToSymbol(table: TableSourceNode | string): string;
     /**
      * Converts a column reference to a property name
      * @param column - Column node
@@ -1616,7 +1767,7 @@ declare class InterceptorPipeline {
     run(ctx: QueryContext, executor: DbExecutor): Promise<QueryResult[]>;
 }
 
-interface OrmOptions {
+interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
     dialect: Dialect;
     executorFactory: DbExecutorFactory;
     interceptors?: InterceptorPipeline;
@@ -1630,56 +1781,16 @@ interface DbExecutorFactory {
 }
 interface ExternalTransaction {
 }
-declare class Orm {
+declare class Orm<E extends DomainEvent = OrmDomainEvent> {
     readonly dialect: Dialect;
     readonly interceptors: InterceptorPipeline;
     readonly namingStrategy: NamingStrategy;
     private readonly executorFactory;
-    constructor(opts: OrmOptions);
+    constructor(opts: OrmOptions<E>);
     createSession(options?: {
         tx?: ExternalTransaction;
-    }): OrmSession;
-    transaction<T>(fn: (session: OrmSession) => Promise<T>): Promise<T>;
-}
-
-declare enum EntityStatus {
-    New = "new",
-    Managed = "managed",
-    Dirty = "dirty",
-    Removed = "removed",
-    Detached = "detached"
-}
-interface TrackedEntity {
-    table: TableDef;
-    entity: any;
-    pk: string | number | null;
-    status: EntityStatus;
-    original: Record<string, any> | null;
-}
-type RelationKey = string;
-type RelationChange<T> = {
-    kind: 'add';
-    entity: T;
-} | {
-    kind: 'attach';
-    entity: T;
-} | {
-    kind: 'remove';
-    entity: T;
-} | {
-    kind: 'detach';
-    entity: T;
-};
-interface RelationChangeEntry {
-    root: any;
-    relationKey: RelationKey;
-    rootTable: TableDef;
-    relationName: string;
-    relation: RelationDef;
-    change: RelationChange<any>;
-}
-interface HasDomainEvents {
-    domainEvents?: any[];
+    }): OrmSession<E>;
+    transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T>;
 }
 
 declare class IdentityMap {
@@ -1727,15 +1838,21 @@ declare class UnitOfWork {
     private getPrimaryKeyValue;
 }
 
-type DomainEventHandler<Context> = (event: any, ctx: Context) => Promise<void> | void;
-declare class DomainEventBus<Context> {
+type EventOfType<E extends DomainEvent, TType extends E['type']> = Extract<E, {
+    type: TType;
+}>;
+type DomainEventHandler<E extends DomainEvent, Context> = (event: E, ctx: Context) => Promise<void> | void;
+type InitialHandlers<E extends DomainEvent, Context> = {
+    [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
+};
+declare class DomainEventBus<E extends DomainEvent, Context> {
     private readonly handlers;
-    constructor(initialHandlers?: Record<string, DomainEventHandler<Context>[]>);
-    register(name: string, handler: DomainEventHandler<Context>): void;
+    constructor(initialHandlers?: InitialHandlers<E, Context>);
+    on<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
+    register<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
     dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void>;
-    private getEventName;
 }
-declare const addDomainEvent: (entity: HasDomainEvents, event: any) => void;
+declare const addDomainEvent: <E extends DomainEvent>(entity: HasDomainEvents<E>, event: E) => void;
 
 declare class RelationChangeProcessor {
     private readonly unitOfWork;
@@ -1759,16 +1876,37 @@ declare class RelationChangeProcessor {
     private resolvePrimaryKeyValue;
 }
 
+/**
+ * Represents a single SQL query log entry
+ */
 interface QueryLogEntry {
+    /** The SQL query that was executed */
     sql: string;
+    /** Parameters used in the query */
     params?: unknown[];
 }
+/**
+ * Function type for query logging callbacks
+ * @param entry - The query log entry to process
+ */
 type QueryLogger = (entry: QueryLogEntry) => void;
+/**
+ * Creates a wrapped database executor that logs all SQL queries
+ * @param executor - Original database executor to wrap
+ * @param logger - Optional logger function to receive query log entries
+ * @returns Wrapped executor that logs queries before execution
+ */
 declare const createQueryLoggingExecutor: (executor: DbExecutor, logger?: QueryLogger) => DbExecutor;
 
+/**
+ * Context for SQL query execution
+ */
 interface ExecutionContext {
+    /** Database dialect to use for SQL generation */
     dialect: Dialect;
+    /** Database executor for running SQL queries */
     executor: DbExecutor;
+    /** Interceptor pipeline for query processing */
     interceptors: InterceptorPipeline;
 }
 
@@ -1785,10 +1923,10 @@ interface EntityContext {
     registerRelationChange(root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>): void;
 }
 
-interface HydrationContext {
+interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
     identityMap: IdentityMap;
     unitOfWork: UnitOfWork;
-    domainEvents: DomainEventBus<any>;
+    domainEvents: DomainEventBus<E, OrmSession<E>>;
     relationChanges: RelationChangeProcessor;
     entityContext: EntityContext;
 }
@@ -1797,22 +1935,22 @@ interface OrmInterceptor {
     beforeFlush?(ctx: EntityContext): Promise<void> | void;
     afterFlush?(ctx: EntityContext): Promise<void> | void;
 }
-interface OrmSessionOptions {
-    orm: Orm;
+interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+    orm: Orm<E>;
     executor: DbExecutor;
     queryLogger?: QueryLogger;
     interceptors?: OrmInterceptor[];
-    domainEventHandlers?: Record<string, DomainEventHandler<OrmSession>[]>;
+    domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
-declare class OrmSession implements EntityContext {
-    readonly orm: Orm;
+declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+    readonly orm: Orm<E>;
     readonly executor: DbExecutor;
     readonly identityMap: IdentityMap;
     readonly unitOfWork: UnitOfWork;
-    readonly domainEvents: DomainEventBus<OrmSession>;
+    readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
     readonly relationChanges: RelationChangeProcessor;
     private readonly interceptors;
-    constructor(opts: OrmSessionOptions);
+    constructor(opts: OrmSessionOptions<E>);
     get dialect(): Dialect;
     get identityBuckets(): Map<string, Map<string, TrackedEntity>>;
     get tracked(): TrackedEntity[];
@@ -1825,7 +1963,9 @@ declare class OrmSession implements EntityContext {
     registerRelationChange: (root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>) => void;
     getEntitiesForTable(table: TableDef): TrackedEntity[];
     registerInterceptor(interceptor: OrmInterceptor): void;
-    registerDomainEventHandler(name: string, handler: DomainEventHandler<OrmSession>): void;
+    registerDomainEventHandler<TType extends E['type']>(type: TType, handler: DomainEventHandler<Extract<E, {
+        type: TType;
+    }>, OrmSession<E>>): void;
     find<TTable extends TableDef>(entityClass: EntityConstructor, id: any): Promise<Entity<TTable> | null>;
     findOne<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable> | null>;
     findMany<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable>[]>;
@@ -1835,11 +1975,21 @@ declare class OrmSession implements EntityContext {
     commit(): Promise<void>;
     rollback(): Promise<void>;
     getExecutionContext(): ExecutionContext;
-    getHydrationContext(): HydrationContext;
+    getHydrationContext(): HydrationContext<E>;
 }
 
 type SelectDialectInput = Dialect | DialectKey;
 
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+type DeepSelectConfig<TTable extends TableDef> = {
+    root?: (keyof TTable['columns'] & string)[];
+} & {
+    [K in keyof TTable['relations'] & string]?: (keyof RelationTargetTable<TTable['relations'][K]>['columns'] & string)[];
+};
+type WhereHasOptions = {
+    correlate?: ExpressionNode;
+};
+type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<any, TChildTable>) => SelectQueryBuilder<any, TChildTable>;
 /**
 
  * Main query builder class for constructing SQL SELECT queries
@@ -1870,7 +2020,13 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>);
     private clone;
+    /**
+     * Applies an alias to the root FROM table.
+     * @param alias - Alias to apply
+     */
+    as(alias: string): SelectQueryBuilder<T, TTable>;
     private resolveQueryNode;
+    private applyCorrelation;
     private createChildBuilder;
     private applyAst;
     private applyJoin;
@@ -1884,7 +2040,12 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with selected columns
   
      */
-    select(columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>): SelectQueryBuilder<T, TTable>;
+    select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns from the root table by name (typed).
+     * @param cols - Column names on the root table
+     */
+    selectColumns<K extends keyof TTable['columns'] & string>(...cols: K[]): SelectQueryBuilder<T, TTable>;
     /**
   
      * Selects raw column expressions
@@ -1923,6 +2084,14 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
   
      */
     withRecursive(name: string, query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
+    /**
+     * Replaces the FROM clause with a derived table (subquery with alias)
+     * @param subquery - Subquery to use as the FROM source
+     * @param alias - Alias for the derived table
+     * @param columnAliases - Optional column alias list
+     * @returns New query builder instance with updated FROM
+     */
+    fromSubquery(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, alias: string, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
     /**
   
      * Selects a subquery as a column
@@ -1935,6 +2104,16 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
   
      */
     selectSubquery(alias: string, sub: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    /**
+     * Adds a JOIN against a derived table (subquery with alias)
+     * @param subquery - Subquery to join
+     * @param alias - Alias for the derived table
+     * @param condition - Join condition expression
+     * @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
+     */
+    joinSubquery(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds an INNER JOIN to the query
@@ -2010,6 +2189,18 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     include(relationName: string, options?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
     includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns for a related table in a single hop.
+     */
+    selectRelationColumns<K extends keyof TTable['relations'] & string, TRel extends RelationDef = TTable['relations'][K], TTarget extends TableDef = RelationTargetTable<TRel>, C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string>(relationName: K, ...cols: C[]): SelectQueryBuilder<T, TTable>;
+    /**
+     * Convenience alias for selecting specific columns from a relation.
+     */
+    includePick<K extends keyof TTable['relations'] & string, TRel extends RelationDef = TTable['relations'][K], TTarget extends TableDef = RelationTargetTable<TRel>, C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string>(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns for the root table and relations from a single config object.
+     */
+    selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable>;
     getLazyRelations(): (keyof RelationMap<TTable>)[];
     getTable(): TTable;
     execute(ctx: OrmSession): Promise<Entity<TTable>[]>;
@@ -2135,7 +2326,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the WHERE EXISTS condition
   
      */
-    whereExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    whereExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a WHERE NOT EXISTS condition to the query
@@ -2145,7 +2336,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the WHERE NOT EXISTS condition
   
      */
-    whereNotExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    whereNotExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a WHERE EXISTS condition based on a relationship
@@ -2157,7 +2348,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the relationship existence check
   
      */
-    whereHas(relationName: string, callback?: <TChildTable extends TableDef>(qb: SelectQueryBuilder<any, TChildTable>) => SelectQueryBuilder<any, TChildTable>): SelectQueryBuilder<T, TTable>;
+    whereHas(relationName: string, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a WHERE NOT EXISTS condition based on a relationship
@@ -2169,7 +2360,7 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with the relationship non-existence check
   
      */
-    whereHasNot(relationName: string, callback?: <TChildTable extends TableDef>(qb: SelectQueryBuilder<any, TChildTable>) => SelectQueryBuilder<any, TChildTable>): SelectQueryBuilder<T, TTable>;
+    whereHasNot(relationName: string, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
     /**
   
      * Compiles the query to SQL for a specific dialect
@@ -2230,4 +2421,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-export { type TableHooks as $, type BelongsToRelation as A, type BinaryExpressionNode as B, type ColumnRef as C, Dialect as D, type ExpressionNode as E, type FunctionNode as F, type BelongsToManyRelation as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type HasManyCollection as K, type LogicalExpressionNode as L, type BelongsToReference as M, type NullExpressionNode as N, type OperandNode as O, type ManyToManyCollection as P, OrmSession as Q, type RelationMap as R, type SelectQueryNode as S, type TableRef as T, type UpdateQueryNode as U, SelectQueryBuilder as V, type WindowFunctionNode as W, type ExecutionContext as X, type HydrationContext as Y, type CheckConstraint as Z, type TableOptions as _, type ColumnNode as a, defineTable as a0, type ColumnType as a1, type ReferentialAction as a2, type RawDefaultValue as a3, type DefaultValue as a4, col as a5, RelationKinds as a6, type RelationType as a7, type CascadeMode as a8, type RelationDef as a9, EntityStatus as aA, type TrackedEntity as aB, type RelationKey as aC, type RelationChange as aD, type RelationChangeEntry as aE, type HasDomainEvents as aF, type QueryLogEntry as aG, type QueryLogger as aH, createQueryLoggingExecutor as aI, type QueryResult as aJ, rowsToQueryResult as aK, type SimpleQueryRunner as aL, createExecutorFromQueryRunner as aM, type EntityOrTableTargetResolver as aN, type EntityConstructor as aO, hasMany as aa, hasOne as ab, belongsTo as ac, belongsToMany as ad, type ColumnToTs as ae, type InferRow as af, type HasOneReference as ag, createColumn as ah, createLiteral as ai, isOperandNode as aj, isFunctionNode as ak, isCaseExpressionNode as al, isWindowFunctionNode as am, isExpressionSelectionNode as an, type HydrationPivotPlan as ao, type HydrationRelationPlan as ap, type HydrationMetadata as aq, type OrmInterceptor as ar, type OrmSessionOptions as as, type OrmOptions as at, type DbExecutorFactory as au, type ExternalTransaction as av, Orm as aw, type DomainEventHandler as ax, DomainEventBus as ay, addDomainEvent as az, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type ColumnDef as h, type TableDef as i, type InsertQueryNode as j, type InsertCompiler as k, type CompiledQuery as l, type DialectKey as m, type UpdateCompiler as n, type DeleteQueryNode as o, type DeleteCompiler as p, type CompilerContext as q, type ForeignKeyReference as r, type IndexColumn as s, type IndexDef as t, type DbExecutor as u, type NamingStrategy as v, type EntityContext as w, type Entity as x, type HasManyRelation as y, type HasOneRelation as z };
+export { type HydrationContext as $, type Entity as A, type BinaryExpressionNode as B, type ColumnRef as C, Dialect as D, type ExpressionNode as E, type FunctionNode as F, type HasManyRelation as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type HasOneRelation as K, type LiteralNode as L, type BelongsToRelation as M, type NullExpressionNode as N, type OperandNode as O, type BelongsToManyRelation as P, type HasManyCollection as Q, type RelationMap as R, type SelectQueryNode as S, type TableRef as T, type UpdateQueryNode as U, type BelongsToReference as V, type WindowFunctionNode as W, type ManyToManyCollection as X, OrmSession as Y, SelectQueryBuilder as Z, type ExecutionContext as _, type ColumnNode as a, type CheckConstraint as a0, type TableOptions as a1, type TableHooks as a2, defineTable as a3, type ColumnType as a4, type ReferentialAction as a5, type RawDefaultValue as a6, type DefaultValue as a7, col as a8, RelationKinds as a9, Orm as aA, type DomainEventHandler as aB, type InitialHandlers as aC, DomainEventBus as aD, addDomainEvent as aE, EntityStatus as aF, type TrackedEntity as aG, type RelationKey as aH, type RelationChange as aI, type RelationChangeEntry as aJ, type DomainEvent as aK, type AnyDomainEvent as aL, type OrmDomainEvent as aM, type HasDomainEvents as aN, type QueryLogEntry as aO, type QueryLogger as aP, createQueryLoggingExecutor as aQ, type QueryResult as aR, rowsToQueryResult as aS, type SimpleQueryRunner as aT, createExecutorFromQueryRunner as aU, type EntityOrTableTargetResolver as aV, type EntityConstructor as aW, type RelationType as aa, type CascadeMode as ab, type RelationDef as ac, hasMany as ad, hasOne as ae, belongsTo as af, belongsToMany as ag, type RelationTargetTable as ah, type ColumnToTs as ai, type InferRow as aj, type HasOneReference as ak, createColumn as al, createLiteral as am, isOperandNode as an, isFunctionNode as ao, isCaseExpressionNode as ap, isWindowFunctionNode as aq, isExpressionSelectionNode as ar, type HydrationPivotPlan as as, type HydrationRelationPlan as at, type HydrationMetadata as au, type OrmInterceptor as av, type OrmSessionOptions as aw, type OrmOptions as ax, type DbExecutorFactory as ay, type ExternalTransaction as az, type LogicalExpressionNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type ColumnDef as h, type TableDef as i, type InsertQueryNode as j, type InsertCompiler as k, type CompiledQuery as l, type DialectKey as m, type UpdateCompiler as n, type DeleteQueryNode as o, type DeleteCompiler as p, type CompilerContext as q, type FunctionTableNode as r, type DerivedTableNode as s, type TableSourceNode as t, type ForeignKeyReference as u, type IndexColumn as v, type IndexDef as w, type DbExecutor as x, type NamingStrategy as y, type EntityContext as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "type": "module",
   "exports": {
     ".": {
@@ -46,6 +46,10 @@
   },
   "devDependencies": {
     "@vitest/ui": "^4.0.14",
+    "mysql2": "^3.15.3",
+    "pg": "^8.16.3",
+    "sqlite3": "^5.1.7",
+    "tedious": "^19.1.3",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^4.0.14"

package/src/codegen/naming-strategy.ts

@@ -1,4 +1,4 @@
-import type { TableNode, FunctionTableNode } from '../core/ast/query.js';
+import type { TableNode, FunctionTableNode, DerivedTableNode, TableSourceNode } from '../core/ast/query.js';
 import type { ColumnNode } from '../core/ast/expression.js';
 
 /**
@@ -7,10 +7,10 @@ import type { ColumnNode } from '../core/ast/expression.js';
 export interface NamingStrategy {
   /**
    * Converts a table name to a TypeScript symbol name
-   * @param table - Table node, function table node, or name
-   * @returns Valid TypeScript identifier
-   */
-  tableToSymbol(table: TableNode | FunctionTableNode | string): string;
+   * @param table - Table node, function table node, or name
+   * @returns Valid TypeScript identifier
+   */
+  tableToSymbol(table: TableSourceNode | string): string;
 
   /**
    * Converts a column reference to a property name
@@ -27,11 +27,16 @@ export interface NamingStrategy {
 export class DefaultNamingStrategy implements NamingStrategy {
   /**
    * Converts table names to TypeScript symbols
-   * @param table - Table node, function table node, or string name
-   * @returns Capitalized table name (handles schema-qualified names)
-   */
-  tableToSymbol(table: TableNode | FunctionTableNode | string): string {
-    const tableName = typeof table === 'string' ? table : table.name;
+   * @param table - Table node, function table node, or string name
+   * @returns Capitalized table name (handles schema-qualified names)
+   */
+  tableToSymbol(table: TableNode | FunctionTableNode | DerivedTableNode | string): string {
+    const tableName =
+      typeof table === 'string'
+        ? table
+        : table.type === 'DerivedTable'
+          ? table.alias
+          : table.name;
 
     // Handle schema-qualified names (e.g., "auth.user" → "AuthUser")
     if (tableName.includes('.')) {