@mikro-orm/sql 7.0.0-dev.228 → 7.0.0-dev.229

package/AbstractSqlDriver.d.ts

@@ -1,4 +1,4 @@
-import { type AnyEntity, type Collection, type Configuration, type ConnectionType, type Constructor, type CountOptions, DatabaseDriver, type DeleteOptions, type Dictionary, type DriverMethodOptions, type EntityData, type EntityDictionary, type EntityField, EntityManagerType, type EntityMetadata, type EntityName, type EntityProperty, type FilterQuery, type FindOneOptions, type FindOptions, type LockOptions, type LoggingOptions, type NativeInsertUpdateManyOptions, type NativeInsertUpdateOptions, type ObjectQuery, type Options, type OrderDefinition, type PopulateOptions, type PopulatePath, type Primary, type QueryOrderMap, type QueryResult, RawQueryFragment, type StreamOptions, type Transaction, type UpsertManyOptions, type UpsertOptions } from '@mikro-orm/core';
+import { type AnyEntity, type Collection, type Configuration, type ConnectionType, type Constructor, type CountOptions, DatabaseDriver, type DeleteOptions, type Dictionary, type DriverMethodOptions, type EntityData, type EntityDictionary, type EntityField, EntityManagerType, type EntityMetadata, type EntityName, type EntityProperty, type FilterQuery, type FindOneOptions, type FindOptions, type FormulaTable, type LockOptions, type LoggingOptions, type NativeInsertUpdateManyOptions, type NativeInsertUpdateOptions, type ObjectQuery, type Options, type OrderDefinition, type PopulateOptions, type PopulatePath, type Primary, type QueryOrderMap, type QueryResult, type Raw, RawQueryFragment, type StreamOptions, type Transaction, type UpsertManyOptions, type UpsertOptions } from '@mikro-orm/core';
 import type { AbstractSqlConnection } from './AbstractSqlConnection.js';
 import type { AbstractSqlPlatform } from './AbstractSqlPlatform.js';
 import { QueryBuilder } from './query/QueryBuilder.js';
@@ -13,6 +13,12 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     protected readonly platform: Platform;
     protected constructor(config: Configuration, platform: Platform, connection: Constructor<Connection>, connector: string[]);
     getPlatform(): Platform;
+    /** Evaluates a formula callback, handling both string and Raw return values. */
+    evaluateFormula(formula: (...args: any[]) => string | Raw, columns: any, table: FormulaTable): string;
+    /** For TPT entities, returns ownProps (columns in this table); otherwise returns all props. */
+    private getTableProps;
+    /** Creates a FormulaTable object for use in formula callbacks. */
+    private createFormulaTable;
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];
     private createQueryBuilderFromOptions;
     find<T extends object, P extends string = never, F extends string = PopulatePath.ALL, E extends string = never>(entityName: EntityName<T>, where: ObjectQuery<T>, options?: FindOptions<T, P, F, E>): Promise<EntityData<T>[]>;
@@ -25,6 +31,12 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     protected wrapVirtualExpressionInSubquery<T extends object>(meta: EntityMetadata<T>, expression: string, where: FilterQuery<T>, options: FindOptions<T, any>, type: QueryType): Promise<T[] | number>;
     protected wrapVirtualExpressionInSubqueryStream<T extends object>(meta: EntityMetadata<T>, expression: string, where: FilterQuery<T>, options: FindOptions<T, any, any, any>, type: QueryType.SELECT): AsyncIterableIterator<T>;
     mapResult<T extends object>(result: EntityData<T>, meta: EntityMetadata<T>, populate?: PopulateOptions<T>[], qb?: QueryBuilder<T, any, any, any>, map?: Dictionary): EntityData<T> | null;
+    /**
+     * Maps aliased columns from TPT parent tables back to their original field names.
+     * TPT parent columns are selected with aliases like `parent_alias__column_name`,
+     * and need to be renamed back to `column_name` for the result mapper to work.
+     */
+    private mapTPTColumns;
     private mapJoinedProps;
     /**
      * Maps a single property from a joined result row into the relation pojo.
@@ -82,6 +94,29 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     mergeJoinedResult<T extends object>(rawResults: EntityData<T>[], meta: EntityMetadata<T>, joinedProps: PopulateOptions<T>[]): EntityData<T>[];
     protected shouldHaveColumn<T, U>(meta: EntityMetadata<T>, prop: EntityProperty<U>, populate: readonly PopulateOptions<U>[], fields?: readonly InternalField<U>[], exclude?: readonly InternalField<U>[]): boolean;
     protected getFieldsForJoinedLoad<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, options: FieldsForJoinedLoadOptions<T>): InternalField<T>[];
+    /**
+     * Adds LEFT JOINs and fields for TPT polymorphic loading when populating a relation to a TPT base class.
+     * @internal
+     */
+    protected addTPTPolymorphicJoinsForRelation<T extends object>(qb: QueryBuilder<T, any, any, any>, meta: EntityMetadata<T>, baseAlias: string, fields: InternalField<T>[]): void;
+    /**
+     * Find the alias for a TPT child table in the query builder.
+     * @internal
+     */
+    protected findTPTChildAlias<T extends object>(qb: QueryBuilder<T, any, any, any>, childMeta: EntityMetadata): string | undefined;
+    /**
+     * Builds a CASE WHEN expression for TPT discriminator.
+     * Determines concrete entity type based on which child table has a non-null PK.
+     * @internal
+     */
+    buildTPTDiscriminatorExpression(meta: EntityMetadata, descendants: EntityMetadata[], aliasMap: Dictionary<string>, baseAlias: string): Raw;
+    /**
+     * Maps TPT child-specific fields during hydration.
+     * When a relation points to a TPT base class, the actual entity might be a child class.
+     * This method reads the discriminator to determine the concrete type and maps child-specific fields.
+     * @internal
+     */
+    protected mapTPTChildFields<T extends object>(relationPojo: EntityData<T>, meta: EntityMetadata<T>, relationAlias: string, qb: QueryBuilder<T, any, any, any>, root: EntityData<T>): void;
     /**
      * @internal
      */

package/AbstractSqlDriver.js

@@ -17,6 +17,21 @@ export class AbstractSqlDriver extends DatabaseDriver {
     getPlatform() {
         return this.platform;
     }
+    /** Evaluates a formula callback, handling both string and Raw return values. */
+    evaluateFormula(formula, columns, table) {
+        const result = formula(columns, table);
+        return isRaw(result) ? this.platform.formatQuery(result.sql, result.params) : result;
+    }
+    /** For TPT entities, returns ownProps (columns in this table); otherwise returns all props. */
+    getTableProps(meta) {
+        return meta.inheritanceType === 'tpt' && meta.ownProps ? meta.ownProps : meta.props;
+    }
+    /** Creates a FormulaTable object for use in formula callbacks. */
+    createFormulaTable(alias, meta, schema) {
+        const effectiveSchema = schema ?? (meta.schema !== '*' ? meta.schema : undefined);
+        const qualifiedName = effectiveSchema ? `${effectiveSchema}.${meta.tableName}` : meta.tableName;
+        return { alias, name: meta.tableName, schema: effectiveSchema, qualifiedName, toString: () => alias };
+    }
     createEntityManager(useContext) {
         const EntityManagerClass = this.config.get('entityManager', SqlEntityManager);
         return new EntityManagerClass(this.config, this, this.metadata, useContext);
@@ -196,6 +211,15 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
     }
     mapResult(result, meta, populate = [], qb, map = {}) {
+        // For TPT inheritance, map aliased parent table columns back to their field names
+        if (qb && meta.inheritanceType === 'tpt' && meta.tptParent) {
+            this.mapTPTColumns(result, meta, qb);
+        }
+        // For TPT polymorphic queries (querying a base class), map child table fields
+        if (qb && meta.inheritanceType === 'tpt' && meta.allTPTDescendants?.length) {
+            const mainAlias = qb.mainAlias?.aliasName ?? 'e0';
+            this.mapTPTChildFields(result, meta, mainAlias, qb, result);
+        }
         const ret = super.mapResult(result, meta);
         /* v8 ignore next */
         if (!ret) {
@@ -207,6 +231,33 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         return ret;
     }
+    /**
+     * Maps aliased columns from TPT parent tables back to their original field names.
+     * TPT parent columns are selected with aliases like `parent_alias__column_name`,
+     * and need to be renamed back to `column_name` for the result mapper to work.
+     */
+    mapTPTColumns(result, meta, qb) {
+        const tptAliases = qb._tptAlias;
+        // Walk up the TPT hierarchy
+        let parentMeta = meta.tptParent;
+        while (parentMeta) {
+            const parentAlias = tptAliases[parentMeta.className];
+            if (parentAlias) {
+                // Rename columns from this parent table
+                for (const prop of parentMeta.ownProps) {
+                    for (const fieldName of prop.fieldNames) {
+                        const aliasedKey = `${parentAlias}__${fieldName}`;
+                        if (aliasedKey in result) {
+                            // Copy the value to the unaliased field name and remove the aliased key
+                            result[fieldName] = result[aliasedKey];
+                            delete result[aliasedKey];
+                        }
+                    }
+                }
+            }
+            parentMeta = parentMeta.tptParent;
+        }
+    }
     mapJoinedProps(result, meta, populate, qb, root, map, parentJoinPath) {
         const joinedProps = this.joinedProps(meta, populate);
         joinedProps.forEach(hint => {
@@ -325,6 +376,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
             for (const prop of targetProps) {
                 this.mapJoinedProp(relationPojo, prop, relationAlias, root, tz, meta2);
             }
+            // Handle TPT polymorphic child fields - map fields from child table aliases
+            this.mapTPTChildFields(relationPojo, meta2, relationAlias, qb, root);
             // properties can be mapped to multiple places, e.g. when sharing a column in multiple FKs,
             // so we need to delete them after everything is mapped from given level
             for (const prop of targetProps) {
@@ -352,7 +405,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
      * Maps a single property from a joined result row into the relation pojo.
      * Handles polymorphic FKs, composite keys, Date parsing, and embedded objects.
      */
-    mapJoinedProp(relationPojo, prop, relationAlias, root, tz, meta) {
+    mapJoinedProp(relationPojo, prop, relationAlias, root, tz, meta, options) {
         if (prop.fieldNames.every(name => typeof root[`${relationAlias}__${name}`] === 'undefined')) {
             return;
         }
@@ -401,6 +454,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 }
             }
         }
+        if (options?.deleteFromRoot) {
+            for (const name of prop.fieldNames) {
+                delete root[`${relationAlias}__${name}`];
+            }
+        }
     }
     async count(entityName, where, options = {}) {
         const meta = this.metadata.get(entityName);
@@ -453,7 +511,8 @@ export class AbstractSqlDriver extends DatabaseDriver {
     async nativeInsertMany(entityName, data, options = {}, transform) {
         options.processCollections ??= true;
         options.convertCustomTypes ??= true;
-        const meta = this.metadata.get(entityName).root;
+        const entityMeta = this.metadata.get(entityName);
+        const meta = entityMeta.inheritanceType === 'tpt' ? entityMeta : entityMeta.root;
         const collections = options.processCollections ? data.map(d => this.extractManyToMany(meta, d)) : [];
         const pks = this.getPrimaryKeyFields(meta);
         const set = new Set();
@@ -470,7 +529,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
         let sql = `insert into ${tableName} `;
         sql += fields.length > 0 ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')' : `(${this.platform.quoteIdentifier(pks[0])})`;
         if (this.platform.usesOutputStatement()) {
-            const returningProps = meta.props
+            const returningProps = this.getTableProps(meta)
                 .filter(prop => (prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated)
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
@@ -577,7 +636,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 .join(', ');
         }
         if (meta && this.platform.usesReturningStatement()) {
-            const returningProps = meta.props
+            const returningProps = this.getTableProps(meta)
                 .filter(prop => (prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated)
                 .filter(prop => !(prop.name in data[0]) || isRaw(data[0][prop.name]));
             const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
@@ -1189,6 +1248,11 @@ export class AbstractSqlDriver extends DatabaseDriver {
         const populate = options.populate ?? [];
         const joinedProps = this.joinedProps(meta, populate, options);
         const populateWhereAll = options?._populateWhere === 'all' || Utils.isEmpty(options?._populateWhere);
+        // Ensure TPT joins are applied early so that _tptAlias is available for join resolution
+        // This is needed when populating relations that are inherited from TPT parent entities
+        if (!options.parentJoinPath) {
+            qb.ensureTPTJoins();
+        }
         // root entity is already handled, skip that
         if (options.parentJoinPath) {
             // alias all fields in the primary table
@@ -1241,6 +1305,12 @@ export class AbstractSqlDriver extends DatabaseDriver {
                         : JoinType.leftJoin;
             const schema = prop.targetMeta.schema === '*' ? (options?.schema ?? this.config.get('schema')) : prop.targetMeta.schema;
             qb.join(field, tableAlias, {}, joinType, path, schema);
+            // For relations to TPT base classes, add LEFT JOINs for all child tables (polymorphic loading)
+            if (meta2.inheritanceType === 'tpt' && meta2.tptChildren?.length && !ref) {
+                // Use the registry metadata to ensure allTPTDescendants is available
+                const tptMeta = this.metadata.get(meta2.class);
+                this.addTPTPolymorphicJoinsForRelation(qb, tptMeta, tableAlias, fields);
+            }
             if (pivotRefJoin) {
                 fields.push(...prop.joinColumns.map(col => qb.helper.mapper(`${tableAlias}.${col}`, qb.type, undefined, `${tableAlias}__${col}`)), ...prop.inverseJoinColumns.map(col => qb.helper.mapper(`${tableAlias}.${col}`, qb.type, undefined, `${tableAlias}__${col}`)));
             }
@@ -1277,6 +1347,110 @@ export class AbstractSqlDriver extends DatabaseDriver {
         }
         return fields;
     }
+    /**
+     * Adds LEFT JOINs and fields for TPT polymorphic loading when populating a relation to a TPT base class.
+     * @internal
+     */
+    addTPTPolymorphicJoinsForRelation(qb, meta, baseAlias, fields) {
+        // allTPTDescendants is pre-computed during discovery, sorted by depth (deepest first)
+        const descendants = meta.allTPTDescendants;
+        const childAliases = {};
+        // LEFT JOIN each descendant table
+        for (const childMeta of descendants) {
+            const childAlias = qb.getNextAlias(childMeta.className);
+            qb.createAlias(childMeta.class, childAlias);
+            childAliases[childMeta.className] = childAlias;
+            qb.addPropertyJoin(childMeta.tptInverseProp, baseAlias, childAlias, JoinType.leftJoin, `[tpt]${meta.className}`);
+            // Add fields from this child (only ownProps, skip PKs)
+            for (const prop of childMeta.ownProps.filter(p => !p.primary && this.platform.shouldHaveColumn(p, []))) {
+                for (const fieldName of prop.fieldNames) {
+                    const field = `${childAlias}.${fieldName}`;
+                    const fieldAlias = `${childAlias}__${fieldName}`;
+                    fields.push(raw(`${this.platform.quoteIdentifier(field)} as ${this.platform.quoteIdentifier(fieldAlias)}`));
+                }
+            }
+        }
+        // Add computed discriminator (descendants already sorted by depth)
+        if (meta.root.tptDiscriminatorColumn) {
+            fields.push(this.buildTPTDiscriminatorExpression(meta, descendants, childAliases, baseAlias));
+        }
+    }
+    /**
+     * Find the alias for a TPT child table in the query builder.
+     * @internal
+     */
+    findTPTChildAlias(qb, childMeta) {
+        const joins = qb._joins;
+        for (const key of Object.keys(joins)) {
+            if (joins[key].table === childMeta.tableName && key.includes('[tpt]')) {
+                return joins[key].alias;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Builds a CASE WHEN expression for TPT discriminator.
+     * Determines concrete entity type based on which child table has a non-null PK.
+     * @internal
+     */
+    buildTPTDiscriminatorExpression(meta, descendants, aliasMap, baseAlias) {
+        const cases = descendants.map(child => {
+            const childAlias = aliasMap[child.className];
+            const pkFieldName = child.properties[child.primaryKeys[0]].fieldNames[0];
+            return `when ${this.platform.quoteIdentifier(`${childAlias}.${pkFieldName}`)} is not null then '${child.discriminatorValue}'`;
+        });
+        const defaultValue = meta.abstract ? 'null' : `'${meta.discriminatorValue}'`;
+        const caseExpr = `case ${cases.join(' ')} else ${defaultValue} end`;
+        const aliased = this.platform.quoteIdentifier(`${baseAlias}__${meta.root.tptDiscriminatorColumn}`);
+        return raw(`${caseExpr} as ${aliased}`);
+    }
+    /**
+     * Maps TPT child-specific fields during hydration.
+     * When a relation points to a TPT base class, the actual entity might be a child class.
+     * This method reads the discriminator to determine the concrete type and maps child-specific fields.
+     * @internal
+     */
+    mapTPTChildFields(relationPojo, meta, relationAlias, qb, root) {
+        // Check if this is a TPT base with polymorphic children
+        if (meta.inheritanceType !== 'tpt' || !meta.root.tptDiscriminatorColumn) {
+            return;
+        }
+        // Read the discriminator value
+        const discriminatorAlias = `${relationAlias}__${meta.root.tptDiscriminatorColumn}`;
+        const discriminatorValue = root[discriminatorAlias];
+        if (!discriminatorValue) {
+            return;
+        }
+        // Set the discriminator in the pojo for EntityFactory
+        relationPojo[meta.root.tptDiscriminatorColumn] = discriminatorValue;
+        // Find the concrete metadata from discriminator map
+        const concreteClass = meta.root.discriminatorMap?.[discriminatorValue];
+        /* v8 ignore next 3 - defensive check for invalid discriminator values */
+        if (!concreteClass) {
+            return;
+        }
+        const concreteMeta = this.metadata.get(concreteClass);
+        if (concreteMeta === meta) {
+            // Already the concrete type, no child fields to map
+            delete root[discriminatorAlias];
+            return;
+        }
+        // Traverse up from concrete type and map fields from each level's table
+        const tz = this.platform.getTimezone();
+        let currentMeta = concreteMeta;
+        while (currentMeta && currentMeta !== meta) {
+            const childAlias = this.findTPTChildAlias(qb, currentMeta);
+            if (childAlias) {
+                // Map fields using same filtering as joined loading, plus skip PKs
+                for (const prop of currentMeta.ownProps.filter(p => !p.primary && this.platform.shouldHaveColumn(p, []))) {
+                    this.mapJoinedProp(relationPojo, prop, childAlias, root, tz, currentMeta, { deleteFromRoot: true });
+                }
+            }
+            currentMeta = currentMeta.tptParent;
+        }
+        // Clean up the discriminator alias
+        delete root[discriminatorAlias];
+    }
     /**
      * @internal
      */
@@ -1306,18 +1480,10 @@ export class AbstractSqlDriver extends DatabaseDriver {
             return [raw(`${prop.customType.convertToJSValueSQL(prefixed, this.platform)} as ${aliased}`)];
         }
         if (prop.formula) {
-            const alias = this.platform.quoteIdentifier(tableAlias);
-            const effectiveSchema = schema ?? (meta.schema !== '*' ? meta.schema : undefined);
-            const qualifiedName = effectiveSchema ? `${effectiveSchema}.${meta.tableName}` : meta.tableName;
-            const table = {
-                alias: alias.toString(),
-                name: meta.tableName,
-                schema: effectiveSchema,
-                qualifiedName,
-                toString: () => alias.toString(),
-            };
-            const columns = meta.createColumnMappingObject();
-            return [raw(`${prop.formula(table, columns)} as ${aliased}`)];
+            const quotedAlias = this.platform.quoteIdentifier(tableAlias).toString();
+            const table = this.createFormulaTable(quotedAlias, meta, schema);
+            const columns = meta.createColumnMappingObject(tableAlias);
+            return [raw(`${this.evaluateFormula(prop.formula, columns, table)} as ${aliased}`)];
         }
         return prop.fieldNames.map(fieldName => {
             return `${tableAlias}.${fieldName} as ${tableAlias}__${fieldName}`;
@@ -1572,7 +1738,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
             if (!options.fields.includes('*') && !options.fields.includes(`${qb.alias}.*`)) {
                 ret.unshift(...meta.primaryKeys.filter(pk => !options.fields.includes(pk)));
             }
-            if (meta.root.discriminatorColumn && !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
+            if (meta.root.inheritanceType === 'sti' && !options.fields.includes(`${qb.alias}.${meta.root.discriminatorColumn}`)) {
                 ret.push(meta.root.discriminatorColumn);
             }
         }
@@ -1589,24 +1755,18 @@ export class AbstractSqlDriver extends DatabaseDriver {
             ret.push('*');
         }
         if (ret.length > 0 && !hasExplicitFields && addFormulas) {
-            const columns = meta.createColumnMappingObject();
+            // Create formula column mapping with unquoted aliases - quoting should be handled by the user via `quote` helper
+            const quotedAlias = this.platform.quoteIdentifier(alias);
+            const columns = meta.createColumnMappingObject(alias);
             const effectiveSchema = schema ?? (meta.schema !== '*' ? meta.schema : undefined);
             for (const prop of meta.props) {
                 if (lazyProps.includes(prop)) {
                     continue;
                 }
                 if (prop.formula) {
-                    const a = this.platform.quoteIdentifier(alias);
                     const aliased = this.platform.quoteIdentifier(prop.fieldNames[0]);
-                    const qualifiedName = effectiveSchema ? `${effectiveSchema}.${meta.tableName}` : meta.tableName;
-                    const table = {
-                        alias: a.toString(),
-                        name: meta.tableName,
-                        schema: effectiveSchema,
-                        qualifiedName,
-                        toString: () => a.toString(),
-                    };
-                    ret.push(raw(`${prop.formula(table, columns)} as ${aliased}`));
+                    const table = this.createFormulaTable(quotedAlias.toString(), meta, effectiveSchema);
+                    ret.push(raw(`${this.evaluateFormula(prop.formula, columns, table)} as ${aliased}`));
                 }
                 if (!prop.object && (prop.hasConvertToDatabaseValueSQL || prop.hasConvertToJSValueSQL)) {
                     ret.push(prop.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.0.0-dev.228",
+  "version": "7.0.0-dev.229",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "type": "module",
   "exports": {
@@ -56,6 +56,6 @@
     "@mikro-orm/core": "^6.6.4"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.0.0-dev.228"
+    "@mikro-orm/core": "7.0.0-dev.229"
   }
 }

package/query/QueryBuilder.d.ts

@@ -202,6 +202,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     protected subQueries: Dictionary<string>;
     protected _mainAlias?: Alias<Entity>;
     protected _aliases: Dictionary<Alias<any>>;
+    protected _tptAlias: Dictionary<string>;
     protected _helper?: QueryBuilderHelper;
     protected _query?: {
         sql?: string;
@@ -209,6 +210,8 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
         qb: NativeQueryBuilder;
     };
     protected readonly platform: AbstractSqlPlatform;
+    private tptJoinsApplied;
+    private readonly autoJoinedPaths;
     /**
      * @internal
      */
@@ -403,7 +406,6 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * Apply filters to the QB where condition.
      */
     applyFilters(filterOptions?: FilterOptions): Promise<void>;
-    private readonly autoJoinedPaths;
     /**
      * @internal
      */
@@ -737,6 +739,13 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      */
     getLoggerContext<T extends Dictionary & LoggingOptions = Dictionary>(): T;
     private fromVirtual;
+    /**
+     * Adds a join from a property object. Used internally for TPT joins where the property
+     * is synthetic (not in entity.properties) but defined on metadata (e.g., tptParentProp).
+     * The caller must create the alias first via createAlias().
+     * @internal
+     */
+    addPropertyJoin(prop: EntityProperty, ownerAlias: string, alias: string, type: JoinType, path: string, schema?: string): string;
     private joinReference;
     protected prepareFields<T>(fields: InternalField<T>[], type?: 'where' | 'groupBy' | 'sub-query', schema?: string): (string | RawQueryFragment)[];
     /**
@@ -748,6 +757,27 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private init;
     private getQueryBase;
     private applyDiscriminatorCondition;
+    /**
+     * Ensures TPT joins are applied. Can be called early before finalize() to populate
+     * the _tptAlias map for use in join resolution. Safe to call multiple times.
+     * @internal
+     */
+    ensureTPTJoins(): void;
+    /**
+     * For TPT (Table-Per-Type) inheritance: INNER JOINs parent tables.
+     * When querying a child entity, we need to join all parent tables.
+     * Field selection is handled separately in addTPTParentFields().
+     */
+    private applyTPTJoins;
+    /**
+     * For TPT inheritance: adds field selections from parent tables.
+     */
+    private addTPTParentFields;
+    /**
+     * For TPT polymorphic queries: LEFT JOINs all child tables when querying a TPT base class.
+     * Adds discriminator and child fields to determine and load the concrete type.
+     */
+    private applyTPTPolymorphicJoins;
     private finalize;
     /** @internal */
     processPopulateHint(): void;
@@ -784,7 +814,8 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     protected transferConditionsToJoin(cond: Dictionary, join: JoinOptions, path?: string): void;
     private wrapModifySubQuery;
     private getSchema;
-    private createAlias;
+    /** @internal */
+    createAlias<U = unknown>(entityName: EntityName<U>, aliasName: string, subQuery?: NativeQueryBuilder): Alias<U>;
     private createMainAlias;
     private fromSubQuery;
     private fromEntityName;