@mikro-orm/core 7.2.0-dev.1 → 7.2.0-dev.11

package/EntityManager.d.ts

@@ -375,12 +375,10 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      */
     nativeDelete<Entity extends object>(entityName: EntityName<Entity>, where: FilterQuery<NoInfer<Entity>>, options?: DeleteOptions<Entity>): Promise<number>;
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
-    map<Entity extends object>(entityName: EntityName<Entity>, result: EntityDictionary<Entity>, options?: {
-        schema?: string;
-        mapped?: boolean;
-    }): Entity;
+    map<Entity extends object>(entityName: EntityName<Entity>, result: EntityDictionary<Entity>, options?: MapOptions): Entity;
     /**
      * Merges given entity to this EntityManager so it becomes managed. You can force refreshing of existing entities
      * via second parameter. By default, it will return already loaded entities without modifying them.
@@ -601,7 +599,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * some additional lazy properties, if so, we reload and merge the data from database
      */
     protected shouldRefresh<T extends object, P extends string = never, F extends string = never, E extends string = never>(meta: EntityMetadata<T>, entity: T, options: FindOneOptions<T, P, F, E>): boolean;
-    protected prepareOptions(options: (FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any> | CountOptions<any, any> | CountByOptions<any>) & AbortQueryOptions): void;
+    protected prepareOptions<Options extends (FindOptions<any, any, any, any> | FindOneOptions<any, any, any, any> | CountOptions<any, any> | CountByOptions<any>) & AbortQueryOptions>(options: Options): Options;
     /**
      * @internal
      */
@@ -667,6 +665,14 @@ export interface CreateOptions<Convert extends boolean> {
      */
     processOnCreateHooksEarly?: boolean;
 }
+export interface MapOptions {
+    /** schema to use when mapping the entity */
+    schema?: string;
+    /** set to true when the result is already mapped to entity property names */
+    mapped?: boolean;
+    /** map the entity in an isolated context without adding it to the identity map */
+    disableIdentityMap?: boolean;
+}
 export interface MergeOptions {
     refresh?: boolean;
     convertCustomTypes?: boolean;

package/EntityManager.js

@@ -116,7 +116,7 @@ export class EntityManager {
             return ret;
         }
         const em = this.getContext();
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         const meta = this.metadata.get(entityName);
         em.validateIndexUsage(meta, where, options);
         await em.tryFlush(entityName, options);
@@ -199,7 +199,7 @@ export class EntityManager {
      */
     async *stream(entityName, options = {}) {
         const em = this.getContext();
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         options.strategy = 'joined';
         await em.tryFlush(entityName, options);
         const where = (await em.processWhere(entityName, options.where ?? {}, options, 'read'));
@@ -258,6 +258,7 @@ export class EntityManager {
      * Registers global filter to this entity manager. Global filters are enabled by default (unless disabled via last parameter).
      */
     addFilter(options) {
+        options = { ...options };
         if (options.entity) {
             options.entity = Utils.asArray(options.entity).map(n => Utils.className(n));
         }
@@ -528,7 +529,7 @@ export class EntityManager {
     async findAndCount(entityName, where, options = {}) {
         const em = this.getContext(false);
         await em.tryFlush(entityName, options);
-        options.flushMode = 'commit'; // do not try to auto flush again
+        options = { ...options, flushMode: 'commit' }; // do not try to auto flush again
         return Promise.all([
             em.find(entityName, where, options),
             em.count(entityName, where, options),
@@ -592,6 +593,7 @@ export class EntityManager {
      */
     async findByCursor(entityName, options) {
         const em = this.getContext(false);
+        options = { ...options };
         options.overfetch ??= true;
         options.where ??= {};
         if (Utils.isEmpty(options.orderBy) && !Raw.hasObjectFragments(options.orderBy)) {
@@ -610,10 +612,10 @@ export class EntityManager {
     async refreshOrFail(entity, options = {}) {
         const ret = await this.refresh(entity, options);
         if (!ret) {
-            options.failHandler ??= this.config.get('findOneOrFailHandler');
+            const failHandler = options.failHandler ?? this.config.get('findOneOrFailHandler');
             const wrapped = helper(entity);
             const where = wrapped.getPrimaryKey();
-            throw options.failHandler(wrapped.__meta.className, where);
+            throw failHandler(wrapped.__meta.className, where);
         }
         return ret;
     }
@@ -667,7 +669,7 @@ export class EntityManager {
             return ret;
         }
         const em = this.getContext();
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         let entity = em.#unitOfWork.tryGetById(entityName, where, options.schema);
         // query for a not managed entity which is already in the identity map as it
         // was provided with a PK this entity does not exist in the db, there can't
@@ -739,11 +741,11 @@ export class EntityManager {
         }
         if (!entity || isStrictViolation) {
             const key = options.strict ? 'findExactlyOneOrFailHandler' : 'findOneOrFailHandler';
-            options.failHandler ??= this.config.get(key);
+            const failHandler = options.failHandler ?? this.config.get(key);
             const name = Utils.className(entityName);
             /* v8 ignore next */
             where = Utils.isEntity(where) ? helper(where).getPrimaryKey() : where;
-            throw options.failHandler(name, where);
+            throw failHandler(name, where);
         }
         return entity;
     }
@@ -778,7 +780,7 @@ export class EntityManager {
             return ret;
         }
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         let entityName;
         let where;
         let entity = null;
@@ -916,7 +918,7 @@ export class EntityManager {
             return ret;
         }
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         let entityName;
         let propIndex;
         if (data === undefined) {
@@ -1202,7 +1204,7 @@ export class EntityManager {
      */
     async lock(entity, lockMode, options = {}) {
         options = Utils.isPlainObject(options) ? options : { lockVersion: options };
-        this.getContext(false).prepareOptions(options);
+        options = this.getContext(false).prepareOptions(options);
         await this.getUnitOfWork().lock(entity, { lockMode, ...options });
     }
     /**
@@ -1210,7 +1212,7 @@ export class EntityManager {
      */
     async insert(entityNameOrEntity, data, options = {}) {
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         let entityName;
         if (data === undefined) {
             entityName = entityNameOrEntity.constructor;
@@ -1277,7 +1279,7 @@ export class EntityManager {
             overrides = overridesOrOptions;
         }
         options ??= {};
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         const meta = em.metadata.get(entityName);
         const res = await em.driver.nativeClone(entityName, where, overrides, {
             ctx: em.#transactionContext,
@@ -1293,7 +1295,7 @@ export class EntityManager {
      */
     async insertMany(entityNameOrEntities, data, options = {}) {
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         let entityName;
         if (data === undefined) {
             entityName = entityNameOrEntities[0].constructor;
@@ -1336,7 +1338,7 @@ export class EntityManager {
      */
     async nativeUpdate(entityName, where, data, options = {}) {
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         await em.processUnionWhere(entityName, options, 'update');
         data = QueryHelper.processObjectParams(data);
         where = await em.processWhere(entityName, where, { ...options, convertCustomTypes: false }, 'update');
@@ -1385,7 +1387,7 @@ export class EntityManager {
      */
     async nativeDelete(entityName, where, options = {}) {
         const em = this.getContext(false);
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         await em.processUnionWhere(entityName, options, 'delete');
         where = (await em.processWhere(entityName, where, options, 'delete'));
         validateParams(where, 'delete condition');
@@ -1397,10 +1399,18 @@ export class EntityManager {
         return res.affectedRows;
     }
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
     map(entityName, result, options = {}) {
-        const { mapped, ...rest } = options;
+        if (options.disableIdentityMap ?? this.config.get('disableIdentityMap')) {
+            const em = this.getContext(false);
+            const fork = em.fork({ keepTransactionContext: true });
+            const ret = fork.map(entityName, result, { ...options, disableIdentityMap: false });
+            fork.clear();
+            return ret;
+        }
+        const { mapped, disableIdentityMap, ...rest } = options;
         const meta = this.metadata.get(entityName);
         const data = (mapped ? result : this.driver.mapResult(result, meta));
         for (const k of Object.keys(data)) {
@@ -1428,6 +1438,7 @@ export class EntityManager {
             return this.merge(entityName.constructor, entityName, data);
         }
         const em = options.disableContextResolution ? this : this.getContext();
+        options = { ...options };
         options.schema ??= em.#schema;
         options.validate ??= true;
         options.cascade ??= true;
@@ -1461,6 +1472,7 @@ export class EntityManager {
      */
     create(entityName, data, options = {}) {
         const em = this.getContext();
+        options = { ...options };
         options.schema ??= em.#schema;
         const entity = em.#entityFactory.create(entityName, data, {
             ...options,
@@ -1484,6 +1496,7 @@ export class EntityManager {
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
     getReference(entityName, id, options = {}) {
+        options = { ...options };
         options.schema ??= this.schema;
         options.convertCustomTypes ??= false;
         const meta = this.metadata.get(entityName);
@@ -1504,13 +1517,10 @@ export class EntityManager {
      */
     async count(entityName, where = {}, options = {}) {
         const em = this.getContext(false);
-        // Shallow copy options since the object will be modified when deleting orderBy
-        options = { ...options };
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         await em.tryFlush(entityName, options);
         where = await em.processWhere(entityName, where, options, 'read');
         options.populate = (await em.preparePopulate(entityName, options));
-        options = { ...options };
         // save the original hint value so we know it was infer/all
         const meta = em.metadata.find(entityName);
         options._populateWhere = options.populateWhere ?? this.config.get('populateWhere');
@@ -1654,7 +1664,7 @@ export class EntityManager {
             return entities;
         }
         const em = this.getContext();
-        em.prepareOptions(options);
+        options = em.prepareOptions(options);
         const entityName = arr[0].constructor;
         const preparedPopulate = await em.preparePopulate(entityName, { populate: populate, filters: options.filters, populateHints: options.populateHints }, options.validate);
         await em.#entityLoader.populate(entityName, arr, preparedPopulate, options);
@@ -1665,6 +1675,7 @@ export class EntityManager {
      */
     fork(options = {}) {
         const em = options.disableContextResolution ? this : this.getContext(false);
+        options = { ...options };
         options.clear ??= true;
         options.useContext ??= false;
         options.freshEventManager ??= false;
@@ -2073,10 +2084,13 @@ export class EntityManager {
         if (!Utils.isEmpty(options.fields) && !Utils.isEmpty(options.exclude)) {
             throw new ValidationError(`Cannot combine 'fields' and 'exclude' option.`);
         }
-        options.schema ??= this.#schema;
-        options.signal ??= this.signal;
-        options.inflightQueryAbortStrategy ??= this.inflightQueryAbortStrategy;
-        options.logging = options.loggerContext = Utils.merge({ id: this.id }, this.loggerContext, options.loggerContext, options.logging);
+        // the options object belongs to the caller, everything below works on our own copy
+        const opts = { ...options };
+        opts.schema ??= this.#schema;
+        opts.signal ??= this.signal;
+        opts.inflightQueryAbortStrategy ??= this.inflightQueryAbortStrategy;
+        opts.logging = opts.loggerContext = Utils.merge({ id: this.id }, this.loggerContext, opts.loggerContext, opts.logging);
+        return opts;
     }
     /**
      * @internal

package/MikroORM.d.ts

@@ -82,6 +82,10 @@ export declare class MikroORM<Driver extends IDatabaseDriver = IDatabaseDriver,
      * Closes the database connection.
      */
     close(force?: boolean): Promise<void>;
+    /**
+     * Closes the database connection, allows using the ORM instance with `await using`.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Gets the `MetadataStorage`.
      */

package/MikroORM.js

@@ -159,6 +159,12 @@ export class MikroORM {
         await this.config.getMetadataCacheAdapter()?.close?.();
         await this.config.getResultCacheAdapter()?.close?.();
     }
+    /**
+     * Closes the database connection, allows using the ORM instance with `await using`.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
     /**
      * Gets the `MetadataStorage` (without parameters) or `EntityMetadata` instance when provided with the `entityName` parameter.
      */

package/cache/CacheAdapter.d.ts

@@ -1,9 +1,10 @@
 /** Interface for async-capable cache storage used by result cache and metadata cache. */
 export interface CacheAdapter {
     /**
-     * Gets the items under `name` key from the cache.
+     * Gets the items under `name` key from the cache. When `origin` is provided, adapters that
+     * track the entry origin should ignore entries cached from a different source file.
      */
-    get<T = any>(name: string): T | Promise<T | undefined> | undefined;
+    get<T = any>(name: string, origin?: string): T | Promise<T | undefined> | undefined;
     /**
      * Sets the item to the cache. `origin` is used for cache invalidation and should reflect the change in data.
      */
@@ -24,9 +25,10 @@ export interface CacheAdapter {
 /** Synchronous variant of CacheAdapter, used for metadata cache where async access is not needed. */
 export interface SyncCacheAdapter extends CacheAdapter {
     /**
-     * Gets the items under `name` key from the cache.
+     * Gets the items under `name` key from the cache. When `origin` is provided, adapters that
+     * track the entry origin should ignore entries cached from a different source file.
      */
-    get<T = any>(name: string): T | undefined;
+    get<T = any>(name: string, origin?: string): T | undefined;
     /**
      * Sets the item to the cache. `origin` is used for cache invalidation and should reflect the change in data.
      */

package/cache/FileCacheAdapter.d.ts

@@ -8,7 +8,7 @@ export declare class FileCacheAdapter implements SyncCacheAdapter {
     /**
      * @inheritDoc
      */
-    get(name: string): any;
+    get(name: string, origin?: string): any;
     /**
      * @inheritDoc
      */

package/cache/FileCacheAdapter.js

@@ -16,12 +16,17 @@ export class FileCacheAdapter {
     /**
      * @inheritDoc
      */
-    get(name) {
+    get(name, origin) {
         const path = this.path(name);
         if (!existsSync(path)) {
             return null;
         }
         const payload = fs.readJSONSync(path);
+        // Two classes with the same name share the cache key, ignore entries cached
+        // from a different source file.
+        if (origin && fs.absolutePath(payload.origin, this.#baseDir) !== fs.absolutePath(origin, this.#baseDir)) {
+            return null;
+        }
         const hash = this.getHash(payload.origin);
         if (!hash || payload.hash !== hash) {
             return null;
@@ -71,7 +76,7 @@ export class FileCacheAdapter {
         let path = typeof this.#options.combined === 'string' ? this.#options.combined : './metadata.json';
         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));
+        writeFileSync(path, JSON.stringify(this.#cache, null, this.#pretty ? 2 : undefined), { flush: true });
         return path;
     }
     path(name) {

package/connections/Connection.d.ts

@@ -51,6 +51,13 @@ export declare abstract class Connection {
      * This method doesn't support transactions, as opposed to `orm.schema.execute()`, which is used internally.
      */
     executeDump(dump: string): Promise<void>;
+    /**
+     * Returns the underlying database client the connection drives — e.g. the `pg` pool, the
+     * `better-sqlite3` database, or the `PGlite` instance — for vendor APIs MikroORM does not wrap.
+     * Each driver narrows the return type to its own client. Its lifecycle belongs to the ORM, so
+     * leave closing it to `orm.close()` unless you supplied the client yourself via `driverOptions`.
+     */
+    getNativeClient(): Promise<unknown>;
     protected onConnect(): Promise<void>;
     /** Executes a callback inside a transaction, committing on success and rolling back on failure. */
     transactional<T>(cb: (trx: Transaction) => Promise<T>, options?: {

package/connections/Connection.js

@@ -65,6 +65,15 @@ export class Connection {
     async executeDump(dump) {
         throw new Error(`Executing SQL dumps is not supported by current driver`);
     }
+    /**
+     * Returns the underlying database client the connection drives — e.g. the `pg` pool, the
+     * `better-sqlite3` database, or the `PGlite` instance — for vendor APIs MikroORM does not wrap.
+     * Each driver narrows the return type to its own client. Its lifecycle belongs to the ORM, so
+     * leave closing it to `orm.close()` unless you supplied the client yourself via `driverOptions`.
+     */
+    async getNativeClient() {
+        throw new Error(`Accessing the native client is not supported by current driver`);
+    }
     async onConnect() {
         const schemaGenerator = this.config.getExtension('@mikro-orm/schema-generator');
         if (this.type === 'write' && schemaGenerator) {

package/drivers/DatabaseDriver.d.ts

@@ -64,6 +64,13 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
         orderBy: OrderDefinition<T>[];
         where: FilterQuery<T>;
     };
+    /**
+     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
+     * property type (never based on the string shape alone), and custom types are restored via
+     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
+     * unless the platform preserves native date types inside JSON documents (mongo).
+     */
+    private mapCursorOffset;
     protected createCursorCondition<T extends object>(definition: (readonly [keyof T & string, QueryOrder])[], offsets: Dictionary[], inverse: boolean, meta: EntityMetadata<T>): FilterQuery<T>;
     /** @internal */
     mapDataToFieldNames(data: Dictionary, stringifyJsonArrays: boolean, properties?: Record<string, EntityProperty>, convertCustomTypes?: boolean, object?: boolean): Dictionary;

package/drivers/DatabaseDriver.js

@@ -7,8 +7,11 @@ import { EntityManager } from '../EntityManager.js';
 import { CursorError, ValidationError } from '../errors.js';
 import { DriverException } from '../exceptions.js';
 import { helper } from '../entity/wrap.js';
+import { Reference } from '../entity/Reference.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
+import { DateTimeType } from '../types/DateTimeType.js';
+import { QueryHelper } from '../utils/QueryHelper.js';
 import { MikroORM } from '../MikroORM.js';
 /** Abstract base class for all database drivers, implementing common driver logic. */
 export class DatabaseDriver {
@@ -141,13 +144,24 @@ export class DatabaseDriver {
             return !!val && typeof val === 'object' && key in val;
         };
         const createCursor = (val, key, inverse = false) => {
-            let def = isCursor(val, key) ? val[key] : val;
-            if (Utils.isPlainObject(def)) {
-                def = Cursor.for(meta, def, orderBy);
+            const def = Reference.unwrapReference((isCursor(val, key) ? val[key] : val));
+            let offsets;
+            // entity (and reference) instances are supported as cursors too, their properties are read the same way
+            if (Utils.isPlainObject(def) || Utils.isEntity(def)) {
+                // POJO values are already JS values, extract them ordered per the definition,
+                // without the JSON round trip `Cursor.for` + `Cursor.decode` would impose
+                offsets = definition.map(([key]) => {
+                    if (def[key] === undefined) {
+                        throw CursorError.missingValue(meta.className, key);
+                    }
+                    return def[key];
+                });
             }
-            /* v8 ignore next */
-            const offsets = def ? Cursor.decode(def) : [];
-            if (definition.length === offsets.length) {
+            else {
+                /* v8 ignore next */
+                offsets = def ? Cursor.decode(def) : [];
+            }
+            if (definition.length > 0 && definition.length === offsets.length) {
                 return this.createCursorCondition(definition, offsets, inverse, meta);
             }
             /* v8 ignore next */
@@ -174,19 +188,67 @@ export class DatabaseDriver {
             const dir = Utils.xor(desc, isLast) ? 'desc' : 'asc';
             return { [prop]: dir };
         };
+        // the cursor condition is created at the driver level, after the EM already converted custom types
+        // in the user `where`, so we need to run the same conversion over it explicitly
+        const where = QueryHelper.processWhere({
+            where: ($and.length > 1 ? { $and } : { ...$and[0] }),
+            entityName: meta.class,
+            metadata: this.metadata,
+            platform: this.platform,
+            convertCustomTypes: options.convertCustomTypes,
+        });
         return {
             orderBy: definition.map(([prop, direction]) => createOrderBy(prop, direction)),
-            where: ($and.length > 1 ? { $and } : { ...$and[0] }),
+            where,
         };
     }
+    /**
+     * Restores the JS value of a single cursor offset: ISO strings become `Date` instances based on the
+     * property type (never based on the string shape alone), and custom types are restored via
+     * `convertToJSValue`. Values compared against a JSON document keep their serialized form instead,
+     * unless the platform preserves native date types inside JSON documents (mongo).
+     */
+    mapCursorOffset(prop, value, insideJson) {
+        if (Utils.isScalarReference(value)) {
+            value = value.unwrap();
+        }
+        // scalar direction on a relation orders by its primary key
+        if (Utils.isEntity(value, true)) {
+            value = helper(value).getPrimaryKey();
+        }
+        if (value == null) {
+            return value;
+        }
+        if (insideJson && !this.platform.preservesDatesInsideJson()) {
+            // compared against the JSON document, which holds the serialized form
+            if (value instanceof Date) {
+                return value.toISOString();
+            }
+            // restore the JS value from the serialized form, `processWhere` then converts it to
+            // the database form, which is what the JSON document holds for custom typed props
+            return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+        }
+        if (typeof value === 'string' &&
+            (prop?.runtimeType === 'Date' ||
+                (prop?.customType && this.platform.getMappedType(prop.columnTypes?.[0] ?? '') instanceof DateTimeType))) {
+            value = new Date(value);
+        }
+        return prop?.customType ? prop.customType.convertToJSValue(value, this.platform) : value;
+    }
     createCursorCondition(definition, offsets, inverse, meta) {
-        const createCondition = (prop, direction, offset, eq = false, path = prop) => {
+        const createCondition = (prop, direction, offset, eq = false, path = prop, properties = meta.properties, insideJson = false) => {
+            const propMeta = properties[prop];
             if (Utils.isPlainObject(direction)) {
                 if (offset === undefined) {
                     throw CursorError.missingValue(meta.className, path);
                 }
+                // POJO cursors can carry entity, reference or embeddable class instances, read their properties directly
+                offset = Reference.unwrapReference(offset);
+                const childProps = propMeta?.kind === ReferenceKind.EMBEDDED ? propMeta.embeddedProps : propMeta?.targetMeta?.properties;
+                insideJson ||=
+                    (propMeta?.kind === ReferenceKind.EMBEDDED && !!propMeta.object) || propMeta?.customType instanceof JsonType;
                 const value = Utils.keys(direction).reduce((o, key) => {
-                    Object.assign(o, createCondition(key, direction[key], offset?.[key], eq, `${path}.${key}`));
+                    Object.assign(o, createCondition(key, direction[key], offset?.[key], eq, `${path}.${key}`, childProps ?? {}, insideJson));
                     return o;
                 }, {});
                 return { [prop]: value };
@@ -209,6 +271,7 @@ export class DatabaseDriver {
             if (offset === undefined) {
                 throw CursorError.missingValue(meta.className, path);
             }
+            offset = this.mapCursorOffset(propMeta, offset, insideJson);
             // Handle null offset (intentional null cursor value)
             if (offset === null) {
                 if (eq) {

package/entity/EntityRepository.d.ts

@@ -1,5 +1,5 @@
 import type { PopulatePath } from '../enums.js';
-import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
+import type { CreateOptions, EntityManager, MapOptions, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
 import type { Dictionary, EntityData, EntityDictionary, EntityKey, EntityName, FilterQuery, Loaded, Primary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement, IndexFilterQuery, WithUsingOptions } from '../typings.js';
 import type { CountByOptions, CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
@@ -115,11 +115,10 @@ export declare class EntityRepository<Entity extends object> {
      */
     nativeDelete(where: FilterQuery<Entity>, options?: DeleteOptions<Entity>): Promise<number>;
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
-    map(result: EntityDictionary<Entity>, options?: {
-        schema?: string;
-    }): Entity;
+    map(result: EntityDictionary<Entity>, options?: Omit<MapOptions, 'mapped'>): Entity;
     /**
      * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
      * The key option specifies which property to use for identity map lookup instead of the primary key.

package/entity/EntityRepository.js

@@ -131,7 +131,8 @@ export class EntityRepository {
         return this.getEntityManager().nativeDelete(this.entityName, where, options);
     }
     /**
-     * Maps raw database result to an entity and merges it to this EntityManager.
+     * Maps raw database result to an entity and merges it to this EntityManager by default.
+     * Use `disableIdentityMap` to return an isolated entity without affecting the current context.
      */
     map(result, options) {
         return this.getEntityManager().map(this.entityName, result, options);

package/hydration/ObjectHydrator.js

@@ -364,6 +364,9 @@ export class ObjectHydrator extends Hydrator {
             ret.push(`    data${dataKey}.forEach((_, idx_${idx}) => {`);
             ret.push(...hydrateEmbedded(prop, [...path, `[idx_${idx}]`], `${dataKey}[idx_${idx}]`).map(l => '    ' + l));
             ret.push(`    });`);
+            ret.push(`  } else if (data${dataKey} === null) {`);
+            /* v8 ignore next */
+            ret.push(`    entity${entityKey} = ${this.config.get('forceUndefined') ? 'undefined' : 'null'};`);
             ret.push(`  }`);
             return ret;
         };

package/metadata/EntitySchema.js

@@ -4,6 +4,8 @@ import { Cascade, ReferenceKind } from '../enums.js';
 import { Type } from '../types/Type.js';
 import { Utils } from '../utils/Utils.js';
 import { EnumArrayType } from '../types/EnumArrayType.js';
+// mirrors `MetadataStorage.META_SYMBOL`, we can't import it here due to a module cycle
+const META_SYMBOL = Symbol.for('@mikro-orm/core/MetadataStorage.META_SYMBOL');
 /** Class-less entity definition that provides a programmatic API for defining entities without decorators. */
 export class EntitySchema {
     /**
@@ -220,8 +222,9 @@ export class EntitySchema {
         // Only set extends if the parent is NOT the auto-generated class for this same entity.
         // When the user extends the auto-generated class (from defineEntity without a class option)
         // and registers their custom class via setClass, we don't want to discover the
-        // auto-generated class as a separate parent entity.
-        if (base !== BaseEntity && base.name !== this._meta.className) {
+        // auto-generated class as a separate parent entity. A parent carrying its own decorator
+        // metadata is a real base class even when a minifier mangles it to the same name as the child.
+        if (base !== BaseEntity && (base.name !== this._meta.className || Object.hasOwn(base, META_SYMBOL))) {
             this._meta.extends ??= base.name ? base : undefined;
         }
     }