@mikro-orm/core 7.0.0-dev.23 → 7.0.0-dev.230

package/connections/Connection.js

@@ -1,4 +1,3 @@
-import { URL } from 'node:url';
 import { Utils } from '../utils/Utils.js';
 export class Connection {
     config;
@@ -33,13 +32,32 @@ export class Connection {
             .forEach(k => delete this.options[k]);
     }
     /**
-     * Ensure the connection exists, this is used to support lazy connect when using `MikroORM.initSync()`
+     * Ensure the connection exists, this is used to support lazy connect when using `new MikroORM()` instead of the async `init` method.
      */
     async ensureConnection() {
         if (!this.connected) {
             await this.connect();
         }
     }
+    /**
+     * 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 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');
+        if (this.type === 'write' && schemaGenerator) {
+            if (this.config.get('ensureDatabase')) {
+                const options = this.config.get('ensureDatabase');
+                await schemaGenerator.ensureDatabase(typeof options === 'boolean' ? {} : { ...options, forceCheck: true });
+            }
+            if (this.config.get('ensureIndexes')) {
+                await schemaGenerator.ensureIndexes();
+            }
+        }
+    }
     async transactional(cb, options) {
         throw new Error(`Transactions are not supported by current driver`);
     }
@@ -67,7 +85,7 @@ export class Connection {
             }
         }
         else {
-            const url = new URL(this.config.getClientUrl());
+            const url = new URL(this.config.get('clientUrl'));
             this.options.host = ret.host = this.options.host ?? this.config.get('host', decodeURIComponent(url.hostname));
             this.options.port = ret.port = this.options.port ?? this.config.get('port', +url.port);
             this.options.user = ret.user = this.options.user ?? this.config.get('user', decodeURIComponent(url.username));
@@ -76,15 +94,6 @@ export class Connection {
         }
         return ret;
     }
-    getClientUrl() {
-        const options = this.getConnectionOptions();
-        const url = new URL(this.config.getClientUrl(true));
-        const password = options.password ? ':*****' : '';
-        const schema = options.schema && options.schema !== this.platform.getDefaultSchemaName()
-            ? `?schema=${options.schema}`
-            : '';
-        return `${url.protocol}//${options.user}${password}@${options.host}:${options.port}${schema}`;
-    }
     setMetadata(metadata) {
         this.metadata = metadata;
     }

package/drivers/DatabaseDriver.d.ts

@@ -1,5 +1,5 @@
-import { type CountOptions, type DeleteOptions, type DriverMethodOptions, EntityManagerType, type FindOneOptions, type FindOptions, type IDatabaseDriver, type LockOptions, type NativeInsertUpdateManyOptions, type NativeInsertUpdateOptions, type OrderDefinition } from './IDatabaseDriver.js';
-import type { ConnectionType, Dictionary, EntityData, EntityDictionary, EntityMetadata, EntityProperty, FilterQuery, PopulateOptions, Primary } from '../typings.js';
+import { type CountOptions, type DeleteOptions, type DriverMethodOptions, EntityManagerType, type FindOneOptions, type FindOptions, type IDatabaseDriver, type LockOptions, type NativeInsertUpdateManyOptions, type NativeInsertUpdateOptions, type OrderDefinition, type StreamOptions } from './IDatabaseDriver.js';
+import type { ConnectionType, Constructor, Dictionary, EntityData, EntityDictionary, EntityMetadata, EntityName, EntityProperty, FilterQuery, PopulateOptions, Primary } from '../typings.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
 import type { Connection, QueryResult, Transaction } from '../connections/Connection.js';
 import { type Configuration, type ConnectionOptions } from '../utils/Configuration.js';
@@ -10,6 +10,7 @@ import type { Collection } from '../entity/Collection.js';
 import { EntityManager } from '../EntityManager.js';
 import { DriverException } from '../exceptions.js';
 import type { Logger } from '../logging/Logger.js';
+import { MikroORM } from '../MikroORM.js';
 export declare abstract class DatabaseDriver<C extends Connection> implements IDatabaseDriver<C> {
     readonly config: Configuration;
     protected readonly dependencies: string[];
@@ -21,29 +22,34 @@ 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: string, 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[]>;
+    findVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
+    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;
-    connect(): Promise<C>;
-    reconnect(): Promise<C>;
+    connect(options?: {
+        skipOnConnect?: boolean;
+    }): Promise<C>;
+    reconnect(options?: {
+        skipOnConnect?: boolean;
+    }): Promise<C>;
     getConnection(type?: ConnectionType): C;
     close(force?: boolean): Promise<void>;
     getPlatform(): Platform;
     setMetadata(metadata: MetadataStorage): void;
     getMetadata(): MetadataStorage;
     getDependencies(): string[];
+    protected isPopulated<T extends object>(meta: EntityMetadata<T>, prop: EntityProperty<T>, hint: PopulateOptions<T>, name?: string): boolean;
     protected processCursorOptions<T extends object, P extends string>(meta: EntityMetadata<T>, options: FindOptions<T, P, any, any>, orderBy: OrderDefinition<T>): {
         orderBy: OrderDefinition<T>[];
         where: FilterQuery<T>;
@@ -52,9 +58,10 @@ 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>;
     /**
      * @inheritDoc
      */
@@ -71,4 +78,6 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
         schema?: string;
         parentSchema?: string;
     }): string | undefined;
+    /** @internal */
+    getORMClass(): Constructor<MikroORM>;
 }

package/drivers/DatabaseDriver.js

@@ -8,7 +8,9 @@ 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 {
     config;
     dependencies;
@@ -31,11 +33,11 @@ export class DatabaseDriver {
         const EntityManagerClass = this.config.get('entityManager', EntityManager);
         return new EntityManagerClass(this.config, this, this.metadata, useContext);
     }
-    /* v8 ignore next 3 */
+    /* v8 ignore next */
     async findVirtual(entityName, where, options) {
         throw new Error(`Virtual entities are not supported by ${this.constructor.name} driver.`);
     }
-    /* v8 ignore next 3 */
+    /* v8 ignore next */
     async countVirtual(entityName, where, options) {
         throw new Error(`Counting virtual entities is not supported by ${this.constructor.name} driver.`);
     }
@@ -47,32 +49,35 @@ export class DatabaseDriver {
     }
     async syncCollections(collections, options) {
         for (const coll of collections) {
+            /* v8 ignore else */
             if (!coll.property.owner) {
                 if (coll.getSnapshot() === undefined) {
                     throw ValidationError.cannotModifyInverseCollection(coll.owner, coll.property);
                 }
                 continue;
             }
-            /* v8 ignore next 3 */
-            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);
+            /* v8 ignore next */
+            {
+                const pk = coll.property.targetMeta.primaryKeys[0];
+                const data = { [coll.property.name]: coll.getIdentifiers(pk) };
+                await this.nativeUpdate(coll.owner.constructor, helper(coll.owner).getPrimaryKey(), data, options);
+            }
         }
     }
     mapResult(result, meta, populate = []) {
         if (!result || !meta) {
             return result ?? null;
         }
-        return this.comparator.mapResult(meta.className, result);
+        return this.comparator.mapResult(meta, result);
     }
-    async connect() {
-        await this.connection.connect();
+    async connect(options) {
+        await this.connection.connect(options);
         await Promise.all(this.replicas.map(replica => replica.connect()));
         return this.connection;
     }
-    async reconnect() {
+    async reconnect(options) {
         await this.close(true);
-        await this.connect();
+        await this.connect(options);
         return this.connection;
     }
     getConnection(type = 'write') {
@@ -105,6 +110,15 @@ export class DatabaseDriver {
     getDependencies() {
         return this.dependencies;
     }
+    isPopulated(meta, prop, hint, name) {
+        if (hint.field === prop.name || hint.field === name || hint.all) {
+            return true;
+        }
+        if (prop.embedded && hint.children && meta.properties[prop.embedded[0]].name === hint.field) {
+            return hint.children.some(c => this.isPopulated(meta, prop, c, prop.embedded[1]));
+        }
+        return false;
+    }
     processCursorOptions(meta, options, orderBy) {
         const { first, last, before, after, overfetch } = options;
         const limit = first ?? last;
@@ -139,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;
                 }, {});
@@ -155,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;
@@ -218,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];
@@ -244,7 +324,7 @@ export class DatabaseDriver {
         return data;
     }
     inlineEmbeddables(meta, data, where) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (data == null) {
             return;
         }
@@ -264,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) {
@@ -304,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', []);
@@ -372,4 +451,8 @@ export class DatabaseDriver {
         const schemaName = meta?.schema === '*' ? this.config.getSchema() : meta?.schema;
         return options?.schema ?? options?.parentSchema ?? schemaName ?? this.config.getSchema();
     }
+    /** @internal */
+    getORMClass() {
+        return MikroORM;
+    }
 }

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 } 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,33 +8,38 @@ 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>;
     readonly config: Configuration;
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];
-    connect(): Promise<C>;
+    connect(options?: {
+        skipOnConnect?: boolean;
+    }): Promise<C>;
     close(force?: boolean): Promise<void>;
-    reconnect(): Promise<C>;
+    reconnect(options?: {
+        skipOnConnect?: boolean;
+    }): Promise<C>;
     getConnection(type?: ConnectionType): C;
     /**
      * 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>[]>;
-    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>>;
+    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: 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
@@ -68,6 +73,18 @@ export type OrderDefinition<T> = (QueryOrderMap<T> & {
 export interface FindAllOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends FindOptions<T, P, F, E> {
     where?: FilterQuery<T>;
 }
+export interface StreamOptions<Entity, Populate extends string = never, Fields extends string = '*', Exclude extends string = never> extends Omit<FindAllOptions<Entity, Populate, Fields, Exclude>, 'cache' | 'before' | 'after' | 'first' | 'last' | 'overfetch' | 'strategy'> {
+    /**
+     * When populating to-many relations, the ORM streams fully merged entities instead of yielding every row.
+     * You can opt out of this behavior by specifying `mergeResults: false`. This will yield every row from
+     * the SQL result, but still mapped to entities, meaning that to-many collections will contain at most
+     * a single item, and you will get duplicate root entities when they have multiple items in the populated
+     * collection.
+     *
+     * @default true
+     */
+    mergeResults?: boolean;
+}
 export type FilterOptions = Dictionary<boolean | Dictionary> | string[] | boolean;
 export interface LoadHint<Entity, Hint extends string = never, Fields extends string = PopulatePath.ALL, Excludes extends string = never> {
     populate?: Populate<Entity, Hint>;
@@ -127,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}`;
@@ -149,10 +166,10 @@ 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 extends object, P extends string = never, F extends string = '*', E extends string = never> extends Omit<FindOptions<T, P, F, E>, 'limit' | 'lockMode'> {
+export interface FindOneOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends Omit<FindOptions<T, P, F, E>, 'limit' | 'lockMode'> {
     lockMode?: LockMode;
     lockVersion?: number | Date;
 }
@@ -172,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> {
@@ -185,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}`;
@@ -230,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,14 +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;
-    isTouched(): 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/BaseEntity.js

@@ -6,9 +6,6 @@ export class BaseEntity {
     isInitialized() {
         return helper(this).__initialized;
     }
-    isTouched() {
-        return helper(this).__touched;
-    }
     populated(populated = true) {
         helper(this).populated(populated);
     }