@mikro-orm/core 7.0.0-dev.156 → 7.0.0-dev.158

package/EntityManager.d.ts

@@ -382,10 +382,26 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Shortcut for `wrap(entity).assign(data, { em })`
      */
     assign<Entity extends object, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(entity: Entity | Partial<Entity>, data: Data & IsSubset<EntityData<Naked, Convert>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<Entity extends object, K extends string & keyof Entity>(entityName: EntityName<Entity>, id: Entity[K], options: Omit<GetReferenceOptions, 'key' | 'wrapped'> & {
+        key: K;
+        wrapped: true;
+    }): Ref<Entity>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<Entity extends object, K extends string & keyof Entity>(entityName: EntityName<Entity>, id: Entity[K], options: Omit<GetReferenceOptions, 'key'> & {
+        key: K;
+        wrapped?: false;
+    }): Entity;
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: true;
     }): Ref<Entity>;
     /**
@@ -395,7 +411,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference<Entity extends object>(entityName: EntityName<Entity>, id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: false;
     }): Entity;
     /**

package/drivers/IDatabaseDriver.d.ts

@@ -247,4 +247,9 @@ export interface GetReferenceOptions {
     wrapped?: boolean;
     convertCustomTypes?: boolean;
     schema?: string;
+    /**
+     * Property name to use for identity map lookup instead of the primary key.
+     * This is useful for creating references by unique non-PK properties.
+     */
+    key?: string;
 }

package/entity/EntityFactory.d.ts

@@ -16,6 +16,11 @@ export interface FactoryOptions {
     schema?: string;
     parentSchema?: string;
     normalizeAccessors?: boolean;
+    /**
+     * Property name to use for identity map lookup instead of the primary key.
+     * This is useful for creating references by unique non-PK properties.
+     */
+    key?: string;
 }
 export declare class EntityFactory {
     private readonly em;
@@ -29,7 +34,7 @@ export declare class EntityFactory {
     constructor(em: EntityManager);
     create<T extends object, P extends string = string>(entityName: EntityName<T>, data: EntityData<T>, options?: FactoryOptions): New<T, P>;
     mergeData<T extends object>(meta: EntityMetadata<T>, entity: T, data: EntityData<T>, options?: FactoryOptions): void;
-    createReference<T extends object>(entityName: EntityName<T>, id: Primary<T> | Primary<T>[] | Record<string, Primary<T>>, options?: Pick<FactoryOptions, 'merge' | 'convertCustomTypes' | 'schema'>): T;
+    createReference<T extends object>(entityName: EntityName<T>, id: Primary<T> | Primary<T>[] | Record<string, Primary<T>>, options?: Pick<FactoryOptions, 'merge' | 'convertCustomTypes' | 'schema' | 'key'>): T;
     createEmbeddable<T extends object>(entityName: EntityName<T>, data: EntityData<T>, options?: Pick<FactoryOptions, 'newEntity' | 'convertCustomTypes'>): T;
     getComparator(): EntityComparator;
     private createEntity;

package/entity/EntityFactory.js

@@ -164,6 +164,18 @@ 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);
+            const exists = this.unitOfWork.getByKey(entityName, options.key, value, schema, options.convertCustomTypes);
+            if (exists) {
+                return exists;
+            }
+            // 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);
+            return entity;
+        }
         if (meta.simplePK) {
             const exists = this.unitOfWork.getById(entityName, id, schema);
             if (exists) {

package/entity/EntityLoader.d.ts

@@ -15,7 +15,7 @@ export type EntityLoaderOptions<Entity, Fields extends string = PopulatePath.ALL
     convertCustomTypes?: boolean;
     ignoreLazyScalarProperties?: boolean;
     filters?: FilterOptions;
-    strategy?: LoadStrategy;
+    strategy?: LoadStrategy | `${LoadStrategy}`;
     lockMode?: Exclude<LockMode, LockMode.OPTIMISTIC>;
     schema?: string;
     connectionType?: ConnectionType;

package/entity/EntityLoader.js

@@ -211,7 +211,8 @@ export class EntityLoader {
     async findChildren(entities, prop, populate, options, ref) {
         const children = Utils.unique(this.getChildReferences(entities, prop, options, ref));
         const meta = prop.targetMeta;
-        let fk = Utils.getPrimaryKeyHash(meta.primaryKeys);
+        // When targetKey is set, use it for FK lookup instead of the PK
+        let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
         let schema = options.schema;
         const partial = !Utils.isEmpty(prop.where) || !Utils.isEmpty(options.where);
         if (prop.kind === ReferenceKind.ONE_TO_MANY || (prop.kind === ReferenceKind.MANY_TO_MANY && !prop.owner)) {
@@ -228,7 +229,8 @@ export class EntityLoader {
         if (!schema && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind)) {
             schema = children.find(e => e.__helper.__schema)?.__helper.__schema;
         }
-        const ids = Utils.unique(children.map(e => e.__helper.getPrimaryKey()));
+        // When targetKey is set, get the targetKey value instead of PK
+        const ids = Utils.unique(children.map(e => prop.targetKey ? e[prop.targetKey] : e.__helper.getPrimaryKey()));
         let where = this.mergePrimaryCondition(ids, fk, options, meta, this.metadata, this.driver.getPlatform());
         const fields = this.buildFields(options.fields, prop, ref);
         /* eslint-disable prefer-const */
@@ -255,19 +257,44 @@ export class EntityLoader {
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
         });
+        // For targetKey relations, wire up loaded entities to parent references
+        // This is needed because the references were created under alternate key,
+        // but loaded entities are stored under PK, so they don't automatically merge
+        if (prop.targetKey && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind)) {
+            const itemsByKey = new Map();
+            for (const item of items) {
+                itemsByKey.set('' + item[prop.targetKey], item);
+            }
+            for (const entity of entities) {
+                const ref = entity[prop.name];
+                /* v8 ignore next */
+                if (!ref) {
+                    continue;
+                }
+                const keyValue = '' + (Reference.isReference(ref) ? ref.unwrap()[prop.targetKey] : ref[prop.targetKey]);
+                const loadedItem = itemsByKey.get(keyValue);
+                if (loadedItem) {
+                    entity[prop.name] = (Reference.isReference(ref) ? Reference.create(loadedItem) : loadedItem);
+                }
+            }
+        }
         if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) && items.length !== children.length) {
             const nullVal = this.em.config.get('forceUndefined') ? undefined : null;
             const itemsMap = new Set();
             const childrenMap = new Set();
+            // Use targetKey value if set, otherwise use serialized PK
+            const getKey = (e) => prop.targetKey ? '' + e[prop.targetKey] : helper(e).getSerializedPrimaryKey();
             for (const item of items) {
-                itemsMap.add(helper(item).getSerializedPrimaryKey());
+                /* v8 ignore next */
+                itemsMap.add(getKey(item));
             }
             for (const child of children) {
-                childrenMap.add(helper(child).getSerializedPrimaryKey());
+                childrenMap.add(getKey(child));
             }
             for (const entity of entities) {
-                const key = helper(entity[prop.name] ?? {})?.getSerializedPrimaryKey();
-                if (childrenMap.has(key) && !itemsMap.has(key)) {
+                const ref = entity[prop.name] ?? {};
+                const key = helper(ref) ? getKey(ref) : undefined;
+                if (key && childrenMap.has(key) && !itemsMap.has(key)) {
                     entity[prop.name] = nullVal;
                     helper(entity).__originalEntityData[prop.name] = null;
                 }

package/entity/EntityRepository.d.ts

@@ -111,10 +111,26 @@ export declare class EntityRepository<Entity extends object> {
     map(result: EntityDictionary<Entity>, options?: {
         schema?: string;
     }): Entity;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<K extends string & keyof Entity>(id: Entity[K], options: Omit<GetReferenceOptions, 'key' | 'wrapped'> & {
+        key: K;
+        wrapped: true;
+    }): Ref<Entity>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<K extends string & keyof Entity>(id: Entity[K], options: Omit<GetReferenceOptions, 'key'> & {
+        key: K;
+        wrapped?: false;
+    }): Entity;
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: true;
     }): Ref<Entity>;
     /**
@@ -124,7 +140,7 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: false;
     }): Entity;
     /**

package/entity/defineEntity.d.ts

@@ -339,6 +339,8 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     referenceColumnName(referenceColumnName: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Override the default database column name on the target entity (see {@doclink naming-strategy | Naming Strategy}). This option is suitable for composite keys, where one property is represented by multiple columns. */
     referencedColumnNames(...referencedColumnNames: string[]): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
+    /** Specify the property name on the target entity that this FK references instead of the primary key. */
+    targetKey(targetKey: string): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** What to do when the target entity gets deleted. */
     deleteRule(deleteRule: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** What to do when the reference to the target entity gets updated. */

package/entity/defineEntity.js

@@ -409,6 +409,10 @@ export class UniversalPropertyOptionsBuilder {
     referencedColumnNames(...referencedColumnNames) {
         return this.assignOptions({ referencedColumnNames });
     }
+    /** Specify the property name on the target entity that this FK references instead of the primary key. */
+    targetKey(targetKey) {
+        return this.assignOptions({ targetKey });
+    }
     /** What to do when the target entity gets deleted. */
     deleteRule(deleteRule) {
         return this.assignOptions({ deleteRule });

package/errors.d.ts

@@ -62,6 +62,9 @@ export declare class MetadataError<T extends AnyEntity = AnyEntity> extends Vali
     static nonPersistentCompositeProp(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
     static propertyTargetsEntityType(meta: EntityMetadata, prop: EntityProperty, target: EntityMetadata): MetadataError<Partial<any>>;
     static fromMissingOption(meta: EntityMetadata, prop: EntityProperty, option: string): MetadataError<Partial<any>>;
+    static targetKeyOnManyToMany(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
+    static targetKeyNotUnique(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
+    static targetKeyNotFound(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
     static dangerousPropertyName(meta: EntityMetadata, prop: EntityProperty): MetadataError<Partial<any>>;
     private static fromMessage;
 }

package/errors.js

@@ -213,6 +213,15 @@ export class MetadataError extends ValidationError {
     static fromMissingOption(meta, prop, option) {
         return this.fromMessage(meta, prop, `is missing '${option}' option`);
     }
+    static targetKeyOnManyToMany(meta, prop) {
+        return this.fromMessage(meta, prop, `uses 'targetKey' option which is not supported for ManyToMany relations`);
+    }
+    static targetKeyNotUnique(meta, prop) {
+        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${prop.type}.${prop.targetKey} is not marked as unique. The target property must have a unique constraint.`);
+    }
+    static targetKeyNotFound(meta, prop) {
+        return this.fromMessage(meta, prop, `has 'targetKey' set to '${prop.targetKey}', but ${prop.type}.${prop.targetKey} does not exist`);
+    }
     static dangerousPropertyName(meta, prop) {
         return this.fromMessage(meta, prop, `uses a dangerous property name '${prop.name}' which could lead to prototype pollution. Please use a different property name.`);
     }

package/hydration/ObjectHydrator.js

@@ -137,11 +137,13 @@ export class ObjectHydrator extends Hydrator {
             ret.push(`    if (isPrimaryKey(data${dataKey}, true)) {`);
             const targetKey = this.safeKey(`${prop.targetMeta.tableName}_${this.tmpIndex++}`);
             context.set(targetKey, prop.targetMeta.class);
+            // When targetKey is set, pass the key option to createReference so it uses the alternate key
+            const keyOption = prop.targetKey ? `, key: '${prop.targetKey}'` : '';
             if (prop.ref) {
-                ret.push(`      entity${entityKey} = Reference.create(factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema }));`);
+                ret.push(`      entity${entityKey} = Reference.create(factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} }));`);
             }
             else {
-                ret.push(`      entity${entityKey} = factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema });`);
+                ret.push(`      entity${entityKey} = factory.createReference(${targetKey}, data${dataKey}, { merge: true, convertCustomTypes, normalizeAccessors, schema${keyOption} });`);
             }
             ret.push(`    } else if (data${dataKey} && typeof data${dataKey} === 'object') {`);
             if (prop.ref) {

package/metadata/MetadataDiscovery.js

@@ -438,7 +438,15 @@ export class MetadataDiscovery {
     }
     initManyToOneFields(prop) {
         const meta2 = prop.targetMeta;
-        const fieldNames = Utils.flatten(meta2.primaryKeys.map(primaryKey => meta2.properties[primaryKey].fieldNames));
+        let fieldNames;
+        // If targetKey is specified, use that property's field names instead of PKs
+        if (prop.targetKey) {
+            const targetProp = meta2.properties[prop.targetKey];
+            fieldNames = targetProp.fieldNames;
+        }
+        else {
+            fieldNames = Utils.flatten(meta2.primaryKeys.map(primaryKey => meta2.properties[primaryKey].fieldNames));
+        }
         Utils.defaultValue(prop, 'referencedTableName', meta2.tableName);
         if (!prop.joinColumns) {
             prop.joinColumns = fieldNames.map(fieldName => this.namingStrategy.joinKeyColumnName(prop.name, fieldName, fieldNames.length > 1));
@@ -1238,7 +1246,8 @@ export class MetadataDiscovery {
         }
         // when the target is a polymorphic embedded entity, `prop.target` is an array of classes, we need to get the metadata by the type name instead
         const meta2 = this.metadata.find(prop.target) ?? this.metadata.getByClassName(prop.type);
-        prop.referencedPKs = meta2.primaryKeys;
+        // If targetKey is specified, use that property instead of PKs for referencedPKs
+        prop.referencedPKs = prop.targetKey ? [prop.targetKey] : meta2.primaryKeys;
         prop.targetMeta = meta2;
         if (!prop.formula && prop.persist === false && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && !prop.embedded) {
             prop.formula = table => `${table}.${this.platform.quoteIdentifier(prop.fieldNames[0])}`;
@@ -1246,10 +1255,14 @@ export class MetadataDiscovery {
     }
     initColumnType(prop) {
         this.initUnsigned(prop);
-        prop.targetMeta?.getPrimaryProps().map(pk => {
-            prop.length ??= pk.length;
-            prop.precision ??= pk.precision;
-            prop.scale ??= pk.scale;
+        // Get the target properties for FK relations - use targetKey property if specified, otherwise PKs
+        const targetProps = prop.targetMeta
+            ? (prop.targetKey ? [prop.targetMeta.properties[prop.targetKey]] : prop.targetMeta.getPrimaryProps())
+            : [];
+        targetProps.map(targetProp => {
+            prop.length ??= targetProp.length;
+            prop.precision ??= targetProp.precision;
+            prop.scale ??= targetProp.scale;
         });
         if (prop.kind === ReferenceKind.SCALAR && (prop.type == null || prop.type === 'object') && prop.columnTypes?.[0]) {
             delete prop.type;
@@ -1282,17 +1295,21 @@ export class MetadataDiscovery {
         }
         const targetMeta = prop.targetMeta;
         prop.columnTypes = [];
-        for (const pk of targetMeta.getPrimaryProps()) {
-            this.initCustomType(targetMeta, pk);
-            this.initColumnType(pk);
-            const mappedType = this.getMappedType(pk);
-            let columnTypes = pk.columnTypes;
-            if (pk.autoincrement) {
-                columnTypes = [mappedType.getColumnType({ ...pk, autoincrement: false }, this.platform)];
+        // Use targetKey property if specified, otherwise use primary key properties
+        const referencedProps = prop.targetKey
+            ? [targetMeta.properties[prop.targetKey]]
+            : targetMeta.getPrimaryProps();
+        for (const referencedProp of referencedProps) {
+            this.initCustomType(targetMeta, referencedProp);
+            this.initColumnType(referencedProp);
+            const mappedType = this.getMappedType(referencedProp);
+            let columnTypes = referencedProp.columnTypes;
+            if (referencedProp.autoincrement) {
+                columnTypes = [mappedType.getColumnType({ ...referencedProp, autoincrement: false }, this.platform)];
             }
             prop.columnTypes.push(...columnTypes);
-            if (!targetMeta.compositePK) {
-                prop.customType = pk.customType;
+            if (!targetMeta.compositePK || prop.targetKey) {
+                prop.customType = referencedProp.customType;
             }
         }
     }

package/metadata/MetadataValidator.d.ts

@@ -8,6 +8,7 @@ export declare class MetadataValidator {
     validateEntityDefinition<T>(metadata: MetadataStorage, name: EntityName<T>, options: MetadataDiscoveryOptions): void;
     validateDiscovered(discovered: EntityMetadata[], options: MetadataDiscoveryOptions): void;
     private validateReference;
+    private validateTargetKey;
     private validateBidirectional;
     private validateOwningSide;
     private validateInverseSide;

package/metadata/MetadataValidator.js

@@ -110,6 +110,25 @@ export class MetadataValidator {
         if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && prop.persist === false && targetMeta.compositePK && options.checkNonPersistentCompositeProps) {
             throw MetadataError.nonPersistentCompositeProp(meta, prop);
         }
+        this.validateTargetKey(meta, prop, targetMeta);
+    }
+    validateTargetKey(meta, prop, targetMeta) {
+        if (!prop.targetKey) {
+            return;
+        }
+        // targetKey is not supported for ManyToMany relations
+        if (prop.kind === ReferenceKind.MANY_TO_MANY) {
+            throw MetadataError.targetKeyOnManyToMany(meta, prop);
+        }
+        // targetKey must point to an existing property
+        const targetProp = targetMeta.properties[prop.targetKey];
+        if (!targetProp) {
+            throw MetadataError.targetKeyNotFound(meta, prop);
+        }
+        // targetKey must point to a unique property
+        if (!targetProp.unique && !targetMeta.uniques?.some(u => u.properties?.includes(prop.targetKey))) {
+            throw MetadataError.targetKeyNotUnique(meta, prop);
+        }
     }
     validateBidirectional(meta, prop) {
         if (prop.inversedBy) {

package/metadata/types.d.ts

@@ -342,6 +342,8 @@ export interface ManyToOneOptions<Owner, Target> extends ReferenceOptions<Owner,
     referenceColumnName?: string;
     /** Override the default database column name on the target entity (see {@doclink naming-strategy | Naming Strategy}). This option is suitable for composite keys, where one property is represented by multiple columns. */
     referencedColumnNames?: string[];
+    /** Specify the property name on the target entity that this FK references instead of the primary key. */
+    targetKey?: string & keyof Target;
     /** What to do when the target entity gets deleted. */
     deleteRule?: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString;
     /** What to do when the reference to the target entity gets updated. */
@@ -388,6 +390,8 @@ export interface OneToOneOptions<Owner, Target> extends Partial<Omit<OneToManyOp
     mapToPk?: boolean;
     /** When a part of a composite column is shared in other properties, use this option to specify what columns are considered as owned by this property. This is useful when your composite property is nullable, but parts of it are not. */
     ownColumns?: string[];
+    /** Specify the property name on the target entity that this FK references instead of the primary key. */
+    targetKey?: string & keyof Target;
     /** What to do when the target entity gets deleted. */
     deleteRule?: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString;
     /** What to do when the reference to the target entity gets updated. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikro-orm/core",
   "type": "module",
-  "version": "7.0.0-dev.156",
+  "version": "7.0.0-dev.158",
   "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.",
   "exports": {
     "./package.json": "./package.json",

package/typings.d.ts

@@ -422,6 +422,7 @@ export interface EntityProperty<Owner = any, Target = any> {
     referencedColumnNames: string[];
     referencedTableName: string;
     referencedPKs: EntityKey<Owner>[];
+    targetKey?: string;
     serializer?: (value: any, options?: SerializeOptions<any>) => any;
     serializedName?: string;
     comment?: string;

package/unit-of-work/ChangeSetComputer.js

@@ -132,7 +132,16 @@ export class ChangeSetComputer {
         const targets = Utils.unwrapProperty(changeSet.entity, changeSet.meta, prop);
         targets.forEach(([target, idx]) => {
             if (!target.__helper.hasPrimaryKey()) {
-                Utils.setPayloadProperty(changeSet.payload, changeSet.meta, prop, target.__helper.__identifier, idx);
+                // When targetKey is set, use that property value instead of the PK identifier
+                let value = prop.targetKey ? target[prop.targetKey] : target.__helper.__identifier;
+                /* v8 ignore next */
+                if (prop.targetKey && prop.targetMeta) {
+                    const targetProp = prop.targetMeta.properties[prop.targetKey];
+                    if (targetProp?.customType) {
+                        value = targetProp.customType.convertToDatabaseValue(value, this.platform, { mode: 'serialization' });
+                    }
+                }
+                Utils.setPayloadProperty(changeSet.payload, changeSet.meta, prop, value, idx);
             }
         });
     }
@@ -145,7 +154,9 @@ export class ChangeSetComputer {
             this.collectionUpdates.add(target);
         }
         if (prop.owner && !this.platform.usesPivotTable()) {
-            changeSet.payload[prop.name] = target.getItems(false).map((item) => item.__helper.__identifier ?? item.__helper.getPrimaryKey());
+            changeSet.payload[prop.name] = target.getItems(false).map((item) => {
+                return item.__helper.__identifier ?? item.__helper.getPrimaryKey();
+            });
         }
     }
 }

package/unit-of-work/IdentityMap.d.ts

@@ -3,7 +3,14 @@ export declare class IdentityMap {
     private readonly defaultSchema?;
     constructor(defaultSchema?: string | undefined);
     private readonly registry;
+    /** Tracks alternate key hashes for each entity so we can clean them up on delete */
+    private readonly alternateKeys;
     store<T>(item: T): void;
+    /**
+     * Stores an entity under an alternate key (non-PK property).
+     * This allows looking up entities by unique properties that are not the primary key.
+     */
+    storeByKey<T>(item: T, key: string, value: string, schema?: string): void;
     delete<T>(item: T): void;
     getByHash<T>(meta: EntityMetadata<T>, hash: string): T | undefined;
     getStore<T>(meta: EntityMetadata<T>): Map<string, T>;
@@ -16,4 +23,9 @@ export declare class IdentityMap {
      */
     get<T>(hash: string): T | undefined;
     private getPkHash;
+    /**
+     * Creates a hash for an alternate key lookup.
+     * Format: `[key]value` or `schema:[key]value`
+     */
+    getKeyHash(key: string, value: string, schema?: string): string;
 }

package/unit-of-work/IdentityMap.js

@@ -4,11 +4,38 @@ export class IdentityMap {
         this.defaultSchema = defaultSchema;
     }
     registry = new Map();
+    /** Tracks alternate key hashes for each entity so we can clean them up on delete */
+    alternateKeys = new WeakMap();
     store(item) {
         this.getStore(item.__meta.root).set(this.getPkHash(item), item);
     }
+    /**
+     * Stores an entity under an alternate key (non-PK property).
+     * This allows looking up entities by unique properties that are not the primary key.
+     */
+    storeByKey(item, key, value, schema) {
+        const hash = this.getKeyHash(key, value, schema);
+        this.getStore(item.__meta.root).set(hash, item);
+        // Track this alternate key so we can clean it up when the entity is deleted
+        let keys = this.alternateKeys.get(item);
+        if (!keys) {
+            keys = new Set();
+            this.alternateKeys.set(item, keys);
+        }
+        keys.add(hash);
+    }
     delete(item) {
-        this.getStore(item.__meta.root).delete(this.getPkHash(item));
+        const meta = item.__meta.root;
+        const store = this.getStore(meta);
+        store.delete(this.getPkHash(item));
+        // Also delete any alternate key entries for this entity
+        const altKeys = this.alternateKeys.get(item);
+        if (altKeys) {
+            for (const hash of altKeys) {
+                store.delete(hash);
+            }
+            this.alternateKeys.delete(item);
+        }
     }
     getByHash(meta, hash) {
         const store = this.getStore(meta);
@@ -69,4 +96,15 @@ export class IdentityMap {
         }
         return hash;
     }
+    /**
+     * Creates a hash for an alternate key lookup.
+     * Format: `[key]value` or `schema:[key]value`
+     */
+    getKeyHash(key, value, schema) {
+        const hash = `[${key}]${value}`;
+        if (schema) {
+            return schema + ':' + hash;
+        }
+        return hash;
+    }
 }

package/unit-of-work/UnitOfWork.d.ts

@@ -46,6 +46,19 @@ export declare class UnitOfWork {
      * Returns entity from the identity map. For composite keys, you need to pass an array of PKs in the same order as they are defined in `meta.primaryKeys`.
      */
     getById<T extends object>(entityName: EntityName<T>, id: Primary<T> | Primary<T>[], schema?: string, convertCustomTypes?: boolean): T | undefined;
+    /**
+     * Returns entity from the identity map by an alternate key (non-PK property).
+     * @param convertCustomTypes - If true, the value is in database format and will be converted to JS format for lookup.
+     *                             If false (default), the value is assumed to be in JS format already.
+     */
+    getByKey<T extends object>(entityName: EntityName<T>, key: string, value: unknown, schema?: string, convertCustomTypes?: boolean): T | undefined;
+    /**
+     * Stores an entity in the identity map under an alternate key (non-PK property).
+     * Also sets the property value on the entity.
+     * @param convertCustomTypes - If true, the value is in database format and will be converted to JS format.
+     *                             If false (default), the value is assumed to be in JS format already.
+     */
+    storeByKey<T extends object>(entity: T, key: string, value: unknown, schema?: string, convertCustomTypes?: boolean): void;
     tryGetById<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, schema?: string, strict?: boolean): T | null;
     /**
      * Returns map of all managed entities.

package/unit-of-work/UnitOfWork.js

@@ -169,6 +169,40 @@ export class UnitOfWork {
         }
         return this.identityMap.getByHash(meta, hash);
     }
+    /**
+     * Returns entity from the identity map by an alternate key (non-PK property).
+     * @param convertCustomTypes - If true, the value is in database format and will be converted to JS format for lookup.
+     *                             If false (default), the value is assumed to be in JS format already.
+     */
+    getByKey(entityName, key, value, schema, convertCustomTypes) {
+        const meta = this.metadata.find(entityName).root;
+        schema ??= meta.schema ?? this.em.config.getSchema();
+        const prop = meta.properties[key];
+        // Convert from DB format to JS format if needed
+        if (convertCustomTypes && prop?.customType) {
+            value = prop.customType.convertToJSValue(value, this.platform, { mode: 'hydration' });
+        }
+        const hash = this.identityMap.getKeyHash(key, '' + value, schema);
+        return this.identityMap.getByHash(meta, hash);
+    }
+    /**
+     * Stores an entity in the identity map under an alternate key (non-PK property).
+     * Also sets the property value on the entity.
+     * @param convertCustomTypes - If true, the value is in database format and will be converted to JS format.
+     *                             If false (default), the value is assumed to be in JS format already.
+     */
+    storeByKey(entity, key, value, schema, convertCustomTypes) {
+        const meta = entity.__meta.root;
+        schema ??= meta.schema ?? this.em.config.getSchema();
+        const prop = meta.properties[key];
+        // Convert from DB format to JS format if needed
+        if (convertCustomTypes && prop?.customType) {
+            value = prop.customType.convertToJSValue(value, this.platform, { mode: 'hydration' });
+        }
+        // Set the property on the entity
+        entity[key] = value;
+        this.identityMap.storeByKey(entity, key, '' + value, schema);
+    }
     tryGetById(entityName, where, schema, strict = true) {
         const pk = Utils.extractPK(where, this.metadata.find(entityName), strict);
         if (!pk) {

package/utils/EntityComparator.js

@@ -510,6 +510,23 @@ export class EntityComparator {
                     ret += `    ret${dataKey} = entity${entityKey};\n`;
                 }
             }
+            else if (prop.targetKey) {
+                // When targetKey is set, extract that property value instead of the PK
+                const targetProp = prop.targetMeta?.properties[prop.targetKey];
+                ret += `    if (entity${entityKey} === null) {\n`;
+                ret += `      ret${dataKey} = null;\n`;
+                ret += `    } else if (typeof entity${entityKey} !== 'undefined') {\n`;
+                ret += `      const val${level} = entity${entityKey}${unwrap};\n`;
+                if (targetProp?.customType) {
+                    // If targetKey property has a custom type, convert to database value
+                    const convertorKey = this.registerCustomType(targetProp, context);
+                    ret += `      ret${dataKey} = convertToDatabaseValue_${convertorKey}(val${level}?.${prop.targetKey});\n`;
+                }
+                else {
+                    ret += `      ret${dataKey} = val${level}?.${prop.targetKey};\n`;
+                }
+                ret += `    }\n`;
+            }
             else {
                 const toArray = (val) => {
                     if (Utils.isPlainObject(val)) {

package/utils/Utils.js

@@ -123,7 +123,7 @@ export function parseJsonSafe(value) {
 }
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.0.0-dev.156';
+    static #ORM_VERSION = '7.0.0-dev.158';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */