@mikro-orm/core 7.0.0-dev.33 → 7.0.0-dev.331

package/entity/BaseEntity.d.ts

@@ -1,20 +1,79 @@
 import { type Ref } from './Reference.js';
-import type { AutoPath, EntityData, EntityDTO, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
+import type { AutoPath, EntityData, EntityDTO, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected, SerializeDTO } from '../typings.js';
 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, Fields extends string = never>(populate: AutoPath<Entity, Hint, PopulatePath.ALL>[] | false, options?: EntityLoaderOptions<Entity, Fields>): 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>>;
+    serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude>): SerializeDTO<Naked, Hint, Exclude>;
     assign<Entity extends this, 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<Entity extends this = this, Hint extends string = never, Fields extends string = '*', Excludes extends string = never>(options?: FindOneOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
     getSchema(): string | undefined;

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

package/entity/Collection.d.ts

@@ -1,5 +1,4 @@
-import type { EntityDTO, EntityKey, FilterQuery, Loaded, LoadedCollection, Populate } from '../typings.js';
-import { ArrayCollection } from './ArrayCollection.js';
+import type { EntityDTO, EntityKey, EntityProperty, FilterQuery, IPrimaryKey, Loaded, LoadedCollection, Populate, Primary } from '../typings.js';
 import { Reference } from './Reference.js';
 import type { Transaction } from '../connections/Connection.js';
 import type { CountOptions, FindOptions } from '../drivers/IDatabaseDriver.js';
@@ -9,10 +8,10 @@ export interface MatchingOptions<T extends object, P extends string = never> ext
     store?: boolean;
     ctx?: Transaction;
 }
-export declare class Collection<T extends object, O extends object = object> extends ArrayCollection<T, O> {
-    private readonly?;
-    private _populated?;
-    private _snapshot?;
+export declare class Collection<T extends object, O extends object = object> {
+    #private;
+    readonly owner: O;
+    [k: number]: T;
     constructor(owner: O, items?: T[], initialized?: boolean);
     /**
      * Creates new Collection instance, assigns it to the owning entity and sets the items to it (propagating them to their inverse sides)
@@ -39,59 +38,124 @@ export declare class Collection<T extends object, O extends object = object> ext
      */
     getItems(check?: boolean): T[];
     toJSON<TT extends T>(): EntityDTO<TT>[];
-    add<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>>, ...entities: (TT | Reference<TT>)[]): void;
+    add<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>>, ...entities: (TT | Reference<TT>)[]): number;
     /**
-     * @inheritDoc
+     * Remove specified item(s) from the collection. Note that removing item from collection does not necessarily imply deleting the target entity,
+     * it means we are disconnecting the relation - removing items from collection, not removing entities from database - `Collection.remove()`
+     * is not the same as `em.remove()`. If we want to delete the entity by removing it from collection, we need to enable `orphanRemoval: true`,
+     * which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.
      */
-    remove<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>> | ((item: TT) => boolean), ...entities: (TT | Reference<TT>)[]): void;
+    remove<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>> | ((item: TT) => boolean), ...entities: (TT | Reference<TT>)[]): number;
     contains<TT extends T>(item: TT | Reference<TT>, check?: boolean): boolean;
     count(): number;
     isEmpty(): boolean;
+    shouldPopulate(populated?: boolean): boolean;
+    populated(populated?: boolean | undefined): void;
+    init<TT extends T, P extends string = never>(options?: InitCollectionOptions<TT, P>): Promise<LoadedCollection<Loaded<TT, P>>>;
+    private getEntityManager;
+    private createCondition;
+    private createManyToManyCondition;
+    private createLoadCountCondition;
+    private checkInitialized;
     /**
-     * @inheritDoc
+     * re-orders items after searching with `$in` operator
+     */
+    private reorderItems;
+    private cancelOrphanRemoval;
+    private validateModification;
+    toArray<TT extends T>(): EntityDTO<TT>[];
+    getIdentifiers<U extends IPrimaryKey = Primary<T> & IPrimaryKey>(field?: string | string[]): U[];
+    /**
+     * @internal
+     */
+    addWithoutPropagation(entity: T): void;
+    set(items: Iterable<T | Reference<T>>): void;
+    private compare;
+    /**
+     * @internal
+     */
+    hydrate(items: T[], forcePropagate?: boolean, partial?: boolean): void;
+    /**
+     * Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity,
+     * it means we are disconnecting the relation - removing items from collection, not removing entities from database - `Collection.remove()`
+     * is not the same as `em.remove()`. If we want to delete the entity by removing it from collection, we need to enable `orphanRemoval: true`,
+     * which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.
+     */
+    removeAll(): void;
+    /**
+     * @internal
+     */
+    removeWithoutPropagation(entity: T): void;
+    /**
+     * Extracts a slice of the collection items starting at position start to end (exclusive) of the collection.
+     * If end is null it returns all elements from start to the end of the collection.
      */
     slice(start?: number, end?: number): T[];
     /**
-     * @inheritDoc
+     * Tests for the existence of an element that satisfies the given predicate.
      */
     exists(cb: (item: T) => boolean): boolean;
     /**
-     * @inheritDoc
+     * Returns the first element of this collection that satisfies the predicate.
+     */
+    find<S extends T>(cb: (item: T, index: number) => item is S): S | undefined;
+    /**
+     * Returns the first element of this collection that satisfies the predicate.
      */
     find(cb: (item: T, index: number) => boolean): T | undefined;
     /**
-     * @inheritDoc
+     * Extracts a subset of the collection items.
+     */
+    filter<S extends T>(cb: (item: T, index: number) => item is S): S[];
+    /**
+     * Extracts a subset of the collection items.
      */
     filter(cb: (item: T, index: number) => boolean): T[];
     /**
-     * @inheritDoc
+     * Maps the collection items based on your provided mapper function.
      */
     map<R>(mapper: (item: T, index: number) => R): R[];
     /**
-     * @inheritDoc
+     * Maps the collection items based on your provided mapper function to a single object.
+     */
+    reduce<R>(cb: (obj: R, item: T, index: number) => R, initial?: R): R;
+    /**
+     * Maps the collection items to a dictionary, indexed by the key you specify.
+     * If there are more items with the same key, only the first one will be present.
      */
     indexBy<K1 extends keyof T, K2 extends keyof T = never>(key: K1): Record<T[K1] & PropertyKey, T>;
     /**
-     * @inheritDoc
+     * Maps the collection items to a dictionary, indexed by the key you specify.
+     * If there are more items with the same key, only the first one will be present.
      */
     indexBy<K1 extends keyof T, K2 extends keyof T = never>(key: K1, valueKey: K2): Record<T[K1] & PropertyKey, T[K2]>;
-    shouldPopulate(populated?: boolean): boolean;
-    populated(populated?: boolean | undefined): void;
-    init<TT extends T, P extends string = never>(options?: InitCollectionOptions<TT, P>): Promise<LoadedCollection<Loaded<TT, P>>>;
-    private getEntityManager;
-    private createCondition;
-    private createOrderBy;
-    private createManyToManyCondition;
-    private createLoadCountCondition;
-    private modify;
-    private checkInitialized;
+    isInitialized(fully?: boolean): boolean;
+    isDirty(): boolean;
+    isPartial(): boolean;
+    setDirty(dirty?: boolean): void;
+    get length(): number;
+    [Symbol.iterator](): IterableIterator<T>;
     /**
-     * re-orders items after searching with `$in` operator
+     * @internal
      */
-    private reorderItems;
-    private cancelOrphanRemoval;
-    private validateItemType;
-    private validateModification;
+    takeSnapshot(forcePropagate?: boolean): void;
+    /**
+     * @internal
+     */
+    getSnapshot(): T[] | undefined;
+    /**
+     * @internal
+     */
+    get property(): EntityProperty;
+    /**
+     * @internal
+     */
+    set property(prop: EntityProperty);
+    protected propagate(item: T, method: 'add' | 'remove' | 'takeSnapshot'): void;
+    protected propagateToInverseSide(item: T, method: 'add' | 'remove' | 'takeSnapshot'): void;
+    protected propagateToOwningSide(item: T, method: 'add' | 'remove' | 'takeSnapshot'): void;
+    protected shouldPropagateToCollection(collection: Collection<O, T>, method: 'add' | 'remove' | 'takeSnapshot'): boolean;
+    protected incrementCount(value: number): void;
 }
 export interface InitCollectionOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends EntityLoaderOptions<T, F, E> {
     dataloader?: boolean;