@mikro-orm/core 7.2.2-dev.3 → 7.2.2-dev.30

package/EntityManager.d.ts

@@ -580,6 +580,11 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Checks whether this EntityManager is currently operating inside a database transaction.
      */
     isInTransaction(): boolean;
+    /**
+     * Checks whether transactions are disabled for this EntityManager.
+     * @internal
+     */
+    isTransactionDisabled(): boolean;
     /**
      * Gets the transaction context (driver dependent object used to make sure queries are executed on same connection).
      */
@@ -633,7 +638,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * @internal
      */
-    tryCache<T extends object, R>(entityName: EntityName<T>, config: boolean | number | [string, number] | undefined, key: unknown, refresh?: boolean, merge?: boolean): Promise<{
+    tryCache<T extends object, R>(entityName: EntityName<T>, config: boolean | number | [string, number] | undefined, key: unknown, refresh?: boolean, merge?: boolean, schema?: string): Promise<{
         data?: R | null;
         key: string;
     } | undefined>;

package/EntityManager.js

@@ -133,7 +133,7 @@ export class EntityManager {
         options.populate = (await em.preparePopulate(entityName, options));
         const populate = options.populate;
         const cacheKey = em.cacheKey(entityName, options, 'em.find', where);
-        const cached = await em.tryCache(entityName, options.cache, cacheKey, options.refresh, true);
+        const cached = await em.tryCache(entityName, options.cache, cacheKey, options.refresh, true, options.schema);
         if (cached?.data) {
             await em.#entityLoader.populate(entityName, cached.data, populate, {
                 ...options,
@@ -789,6 +789,10 @@ export class EntityManager {
                 .getHydrator(this.metadata)
                 .hydrate(ref, helper(ref).__meta, data, em.#entityFactory, 'full', false, false);
             Utils.merge(helper(ref).__originalEntityData, this.#comparator.prepareEntity(e));
+            // index a refreshed `targetKey` value, `getByKey` ignores the old one as stale
+            if (helper(ref).__meta.root.targetKeys) {
+                em.#unitOfWork.getIdentityMap().store(ref);
+            }
             found ||= ref === entity;
         }
         if (!found) {
@@ -834,7 +838,7 @@ export class EntityManager {
         validateParams(where);
         options.populate = (await em.preparePopulate(entityName, options));
         const cacheKey = em.cacheKey(entityName, options, 'em.findOne', where);
-        const cached = await em.tryCache(entityName, options.cache, cacheKey, options.refresh, true);
+        const cached = await em.tryCache(entityName, options.cache, cacheKey, options.refresh, true, options.schema);
         if (cached?.data !== undefined) {
             if (cached.data) {
                 await em.#entityLoader.populate(entityName, [cached.data], options.populate, {
@@ -994,13 +998,14 @@ export class EntityManager {
         });
         const uniqueFields = options.onConflictFields ??
             (Utils.isPlainObject(where) ? Object.keys(where) : meta.primaryKeys);
-        const returning = getOnConflictReturningFields(meta, data, uniqueFields, options);
+        const platform = this.getPlatform();
+        const returning = getOnConflictReturningFields(meta, data, uniqueFields, options, platform);
         if (options.onConflictWhere && !ret.row) {
             returning.push(...Object.keys(data));
         }
         if (options.onConflictAction === 'ignore' ||
             !helper(entity).hasPrimaryKey() ||
-            (returning.length > 0 && !(this.getPlatform().usesReturningStatement() && ret.row))) {
+            (returning.length > 0 && !((platform.usesReturningStatement() || platform.usesOutputStatement()) && ret.row))) {
             const where = {};
             if (Array.isArray(uniqueFields)) {
                 for (const prop of uniqueFields) {
@@ -1091,6 +1096,41 @@ export class EntityManager {
             }
             return ret;
         }
+        // merge fields are derived from the first row, rows of a different shape need their own statement
+        if (!options.onConflictMergeFields && options.onConflictAction !== 'ignore') {
+            const pks = this.metadata.get(entityName).primaryKeys;
+            const shapes = new Map();
+            data.forEach((row, i) => {
+                // entity instances carry their unset properties as `undefined` keys, while in plain rows those are merged as `null`
+                const shape = Object.keys(row)
+                    .filter(key => !pks.includes(key) && !(Utils.isEntity(row) && row[key] === undefined))
+                    .sort()
+                    .join();
+                const idx = shapes.get(shape) ?? [];
+                shapes.set(shape, idx);
+                idx.push(i);
+            });
+            if (shapes.size > 1) {
+                const ret = [];
+                for (const idx of shapes.values()) {
+                    const res = await this.upsertMany(entityName, idx.map(i => data[i]), options);
+                    const seen = new Set();
+                    let j = 0;
+                    // `res` holds every entity once, so skip the rows resolving to an entity an earlier row already took
+                    for (const i of idx) {
+                        const row = data[i];
+                        const entity = Utils.isEntity(row)
+                            ? row
+                            : em.#unitOfWork.tryGetById(entityName, row, options.schema, false);
+                        if (!seen.has(entity)) {
+                            seen.add((ret[i] = res[j++]));
+                        }
+                    }
+                }
+                // rows resolving to the same entity are returned once, as in the single statement path
+                return [...new Set(ret.filter(entity => entity))];
+            }
+        }
         // the rows are replaced with their processed copies below, keep the caller's array intact
         data = [...data];
         const meta = this.metadata.get(entityName);
@@ -1098,9 +1138,10 @@ export class EntityManager {
         const generatedFields = new Set();
         const allData = [];
         const allWhere = [];
+        const dataIndexes = [];
+        const result = [];
         const entities = new Map();
         const entitiesByData = new Map();
-        const entitiesByAllDataIdx = new Map();
         for (let i = 0; i < data.length; i++) {
             let row = data[i];
             let where;
@@ -1108,14 +1149,12 @@ export class EntityManager {
                 const entity = row;
                 if (helper(entity).__managed && helper(entity).__em === em && !this.config.get('upsertManaged')) {
                     em.#entityFactory.mergeData(meta, entity, row, { initialized: true });
-                    entities.set(entity, row);
-                    entitiesByData.set(row, entity);
+                    result[i] = entity;
                     continue;
                 }
                 where = helper(entity).getPrimaryKey();
                 getOnCreateGeneratedFields(meta, entity).forEach(field => generatedFields.add(field));
                 em.#entityFactory.assignDefaultValues(entity, meta);
-                entitiesByAllDataIdx.set(allData.length, entity);
                 row = em.#comparator.prepareEntity(entity);
             }
             else {
@@ -1125,8 +1164,7 @@ export class EntityManager {
                     const exists = em.#unitOfWork.getById(entityName, where, options.schema);
                     if (exists) {
                         em.assign(exists, row);
-                        entities.set(exists, row);
-                        entitiesByData.set(row, exists);
+                        result[i] = exists;
                         continue;
                     }
                 }
@@ -1159,22 +1197,25 @@ export class EntityManager {
             validateParams(row, 'insert data');
             allData.push(row);
             allWhere.push(where);
+            dataIndexes.push(i);
         }
-        if (entities.size === data.length) {
-            return [...entities.keys()];
+        if (allData.length === 0) {
+            return [...new Set(result)];
         }
         // `onCreate` generated values are for the insert clause only, they must not overwrite existing rows
         if (generatedFields.size > 0 && !options.onConflictMergeFields) {
             options.onConflictExcludeFields = [...(options.onConflictExcludeFields ?? []), ...generatedFields];
         }
         if (em.eventManager.hasListeners(EventType.beforeUpsert, meta)) {
-            for (const dto of data) {
-                const entity = entitiesByData.get(dto) ?? dto;
+            for (const index of dataIndexes) {
+                const entity = data[index];
                 await em.eventManager.dispatchEvent(EventType.beforeUpsert, { entity, em, meta }, meta);
             }
-            for (const [idx, entity] of entitiesByAllDataIdx) {
-                allData[idx] = em.#comparator.prepareEntity(entity);
-            }
+            dataIndexes.forEach((index, idx) => {
+                if (Utils.isEntity(data[index])) {
+                    allData[idx] = em.#comparator.prepareEntity(data[index]);
+                }
+            });
         }
         const res = await em.withSessionContext(options.ctx ?? em.#transactionContext, ctx => em.driver.nativeUpdateMany(entityName, allWhere, allData, {
             upsert: true,
@@ -1182,15 +1223,16 @@ export class EntityManager {
             ...options,
             ctx,
         }));
-        entities.clear();
-        entitiesByData.clear();
         const loadPK = new Map();
         allData.forEach((row, i) => {
-            em.#unitOfWork.getChangeSetPersister().mapReturnedValues(Utils.isEntity(data[i]) ? data[i] : null, Utils.isEntity(data[i]) ? {} : data[i], 
+            // Managed inputs skipped by the SQL batch still occupy positions in `data`.
+            const index = dataIndexes[i];
+            const item = data[index];
+            em.#unitOfWork.getChangeSetPersister().mapReturnedValues(Utils.isEntity(item) ? item : null, Utils.isEntity(item) ? {} : item, 
             // A suppressed conflict omits its row; positional mapping would hydrate a different entity.
             res.rows?.length === allData.length ? res.rows[i] : undefined, meta, true);
-            const entity = Utils.isEntity(data[i])
-                ? data[i]
+            const entity = Utils.isEntity(item)
+                ? item
                 : em.#entityFactory.create(entityName, row, {
                     refresh: true,
                     initialized: true,
@@ -1201,16 +1243,19 @@ export class EntityManager {
             }
             entities.set(entity, row);
             entitiesByData.set(row, entity);
+            result[index] = entity;
         });
         // skip the reload only when RETURNING brought back a row for every input
         // (onConflictWhere can suppress writes, leaving some rows out)
         // oxfmt-ignore
         const uniqueFields = options.onConflictFields ?? (Utils.isPlainObject(allWhere[0]) ? Object.keys(allWhere[0]).flatMap(key => Utils.splitPrimaryKeys(key)) : meta.primaryKeys);
-        const returning = getOnConflictReturningFields(meta, data[0], uniqueFields, options);
+        const platform = this.getPlatform();
+        const returning = getOnConflictReturningFields(meta, data[dataIndexes[0]], uniqueFields, options, platform);
         if (options.onConflictWhere && res.rows?.length !== allData.length) {
             returning.push(...meta.comparableProps.filter(p => !p.lazy && !p.embeddable).map(p => p.name));
         }
-        const reloadFields = returning.length > 0 && !(this.getPlatform().usesReturningStatement() && res.rows?.length === data.length);
+        const reloadFields = returning.length > 0 &&
+            !((platform.usesReturningStatement() || platform.usesOutputStatement()) && res.rows?.length === allData.length);
         if (options.onConflictAction === 'ignore' || (!res.rows?.length && loadPK.size > 0) || reloadFields) {
             const unique = meta.hydrateProps.filter(p => !p.lazy).map(p => p.name);
             const add = new Set(propIndex !== false && propIndex >= 0
@@ -1220,7 +1265,8 @@ export class EntityManager {
                 Utils.keys(cond).forEach(key => add.add(key));
             }
             const where = { $or: [] };
-            data.forEach((item, idx) => {
+            dataIndexes.forEach((index, idx) => {
+                const item = data[index];
                 where.$or[idx] = {};
                 const props = Array.isArray(uniqueFields) ? uniqueFields : Object.keys(item);
                 props.forEach(prop => {
@@ -1290,7 +1336,7 @@ export class EntityManager {
                 await em.eventManager.dispatchEvent(EventType.afterUpsert, { entity, em, meta }, meta);
             }
         }
-        return [...entities.keys()];
+        return [...new Set(result)];
     }
     /**
      * Runs your callback wrapped inside a database transaction.
@@ -1947,6 +1993,13 @@ export class EntityManager {
     isInTransaction() {
         return !!this.getContext(false).#transactionContext;
     }
+    /**
+     * Checks whether transactions are disabled for this EntityManager.
+     * @internal
+     */
+    isTransactionDisabled() {
+        return !!this.getContext(false).#disableTransactions;
+    }
     /**
      * Gets the transaction context (driver dependent object used to make sure queries are executed on same connection).
      */
@@ -2302,7 +2355,7 @@ export class EntityManager {
     /**
      * @internal
      */
-    async tryCache(entityName, config, key, refresh, merge) {
+    async tryCache(entityName, config, key, refresh, merge, schema) {
         config ??= this.config.get('resultCache').global;
         if (!config) {
             return undefined;
@@ -2324,6 +2377,7 @@ export class EntityManager {
             merge: true,
             convertCustomTypes: false,
             refresh,
+            schema,
             recomputeSnapshot: true,
         };
         if (Array.isArray(cached) && merge) {

package/entity/EntityFactory.d.ts

@@ -51,6 +51,7 @@ export declare class EntityFactory {
     assignDefaultValues<T extends object>(entity: T, meta: EntityMetadata<T>, onCreateOnly?: boolean): void;
     private hydrate;
     private findEntity;
+    private findEntityByPrimaryKey;
     private processDiscriminatorColumn;
     /**
      * denormalize PK to value required by driver (e.g. ObjectId)

package/entity/EntityFactory.js

@@ -55,6 +55,10 @@ export class EntityFactory {
             Utils.dropUndefinedProperties(data);
             this.mergeData(meta2, exists, data, options);
             wrapped.__processing = false;
+            // index a merged `targetKey` value, `getByKey` ignores the old one as stale
+            if (meta2.root.targetKeys) {
+                this.unitOfWork.getIdentityMap().store(exists);
+            }
             wrapped.__initialized ||= !!options.initialized;
             if (wrapped.isInitialized()) {
                 if (!wasInitialized) {
@@ -232,9 +236,9 @@ export class EntityFactory {
         options.convertCustomTypes ??= true;
         const meta = this.#metadata.get(entityName);
         const schema = this.#driver.getSchemaName(meta, options);
-        // Handle alternate key lookup
-        if (options.key) {
-            const value = '' + (Array.isArray(id) ? id[0] : Utils.isPlainObject(id) ? id[options.key] : id);
+        // Handle alternate key lookup, a `key` pointing at the single PK is a plain PK reference
+        if (options.key && !(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === options.key)) {
+            const value = Array.isArray(id) ? id[0] : Utils.isPlainObject(id) ? id[options.key] : id;
             const exists = this.unitOfWork.getByKey(entityName, options.key, value, schema, options.convertCustomTypes);
             if (exists) {
                 return exists;
@@ -242,6 +246,8 @@ export class EntityFactory {
             // Create entity stub - storeByKey will set the alternate key property and store in identity map
             const entity = this.create(entityName, {}, { ...options, initialized: false });
             this.unitOfWork.storeByKey(entity, options.key, value, schema, options.convertCustomTypes);
+            // snapshot the stub like a PK reference, so flush treats it as existing instead of inserting it
+            helper(entity).__originalEntityData = this.#comparator.prepareEntity(entity);
             return entity;
         }
         if (meta.simplePK) {
@@ -310,6 +316,12 @@ export class EntityFactory {
         if (options.merge && !options.newEntity) {
             this.#hydrator.hydrateReference(entity, meta, data, this, options.convertCustomTypes, options.schema, options.parentSchema);
             this.unitOfWork.register(entity);
+            // relations hydrated together with this entity (joined strategy) resolve it via `targetKey` before it is hydrated
+            for (const key of meta.root.targetKeys ?? []) {
+                if (data[key] != null) {
+                    this.unitOfWork.storeByKey(entity, key, data[key], schema, options.convertCustomTypes);
+                }
+            }
         }
         if (options.initialized) {
             EntityHelper.ensurePropagation(entity);
@@ -379,6 +391,23 @@ export class EntityFactory {
     }
     findEntity(data, meta, options) {
         const schema = this.#driver.getSchemaName(meta, options);
+        const exists = this.findEntityByPrimaryKey(data, meta, schema, options);
+        // a new entity must not adopt a reference stub, that one is never inserted
+        if (exists || Array.isArray(data) || options.newEntity) {
+            return exists;
+        }
+        // a reference created via `targetKey` is only known by that key until the entity is loaded
+        for (const key of meta.root.targetKeys ?? []) {
+            if (data[key] != null) {
+                const ref = this.unitOfWork.getByKey(meta.class, key, data[key], schema, options.convertCustomTypes);
+                if (ref && !helper(ref).__initialized) {
+                    return ref;
+                }
+            }
+        }
+        return undefined;
+    }
+    findEntityByPrimaryKey(data, meta, schema, options) {
         if (meta.simplePK) {
             return this.unitOfWork.getById(meta.class, data[meta.primaryKeys[0]], schema);
         }

package/entity/EntityLoader.js

@@ -197,9 +197,9 @@ export class EntityLoader {
         this.initializeCollections(filtered, prop, field, items, customOrder, isPartial, hasLimit);
         return items;
     }
-    async populateScalar(meta, filtered, options) {
-        const pk = Utils.getPrimaryKeyHash(meta.primaryKeys);
-        const ids = Utils.unique(filtered.map(e => Utils.getPrimaryKeyValues(e, meta, true)));
+    async populateScalar(meta, filtered, options, key) {
+        const pk = (key ?? Utils.getPrimaryKeyHash(meta.primaryKeys));
+        const ids = Utils.unique(filtered.map(e => (key ? e[key] : Utils.getPrimaryKeyValues(e, meta, true))));
         const where = this.mergePrimaryCondition(ids, pk, options, meta, this.#metadata, this.#driver.getPlatform());
         const { filters, convertCustomTypes, lockMode, strategy, populateWhere, connectionType, logging, fields } = options;
         await this.#em.find(meta.class, where, {
@@ -221,7 +221,8 @@ export class EntityLoader {
         const needsFkLoad = [];
         for (const entity of entities) {
             const refValue = entity[prop.name];
-            if (refValue && helper(refValue).hasPrimaryKey()) {
+            // a `targetKey` reference is identified by its key, it might not have the PK yet
+            if (refValue && helper(refValue).getTargetKeyValue(prop.targetKey) != null) {
                 if ((ref && !options.refresh) || // :ref hint - already have reference
                     (!ref && helper(refValue).__initialized && !options.refresh) // already loaded
                 ) {
@@ -246,7 +247,7 @@ export class EntityLoader {
             if (!ref) {
                 for (const entity of needsFkLoad) {
                     const refValue = entity[prop.name];
-                    if (refValue && helper(refValue).hasPrimaryKey()) {
+                    if (refValue && helper(refValue).getTargetKeyValue(prop.targetKey) != null) {
                         toPopulate.push(entity);
                     }
                 }
@@ -268,7 +269,7 @@ export class EntityLoader {
         const allItems = [];
         await Promise.all([...groups].map(async ([discriminator, children]) => {
             const targetMeta = this.#metadata.find(prop.discriminatorMap[discriminator]);
-            await this.populateScalar(targetMeta, children, options);
+            await this.populateScalar(targetMeta, children, options, prop.targetKey);
             allItems.push(...children);
         }));
         return allItems;

package/entity/WrappedEntity.js

@@ -83,7 +83,12 @@ export class WrappedEntity {
         if (!this.__em) {
             throw ValidationError.entityNotManaged(this.entity);
         }
-        return this.__em.findOne(this.entity.constructor, this.entity, {
+        // a reference known only by its `targetKey` has no PK, so look it up by the key instead
+        const key = this.hasPrimaryKey()
+            ? undefined
+            : this.__meta.root.targetKeys?.find(k => this.entity[k] != null);
+        const where = key ? { [key]: this.entity[key] } : this.entity;
+        return this.__em.findOne(this.entity.constructor, where, {
             ...options,
             refresh: true,
             schema: this.__schema,

package/entity/defineEntity.d.ts

@@ -267,7 +267,7 @@ export declare class UniversalPropertyOptionsBuilder<in out Value, in out Option
         autoincrement: false;
     }, IncludeKeys>, IncludeKeys>;
     /**
-     * Add the property to the `returning` statement.
+     * Add the property to the `returning` clause of inserts, updates and upserts, reloading the database value into the entity.
      */
     returning(returning?: boolean): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /**

package/entity/defineEntity.js

@@ -88,7 +88,7 @@ export class UniversalPropertyOptionsBuilder {
         return this.assignOptions({ autoincrement });
     }
     /**
-     * Add the property to the `returning` statement.
+     * Add the property to the `returning` clause of inserts, updates and upserts, reloading the database value into the entity.
      */
     returning(returning = true) {
         return this.assignOptions({ returning });

package/errors.d.ts

@@ -10,6 +10,7 @@ export declare class ValidationError<T extends AnyEntity = AnyEntity> extends Er
     static fromWrongPropertyType(entity: AnyEntity, property: string, expectedType: string, givenType: string, givenValue: string): ValidationError;
     static fromWrongRepositoryType(entityName: string, repoType: string, method: string): ValidationError;
     static fromMergeWithoutPK(meta: EntityMetadata): ValidationError;
+    static referenceWithoutPK(entity: AnyEntity): ValidationError;
     static transactionRequired(): ValidationError;
     static entityNotManaged(entity: AnyEntity): ValidationError;
     static notEntity(owner: AnyEntity, prop: EntityProperty, data: any): ValidationError;

package/errors.js

@@ -28,6 +28,9 @@ export class ValidationError extends Error {
     static fromMergeWithoutPK(meta) {
         return new ValidationError(`You cannot merge entity '${meta.className}' without identifier!`);
     }
+    static referenceWithoutPK(entity) {
+        return new ValidationError(`Entity '${entity.constructor.name}' is only known by an alternate key and has no primary key, load it first`, entity);
+    }
     static transactionRequired() {
         return new ValidationError('An open transaction is required for this operation');
     }

package/hydration/ObjectHydrator.js

@@ -207,7 +207,7 @@ export class ObjectHydrator extends Hydrator {
             if (prop.customType?.ensureComparable(meta, prop)) {
                 registerCustomType(prop, this.safeKey(prop.name), 'convertToDatabaseValue', context);
                 ret.push(`  if (data${dataKey} != null && typeof data${dataKey} !== 'object' && convertCustomTypes) {`);
-                ret.push(`    data${dataKey} = convertToDatabaseValue_${this.safeKey(prop.name)}(entity${entityKey}.__helper.getPrimaryKey());`);
+                ret.push(`    data${dataKey} = convertToDatabaseValue_${this.safeKey(prop.name)}(entity${entityKey}.__helper.getTargetKeyValue(${prop.targetKey ? this.quote(prop.targetKey) : ''}));`);
                 ret.push(`  }`);
             }
             return ret;
@@ -407,7 +407,7 @@ export class ObjectHydrator extends Hydrator {
         const code = `// compiled hydrator for entity ${meta.className} (${type + normalizeAccessors ? ' normalized' : ''})\n` +
             `return function(entity, data, factory, newEntity, convertCustomTypes, schema, parentSchema, normalizeAccessors) {\n` +
             `${lines.join('\n')}\n}`;
-        const fnKey = `hydrator-${meta.uniqueName}-${type}-${normalizeAccessors}`;
+        const fnKey = `hydrator-${meta.compiledName}-${type}-${normalizeAccessors}`;
         const hydrator = Utils.createFunction(context, code, this.config.get('compiledFunctions'), fnKey);
         this.#hydrators[key].set(meta.class, hydrator);
         return hydrator;

package/metadata/MetadataDiscovery.d.ts

@@ -128,6 +128,8 @@ export declare class MetadataDiscovery {
     private initRelation;
     /** Resolves the `through` option of a virtual to-one relation into a read-only formula property. */
     private initThroughRelation;
+    /** `returning` is only honoured for physical columns that can be hydrated back into the entity. */
+    private initReturning;
     private initColumnType;
     private getMappedType;
     private getPrefix;

package/metadata/MetadataDiscovery.js

@@ -174,6 +174,7 @@ export class MetadataDiscovery {
             this.initRelation(p);
             this.initThroughRelation(m, p);
             this.initColumnType(p);
+            this.initReturning(p);
         });
         forEachProp((m, p) => this.initIndexes(m, p));
         filtered.forEach(meta => this.autoWireBidirectionalProperties(meta));
@@ -546,7 +547,7 @@ export class MetadataDiscovery {
             const fieldNames1 = prop.targetMeta.getPrimaryProps().flatMap(pk => pk.fieldNames);
             const idColumns = fieldNames1.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, fieldNames1.length > 1));
             prop.fieldNames ??= [prop.discriminatorColumn, ...idColumns];
-            prop.joinColumns ??= idColumns;
+            prop.joinColumns ??= prop.fieldNames.slice(1);
             prop.referencedColumnNames ??= fieldNames1;
             prop.referencedTableName ??= prop.targetMeta.tableName;
             return;
@@ -563,7 +564,10 @@ export class MetadataDiscovery {
         }
         Utils.defaultValue(prop, 'referencedTableName', meta2.tableName);
         if (!prop.joinColumns) {
-            prop.joinColumns = fieldNames.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
+            // must match the real FK columns, which ignore `targetKey` naming for simple PK targets
+            prop.joinColumns = prop.targetKey
+                ? prop.fieldNames
+                : fieldNames.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
         }
         if (!prop.referencedColumnNames) {
             prop.referencedColumnNames = fieldNames;
@@ -669,6 +673,12 @@ export class MetadataDiscovery {
                 if (prop2.kind !== ReferenceKind.SCALAR && prop2.type === meta.className) {
                     meta.referencingProperties.push({ meta: meta2, prop: prop2 });
                 }
+                if (prop2.targetKey &&
+                    (prop2.type === meta.className || prop2.polymorphTargets?.some(t => t.className === meta.className)) &&
+                    !(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === prop2.targetKey) &&
+                    !meta.root.targetKeys?.includes(prop2.targetKey)) {
+                    (meta.root.targetKeys ??= []).push(prop2.targetKey);
+                }
             }
         }
     }
@@ -1173,12 +1183,24 @@ export class MetadataDiscovery {
         if (!prop.discriminator && !prop.discriminatorColumn && !prop.discriminatorMap && !Array.isArray(prop.target)) {
             return;
         }
+        const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
+        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
         prop.polymorphic = true;
         prop.discriminator ??= prop.name;
+        // explicit `fieldNames` use the `[discriminatorColumn, ...fkIdColumns]` layout
+        if (isToOne && prop.fieldNames && prop.fieldNames.length > 1) {
+            prop.discriminatorColumn ??= prop.fieldNames[0];
+            // `EntitySchema` mirrors `fieldNames` into `joinColumns`, let `initManyToOneFields` derive them after embedded prefixing
+            if (Utils.equals(prop.joinColumns, prop.fieldNames)) {
+                delete prop.joinColumns;
+            }
+        }
         prop.discriminatorColumn ??= this.#namingStrategy.discriminatorColumnName(prop.discriminator);
         prop.createForeignKeyConstraint = false;
-        const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
-        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
+        // a single field name can only be the FK column, e.g. mirrored from `joinColumn`
+        if (isToOne && prop.fieldNames?.length === 1) {
+            prop.fieldNames = [prop.discriminatorColumn, ...prop.fieldNames];
+        }
         if (isToOne || isUnionTargetMN) {
             const types = prop.type.split(/ ?\| ?/);
             prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
@@ -1438,7 +1460,8 @@ export class MetadataDiscovery {
                     }
                 }
                 rootProp.stiFieldNameMap[meta.discriminatorValue] = prop.fieldNames[0];
-                rootProp.stiFieldNames.push(...prop.fieldNames);
+                // subtypes that only differ in type share the column
+                rootProp.stiFieldNames = Utils.unique([...rootProp.stiFieldNames, ...prop.fieldNames]);
                 newProp.nullable = true;
                 newProp.name = name;
                 newProp.hydrate = false;
@@ -2129,6 +2152,16 @@ export class MetadataDiscovery {
         prop.persist = false;
         prop.formula = columns => this.#platform.getThroughRelationFormula(prop, columns);
     }
+    /** `returning` is only honoured for physical columns that can be hydrated back into the entity. */
+    initReturning(prop) {
+        const owning = prop.kind === ReferenceKind.SCALAR ||
+            prop.kind === ReferenceKind.MANY_TO_ONE ||
+            (prop.kind === ReferenceKind.ONE_TO_ONE && prop.owner) ||
+            (prop.kind === ReferenceKind.EMBEDDED && prop.object);
+        if (prop.returning && (!owning || prop.persist === false || prop.hydrate === false || prop.formula)) {
+            prop.returning = false;
+        }
+    }
     initColumnType(prop) {
         this.initUnsigned(prop);
         // Get the target properties for FK relations - use targetKey property if specified, otherwise PKs

package/metadata/MetadataStorage.d.ts

@@ -32,6 +32,13 @@ export declare class MetadataStorage {
     getById<T>(id: number): EntityMetadata<T>;
     /** Returns metadata by class name, optionally throwing if not found. */
     getByClassName<T = any, V extends boolean = true>(className: string, validate?: V): V extends true ? EntityMetadata<T> : EntityMetadata<T> | undefined;
+    /**
+     * Returns the first registered metadata with the given table name, in registration order (entities sharing
+     * a table, like STI children, resolve to the one registered first). The index is built on first use, as table
+     * names are only final once discovery has finished.
+     * @internal
+     */
+    getByTableName<T = any>(tableName: string): EntityMetadata<T> | undefined;
     /** Returns metadata by unique name, optionally throwing if not found. */
     getByUniqueName<T = any, V extends boolean = true>(uniqueName: string, validate?: V): V extends true ? EntityMetadata<T> : EntityMetadata<T> | undefined;
     private validate;

package/metadata/MetadataStorage.js

@@ -18,6 +18,8 @@ export class MetadataStorage {
     #classNameMap;
     #uniqueNameMap;
     #ambiguousNames = new Set();
+    /** Built on first use by `getByTableName()`, dropped whenever an entity is registered or removed. */
+    #tableNameMap;
     constructor(metadata = {}) {
         this.#idMap = {};
         this.#uniqueNameMap = {};
@@ -102,6 +104,7 @@ export class MetadataStorage {
     /** Registers metadata for the given entity. */
     set(entityName, meta) {
         this.#metadataMap.set(entityName, meta);
+        this.#tableNameMap = undefined;
         this.#idMap[meta._id] = meta;
         this.#uniqueNameMap[meta.uniqueName] = meta;
         const className = Utils.className(entityName);
@@ -110,6 +113,12 @@ export class MetadataStorage {
         if (existing && existing !== meta && existing.class !== meta.class) {
             this.#ambiguousNames.add(className);
         }
+        // colliding names are numbered in storage order, which follows the discovery config, not module evaluation
+        const sameName = this.#ambiguousNames.has(className)
+            ? [...new Set(this.#metadataMap.values())].filter(m => m.className === meta.className)
+            : [meta];
+        const ordinal = sameName.indexOf(meta);
+        meta.compiledName = ordinal > 0 ? `${meta.className}#${ordinal}` : meta.className;
         this.#classNameMap[className] = meta;
         return meta;
     }
@@ -118,6 +127,7 @@ export class MetadataStorage {
         const meta = this.find(entityName);
         if (meta) {
             this.#metadataMap.delete(meta.class);
+            this.#tableNameMap = undefined;
             delete this.#idMap[meta._id];
             delete this.#uniqueNameMap[meta.uniqueName];
             delete this.#classNameMap[meta.className];
@@ -145,6 +155,23 @@ export class MetadataStorage {
     getByClassName(className, validate = true) {
         return this.validate(this.#classNameMap[className], className, validate);
     }
+    /**
+     * Returns the first registered metadata with the given table name, in registration order (entities sharing
+     * a table, like STI children, resolve to the one registered first). The index is built on first use, as table
+     * names are only final once discovery has finished.
+     * @internal
+     */
+    getByTableName(tableName) {
+        if (!this.#tableNameMap) {
+            this.#tableNameMap = new Map();
+            for (const meta of this.#metadataMap.values()) {
+                if (!this.#tableNameMap.has(meta.tableName)) {
+                    this.#tableNameMap.set(meta.tableName, meta);
+                }
+            }
+        }
+        return this.#tableNameMap.get(tableName);
+    }
     /** Returns metadata by unique name, optionally throwing if not found. */
     getByUniqueName(uniqueName, validate = true) {
         return this.validate(this.#uniqueNameMap[uniqueName], uniqueName, validate);