@mikro-orm/core 7.0.0-dev.99 → 7.0.0-rc.0

package/MikroORM.js

@@ -4,31 +4,35 @@ import { Configuration } from './utils/Configuration.js';
 import { loadEnvironmentVars } from './utils/env-vars.js';
 import { Utils } from './utils/Utils.js';
 import { colors } from './logging/colors.js';
-async function registerExtension(name, mod, extensions) {
-    /* v8 ignore next */
-    const resolved = await mod.catch(() => null);
-    const module = resolved?.[name];
-    /* v8 ignore else */
-    if (module) {
-        extensions.push(module);
+async function tryRegisterExtension(name, pkg, extensions) {
+    try {
+        const url = import.meta.resolve(pkg);
+        const mod = await import(url);
+        if (mod[name]) {
+            extensions.push(mod[name]);
+        }
+    }
+    catch {
+        // not installed
     }
 }
 /** @internal */
-export async function lookupExtensions(options) {
+export async function loadOptionalDependencies(options) {
+    await import('@mikro-orm/core/fs-utils').then(m => m.fs.init()).catch(() => null);
     const extensions = options.extensions ?? [];
     const exists = (name) => extensions.some(ext => ext.name === name);
     if (!exists('SeedManager')) {
-        await registerExtension('SeedManager', import((() => '@mikro-orm/seeder')()), extensions);
+        await tryRegisterExtension('SeedManager', '@mikro-orm/seeder', extensions);
     }
     if (!exists('Migrator')) {
-        await registerExtension('Migrator', import((() => '@mikro-orm/migrations')()), extensions);
+        await tryRegisterExtension('Migrator', '@mikro-orm/migrations', extensions);
     }
     /* v8 ignore if */
     if (!exists('Migrator')) {
-        await registerExtension('Migrator', import((() => '@mikro-orm/migrations-mongodb')()), extensions);
+        await tryRegisterExtension('Migrator', '@mikro-orm/migrations-mongodb', extensions);
     }
     if (!exists('EntityGenerator')) {
-        await registerExtension('EntityGenerator', import((() => '@mikro-orm/entity-generator')()), extensions);
+        await tryRegisterExtension('EntityGenerator', '@mikro-orm/entity-generator', extensions);
     }
     options.extensions = extensions;
     const metadataCacheEnabled = options.metadataCache?.enabled || options.metadataProvider?.useCache?.();
@@ -85,7 +89,7 @@ export class MikroORM {
         options = { ...options };
         options.discovery ??= {};
         options.discovery.skipSyncDiscovery ??= true;
-        await lookupExtensions(options);
+        await loadOptionalDependencies(options);
         const orm = new this(options);
         const preferTs = orm.config.get('preferTs', Utils.detectTypeScriptSupport());
         orm.metadata = await orm.discovery.discover(preferTs);
@@ -94,13 +98,15 @@ export class MikroORM {
     }
     /**
      * Synchronous variant of the `init` method with some limitations:
-     * - database connection will be established when you first interact with the database (or you can use `orm.connect()` explicitly)
-     * - no loading of the `config` file, `options` parameter is mandatory
-     * - no support for folder based discovery
+     * - folder-based discovery not supported
+     * - ORM extensions are not autoloaded
+     * - when metadata cache is enabled, `FileCacheAdapter` needs to be explicitly set in the config
      */
     constructor(options) {
         const env = loadEnvironmentVars();
-        options = Utils.merge(options, env);
+        options = options.preferEnvVars
+            ? Utils.merge(options, env)
+            : Utils.merge(env, options);
         this.config = new Configuration(options);
         const discovery = this.config.get('discovery');
         this.driver = this.config.getDriver();
@@ -158,7 +164,6 @@ export class MikroORM {
      */
     getMetadata(entityName) {
         if (entityName) {
-            entityName = Utils.className(entityName);
             return this.metadata.get(entityName);
         }
         return this.metadata;
@@ -181,8 +186,8 @@ export class MikroORM {
         const tmp = this.discovery.discoverReferences(Utils.asArray(entities));
         const metadata = this.discovery.processDiscoveredEntities(tmp);
         for (const meta of metadata) {
-            this.metadata.set(meta.className, meta);
-            meta.root = this.metadata.get(meta.root.className);
+            this.metadata.set(meta.class, meta);
+            meta.root = this.metadata.get(meta.root.class);
         }
         this.metadata.decorate(this.em);
     }

package/cache/FileCacheAdapter.js

@@ -53,7 +53,15 @@ export class FileCacheAdapter {
     clear() {
         const path = this.path('*');
         const files = fs.glob(path);
-        files.forEach(file => unlinkSync(file));
+        for (const file of files) {
+            /* v8 ignore next */
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // ignore if file is already gone
+            }
+        }
         this.cache = {};
     }
     combine() {
@@ -63,7 +71,7 @@ export class FileCacheAdapter {
         let path = typeof this.options.combined === 'string'
             ? this.options.combined
             : './metadata.json';
-        path = Utils.normalizePath(this.options.cacheDir, path);
+        path = fs.normalizePath(this.options.cacheDir, path);
         this.options.combined = path; // override in the options, so we can log it from the CLI in `cache:generate` command
         writeFileSync(path, JSON.stringify(this.cache, null, this.pretty ? 2 : undefined));
         return path;
@@ -73,7 +81,7 @@ export class FileCacheAdapter {
         return `${this.options.cacheDir}/${name}.json`;
     }
     getHash(origin) {
-        origin = Utils.absolutePath(origin, this.baseDir);
+        origin = fs.absolutePath(origin, this.baseDir);
         if (!existsSync(origin)) {
             return null;
         }

package/connections/Connection.d.ts

@@ -43,9 +43,10 @@ export declare abstract class Connection {
      */
     ensureConnection(): Promise<void>;
     /**
-     * Load schema dump from file and execute it. Not supported by MongoDB driver.
+     * Execute raw SQL queries, handy from running schema dump loaded from a file.
+     * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
      */
-    loadFile(path: string): Promise<void>;
+    executeDump(dump: string): Promise<void>;
     protected onConnect(): Promise<void>;
     transactional<T>(cb: (trx: Transaction) => Promise<T>, options?: {
         isolationLevel?: IsolationLevel | `${IsolationLevel}`;

package/connections/Connection.js

@@ -40,10 +40,11 @@ export class Connection {
         }
     }
     /**
-     * Load schema dump from file and execute it. Not supported by MongoDB driver.
+     * Execute raw SQL queries, handy from running schema dump loaded from a file.
+     * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
      */
-    async loadFile(path) {
-        throw new Error(`Loading SQL files is not supported by current driver`);
+    async executeDump(dump) {
+        throw new Error(`Executing SQL dumps is not supported by current driver`);
     }
     async onConnect() {
         const schemaGenerator = this.config.getExtension('@mikro-orm/schema-generator');

package/drivers/DatabaseDriver.d.ts

@@ -22,18 +22,18 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     protected comparator: EntityComparator;
     protected metadata: MetadataStorage;
     protected constructor(config: Configuration, dependencies: string[]);
-    abstract find<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: string, where: FilterQuery<T>, options?: FindOptions<T, P, F, E>): Promise<EntityData<T>[]>;
-    abstract findOne<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: string, where: FilterQuery<T>, options?: FindOneOptions<T, P, F, E>): Promise<EntityData<T> | null>;
-    abstract nativeInsert<T extends object>(entityName: string, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
-    abstract nativeInsertMany<T extends object>(entityName: string, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
-    abstract nativeUpdate<T extends object>(entityName: string, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
-    nativeUpdateMany<T extends object>(entityName: string, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
-    abstract nativeDelete<T extends object>(entityName: string, where: FilterQuery<T>, options?: DeleteOptions<T>): Promise<QueryResult<T>>;
-    abstract count<T extends object, P extends string = never>(entityName: string, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
+    abstract find<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: FindOptions<T, P, F, E>): Promise<EntityData<T>[]>;
+    abstract findOne<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: FindOneOptions<T, P, F, E>): Promise<EntityData<T> | null>;
+    abstract nativeInsert<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    abstract nativeInsertMany<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
+    abstract nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
+    abstract nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: DeleteOptions<T>): Promise<QueryResult<T>>;
+    abstract count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];
     findVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
-    countVirtual<T extends object>(entityName: string, where: FilterQuery<T>, options: CountOptions<T, any>): Promise<number>;
-    aggregate(entityName: string, pipeline: any[]): Promise<any[]>;
+    countVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: CountOptions<T, any>): Promise<number>;
+    aggregate(entityName: EntityName, pipeline: any[]): Promise<any[]>;
     loadFromPivotTable<T extends object, O extends object>(prop: EntityProperty, owners: Primary<O>[][], where?: FilterQuery<any>, orderBy?: OrderDefinition<T>, ctx?: Transaction, options?: FindOptions<T, any, any, any>, pivotJoin?: boolean): Promise<Dictionary<T[]>>;
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
     mapResult<T extends object>(result: EntityDictionary<T>, meta?: EntityMetadata<T>, populate?: PopulateOptions<T>[]): EntityData<T> | null;
@@ -58,7 +58,7 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     /** @internal */
     mapDataToFieldNames(data: Dictionary, stringifyJsonArrays: boolean, properties?: Record<string, EntityProperty>, convertCustomTypes?: boolean, object?: boolean): Dictionary;
     protected inlineEmbeddables<T extends object>(meta: EntityMetadata<T>, data: T, where?: boolean): void;
-    protected getPrimaryKeyFields(entityName: string): string[];
+    protected getPrimaryKeyFields<T>(meta: EntityMetadata<T>): string[];
     protected createReplicas(cb: (c: ConnectionOptions) => C): C[];
     lockPessimistic<T extends object>(entity: T, options: LockOptions): Promise<void>;
     abstract stream<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: StreamOptions<T>): AsyncIterableIterator<T>;

package/drivers/DatabaseDriver.js

@@ -8,6 +8,7 @@ import { EntityManager } from '../EntityManager.js';
 import { CursorError, ValidationError } from '../errors.js';
 import { DriverException } from '../exceptions.js';
 import { helper } from '../entity/wrap.js';
+import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
 import { MikroORM } from '../MikroORM.js';
 export class DatabaseDriver {
@@ -59,7 +60,7 @@ export class DatabaseDriver {
             {
                 const pk = coll.property.targetMeta.primaryKeys[0];
                 const data = { [coll.property.name]: coll.getIdentifiers(pk) };
-                await this.nativeUpdate(coll.owner.constructor.name, helper(coll.owner).getPrimaryKey(), data, options);
+                await this.nativeUpdate(coll.owner.constructor, helper(coll.owner).getPrimaryKey(), data, options);
             }
         }
     }
@@ -67,7 +68,7 @@ export class DatabaseDriver {
         if (!result || !meta) {
             return result ?? null;
         }
-        return this.comparator.mapResult(meta.className, result);
+        return this.comparator.mapResult(meta, result);
     }
     async connect(options) {
         await this.connection.connect(options);
@@ -152,7 +153,7 @@ export class DatabaseDriver {
         }
         const createOrderBy = (prop, direction) => {
             if (Utils.isPlainObject(direction)) {
-                const value = Utils.keys(direction).reduce((o, key) => {
+                const value = Utils.getObjectQueryKeys(direction).reduce((o, key) => {
                     Object.assign(o, createOrderBy(key, direction[key]));
                     return o;
                 }, {});
@@ -168,22 +169,51 @@ export class DatabaseDriver {
         };
     }
     createCursorCondition(definition, offsets, inverse, meta) {
-        const createCondition = (prop, direction, offset, eq = false) => {
-            if (offset === null) {
-                throw CursorError.missingValue(meta.className, prop);
-            }
+        const createCondition = (prop, direction, offset, eq = false, path = prop) => {
             if (Utils.isPlainObject(direction)) {
+                if (offset === undefined) {
+                    throw CursorError.missingValue(meta.className, path);
+                }
                 const value = Utils.keys(direction).reduce((o, key) => {
-                    if (Utils.isEmpty(offset[key])) {
-                        throw CursorError.missingValue(meta.className, `${prop}.${key}`);
-                    }
-                    Object.assign(o, createCondition(key, direction[key], offset[key], eq));
+                    Object.assign(o, createCondition(key, direction[key], offset?.[key], eq, `${path}.${key}`));
                     return o;
                 }, {});
-                return ({ [prop]: value });
+                return { [prop]: value };
             }
-            const desc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
-            const operator = Utils.xor(desc, inverse) ? '$lt' : '$gt';
+            const isDesc = direction === QueryOrderNumeric.DESC || direction.toString().toLowerCase() === 'desc';
+            const dirStr = direction.toString().toLowerCase();
+            let nullsFirst;
+            if (dirStr.includes('nulls first')) {
+                nullsFirst = true;
+            }
+            else if (dirStr.includes('nulls last')) {
+                nullsFirst = false;
+            }
+            else {
+                // Default: NULLS LAST for ASC, NULLS FIRST for DESC (matches most databases)
+                nullsFirst = isDesc;
+            }
+            const operator = Utils.xor(isDesc, inverse) ? '$lt' : '$gt';
+            // For leaf-level properties, undefined means missing value
+            if (offset === undefined) {
+                throw CursorError.missingValue(meta.className, path);
+            }
+            // Handle null offset (intentional null cursor value)
+            if (offset === null) {
+                if (eq) {
+                    // Equal to null
+                    return { [prop]: null };
+                }
+                // Strict comparison with null cursor value
+                // hasItemsAfterNull: forward + nullsFirst, or backward + nullsLast
+                const hasItemsAfterNull = Utils.xor(nullsFirst, inverse);
+                if (hasItemsAfterNull) {
+                    return { [prop]: { $ne: null } };
+                }
+                // No items after null in this direction, return impossible condition
+                return { [prop]: [] };
+            }
+            // Non-null offset
             return { [prop]: { [operator + (eq ? 'e' : '')]: offset } };
         };
         const [order, ...otherOrders] = definition;
@@ -231,6 +261,43 @@ export class DatabaseDriver {
                 }
                 return;
             }
+            // Handle polymorphic relations - convert tuple or PolymorphicRef to separate columns
+            // Tuple format: ['discriminator', id] or ['discriminator', id1, id2] for composite keys
+            // Must be checked BEFORE joinColumns array handling since polymorphic uses fieldNames (includes discriminator)
+            if (prop.polymorphic && prop.fieldNames && prop.fieldNames.length >= 2) {
+                let discriminator;
+                let ids;
+                if (Array.isArray(data[k]) && typeof data[k][0] === 'string' && prop.discriminatorMap?.[data[k][0]]) {
+                    // Tuple format: ['discriminator', ...ids]
+                    const [disc, ...rest] = data[k];
+                    discriminator = disc;
+                    ids = rest;
+                }
+                else if (data[k] instanceof PolymorphicRef) {
+                    // PolymorphicRef wrapper (internal use)
+                    discriminator = data[k].discriminator;
+                    const polyId = data[k].id;
+                    // Handle object-style composite key IDs like { tenantId: 1, orgId: 100 }
+                    if (polyId && typeof polyId === 'object' && !Array.isArray(polyId)) {
+                        const targetEntity = prop.discriminatorMap?.[discriminator];
+                        const targetMeta = this.metadata.get(targetEntity);
+                        ids = targetMeta.primaryKeys.map(pk => polyId[pk]);
+                    }
+                    else {
+                        ids = Utils.asArray(polyId);
+                    }
+                }
+                if (discriminator) {
+                    const discriminatorColumn = prop.fieldNames[0];
+                    const idColumns = prop.fieldNames.slice(1);
+                    delete data[k];
+                    data[discriminatorColumn] = discriminator;
+                    idColumns.forEach((col, idx) => {
+                        data[col] = ids[idx];
+                    });
+                    return;
+                }
+            }
             if (prop.joinColumns && Array.isArray(data[k])) {
                 const copy = Utils.flatten(data[k]);
                 delete data[k];
@@ -277,38 +344,38 @@ export class DatabaseDriver {
                     // explicitly allow `$exists`, `$eq` and `$ne` operators here as they can't be misused this way
                     const operator = Object.keys(data[prop.name]).some(f => Utils.isOperator(f) && !['$exists', '$ne', '$eq'].includes(f));
                     if (operator) {
-                        throw ValidationError.cannotUseOperatorsInsideEmbeddables(meta.className, prop.name, data);
+                        throw ValidationError.cannotUseOperatorsInsideEmbeddables(meta.class, prop.name, data);
                     }
                     if (prop.object && where) {
                         const inline = (payload, sub, path) => {
                             if (sub.kind === ReferenceKind.EMBEDDED && Utils.isObject(payload[sub.embedded[1]])) {
                                 return Object.keys(payload[sub.embedded[1]]).forEach(kkk => {
                                     if (!sub.embeddedProps[kkk]) {
-                                        throw ValidationError.invalidEmbeddableQuery(meta.className, kkk, sub.type);
+                                        throw ValidationError.invalidEmbeddableQuery(meta.class, kkk, sub.type);
                                     }
-                                    inline(payload[sub.embedded[1]], sub.embeddedProps[kkk], [...path, sub.embedded[1]]);
+                                    inline(payload[sub.embedded[1]], sub.embeddedProps[kkk], [...path, sub.fieldNames[0]]);
                                 });
                             }
-                            data[`${path.join('.')}.${sub.embedded[1]}`] = payload[sub.embedded[1]];
+                            data[`${path.join('.')}.${sub.fieldNames[0]}`] = payload[sub.embedded[1]];
                         };
                         const parentPropName = kk.substring(0, kk.indexOf('.'));
                         // we might be using some native JSON operator, e.g. with mongodb's `$geoWithin` or `$exists`
                         if (props[kk]) {
                             /* v8 ignore next */
-                            inline(data[prop.name], props[kk] || props[parentPropName], [prop.name]);
+                            inline(data[prop.name], props[kk] || props[parentPropName], [prop.fieldNames[0]]);
                         }
                         else if (props[parentPropName]) {
-                            data[`${prop.name}.${kk}`] = data[prop.name][kk];
+                            data[`${prop.fieldNames[0]}.${kk}`] = data[prop.name][kk];
                         }
                         else {
                             unknownProp = true;
                         }
                     }
                     else if (props[kk]) {
-                        data[props[kk].name] = data[prop.name][props[kk].embedded[1]];
+                        data[props[kk].fieldNames[0]] = data[prop.name][props[kk].embedded[1]];
                     }
                     else {
-                        throw ValidationError.invalidEmbeddableQuery(meta.className, kk, prop.type);
+                        throw ValidationError.invalidEmbeddableQuery(meta.class, kk, prop.type);
                     }
                 });
                 if (!unknownProp) {
@@ -317,9 +384,8 @@ export class DatabaseDriver {
             }
         });
     }
-    getPrimaryKeyFields(entityName) {
-        const meta = this.metadata.find(entityName);
-        return meta ? Utils.flatten(meta.getPrimaryProps().map(pk => pk.fieldNames)) : [this.config.getNamingStrategy().referenceColumnName()];
+    getPrimaryKeyFields(meta) {
+        return meta.getPrimaryProps().flatMap(pk => pk.fieldNames);
     }
     createReplicas(cb) {
         const replicas = this.config.get('replicas', []);

package/drivers/IDatabaseDriver.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionType, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, QBFilterQuery, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName } from '../typings.js';
+import type { ConnectionType, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName } from '../typings.js';
 import type { Connection, QueryResult, Transaction } from '../connections/Connection.js';
 import type { FlushMode, LockMode, QueryOrderMap, QueryFlag, LoadStrategy, PopulateHint, PopulatePath } from '../enums.js';
 import type { Platform } from '../platforms/Platform.js';
@@ -8,7 +8,7 @@ import type { EntityManager } from '../EntityManager.js';
 import type { DriverException } from '../exceptions.js';
 import type { Configuration } from '../utils/Configuration.js';
 import type { LoggingOptions, LogContext } from '../logging/Logger.js';
-import type { RawQueryFragment } from '../utils/RawQueryFragment.js';
+import type { Raw } from '../utils/RawQueryFragment.js';
 export declare const EntityManagerType: unique symbol;
 export interface IDatabaseDriver<C extends Connection = Connection> {
     [EntityManagerType]: EntityManager<this>;
@@ -25,21 +25,21 @@ export interface IDatabaseDriver<C extends Connection = Connection> {
     /**
      * Finds selection of entities
      */
-    find<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: string, where: FilterQuery<T>, options?: FindOptions<T, P, F, E>): Promise<EntityData<T>[]>;
+    find<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: FindOptions<T, P, F, E>): Promise<EntityData<T>[]>;
     /**
      * Finds single entity (table row, document)
      */
-    findOne<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: string, where: FilterQuery<T>, options?: FindOneOptions<T, P, F, E>): Promise<EntityData<T> | null>;
-    findVirtual<T extends object>(entityName: string, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
+    findOne<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: FindOneOptions<T, P, F, E>): Promise<EntityData<T> | null>;
+    findVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
     stream<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: StreamOptions<T>): AsyncIterableIterator<T>;
-    nativeInsert<T extends object>(entityName: string, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
-    nativeInsertMany<T extends object>(entityName: string, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
-    nativeUpdate<T extends object>(entityName: string, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
-    nativeUpdateMany<T extends object>(entityName: string, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
-    nativeDelete<T extends object>(entityName: string, where: FilterQuery<T>, options?: NativeDeleteOptions<T>): Promise<QueryResult<T>>;
+    nativeInsert<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    nativeInsertMany<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
+    nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
+    nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: NativeDeleteOptions<T>): Promise<QueryResult<T>>;
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
-    count<T extends object, P extends string = never>(entityName: string, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
-    aggregate(entityName: string, pipeline: any[]): Promise<any[]>;
+    count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
+    aggregate(entityName: EntityName, pipeline: any[]): Promise<any[]>;
     mapResult<T extends object>(result: EntityDictionary<T>, meta: EntityMetadata<T>, populate?: PopulateOptions<T>[]): EntityData<T> | null;
     /**
      * When driver uses pivot tables for M:N, this method will load identifiers for given collections from them
@@ -144,7 +144,7 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     flags?: QueryFlag[];
     /** sql only */
     groupBy?: string | string[];
-    having?: QBFilterQuery<Entity>;
+    having?: FilterQuery<Entity>;
     /** sql only */
     strategy?: LoadStrategy | `${LoadStrategy}`;
     flushMode?: FlushMode | `${FlushMode}`;
@@ -166,7 +166,7 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     /** @internal used to apply filters to the auto-joined relations */
     em?: EntityManager;
 }
-export interface FindByCursorOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never, I extends boolean = true> extends Omit<FindOptions<T, P, F, E>, 'limit' | 'offset'> {
+export interface FindByCursorOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never, I extends boolean = true> extends Omit<FindAllOptions<T, P, F, E>, 'limit' | 'offset'> {
     includeCount?: I;
 }
 export interface FindOneOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends Omit<FindOptions<T, P, F, E>, 'limit' | 'lockMode'> {
@@ -189,10 +189,11 @@ export interface NativeInsertUpdateManyOptions<T> extends NativeInsertUpdateOpti
     processCollections?: boolean;
 }
 export interface UpsertOptions<Entity, Fields extends string = never> extends Omit<NativeInsertUpdateOptions<Entity>, 'upsert'> {
-    onConflictFields?: (keyof Entity)[] | RawQueryFragment;
+    onConflictFields?: (keyof Entity)[] | Raw;
     onConflictAction?: 'ignore' | 'merge';
     onConflictMergeFields?: AutoPath<Entity, Fields, `${PopulatePath.ALL}`>[];
     onConflictExcludeFields?: AutoPath<Entity, Fields, `${PopulatePath.ALL}`>[];
+    onConflictWhere?: FilterQuery<Entity>;
     disableIdentityMap?: boolean;
 }
 export interface UpsertManyOptions<Entity, Fields extends string = never> extends UpsertOptions<Entity, Fields> {
@@ -202,7 +203,7 @@ export interface CountOptions<T extends object, P extends string = never> {
     filters?: FilterOptions;
     schema?: string;
     groupBy?: string | readonly string[];
-    having?: QBFilterQuery<T>;
+    having?: FilterQuery<T>;
     cache?: boolean | number | [string, number];
     populate?: Populate<T, P>;
     populateWhere?: ObjectQuery<T> | PopulateHint | `${PopulateHint}`;
@@ -247,4 +248,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/BaseEntity.d.ts

@@ -4,13 +4,73 @@ import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import { type SerializeOptions } from '../serialization/EntitySerializer.js';
 import type { FindOneOptions } from '../drivers/IDatabaseDriver.js';
+import type { PopulatePath } from '../enums.js';
 export declare abstract class BaseEntity {
     isInitialized(): boolean;
     populated(populated?: boolean): void;
-    populate<Entity extends this = this, Hint extends string = never>(populate: AutoPath<Entity, Hint>[] | false, options?: EntityLoaderOptions<Entity>): Promise<Loaded<Entity, Hint>>;
+    populate<Entity extends this = this, Hint extends string = never>(populate: AutoPath<Entity, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Entity>): Promise<Loaded<Entity, Hint>>;
     toReference<Entity extends this = this>(): Ref<Entity> & LoadedReference<Loaded<Entity, AddEager<Entity>>>;
+    /**
+     * Converts the entity to a plain object representation.
+     *
+     * **Note on typing with `Loaded` entities:** When called on a `Loaded<Entity, 'relation'>` type,
+     * the return type will be `EntityDTO<Entity>` (with relations as primary keys), not
+     * `EntityDTO<Loaded<Entity, 'relation'>>` (with loaded relations as nested objects).
+     * This is a TypeScript limitation - the `this` type resolves to the class, not the `Loaded` wrapper.
+     *
+     * For correct typing that reflects loaded relations, use `wrap()`:
+     * ```ts
+     * const result = await em.find(User, {}, { populate: ['profile'] });
+     * // Type: EntityDTO<User> (profile is number)
+     * const obj1 = result[0].toObject();
+     * // Type: EntityDTO<Loaded<User, 'profile'>> (profile is nested object)
+     * const obj2 = wrap(result[0]).toObject();
+     * ```
+     *
+     * Runtime values are correct in both cases - only the static types differ.
+     */
     toObject<Entity extends this = this>(): EntityDTO<Entity>;
+    /**
+     * Converts the entity to a plain object representation.
+     *
+     * **Note on typing with `Loaded` entities:** When called on a `Loaded<Entity, 'relation'>` type,
+     * the return type will be `EntityDTO<Entity>` (with relations as primary keys), not
+     * `EntityDTO<Loaded<Entity, 'relation'>>` (with loaded relations as nested objects).
+     * This is a TypeScript limitation - the `this` type resolves to the class, not the `Loaded` wrapper.
+     *
+     * For correct typing that reflects loaded relations, use `wrap()`:
+     * ```ts
+     * const result = await em.find(User, {}, { populate: ['profile'] });
+     * // Type: EntityDTO<User> (profile is number)
+     * const obj1 = result[0].toObject();
+     * // Type: EntityDTO<Loaded<User, 'profile'>> (profile is nested object)
+     * const obj2 = wrap(result[0]).toObject();
+     * ```
+     *
+     * Runtime values are correct in both cases - only the static types differ.
+     */
     toObject<Entity extends this = this>(ignoreFields: never[]): EntityDTO<Entity>;
+    /**
+     * Converts the entity to a plain object representation.
+     *
+     * **Note on typing with `Loaded` entities:** When called on a `Loaded<Entity, 'relation'>` type,
+     * the return type will be `EntityDTO<Entity>` (with relations as primary keys), not
+     * `EntityDTO<Loaded<Entity, 'relation'>>` (with loaded relations as nested objects).
+     * This is a TypeScript limitation - the `this` type resolves to the class, not the `Loaded` wrapper.
+     *
+     * For correct typing that reflects loaded relations, use `wrap()`:
+     * ```ts
+     * const result = await em.find(User, {}, { populate: ['profile'] });
+     * // Type: EntityDTO<User> (profile is number)
+     * const obj1 = result[0].toObject();
+     * // Type: EntityDTO<Loaded<User, 'profile'>> (profile is nested object)
+     * const obj2 = wrap(result[0]).toObject();
+     * ```
+     *
+     * Runtime values are correct in both cases - only the static types differ.
+     *
+     * @param ignoreFields - Array of field names to omit from the result.
+     */
     toObject<Entity extends this = this, Ignored extends EntityKey<Entity> = never>(ignoreFields: Ignored[]): Omit<EntityDTO<Entity>, Ignored>;
     toPOJO<Entity extends this = this>(): EntityDTO<Entity>;
     serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude>): EntityDTO<Loaded<Naked, Hint>>;

package/entity/Collection.d.ts

@@ -62,7 +62,6 @@ export declare class Collection<T extends object, O extends object = object> {
     init<TT extends T, P extends string = never>(options?: InitCollectionOptions<TT, P>): Promise<LoadedCollection<Loaded<TT, P>>>;
     private getEntityManager;
     private createCondition;
-    private createOrderBy;
     private createManyToManyCondition;
     private createLoadCountCondition;
     private checkInitialized;
@@ -104,10 +103,18 @@ export declare class Collection<T extends object, O extends object = object> {
      * Tests for the existence of an element that satisfies the given predicate.
      */
     exists(cb: (item: T) => boolean): boolean;
+    /**
+     * Returns the first element of this collection that satisfies the predicate.
+     */
+    find<S extends T>(cb: (item: T, index: number) => item is S): S | undefined;
     /**
      * Returns the first element of this collection that satisfies the predicate.
      */
     find(cb: (item: T, index: number) => boolean): T | undefined;
+    /**
+     * Extracts a subset of the collection items.
+     */
+    filter<S extends T>(cb: (item: T, index: number) => item is S): S[];
     /**
      * Extracts a subset of the collection items.
      */