@mikro-orm/core 7.0.0-dev.3 → 7.0.0-dev.300

package/entity/EntityRepository.d.ts

@@ -2,7 +2,7 @@ import type { PopulatePath } from '../enums.js';
 import type { CreateOptions, EntityManager, MergeOptions } from '../EntityManager.js';
 import type { AssignOptions } from './EntityAssigner.js';
 import type { EntityData, EntityName, Primary, Loaded, FilterQuery, EntityDictionary, AutoPath, RequiredEntityData, Ref, EntityType, EntityDTO, MergeSelected, FromEntityType, IsSubset, MergeLoaded, ArrayElement } from '../typings.js';
-import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
+import type { CountOptions, DeleteOptions, FindAllOptions, FindByCursorOptions, FindOneOptions, FindOneOrFailOptions, FindOptions, GetReferenceOptions, NativeInsertUpdateOptions, StreamOptions, UpdateOptions, UpsertManyOptions, UpsertOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
 import type { Cursor } from '../utils/Cursor.js';
 export declare class EntityRepository<Entity extends object> {
@@ -80,11 +80,15 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    findByCursor<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(where: FilterQuery<Entity>, options: FindByCursorOptions<Entity, Hint, Fields, Excludes>): Promise<Cursor<Entity, Hint, Fields, Excludes>>;
+    findByCursor<Hint extends string = never, Fields extends string = '*', Excludes extends string = never, IncludeCount extends boolean = true>(options: FindByCursorOptions<Entity, Hint, Fields, Excludes, IncludeCount>): Promise<Cursor<Entity, Hint, Fields, Excludes, IncludeCount>>;
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
      */
     findAll<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: FindAllOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;
+    /**
+     * @inheritDoc EntityManager.stream
+     */
+    stream<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: StreamOptions<Entity, Hint, Fields, Excludes>): AsyncIterableIterator<Loaded<Entity, Hint, Fields, Excludes>>;
     /**
      * @inheritDoc EntityManager.insert
      */
@@ -107,10 +111,26 @@ export declare class EntityRepository<Entity extends object> {
     map(result: EntityDictionary<Entity>, options?: {
         schema?: string;
     }): Entity;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<K extends string & keyof Entity>(id: Entity[K], options: Omit<GetReferenceOptions, 'key' | 'wrapped'> & {
+        key: K;
+        wrapped: true;
+    }): Ref<Entity>;
+    /**
+     * Gets a reference to the entity identified by the given type and alternate key property without actually loading it.
+     * The key option specifies which property to use for identity map lookup instead of the primary key.
+     */
+    getReference<K extends string & keyof Entity>(id: Entity[K], options: Omit<GetReferenceOptions, 'key'> & {
+        key: K;
+        wrapped?: false;
+    }): Entity;
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: true;
     }): Ref<Entity>;
     /**
@@ -120,7 +140,7 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Gets a reference to the entity identified by the given type and identifier without actually loading it, if the entity is not yet loaded
      */
-    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped'> & {
+    getReference(id: Primary<Entity>, options: Omit<GetReferenceOptions, 'wrapped' | 'key'> & {
         wrapped: false;
     }): Entity;
     /**
@@ -130,7 +150,7 @@ export declare class EntityRepository<Entity extends object> {
     /**
      * Loads specified relations in batch. This will execute one query for each relation, that will populate it on all the specified entities.
      */
-    populate<Ent extends Entity | Entity[], Hint extends string = never, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Fields extends string = '*', Excludes extends string = never>(entities: Ent, populate: AutoPath<Naked, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Naked, Fields, Excludes>): Promise<Ent extends object[] ? MergeLoaded<ArrayElement<Ent>, Naked, Hint, Fields, Excludes>[] : MergeLoaded<Ent, Naked, Hint, Fields, Excludes>>;
+    populate<Ent extends Entity | Entity[], Hint extends string = never, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Fields extends string = never, Excludes extends string = never>(entities: Ent, populate: AutoPath<Naked, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Naked, Fields, Excludes>): Promise<Ent extends object[] ? MergeLoaded<ArrayElement<Ent>, Naked, Hint, Fields, Excludes>[] : MergeLoaded<Ent, Naked, Hint, Fields, Excludes>>;
     /**
      * Creates new instance of given entity and populates it with given data.
      * The entity constructor will be used unless you provide `{ managed: true }` in the `options` parameter.
@@ -146,13 +166,13 @@ export declare class EntityRepository<Entity extends object> {
      * The newly created entity will be automatically marked for persistence via `em.persist` unless you disable this
      * behavior, either locally via `persist: false` option, or globally via `persistOnCreate` ORM config option.
      */
-    create<Convert extends boolean = false>(data: RequiredEntityData<Entity, never, Convert>, options?: CreateOptions<Convert>): Entity;
+    create<Convert extends boolean = false, Data extends RequiredEntityData<Entity, never, Convert> = RequiredEntityData<Entity, never, Convert>>(data: Data & IsSubset<RequiredEntityData<Entity, never, Convert>, Data>, options?: CreateOptions<Convert>): Entity;
     /**
      * Creates new instance of given entity and populates it with given data.
      * The entity constructor will be used unless you provide `{ managed: true }` in the `options` parameter.
      * The constructor will be given parameters based on the defined constructor of the entity. If the constructor
      * parameter matches a property name, its value will be extracted from `data`. If no matching property exists,
-     * the whole `data` parameter will be passed. This means we can also define `constructor(data: Partial<T>)` and
+     * the whole `data` parameter will be pass. This means we can also define `constructor(data: Partial<T>)` and
      * `em.create()` will pass the data into it (unless we have a property named `data` too).
      *
      * The parameters are strictly checked, you need to provide all required properties. You can use `OptionalProps`
@@ -162,7 +182,7 @@ export declare class EntityRepository<Entity extends object> {
      * The newly created entity will be automatically marked for persistence via `em.persist` unless you disable this
      * behavior, either locally via `persist: false` option, or globally via `persistOnCreate` ORM config option.
      */
-    create<Convert extends boolean = false>(data: EntityData<Entity, Convert>, options: CreateOptions<Convert> & {
+    create<Convert extends boolean = false, Data extends EntityData<Entity, Convert> = EntityData<Entity, Convert>>(data: Data & IsSubset<EntityData<Entity, Convert>, Data>, options: CreateOptions<Convert> & {
         partial: true;
     }): Entity;
     /**

package/entity/EntityRepository.js

@@ -90,8 +90,8 @@ export class EntityRepository {
     /**
      * @inheritDoc EntityManager.findByCursor
      */
-    async findByCursor(where, options) {
-        return this.getEntityManager().findByCursor(this.entityName, where, options);
+    async findByCursor(options) {
+        return this.getEntityManager().findByCursor(this.entityName, options);
     }
     /**
      * Finds all entities of given type. You can pass additional options via the `options` parameter.
@@ -99,6 +99,12 @@ export class EntityRepository {
     async findAll(options) {
         return this.getEntityManager().findAll(this.entityName, options);
     }
+    /**
+     * @inheritDoc EntityManager.stream
+     */
+    async *stream(options) {
+        yield* this.getEntityManager().stream(this.entityName, options);
+    }
     /**
      * @inheritDoc EntityManager.insert
      */

package/entity/PolymorphicRef.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wrapper class for polymorphic relation reference data.
+ * Holds the discriminator value (type identifier) and the primary key value(s).
+ * Used internally to track polymorphic FK values before hydration.
+ */
+export declare class PolymorphicRef {
+    readonly discriminator: string;
+    id: unknown;
+    constructor(discriminator: string, id: unknown);
+    /** Returns `[discriminator, ...idValues]` tuple suitable for column-level expansion. */
+    toTuple(): unknown[];
+}

package/entity/PolymorphicRef.js

@@ -0,0 +1,18 @@
+import { Utils } from '../utils/Utils.js';
+/**
+ * Wrapper class for polymorphic relation reference data.
+ * Holds the discriminator value (type identifier) and the primary key value(s).
+ * Used internally to track polymorphic FK values before hydration.
+ */
+export class PolymorphicRef {
+    discriminator;
+    id;
+    constructor(discriminator, id) {
+        this.discriminator = discriminator;
+        this.id = id;
+    }
+    /** Returns `[discriminator, ...idValues]` tuple suitable for column-level expansion. */
+    toTuple() {
+        return [this.discriminator, ...Utils.asArray(this.id)];
+    }
+}

package/entity/Reference.d.ts

@@ -1,8 +1,8 @@
-import { inspect } from 'node:util';
-import type { AddEager, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
+import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
 import type { FindOneOptions, FindOneOrFailOptions } from '../drivers/IDatabaseDriver.js';
 export declare class Reference<T extends object> {
     private entity;
+    private property?;
     constructor(entity: T);
     static create<T extends object>(entity: T | Ref<T>): Ref<T>;
     static createFromPK<T extends object>(entityType: EntityClass<T>, pk: Primary<T>, options?: {
@@ -42,8 +42,6 @@ export declare class Reference<T extends object> {
     isInitialized(): boolean;
     populated(populated?: boolean): void;
     toJSON(...args: any[]): Dictionary;
-    /** @ignore */
-    [inspect.custom](depth?: number): string;
 }
 export declare class ScalarReference<Value> {
     private value?;
@@ -56,12 +54,15 @@ export declare class ScalarReference<Value> {
      * Returns either the whole entity, or the requested property.
      */
     load(options?: Omit<LoadReferenceOptions<any, any>, 'populate' | 'fields' | 'exclude'>): Promise<Value | undefined>;
+    /**
+     * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
+     * Returns the entity or throws an error just like `em.findOneOrFail()` (and respects the same config options).
+     */
+    loadOrFail(options?: Omit<LoadReferenceOrFailOptions<any, any>, 'populate' | 'fields' | 'exclude'>): Promise<Value>;
     set(value: Value): void;
     bind<Entity extends object>(entity: Entity, property: EntityKey<Entity>): void;
     unwrap(): Value | undefined;
     isInitialized(): boolean;
-    /** @ignore */
-    [inspect.custom](): string;
 }
 export interface LoadReferenceOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never> extends FindOneOptions<T, P, F, E> {
     dataloader?: boolean;
@@ -72,15 +73,11 @@ export interface LoadReferenceOrFailOptions<T extends object, P extends string =
 /**
  * shortcut for `wrap(entity).toReference()`
  */
-export declare function ref<T>(entity: T | Ref<T>): Ref<T> & LoadedReference<Loaded<T, AddEager<T>>>;
+export declare function ref<I extends unknown | Ref<unknown> | undefined | null, T extends I & {}>(entity: I): Ref<T> & LoadedReference<Loaded<T, AddEager<T>>> | AddOptional<typeof entity>;
 /**
  * shortcut for `Reference.createFromPK(entityType, pk)`
  */
-export declare function ref<T, PKV extends Primary<T> = Primary<T>>(entityType: EntityClass<T>, pk?: T | PKV): Ref<T>;
-/**
- * shortcut for `wrap(entity).toReference()`
- */
-export declare function ref<T>(value: T | Ref<T>): Ref<T> & LoadedReference<Loaded<T, AddEager<T>>>;
+export declare function ref<I extends unknown | undefined | null, T, PKV extends Primary<T> = Primary<T>>(entityType: EntityClass<T>, pk: I): Ref<T> | AddOptional<typeof pk>;
 /**
  * shortcut for `Reference.createNakedFromPK(entityType, pk)`
  */

package/entity/Reference.js

@@ -1,9 +1,12 @@
-import { inspect } from 'node:util';
 import { DataloaderType } from '../enums.js';
 import { helper, wrap } from './wrap.js';
 import { Utils } from '../utils/Utils.js';
+import { QueryHelper } from '../utils/QueryHelper.js';
+import { NotFoundError } from '../errors.js';
+import { inspect } from '../logging/inspect.js';
 export class Reference {
     entity;
+    property;
     constructor(entity) {
         this.entity = entity;
         this.set(entity);
@@ -33,10 +36,15 @@ export class Reference {
     }
     static createFromPK(entityType, pk, options) {
         const ref = this.createNakedFromPK(entityType, pk, options);
-        return helper(ref).toReference();
+        return helper(ref)?.toReference() ?? ref;
     }
     static createNakedFromPK(entityType, pk, options) {
         const factory = entityType.prototype.__factory;
+        if (!factory) {
+            // this can happen only if `ref()` is used as a property initializer, and the value is important only for the
+            // inference of defaults, so it's fine to return it directly without wrapping with `Reference` class
+            return pk;
+        }
         const entity = factory.createReference(entityType, pk, {
             merge: false,
             convertCustomTypes: false,
@@ -58,7 +66,9 @@ export class Reference {
      */
     static wrapReference(entity, prop) {
         if (entity && prop.ref && !Reference.isReference(entity)) {
-            return Reference.create(entity);
+            const ref = Reference.create(entity);
+            ref.property = prop;
+            return ref;
         }
         return entity;
     }
@@ -78,13 +88,14 @@ export class Reference {
         if (!wrapped.__em) {
             return this.entity;
         }
+        options = { ...options, filters: QueryHelper.mergePropertyFilters(this.property?.filters, options.filters) };
         if (this.isInitialized() && !options.refresh && options.populate) {
             await wrapped.__em.populate(this.entity, options.populate, options);
         }
         if (!this.isInitialized() || options.refresh) {
             if (options.dataloader ?? [DataloaderType.ALL, DataloaderType.REFERENCE].includes(wrapped.__em.config.getDataloaderType())) {
-                // eslint-disable-next-line dot-notation
-                return wrapped.__em['refLoader'].load([this, options]);
+                const dataLoader = await wrapped.__em.getDataLoader('ref');
+                return dataLoader.load([this, options]);
             }
             return wrapped.init(options);
         }
@@ -135,9 +146,9 @@ export class Reference {
         return wrap(this.entity).toJSON(...args);
     }
     /** @ignore */
-    [inspect.custom](depth = 2) {
+    [Symbol.for('nodejs.util.inspect.custom')](depth = 2) {
         const object = { ...this };
-        const hidden = ['meta'];
+        const hidden = ['meta', 'property'];
         hidden.forEach(k => delete object[k]);
         const ret = inspect(object, { depth });
         const wrapped = helper(this.entity);
@@ -171,6 +182,20 @@ export class ScalarReference {
         }
         return this.value;
     }
+    /**
+     * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
+     * Returns the entity or throws an error just like `em.findOneOrFail()` (and respects the same config options).
+     */
+    async loadOrFail(options = {}) {
+        const ret = await this.load(options);
+        if (ret == null) {
+            const wrapped = helper(this.entity);
+            options.failHandler ??= wrapped.__em.config.get('findOneOrFailHandler');
+            const entityName = this.entity.constructor.name;
+            throw NotFoundError.failedToLoadProperty(entityName, this.property, wrapped.getPrimaryKey());
+        }
+        return ret;
+    }
     set(value) {
         this.value = value;
         this.initialized = true;
@@ -186,9 +211,9 @@ export class ScalarReference {
     isInitialized() {
         return this.initialized;
     }
-    /* v8 ignore next 4 */
     /** @ignore */
-    [inspect.custom]() {
+    /* v8 ignore next */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.initialized ? `Ref<${inspect(this.value)}>` : `Ref<?>`;
     }
 }

package/entity/WrappedEntity.d.ts

@@ -1,7 +1,6 @@
 import type { PopulatePath } from '../enums.js';
-import { inspect } from 'node:util';
 import type { EntityManager } from '../EntityManager.js';
-import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
+import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, SerializeDTO, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
 import { Reference } from './Reference.js';
 import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
@@ -11,7 +10,6 @@ import { type SerializeOptions } from '../serialization/EntitySerializer.js';
 import type { FindOneOptions, LoadHint } from '../drivers/IDatabaseDriver.js';
 export declare class WrappedEntity<Entity extends object> {
     __initialized: boolean;
-    __touched: boolean;
     __populated?: boolean;
     __managed?: boolean;
     __onLoadFired?: boolean;
@@ -41,18 +39,17 @@ export declare class WrappedEntity<Entity extends object> {
     private readonly pkGetterConverted?;
     constructor(entity: Entity, hydrator: IHydrator, pkGetter?: (e: Entity) => Primary<Entity>, pkSerializer?: (e: Entity) => string, pkGetterConverted?: (e: Entity) => Primary<Entity>);
     isInitialized(): boolean;
-    isTouched(): boolean;
     isManaged(): boolean;
     populated(populated?: boolean | undefined): void;
     setSerializationContext<Hint extends string = never, Fields extends string = '*', Exclude extends string = never>(options: LoadHint<Entity, Hint, Fields, Exclude>): void;
     toReference(): Ref<Entity> & LoadedReference<Loaded<Entity, AddEager<Entity>>>;
     toObject<Ignored extends EntityKey<Entity> = never>(ignoreFields?: Ignored[]): Omit<EntityDTO<Entity>, Ignored>;
-    serialize<Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Entity, Hint, Exclude>): EntityDTO<Loaded<Entity, Hint>>;
+    serialize<Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Entity, Hint, Exclude>): SerializeDTO<Entity, Hint, Exclude>;
     toPOJO(): EntityDTO<Entity>;
     toJSON(...args: any[]): EntityDictionary<Entity>;
     assign<Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(data: Data & IsSubset<EntityData<Naked>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
     init<Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: FindOneOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
-    populate<Hint extends string = never>(populate: AutoPath<Entity, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Entity>): Promise<Loaded<Entity, Hint>>;
+    populate<Hint extends string = never, Fields extends string = never>(populate: AutoPath<Entity, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Entity, Fields>): Promise<Loaded<Entity, Hint>>;
     hasPrimaryKey(): boolean;
     getPrimaryKey(convertCustomTypes?: boolean): Primary<Entity> | null;
     getPrimaryKeys(convertCustomTypes?: boolean): Primary<Entity>[] | null;
@@ -64,6 +61,4 @@ export declare class WrappedEntity<Entity extends object> {
     get __platform(): import("../index.js").Platform;
     get __config(): import("../index.js").Configuration<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("../index.js").Connection>, EntityManager<import("../drivers/IDatabaseDriver.js").IDatabaseDriver<import("../index.js").Connection>>>;
     get __primaryKeys(): Primary<Entity>[];
-    /** @ignore */
-    [inspect.custom](): string;
 }

package/entity/WrappedEntity.js

@@ -1,4 +1,3 @@
-import { inspect } from 'node:util';
 import { Reference } from './Reference.js';
 import { EntityTransformer } from '../serialization/EntityTransformer.js';
 import { EntityAssigner } from './EntityAssigner.js';
@@ -15,7 +14,6 @@ export class WrappedEntity {
         this.pkSerializer = pkSerializer;
         this.pkGetterConverted = pkGetterConverted;
         this.__initialized = true;
-        this.__touched = false;
         this.__serializationContext = {};
         this.__loadedProperties = new Set();
         this.__data = {};
@@ -24,9 +22,6 @@ export class WrappedEntity {
     isInitialized() {
         return this.__initialized;
     }
-    isTouched() {
-        return this.__touched;
-    }
     isManaged() {
         return !!this.__managed;
     }
@@ -76,7 +71,7 @@ export class WrappedEntity {
         if (!this.__em) {
             throw ValidationError.entityNotManaged(this.entity);
         }
-        return this.__em.findOne(this.entity.constructor.name, this.entity, { ...options, refresh: true, schema: this.__schema });
+        return this.__em.findOne(this.entity.constructor, this.entity, { ...options, refresh: true, schema: this.__schema });
     }
     async populate(populate, options = {}) {
         if (!this.__em) {
@@ -150,10 +145,10 @@ export class WrappedEntity {
         return this.__em?.config ?? this.entity.__config;
     }
     get __primaryKeys() {
-        return Utils.getPrimaryKeyValues(this.entity, this.__meta.primaryKeys);
+        return Utils.getPrimaryKeyValues(this.entity, this.__meta);
     }
     /** @ignore */
-    [inspect.custom]() {
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         return `[WrappedEntity<${this.__meta.className}>]`;
     }
 }