@mikro-orm/core 7.0.0-dev.2 → 7.0.0-dev.200

package/connections/Connection.js

@@ -1,4 +1,3 @@
-import { URL } from 'node:url';
 import { Utils } from '../utils/Utils.js';
 export class Connection {
     config;
@@ -33,23 +32,42 @@ 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`);
     }
     async begin(options) {
         throw new Error(`Transactions are not supported by current driver`);
     }
-    async commit(ctx, eventBroadcaster) {
+    async commit(ctx, eventBroadcaster, loggerContext) {
         throw new Error(`Transactions are not supported by current driver`);
     }
-    async rollback(ctx, eventBroadcaster) {
+    async rollback(ctx, eventBroadcaster, loggerContext) {
         throw new Error(`Transactions are not supported by current driver`);
     }
     getConnectionOptions() {
@@ -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

@@ -9,6 +9,7 @@ import { CursorError, ValidationError } from '../errors.js';
 import { DriverException } from '../exceptions.js';
 import { helper } from '../entity/wrap.js';
 import { JsonType } from '../types/JsonType.js';
+import { MikroORM } from '../MikroORM.js';
 export class DatabaseDriver {
     config;
     dependencies;
@@ -31,11 +32,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 +48,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 +109,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 +152,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 +168,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;
@@ -244,7 +286,7 @@ export class DatabaseDriver {
         return data;
     }
     inlineEmbeddables(meta, data, where) {
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (data == null) {
             return;
         }
@@ -264,38 +306,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 +346,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 +413,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, QBFilterQuery, 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>;
@@ -146,10 +163,13 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     hintComments?: string | string[];
     loggerContext?: LogContext;
     logging?: LoggingOptions;
+    /** @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> 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;
 }
@@ -163,15 +183,17 @@ export interface NativeInsertUpdateOptions<T> {
     schema?: string;
     /** `nativeUpdate()` only option */
     upsert?: boolean;
+    loggerContext?: LogContext;
 }
 export interface NativeInsertUpdateManyOptions<T> extends NativeInsertUpdateOptions<T> {
     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> {
@@ -197,6 +219,8 @@ export interface CountOptions<T extends object, P extends string = never> {
     hintComments?: string | string[];
     loggerContext?: LogContext;
     logging?: LoggingOptions;
+    /** @internal used to apply filters to the auto-joined relations */
+    em?: EntityManager;
 }
 export interface UpdateOptions<T> {
     filters?: FilterOptions;
@@ -218,9 +242,15 @@ export interface LockOptions extends DriverMethodOptions {
 export interface DriverMethodOptions {
     ctx?: Transaction;
     schema?: string;
+    loggerContext?: LogContext;
 }
 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,11 +4,11 @@ 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>>>;
     toObject<Entity extends this = this>(): EntityDTO<Entity>;
     toObject<Entity extends this = this>(ignoreFields: never[]): EntityDTO<Entity>;

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);
     }