metal-orm 1.0.58 → 1.0.60

package/dist/index.d.ts

@@ -251,10 +251,10 @@ interface BelongsToRelation<TTarget extends TableDef = TableDef> {
 /**
  * Many-to-many relationship definition with rich pivot metadata
  */
-interface BelongsToManyRelation<TTarget extends TableDef = TableDef> {
+interface BelongsToManyRelation<TTarget extends TableDef = TableDef, TPivot extends TableDef = TableDef> {
     type: typeof RelationKinds.BelongsToMany;
     target: TTarget;
-    pivotTable: TableDef;
+    pivotTable: TPivot;
     pivotForeignKeyToRoot: string;
     pivotForeignKeyToTarget: string;
     localKey?: string;
@@ -308,7 +308,7 @@ declare const belongsTo: <TTarget extends TableDef>(target: TTarget, foreignKey:
  * @param options - Pivot metadata configuration
  * @returns BelongsToManyRelation definition
  */
-declare const belongsToMany: <TTarget extends TableDef>(target: TTarget, pivotTable: TableDef, options: {
+declare const belongsToMany: <TTarget extends TableDef, TPivot extends TableDef = TableDef>(target: TTarget, pivotTable: TPivot, options: {
     pivotForeignKeyToRoot: string;
     pivotForeignKeyToTarget: string;
     localKey?: string;
@@ -316,7 +316,7 @@ declare const belongsToMany: <TTarget extends TableDef>(target: TTarget, pivotTa
     pivotPrimaryKey?: string;
     defaultPivotColumns?: string[];
     cascade?: CascadeMode;
-}) => BelongsToManyRelation<TTarget>;
+}) => BelongsToManyRelation<TTarget, TPivot>;
 
 interface IndexColumn {
     column: string;
@@ -397,6 +397,12 @@ 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>;
+/**
+ * Assigns relations to a table definition while preserving literal typing.
+ */
+declare function setRelations<TTable extends TableDef, TRelations extends Record<string, RelationDef>>(table: TTable, relations: TRelations): asserts table is TTable & {
+    relations: TRelations;
+};
 type DirectColumnKeys<T extends TableDef> = Exclude<keyof T["columns"] & string, keyof T | "$">;
 type TableRef$1<T extends TableDef> = T & {
     [K in DirectColumnKeys<T>]: T["columns"][K];
@@ -438,7 +444,7 @@ declare function getColumn<T extends TableDef>(table: T, key: string): ColumnDef
 /**
  * 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;
+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, TableDef> ? TTarget : never;
 type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
 /**
  * Maps a ColumnDef to its TypeScript type representation
@@ -452,7 +458,7 @@ type ColumnToTs<T extends ColumnDef> = [
 type InferRow<TTable extends TableDef> = {
     [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
 };
-type RelationResult$1<T extends RelationDef> = T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] : T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & {
+type RelationResult$1<T extends RelationDef> = T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] : T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToManyRelation<infer TTarget, TableDef> ? (InferRow<TTarget> & {
     _pivot?: Record<string, unknown>;
 })[] : never;
 /**
@@ -488,7 +494,7 @@ interface HasOneReferenceApi<TChild extends object = object> {
     set(data: Partial<TChild> | TChild | null): TChild | null;
 }
 type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
-interface ManyToManyCollection<TTarget> {
+interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
     length: number;
     [Symbol.iterator](): Iterator<TTarget>;
     load(): Promise<TTarget[]>;
@@ -496,6 +502,8 @@ interface ManyToManyCollection<TTarget> {
     attach(target: TTarget | number | string): void;
     detach(target: TTarget | number | string): void;
     syncByIds(ids: (number | string)[]): Promise<void>;
+    /** @internal Type-level marker for the related pivot entity */
+    readonly __pivotType?: TPivot;
 }
 type EntityInstance<TTable extends TableDef, TRow = InferRow<TTable>> = TRow & {
     [K in keyof RelationMap<TTable>]: RelationWrapper$1<TTable['relations'][K]>;
@@ -2157,10 +2165,25 @@ interface RelationIncludeOptions {
     filter?: ExpressionNode;
     joinKind?: RelationIncludeJoinKind;
     pivot?: {
-        columns?: string[];
+        columns?: readonly string[];
         aliasPrefix?: string;
     };
 }
+type ColumnKeys$1<T> = T extends {
+    columns: infer Columns;
+} ? keyof Columns & string : string;
+type PivotColumnKeys<TPivot> = ColumnKeys$1<TPivot> extends never ? string : ColumnKeys$1<TPivot>;
+type RelationTargetColumns<TRel extends RelationDef> = ColumnKeys$1<RelationTargetTable<TRel>>;
+type BelongsToManyPivotColumns<TRel extends RelationDef> = TRel extends BelongsToManyRelation<TableDef, infer TPivot> ? PivotColumnKeys<TPivot> : never;
+type TypedRelationIncludeOptions<TRel extends RelationDef> = TRel extends BelongsToManyRelation ? Omit<RelationIncludeOptions, 'columns' | 'pivot'> & {
+    columns?: readonly RelationTargetColumns<TRel>[];
+    pivot?: {
+        columns?: readonly BelongsToManyPivotColumns<TRel>[];
+        aliasPrefix?: string;
+    };
+} : Omit<RelationIncludeOptions, 'columns' | 'pivot'> & {
+    columns?: readonly RelationTargetColumns<TRel>[];
+};
 
 /**
  * Service for handling relation operations (joins, includes, etc.)
@@ -2171,6 +2194,8 @@ declare class RelationService {
     private readonly hydration;
     private readonly createQueryAstService;
     private readonly projectionHelper;
+    private readonly joinPlanner;
+    private readonly cteBuilder;
     /**
      * Creates a new RelationService instance
      * @param table - Table definition
@@ -2207,15 +2232,6 @@ declare class RelationService {
      * @returns Modified query AST with relation correlation
      */
     applyRelationCorrelation(relationName: string, ast: SelectQueryNode, additionalCorrelation?: ExpressionNode): SelectQueryNode;
-    /**
-     * Creates a join node for a relation
-     * @param state - Current query state
-     * @param relationName - Name of the relation
-     * @param joinKind - Type of join to use
-     * @param extraCondition - Additional join condition
-     * @returns Updated query state with join
-     */
-    private withJoin;
     /**
      * Selects columns for a relation
      * @param state - Current query state
@@ -2225,16 +2241,6 @@ declare class RelationService {
      */
     private selectColumns;
     private combineWithAnd;
-    private splitFilterExpressions;
-    private flattenAnd;
-    private isExpressionSelfContained;
-    private collectReferencedTables;
-    private collectFromExpression;
-    private collectFromOperand;
-    private collectFromOrderingTerm;
-    private createFilteredRelationCte;
-    private generateUniqueCteName;
-    private resolveTargetTableName;
     /**
      * Gets a relation definition by name
      * @param relationName - Name of the relation
@@ -2474,8 +2480,9 @@ type EntityConstructor<T = object> = new (...args: never[]) => T;
 type EntityOrTableTarget = EntityConstructor | TableDef;
 /**
  * Resolver for entity or table target, can be direct or function.
+ * @typeParam T - Specific target type that should be resolved
  */
-type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
+type EntityOrTableTargetResolver<T extends EntityOrTableTarget = EntityOrTableTarget> = T | (() => T);
 /**
  * Simplified column definition structure used during metadata registration.
  * @template T - Concrete column definition type being extended
@@ -2499,7 +2506,7 @@ interface HasManyRelationMetadata extends BaseRelationMetadata {
     /** The relation kind */
     kind: typeof RelationKinds.HasMany;
     /** The foreign key */
-    foreignKey: string;
+    foreignKey?: string;
     /** Optional local key */
     localKey?: string;
 }
@@ -2510,7 +2517,7 @@ interface HasOneRelationMetadata extends BaseRelationMetadata {
     /** The relation kind */
     kind: typeof RelationKinds.HasOne;
     /** The foreign key */
-    foreignKey: string;
+    foreignKey?: string;
     /** Optional local key */
     localKey?: string;
 }
@@ -2534,9 +2541,9 @@ interface BelongsToManyRelationMetadata extends BaseRelationMetadata {
     /** The pivot table */
     pivotTable: EntityOrTableTargetResolver;
     /** The pivot foreign key to root */
-    pivotForeignKeyToRoot: string;
+    pivotForeignKeyToRoot?: string;
     /** The pivot foreign key to target */
-    pivotForeignKeyToTarget: string;
+    pivotForeignKeyToTarget?: string;
     /** Optional local key */
     localKey?: string;
     /** Optional target key */
@@ -2584,7 +2591,7 @@ interface TrackedEntity {
 /**
  * Type representing a key for relation navigation
  */
-type RelationKey = string;
+type RelationKey$1 = string;
 /**
  * Represents a change operation on a relation
  * @typeParam T - Type of the related entity
@@ -2609,7 +2616,7 @@ interface RelationChangeEntry {
     /** Root entity that owns the relation */
     root: unknown;
     /** Key of the relation being changed */
-    relationKey: RelationKey;
+    relationKey: RelationKey$1;
     /** Table definition of the root entity */
     rootTable: TableDef;
     /** Name of the relation */
@@ -3197,7 +3204,7 @@ interface EntityContext {
      * @param relation - The relation definition
      * @param change - The relation change
      */
-    registerRelationChange(root: unknown, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>): void;
+    registerRelationChange(root: unknown, relationKey: RelationKey$1, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>): void;
 }
 
 /**
@@ -3380,7 +3387,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      * @param relation - The relation definition
      * @param change - The relation change
      */
-    registerRelationChange: (root: unknown, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>) => void;
+    registerRelationChange: (root: unknown, relationKey: RelationKey$1, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>) => void;
     /**
      * Gets all tracked entities for a specific table.
      * @param table - The table definition
@@ -3480,6 +3487,11 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
     getHydrationContext(): HydrationContext<E>;
 }
 
+type WhereHasOptions = {
+    correlate?: ExpressionNode;
+};
+type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<unknown, TChildTable>) => SelectQueryBuilder<unknown, TChildTable>;
+
 type SelectDialectInput = Dialect | DialectKey;
 
 type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
@@ -3492,10 +3504,6 @@ type DeepSelectEntry<TTable extends TableDef> = {
     columns: string[];
 };
 type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
-type WhereHasOptions = {
-    correlate?: ExpressionNode;
-};
-type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<unknown, TChildTable>) => SelectQueryBuilder<unknown, TChildTable>;
 /**
  * Main query builder class for constructing SQL SELECT queries
  * @typeParam T - Result type for projections (unused)
@@ -3505,7 +3513,13 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
     private readonly env;
     private readonly context;
     private readonly columnSelector;
-    private readonly relationManager;
+    private readonly fromFacet;
+    private readonly joinFacet;
+    private readonly projectionFacet;
+    private readonly predicateFacet;
+    private readonly cteFacet;
+    private readonly setOpFacet;
+    private readonly relationFacet;
     private readonly lazyRelations;
     private readonly lazyRelationOptions;
     /**
@@ -3526,6 +3540,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>;
     /**
@@ -3541,22 +3557,6 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @returns New SelectQueryBuilder instance for the child table
      */
     private createChildBuilder;
-    /**
-     * Applies an AST mutation using the query AST service
-     * @param context - Current query context
-     * @param mutator - Function that mutates the AST
-     * @returns Updated query context
-     */
-    private applyAst;
-    /**
-     * Applies a join to the query context
-     * @param context - Current query context
-     * @param table - Table to join
-     * @param condition - Join condition
-     * @param kind - Join kind
-     * @returns Updated query context with join applied
-     */
-    private applyJoin;
     /**
      * Applies a set operation to the query
      * @param operator - Set operation kind
@@ -3569,6 +3569,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>;
@@ -3576,6 +3585,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>;
     /**
@@ -3584,6 +3595,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>;
     /**
@@ -3592,6 +3609,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>;
     /**
@@ -3600,6 +3630,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>;
     /**
@@ -3608,6 +3643,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;
@@ -3620,6 +3662,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>;
     /**
@@ -3630,6 +3678,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>;
     /**
@@ -3640,6 +3697,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;
@@ -3652,6 +3718,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>;
     /**
@@ -3659,6 +3730,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>;
     /**
@@ -3666,6 +3742,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>;
     /**
@@ -3673,6 +3754,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>;
     /**
@@ -3681,6 +3764,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>;
     /**
@@ -3688,23 +3775,44 @@ 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?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
+    include<K extends keyof TTable['relations'] & string>(relationName: K, options?: TypedRelationIncludeOptions<TTable['relations'][K]>): SelectQueryBuilder<T, TTable>;
     /**
      * Includes a relation lazily in the query results
      * @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?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
+    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, 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>;
+    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>;
     /**
@@ -3726,10 +3834,25 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * Executes the query and returns hydrated results
      * @param ctx - ORM session context
      * @returns Promise of entity instances
+     * @example
+     * const users = await qb.select('id', 'name')
+     *   .where(eq(userTable.columns.active, true))
+     *   .execute(session);
      */
     execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]>;
-    private withAst;
+    /**
+     * Executes a count query for the current builder without LIMIT/OFFSET clauses.
+     *
+     * @example
+     * const total = await qb.count(session);
+     */
     count(session: OrmSession): Promise<number>;
+    /**
+     * Executes the query and returns both the paged items and the total.
+     *
+     * @example
+     * const { items, totalItems } = await qb.executePaged(session, { page: 1, pageSize: 20 });
+     */
     executePaged(session: OrmSession, options: {
         page: number;
         pageSize: number;
@@ -3742,24 +3865,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>[]>;
     /**
      * 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>;
     /**
@@ -3767,6 +3908,9 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param term - Column definition or ordering term to order by
      * @param directionOrOptions - Order direction or options (defaults to ASC)
      * @returns New query builder instance with the ORDER BY clause
+     *
+     * @example
+     * qb.orderBy(userTable.columns.createdAt, 'DESC');
      */
     orderBy(term: ColumnDef | OrderingTerm, directionOrOptions?: OrderDirection | {
         direction?: OrderDirection;
@@ -3777,54 +3921,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>;
     /**
@@ -3832,6 +4017,9 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param relationName - Name of the relationship to check
      * @param callback - Optional callback to modify the relationship query
      * @returns New query builder instance with the relationship existence check
+     *
+     * @example
+     * qb.whereHas('posts', postQb => postQb.where(eq(postTable.columns.published, true)));
      */
     whereHas<K extends keyof TTable['relations'] & string>(relationName: K, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
     /**
@@ -3839,28 +4027,48 @@ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef
      * @param relationName - Name of the relationship to check
      * @param callback - Optional callback to modify the relationship query
      * @returns New query builder instance with the relationship non-existence check
+     *
+     * @example
+     * qb.whereHasNot('posts', postQb => postQb.where(eq(postTable.columns.published, true)));
      */
     whereHasNot<K extends keyof TTable['relations'] & string>(relationName: K, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
     /**
      * 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;
 }
@@ -4259,6 +4467,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.
@@ -4579,6 +4849,26 @@ declare const generateCreateTableSql: (table: TableDef, dialect: SchemaDialect)
  * @returns The SQL statements.
  */
 declare const generateSchemaSql: (tables: TableDef[], dialect: SchemaDialect) => string[];
+/**
+ * Convenience wrapper for generateSchemaSql with rest args.
+ * @param dialect - The schema dialect used to render SQL.
+ * @param tables - The table definitions to create.
+ */
+declare const generateSchemaSqlFor: (dialect: SchemaDialect, ...tables: TableDef[]) => string[];
+/**
+ * Generates and executes schema SQL for the provided tables.
+ * @param executor - The database executor to run statements with.
+ * @param tables - The table definitions to create.
+ * @param dialect - The schema dialect used to render SQL.
+ */
+declare const executeSchemaSql: (executor: DbExecutor, tables: TableDef[], dialect: SchemaDialect) => Promise<void>;
+/**
+ * Convenience wrapper for executeSchemaSql with rest args.
+ * @param executor - The database executor to run statements with.
+ * @param dialect - The schema dialect used to render SQL.
+ * @param tables - The table definitions to create.
+ */
+declare const executeSchemaSqlFor: (executor: DbExecutor, dialect: SchemaDialect, ...tables: TableDef[]) => Promise<void>;
 
 /** The kind of schema change. */
 type SchemaChangeKind = 'createTable' | 'dropTable' | 'addColumn' | 'dropColumn' | 'alterColumn' | 'addIndex' | 'dropIndex';
@@ -5468,6 +5758,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
     private mapOp;
 }
 
+type RelationKey<TTable extends TableDef> = Extract<keyof RelationMap<TTable>, string>;
 /**
  * Metadata stored on entity instances for ORM internal use
  * @typeParam TTable - Table definition type
@@ -5478,7 +5769,7 @@ interface EntityMeta<TTable extends TableDef> {
     /** Table definition */
     table: TTable;
     /** Relations that should be loaded lazily */
-    lazyRelations: (keyof RelationMap<TTable>)[];
+    lazyRelations: RelationKey<TTable>[];
     /** Include options for lazy relations */
     lazyRelationOptions: Map<string, RelationIncludeOptions>;
     /** Cache for relation promises */
@@ -5497,7 +5788,8 @@ interface EntityMeta<TTable extends TableDef> {
  * @param factory - The factory function to create the cache
  * @returns Promise with the cached relation data
  */
-declare const relationLoaderCache: <T extends Map<string, unknown>>(meta: EntityMeta<TableDef>, relationName: string, factory: () => Promise<T>) => Promise<T>;
+declare const relationLoaderCache: <TTable extends TableDef, T extends Map<string, unknown>>(meta: EntityMeta<TTable>, relationName: string, factory: () => Promise<T>) => Promise<T>;
+
 /**
  * Creates an entity proxy with lazy loading capabilities.
  * @template TTable - The table type
@@ -5508,7 +5800,7 @@ declare const relationLoaderCache: <T extends Map<string, unknown>>(meta: Entity
  * @param lazyRelations - Optional lazy relations
  * @returns The entity instance
  */
-declare const createEntityProxy: <TTable extends TableDef, TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: TLazy[], lazyRelationOptions?: Map<string, RelationIncludeOptions>) => EntityInstance<TTable>;
+declare const createEntityProxy: <TTable extends TableDef, TLazy extends RelationKey<TTable> = RelationKey<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: TLazy[], lazyRelationOptions?: Map<string, RelationIncludeOptions>) => EntityInstance<TTable>;
 /**
  * Creates an entity instance from a database row.
  * @template TTable - The table type
@@ -5519,12 +5811,13 @@ declare const createEntityProxy: <TTable extends TableDef, TLazy extends keyof R
  * @param lazyRelations - Optional lazy relations
  * @returns The entity instance
  */
-declare const createEntityFromRow: <TTable extends TableDef, TResult extends EntityInstance<TTable> = EntityInstance<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: (keyof RelationMap<TTable>)[], lazyRelationOptions?: Map<string, RelationIncludeOptions>) => TResult;
+declare const createEntityFromRow: <TTable extends TableDef, TResult extends EntityInstance<TTable> = EntityInstance<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: RelationKey<TTable>[], lazyRelationOptions?: Map<string, RelationIncludeOptions>) => TResult;
 
 /**
  * An array of database rows, each represented as a record of string keys to unknown values.
  */
 type Rows$3 = Record<string, unknown>[];
+
 /**
  * Loads related entities for a has-many relation in batch.
  * @param ctx - The entity context.
@@ -5534,6 +5827,7 @@ type Rows$3 = Record<string, unknown>[];
  * @returns A promise resolving to a map of root keys to arrays of related rows.
  */
 declare const loadHasManyRelation: (ctx: EntityContext, rootTable: TableDef, relationName: string, relation: HasManyRelation, options?: RelationIncludeOptions) => Promise<Map<string, Rows$3>>;
+
 /**
  * Loads related entities for a has-one relation in batch.
  * @param ctx - The entity context.
@@ -5543,6 +5837,7 @@ declare const loadHasManyRelation: (ctx: EntityContext, rootTable: TableDef, rel
  * @returns A promise resolving to a map of root keys to single related rows.
  */
 declare const loadHasOneRelation: (ctx: EntityContext, rootTable: TableDef, relationName: string, relation: HasOneRelation, options?: RelationIncludeOptions) => Promise<Map<string, Record<string, unknown>>>;
+
 /**
  * Loads related entities for a belongs-to relation in batch.
  * @param ctx - The entity context.
@@ -5552,6 +5847,7 @@ declare const loadHasOneRelation: (ctx: EntityContext, rootTable: TableDef, rela
  * @returns A promise resolving to a map of foreign keys to single related rows.
  */
 declare const loadBelongsToRelation: (ctx: EntityContext, rootTable: TableDef, relationName: string, relation: BelongsToRelation, options?: RelationIncludeOptions) => Promise<Map<string, Record<string, unknown>>>;
+
 /**
  * Loads related entities for a belongs-to-many relation in batch, including pivot data.
  * @param ctx - The entity context.
@@ -5688,7 +5984,7 @@ type Rows = Record<string, unknown>[];
  *
  * @template TTarget The type of the target entities in the collection.
  */
-declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
+declare class DefaultManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> implements ManyToManyCollection<TTarget, TPivot> {
     private readonly ctx;
     private readonly meta;
     private readonly root;
@@ -5789,51 +6085,6 @@ type Jsonify<T> = {
  */
 declare const jsonify: <T extends object>(value: T) => Jsonify<T>;
 
-/**
- * Context object provided by standard decorators in newer TypeScript versions.
- */
-interface StandardDecoratorContext {
-    kind: string;
-    name?: string | symbol;
-    metadata?: Record<PropertyKey, unknown>;
-    static?: boolean;
-    private?: boolean;
-}
-/**
- * Dual-mode property decorator that supports both legacy and standard decorator syntax.
- */
-interface DualModePropertyDecorator {
-    (target: object, propertyKey: string | symbol): void;
-    (value: unknown, context: StandardDecoratorContext): void;
-}
-/**
- * Dual-mode class decorator that supports both legacy and standard decorator syntax.
- */
-interface DualModeClassDecorator {
-    <TFunction extends Function>(value: TFunction): void | TFunction;
-    <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
-}
-/**
- * Bag for storing decorator metadata during the decoration phase.
- */
-interface DecoratorMetadataBag {
-    columns: Array<{
-        propertyName: string;
-        column: ColumnDefLike;
-    }>;
-    relations: Array<{
-        propertyName: string;
-        relation: RelationMetadata;
-    }>;
-}
-/**
- * Public helper to read decorator metadata from a class constructor.
- * Standard decorators only; legacy metadata is intentionally ignored.
- * @param ctor - The entity constructor.
- * @returns The metadata bag if present.
- */
-declare const getDecoratorMetadata: (ctor: object) => DecoratorMetadataBag | undefined;
-
 /**
  * Options for defining an entity.
  */
@@ -5846,7 +6097,7 @@ interface EntityOptions {
  * @param options - Configuration options for the entity.
  * @returns A class decorator that registers the entity metadata.
  */
-declare function Entity(options?: EntityOptions): DualModeClassDecorator;
+declare function Entity(options?: EntityOptions): <T extends EntityConstructor>(value: T, context: ClassDecoratorContext) => T;
 
 /**
  * Options for defining a column in an entity.
@@ -5868,14 +6119,14 @@ type ColumnInput = ColumnOptions | ColumnDef;
  * @param definition - The column definition or options.
  * @returns A property decorator that registers the column metadata.
  */
-declare function Column(definition: ColumnInput): DualModePropertyDecorator;
+declare function Column(definition: ColumnInput): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 /**
  * Decorator to define a primary key column on an entity property.
  * Sets the primary flag to true and delegates to Column decorator.
  * @param definition - The column definition or options.
  * @returns A property decorator that registers the primary key column metadata.
  */
-declare function PrimaryKey(definition: ColumnInput): DualModePropertyDecorator;
+declare function PrimaryKey(definition: ColumnInput): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 
 interface BaseRelationOptions {
     target: EntityOrTableTargetResolver;
@@ -5886,28 +6137,28 @@ interface BaseRelationOptions {
  * Options for HasMany relation.
  */
 interface HasManyOptions extends BaseRelationOptions {
-    foreignKey: string;
+    foreignKey?: string;
 }
 /**
  * Options for HasOne relation.
  */
 interface HasOneOptions extends BaseRelationOptions {
-    foreignKey: string;
+    foreignKey?: string;
 }
 /**
  * Options for BelongsTo relation.
  */
 interface BelongsToOptions extends BaseRelationOptions {
-    foreignKey: string;
+    foreignKey?: string;
 }
 /**
  * Options for BelongsToMany relation.
  */
-interface BelongsToManyOptions {
-    target: EntityOrTableTargetResolver;
-    pivotTable: EntityOrTableTargetResolver;
-    pivotForeignKeyToRoot: string;
-    pivotForeignKeyToTarget: string;
+interface BelongsToManyOptions<TTarget extends EntityOrTableTarget = EntityOrTableTarget, TPivot extends EntityOrTableTarget = EntityOrTableTarget> {
+    target: EntityOrTableTargetResolver<TTarget>;
+    pivotTable: EntityOrTableTargetResolver<TPivot>;
+    pivotForeignKeyToRoot?: string;
+    pivotForeignKeyToTarget?: string;
     localKey?: string;
     targetKey?: string;
     pivotPrimaryKey?: string;
@@ -5919,25 +6170,25 @@ interface BelongsToManyOptions {
  * @param options - The relation options.
  * @returns A property decorator that registers the relation metadata.
  */
-declare function HasMany(options: HasManyOptions): DualModePropertyDecorator;
+declare function HasMany(options: HasManyOptions): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 /**
  * Decorator to define a HasOne relation on an entity property.
  * @param options - The relation options.
  * @returns A property decorator that registers the relation metadata.
  */
-declare function HasOne(options: HasOneOptions): DualModePropertyDecorator;
+declare function HasOne(options: HasOneOptions): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 /**
  * Decorator to define a BelongsTo relation on an entity property.
  * @param options - The relation options.
  * @returns A property decorator that registers the relation metadata.
  */
-declare function BelongsTo(options: BelongsToOptions): DualModePropertyDecorator;
+declare function BelongsTo(options: BelongsToOptions): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 /**
  * Decorator to define a BelongsToMany relation on an entity property.
  * @param options - The relation options.
  * @returns A property decorator that registers the relation metadata.
  */
-declare function BelongsToMany(options: BelongsToManyOptions): DualModePropertyDecorator;
+declare function BelongsToMany<TTarget extends EntityOrTableTarget = EntityOrTableTarget, TPivot extends EntityOrTableTarget = EntityOrTableTarget>(options: BelongsToManyOptions<TTarget, TPivot>): (_value: unknown, context: ClassFieldDecoratorContext) => void;
 
 /**
  * Bootstraps all entities by building their table definitions and relations.
@@ -5964,7 +6215,7 @@ type EntityTable<TEntity extends object> = Omit<TableDef<{
     [K in SelectableKeys<TEntity>]: ColumnDef;
 }>, 'relations'> & {
     relations: {
-        [K in RelationKeys<TEntity>]: NonNullable<TEntity[K]> extends HasManyCollection<infer TChild> ? HasManyRelation<EntityTable<NonNullable<TChild> & object>> : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget> ? BelongsToManyRelation<EntityTable<NonNullable<TTarget> & object>> : 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;
+        [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>>;
@@ -5974,7 +6225,27 @@ declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor
  * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
-declare const entityRef: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => TableRef$1<TTable>;
+declare const entityRef: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => TableRef$1<EntityTable<TEntity>>;
+
+/**
+ * Bag for storing decorator metadata during the decoration phase.
+ */
+interface DecoratorMetadataBag {
+    columns: Array<{
+        propertyName: string;
+        column: ColumnDefLike;
+    }>;
+    relations: Array<{
+        propertyName: string;
+        relation: RelationMetadata;
+    }>;
+}
+/**
+ * Public helper to read decorator metadata from a class constructor.
+ * @param ctor - The entity constructor.
+ * @returns The metadata bag if present.
+ */
+declare const getDecoratorMetadata: (ctor: object) => DecoratorMetadataBag | undefined;
 
 type PoolOptions = {
     /** Maximum number of live resources (idle + leased). */
@@ -6139,4 +6410,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, 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, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, 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, 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, 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 };