@mikro-orm/core 7.0.2-dev.12 → 7.0.2-dev.14

package/entity/BaseEntity.js

@@ -2,37 +2,48 @@ import { Reference } from './Reference.js';
 import { EntityAssigner } from './EntityAssigner.js';
 import { EntitySerializer } from '../serialization/EntitySerializer.js';
 import { helper } from './wrap.js';
+/** Base class for entities providing convenience methods like `assign()`, `toObject()`, and `populate()`. */
 export class BaseEntity {
+    /** Returns whether the entity has been fully loaded from the database. */
     isInitialized() {
         return helper(this).__initialized;
     }
+    /** Marks the entity as populated or not for serialization purposes. */
     populated(populated = true) {
         helper(this).populated(populated);
     }
+    /** Loads the specified relations on this entity. */
     async populate(populate, options = {}) {
         return helper(this).populate(populate, options);
     }
+    /** Returns a Reference wrapper for this entity. */
     toReference() {
         return Reference.create(this);
     }
     toObject(ignoreFields) {
         return helper(this).toObject(ignoreFields);
     }
+    /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO() {
         return helper(this).toPOJO();
     }
+    /** Serializes the entity with control over which relations and fields to include or exclude. */
     serialize(options) {
         return EntitySerializer.serialize(this, options);
     }
+    /** Assigns the given data to this entity, updating its properties and relations. */
     assign(data, options = {}) {
         return EntityAssigner.assign(this, data, options);
     }
+    /** Initializes (refreshes) the entity by reloading it from the database. Returns null if not found. */
     init(options) {
         return helper(this).init(options);
     }
+    /** Returns the database schema this entity belongs to. */
     getSchema() {
         return helper(this).getSchema();
     }
+    /** Sets the database schema for this entity. */
     setSchema(schema) {
         helper(this).setSchema(schema);
     }

package/entity/Collection.d.ts

@@ -3,11 +3,16 @@ import { Reference } from './Reference.js';
 import type { Transaction } from '../connections/Connection.js';
 import type { CountOptions, FindOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
+/** Options for the `Collection.matching()` method to query a subset of collection items from the database. */
 export interface MatchingOptions<T extends object, P extends string = never> extends FindOptions<T, P> {
+    /** Additional filtering conditions for the query. */
     where?: FilterQuery<T>;
+    /** Whether to store the matched items in the collection (makes it read-only). */
     store?: boolean;
+    /** Transaction context for the query. */
     ctx?: Transaction;
 }
+/** Represents a to-many relation (1:m or m:n) as an iterable, managed collection of entities. */
 export declare class Collection<T extends object, O extends object = object> {
     #private;
     readonly owner: O;
@@ -32,12 +37,15 @@ export declare class Collection<T extends object, O extends object = object> {
      * The value is cached (unless you use the `where` option), use `refresh: true` to force reload it.
      */
     loadCount(options?: LoadCountOptions<T> | boolean): Promise<number>;
+    /** Queries a subset of the collection items from the database with custom filtering, ordering, and pagination. */
     matching<TT extends T, P extends string = never>(options: MatchingOptions<T, P>): Promise<Loaded<TT, P>[]>;
     /**
      * Returns the items (the collection must be initialized)
      */
     getItems(check?: boolean): T[];
+    /** Serializes the collection items to plain JSON objects. Returns an empty array if not initialized. */
     toJSON<TT extends T>(): EntityDTO<TT>[];
+    /** Adds one or more items to the collection, propagating the change to the inverse side. Returns the number of items added. */
     add<TT extends T>(entity: TT | Reference<TT> | Iterable<TT | Reference<TT>>, ...entities: (TT | Reference<TT>)[]): number;
     /**
      * Remove specified item(s) from the collection. Note that removing item from collection does not necessarily imply deleting the target entity,
@@ -46,11 +54,17 @@ export declare class Collection<T extends object, O extends object = object> {
      * 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>)[]): number;
+    /** Checks whether the collection contains the given item. */
     contains<TT extends T>(item: TT | Reference<TT>, check?: boolean): boolean;
+    /** Returns the number of items in the collection. Throws if the collection is not initialized. */
     count(): number;
+    /** Returns true if the collection has no items. Throws if the collection is not initialized. */
     isEmpty(): boolean;
+    /** Returns whether this collection should be included in serialization based on its populated state. */
     shouldPopulate(populated?: boolean): boolean;
+    /** Marks the collection as populated or not for serialization purposes. */
     populated(populated?: boolean | undefined): void;
+    /** Initializes the collection by loading its items from the database. */
     init<TT extends T, P extends string = never>(options?: InitCollectionOptions<TT, P>): Promise<LoadedCollection<Loaded<TT, P>>>;
     private getEntityManager;
     private createCondition;
@@ -63,12 +77,15 @@ export declare class Collection<T extends object, O extends object = object> {
     private reorderItems;
     private cancelOrphanRemoval;
     private validateModification;
+    /** Converts all items in the collection to plain DTO objects. */
     toArray<TT extends T>(): EntityDTO<TT>[];
+    /** Returns the primary key values (or a specific field) of all items in the collection. */
     getIdentifiers<U extends IPrimaryKey = Primary<T> & IPrimaryKey>(field?: string | string[]): U[];
     /**
      * @internal
      */
     addWithoutPropagation(entity: T): void;
+    /** Replaces all items in the collection with the given items. */
     set(items: Iterable<T | Reference<T>>): void;
     private compare;
     /**
@@ -129,8 +146,10 @@ export declare class Collection<T extends object, O extends object = object> {
      * 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]>;
+    /** Returns whether the collection has been initialized. Pass `fully = true` to also check that all items are initialized. */
     isInitialized(fully?: boolean): boolean;
     isDirty(): boolean;
+    /** Returns whether the collection was partially loaded (propagation is disabled for partial collections). */
     isPartial(): boolean;
     setDirty(dirty?: boolean): void;
     get length(): number;
@@ -157,12 +176,19 @@ export declare class Collection<T extends object, O extends object = object> {
     protected shouldPropagateToCollection(collection: Collection<O, T>, method: 'add' | 'remove' | 'takeSnapshot'): boolean;
     protected incrementCount(value: number): void;
 }
+/** Options for initializing a collection via `init()` or `load()`. */
 export interface InitCollectionOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends EntityLoaderOptions<T, F, E> {
+    /** Whether to use the dataloader for batching collection loads. */
     dataloader?: boolean;
+    /** Relations to populate on the loaded items. */
     populate?: Populate<T, P>;
+    /** Populate only references (without loading full entities). Works only with M:N collections that use pivot table. */
     ref?: boolean;
 }
+/** Options for the `Collection.loadCount()` method. */
 export interface LoadCountOptions<T extends object> extends CountOptions<T, '*'> {
+    /** Whether to reload the count from the database even if it is already cached. */
     refresh?: boolean;
+    /** Additional filtering conditions for the count query. */
     where?: FilterQuery<T>;
 }

package/entity/Collection.js

@@ -5,6 +5,7 @@ import { Reference } from './Reference.js';
 import { helper, wrap } from './wrap.js';
 import { QueryHelper } from '../utils/QueryHelper.js';
 import { inspect } from '../logging/inspect.js';
+/** Represents a to-many relation (1:m or m:n) as an iterable, managed collection of entities. */
 export class Collection {
     owner;
     #items = new Set();
@@ -91,6 +92,7 @@ export class Collection {
         }
         return count;
     }
+    /** Queries a subset of the collection items from the database with custom filtering, ordering, and pagination. */
     async matching(options) {
         const em = this.getEntityManager();
         const { where, ctx, ...opts } = options;
@@ -128,12 +130,14 @@ export class Collection {
         }
         return [...this.#items];
     }
+    /** Serializes the collection items to plain JSON objects. Returns an empty array if not initialized. */
     toJSON() {
         if (!this.isInitialized()) {
             return [];
         }
         return this.toArray();
     }
+    /** Adds one or more items to the collection, propagating the change to the inverse side. Returns the number of items added. */
     add(entity, ...entities) {
         entities = Utils.asArray(entity).concat(entities);
         const unwrapped = entities.map(i => Reference.unwrapReference(i));
@@ -203,6 +207,7 @@ export class Collection {
         }
         return removed;
     }
+    /** Checks whether the collection contains the given item. */
     contains(item, check = true) {
         if (check) {
             this.checkInitialized();
@@ -210,14 +215,17 @@ export class Collection {
         const entity = Reference.unwrapReference(item);
         return this.#items.has(entity);
     }
+    /** Returns the number of items in the collection. Throws if the collection is not initialized. */
     count() {
         this.checkInitialized();
         return this.#items.size;
     }
+    /** Returns true if the collection has no items. Throws if the collection is not initialized. */
     isEmpty() {
         this.checkInitialized();
         return this.count() === 0;
     }
+    /** Returns whether this collection should be included in serialization based on its populated state. */
     shouldPopulate(populated) {
         if (!this.isInitialized(true)) {
             return false;
@@ -227,9 +235,11 @@ export class Collection {
         }
         return !!populated;
     }
+    /** Marks the collection as populated or not for serialization purposes. */
     populated(populated = true) {
         this.#populated = populated;
     }
+    /** Initializes the collection by loading its items from the database. */
     async init(options = {}) {
         if (this.#dirty) {
             const items = [...this.#items];
@@ -377,12 +387,14 @@ export class Collection {
             throw ValidationError.cannotModifyInverseCollection(this.owner, this.property);
         }
     }
+    /** Converts all items in the collection to plain DTO objects. */
     toArray() {
         if (this.#items.size === 0) {
             return [];
         }
         return this.map(item => wrap(item).toJSON());
     }
+    /** Returns the primary key values (or a specific field) of all items in the collection. */
     getIdentifiers(field) {
         const items = this.getItems();
         const targetMeta = this.property.targetMeta;
@@ -416,6 +428,7 @@ export class Collection {
             this.#dirty = true;
         }
     }
+    /** Replaces all items in the collection with the given items. */
     set(items) {
         if (!this.#initialized) {
             this.#initialized = true;
@@ -571,6 +584,7 @@ export class Collection {
             return obj;
         }, {});
     }
+    /** Returns whether the collection has been initialized. Pass `fully = true` to also check that all items are initialized. */
     isInitialized(fully = false) {
         if (!this.#initialized || !fully) {
             return this.#initialized;
@@ -585,6 +599,7 @@ export class Collection {
     isDirty() {
         return this.#dirty;
     }
+    /** Returns whether the collection was partially loaded (propagation is disabled for partial collections). */
     isPartial() {
         return this.#partial;
     }

package/entity/EntityAssigner.d.ts

@@ -1,6 +1,8 @@
 import type { EntityManager } from '../EntityManager.js';
 import type { EntityData, EntityDTO, EntityProperty, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
+/** Handles assigning data to entities, resolving relations, and propagating changes. */
 export declare class EntityAssigner {
+    /** Assigns the given data to the entity, resolving relations and handling custom types. */
     static assign<Entity extends object, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(entity: Entity, data: Data & IsSubset<EntityData<Naked, Convert>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
     private static assignProperty;
     /**
@@ -16,6 +18,7 @@ export declare class EntityAssigner {
     private static createCollectionItem;
 }
 export declare const assign: typeof EntityAssigner.assign;
+/** Options controlling how data is assigned to an entity via `assign()`. */
 export interface AssignOptions<Convert extends boolean> {
     /**
      * Allows disabling processing of nested relations. When disabled, an object payload in place of a relation always

package/entity/EntityAssigner.js

@@ -6,7 +6,9 @@ import { validateProperty } from './validators.js';
 import { helper, wrap } from './wrap.js';
 import { EntityHelper } from './EntityHelper.js';
 import { ValidationError } from '../errors.js';
+/** Handles assigning data to entities, resolving relations, and propagating changes. */
 export class EntityAssigner {
+    /** Assigns the given data to the entity, resolving relations and handling custom types. */
     static assign(entity, data, options = {}) {
         let opts = options;
         if (opts.visited?.has(entity)) {

package/entity/EntityFactory.d.ts

@@ -1,20 +1,30 @@
 import type { EntityData, EntityMetadata, EntityName, New, Primary } from '../typings.js';
 import type { EntityManager } from '../EntityManager.js';
 import type { EntityComparator } from '../utils/EntityComparator.js';
+/** @internal Options for creating and merging entities via the EntityFactory. */
 export interface FactoryOptions {
+    /** Whether the entity should be marked as initialized. */
     initialized?: boolean;
+    /** Whether the entity is being newly created (uses constructor). */
     newEntity?: boolean;
     /**
      * Property `onCreate` hooks are normally executed during `flush` operation.
      * With this option, they will be processed early inside `em.create()` method.
      */
     processOnCreateHooksEarly?: boolean;
+    /** Whether to merge the entity into the identity map. */
     merge?: boolean;
+    /** Whether to refresh an already loaded entity with new data. */
     refresh?: boolean;
+    /** Whether to convert custom types during hydration. */
     convertCustomTypes?: boolean;
+    /** Whether to recompute the entity snapshot after creation. */
     recomputeSnapshot?: boolean;
+    /** Schema from FindOptions, overrides default schema. */
     schema?: string;
+    /** Parent entity schema for nested entity creation. */
     parentSchema?: string;
+    /** Whether to normalize accessors to the correct property names (normally handled via result mapper). */
     normalizeAccessors?: boolean;
     /**
      * Property name to use for identity map lookup instead of the primary key.
@@ -22,13 +32,19 @@ export interface FactoryOptions {
      */
     key?: string;
 }
+/** @internal Factory responsible for creating, merging, and hydrating entity instances. */
 export declare class EntityFactory {
     #private;
     constructor(em: EntityManager);
+    /** Creates a new entity instance or returns an existing one from the identity map, hydrating it with the provided data. */
     create<T extends object, P extends string = string>(entityName: EntityName<T>, data: EntityData<T>, options?: FactoryOptions): New<T, P>;
+    /** Merges new data into an existing entity, preserving user-modified properties. */
     mergeData<T extends object>(meta: EntityMetadata<T>, entity: T, data: EntityData<T>, options?: FactoryOptions): void;
+    /** Creates or retrieves an uninitialized entity reference by its primary key or alternate key. */
     createReference<T extends object>(entityName: EntityName<T>, id: Primary<T> | Primary<T>[] | Record<string, Primary<T>>, options?: Pick<FactoryOptions, 'merge' | 'convertCustomTypes' | 'schema' | 'key'>): T;
+    /** Creates an embeddable entity instance from the provided data. */
     createEmbeddable<T extends object>(entityName: EntityName<T>, data: EntityData<T>, options?: Pick<FactoryOptions, 'newEntity' | 'convertCustomTypes'>): T;
+    /** Returns the EntityComparator instance used for diffing entities. */
     getComparator(): EntityComparator;
     private createEntity;
     private assignDefaultValues;

package/entity/EntityFactory.js

@@ -5,6 +5,7 @@ import { Reference } from './Reference.js';
 import { helper } from './wrap.js';
 import { EntityHelper } from './EntityHelper.js';
 import { JsonType } from '../types/JsonType.js';
+/** @internal Factory responsible for creating, merging, and hydrating entity instances. */
 export class EntityFactory {
     #driver;
     #platform;
@@ -24,6 +25,7 @@ export class EntityFactory {
         this.#eventManager = this.#em.getEventManager();
         this.#comparator = this.#em.getComparator();
     }
+    /** Creates a new entity instance or returns an existing one from the identity map, hydrating it with the provided data. */
     create(entityName, data, options = {}) {
         data = Reference.unwrapReference(data);
         options.initialized ??= true;
@@ -108,6 +110,7 @@ export class EntityFactory {
         wrapped.__processing = false;
         return entity;
     }
+    /** Merges new data into an existing entity, preserving user-modified properties. */
     mergeData(meta, entity, data, options = {}) {
         // merge unchanged properties automatically
         data = QueryHelper.processParams(data);
@@ -181,6 +184,7 @@ export class EntityFactory {
         });
         this.unitOfWork.normalizeEntityData(meta, originalEntityData);
     }
+    /** Creates or retrieves an uninitialized entity reference by its primary key or alternate key. */
     createReference(entityName, id, options = {}) {
         options.convertCustomTypes ??= true;
         const meta = this.#metadata.get(entityName);
@@ -218,12 +222,14 @@ export class EntityFactory {
         }
         return this.create(entityName, id, { ...options, initialized: false });
     }
+    /** Creates an embeddable entity instance from the provided data. */
     createEmbeddable(entityName, data, options = {}) {
         data = { ...data };
         const meta = this.#metadata.get(entityName);
         const meta2 = this.processDiscriminatorColumn(meta, data);
         return this.createEntity(data, meta2, options);
     }
+    /** Returns the EntityComparator instance used for diffing entities. */
     getComparator() {
         return this.#comparator;
     }

package/entity/EntityLoader.d.ts

@@ -3,24 +3,42 @@ import type { EntityManager } from '../EntityManager.js';
 import { LoadStrategy, type LockMode, type PopulateHint, PopulatePath, type QueryOrderMap } from '../enums.js';
 import type { FilterOptions } from '../drivers/IDatabaseDriver.js';
 import type { LoggingOptions } from '../logging/Logger.js';
+/** Options for controlling how relations are loaded by the EntityLoader. */
 export interface EntityLoaderOptions<Entity, Fields extends string = PopulatePath.ALL, Excludes extends string = never> {
+    /** Select specific fields to load (partial loading). */
     fields?: readonly AutoPath<Entity, Fields, `${PopulatePath.ALL}`>[];
+    /** Fields to exclude from loading. */
     exclude?: readonly AutoPath<Entity, Excludes>[];
+    /** Additional filtering conditions applied to populated relations. */
     where?: FilterQuery<Entity>;
+    /** Controls how `where` conditions are applied to populated relations. */
     populateWhere?: PopulateHint | `${PopulateHint}`;
+    /** Ordering for populated relations. */
     orderBy?: QueryOrderMap<Entity> | QueryOrderMap<Entity>[];
+    /** Whether to reload already loaded entities. */
     refresh?: boolean;
+    /** Whether to validate the populate hint against the entity metadata. */
     validate?: boolean;
+    /** Whether to look up eager-loaded relationships automatically. */
     lookup?: boolean;
+    /** Whether to convert custom types during hydration. */
     convertCustomTypes?: boolean;
+    /** Whether to skip loading lazy scalar properties. */
     ignoreLazyScalarProperties?: boolean;
+    /** Filter options to apply when loading relations. */
     filters?: FilterOptions;
+    /** Loading strategy to use (select-in, joined, or balanced). */
     strategy?: LoadStrategy | `${LoadStrategy}`;
+    /** Lock mode for the query (pessimistic locking). */
     lockMode?: Exclude<LockMode, LockMode.OPTIMISTIC>;
+    /** Database schema override. */
     schema?: string;
+    /** Connection type (read or write replica). */
     connectionType?: ConnectionType;
+    /** Logging options for the query. */
     logging?: LoggingOptions;
 }
+/** Responsible for batch-loading entity relations using either select-in or joined loading strategies. */
 export declare class EntityLoader {
     #private;
     constructor(em: EntityManager);
@@ -29,6 +47,7 @@ export declare class EntityLoader {
      * This will execute one query for each relation, that will populate it on all the specified entities.
      */
     populate<Entity extends object, Fields extends string = PopulatePath.ALL>(entityName: EntityName<Entity>, entities: Entity[], populate: PopulateOptions<Entity>[] | boolean, options: EntityLoaderOptions<Entity, Fields>): Promise<void>;
+    /** Normalizes populate hints into a structured array of PopulateOptions, expanding dot paths and eager relations. */
     normalizePopulate<Entity>(entityName: EntityName<Entity>, populate: (PopulateOptions<Entity> | boolean)[] | PopulateOptions<Entity> | boolean, strategy?: LoadStrategy, lookup?: boolean, exclude?: string[]): PopulateOptions<Entity>[];
     private setSerializationContext;
     /**

package/entity/EntityLoader.js

@@ -6,6 +6,7 @@ import { Reference } from './Reference.js';
 import { helper } from './wrap.js';
 import { expandDotPaths } from './utils.js';
 import { Raw } from '../utils/RawQueryFragment.js';
+/** Responsible for batch-loading entity relations using either select-in or joined loading strategies. */
 export class EntityLoader {
     #metadata;
     #driver;
@@ -56,6 +57,7 @@ export class EntityLoader {
             visited.delete(entity);
         }
     }
+    /** Normalizes populate hints into a structured array of PopulateOptions, expanding dot paths and eager relations. */
     normalizePopulate(entityName, populate, strategy, lookup = true, exclude) {
         const meta = this.#metadata.find(entityName);
         let normalized = Utils.asArray(populate).map(field => {

package/entity/EntityRepository.d.ts

@@ -5,6 +5,7 @@ import type { EntityData, EntityName, Primary, Loaded, FilterQuery, EntityDictio
 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';
+/** Repository class providing a type-safe API for querying and persisting a specific entity type. */
 export declare class EntityRepository<Entity extends object> {
     protected readonly em: EntityManager;
     protected readonly entityName: EntityName<Entity>;
@@ -198,6 +199,7 @@ export declare class EntityRepository<Entity extends object> {
      * Returns total number of entities matching your `where` query.
      */
     count<Hint extends string = never>(where?: FilterQuery<Entity>, options?: CountOptions<Entity, Hint>): Promise<number>;
+    /** Returns the entity class name associated with this repository. */
     getEntityName(): string;
     /**
      * Returns the underlying EntityManager instance

package/entity/EntityRepository.js

@@ -1,5 +1,6 @@
 import { ValidationError } from '../errors.js';
 import { Utils } from '../utils/Utils.js';
+/** Repository class providing a type-safe API for querying and persisting a specific entity type. */
 export class EntityRepository {
     em;
     entityName;
@@ -193,6 +194,7 @@ export class EntityRepository {
     async count(where = {}, options = {}) {
         return this.getEntityManager().count(this.entityName, where, options);
     }
+    /** Returns the entity class name associated with this repository. */
     getEntityName() {
         return Utils.className(this.entityName);
     }

package/entity/Reference.d.ts

@@ -1,13 +1,17 @@
 import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
 import type { FindOneOptions, FindOneOrFailOptions } from '../drivers/IDatabaseDriver.js';
+/** Wrapper around an entity that provides lazy loading capabilities and identity-preserving reference semantics. */
 export declare class Reference<T extends object> {
     private entity;
     private property?;
     constructor(entity: T);
+    /** Creates a Reference wrapper for the given entity, preserving identity if one already exists. */
     static create<T extends object>(entity: T | Ref<T>): Ref<T>;
+    /** Creates a Reference wrapper for an entity identified by its primary key, wrapped in a Ref. */
     static createFromPK<T extends object>(entityType: EntityClass<T>, pk: Primary<T>, options?: {
         schema?: string;
     }): Ref<T>;
+    /** Creates an uninitialized entity reference by primary key without wrapping it in a Reference. */
     static createNakedFromPK<T extends object>(entityType: EntityClass<T>, pk: Primary<T>, options?: {
         schema?: string;
     }): T;
@@ -35,14 +39,22 @@ export declare class Reference<T extends object> {
      */
     loadOrFail<TT extends T, P extends string = never, F extends string = '*', E extends string = never>(options?: LoadReferenceOrFailOptions<TT, P, F, E>): Promise<Loaded<TT, P, F, E>>;
     private set;
+    /** Returns the underlying entity without checking initialization state. */
     unwrap(): T;
+    /** Returns the underlying entity, throwing an error if the reference is not initialized. */
     getEntity(): T;
+    /** Returns the value of a property on the underlying entity. Throws if the reference is not initialized. */
     getProperty<K extends keyof T>(prop: K): T[K];
+    /** Loads the entity if needed, then returns the value of the specified property. */
     loadProperty<TT extends T, P extends string = never, K extends keyof TT = keyof TT>(prop: K, options?: LoadReferenceOrFailOptions<TT, P>): Promise<Loaded<TT, P>[K]>;
+    /** Returns whether the underlying entity has been fully loaded from the database. */
     isInitialized(): boolean;
+    /** Marks the underlying entity as populated or not for serialization purposes. */
     populated(populated?: boolean): void;
+    /** Serializes the underlying entity to a plain JSON object. */
     toJSON(...args: any[]): Dictionary;
 }
+/** Wrapper for lazy scalar properties that provides on-demand loading from the database. */
 export declare class ScalarReference<Value> {
     #private;
     private value?;
@@ -58,15 +70,23 @@ export declare class ScalarReference<Value> {
      * 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>;
+    /** Sets the scalar value and marks the reference as initialized. */
     set(value: Value): void;
+    /** Binds this scalar reference to a specific entity and property for lazy loading support. */
     bind<Entity extends object>(entity: Entity, property: EntityKey<Entity>): void;
+    /** Returns the current scalar value, or undefined if not yet loaded. */
     unwrap(): Value | undefined;
+    /** Returns whether the scalar value has been loaded. */
     isInitialized(): boolean;
 }
+/** Options for `Reference.load()` to control how the referenced entity is loaded. */
 export interface LoadReferenceOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never> extends FindOneOptions<T, P, F, E> {
+    /** Whether to use the dataloader for batching reference loads. */
     dataloader?: boolean;
 }
+/** Options for `Reference.loadOrFail()` which throws when the entity is not found. */
 export interface LoadReferenceOrFailOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never> extends FindOneOrFailOptions<T, P, F, E> {
+    /** Whether to use the dataloader for batching reference loads. */
     dataloader?: boolean;
 }
 /**

package/entity/Reference.js

@@ -4,6 +4,7 @@ import { Utils } from '../utils/Utils.js';
 import { QueryHelper } from '../utils/QueryHelper.js';
 import { NotFoundError } from '../errors.js';
 import { inspect } from '../logging/inspect.js';
+/** Wrapper around an entity that provides lazy loading capabilities and identity-preserving reference semantics. */
 export class Reference {
     entity;
     property;
@@ -26,6 +27,7 @@ export class Reference {
             });
         }
     }
+    /** Creates a Reference wrapper for the given entity, preserving identity if one already exists. */
     static create(entity) {
         const unwrapped = Reference.unwrapReference(entity);
         const ref = helper(entity).toReference();
@@ -34,10 +36,12 @@ export class Reference {
         }
         return ref;
     }
+    /** Creates a Reference wrapper for an entity identified by its primary key, wrapped in a Ref. */
     static createFromPK(entityType, pk, options) {
         const ref = this.createNakedFromPK(entityType, pk, options);
         return helper(ref)?.toReference() ?? ref;
     }
+    /** Creates an uninitialized entity reference by primary key without wrapping it in a Reference. */
     static createNakedFromPK(entityType, pk, options) {
         const factory = entityType.prototype.__factory;
         if (!factory) {
@@ -121,28 +125,35 @@ export class Reference {
         this.entity = Reference.unwrapReference(entity);
         delete helper(this.entity).__reference;
     }
+    /** Returns the underlying entity without checking initialization state. */
     unwrap() {
         return this.entity;
     }
+    /** Returns the underlying entity, throwing an error if the reference is not initialized. */
     getEntity() {
         if (!this.isInitialized()) {
             throw new Error(`Reference<${helper(this.entity).__meta.name}> ${helper(this.entity).getPrimaryKey()} not initialized`);
         }
         return this.entity;
     }
+    /** Returns the value of a property on the underlying entity. Throws if the reference is not initialized. */
     getProperty(prop) {
         return this.getEntity()[prop];
     }
+    /** Loads the entity if needed, then returns the value of the specified property. */
     async loadProperty(prop, options) {
         await this.loadOrFail(options);
         return this.getEntity()[prop];
     }
+    /** Returns whether the underlying entity has been fully loaded from the database. */
     isInitialized() {
         return helper(this.entity).__initialized;
     }
+    /** Marks the underlying entity as populated or not for serialization purposes. */
     populated(populated) {
         helper(this.entity).populated(populated);
     }
+    /** Serializes the underlying entity to a plain JSON object. */
     toJSON(...args) {
         return wrap(this.entity).toJSON(...args);
     }
@@ -160,6 +171,7 @@ export class Reference {
         return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
     }
 }
+/** Wrapper for lazy scalar properties that provides on-demand loading from the database. */
 export class ScalarReference {
     value;
     entity;
@@ -197,18 +209,22 @@ export class ScalarReference {
         }
         return ret;
     }
+    /** Sets the scalar value and marks the reference as initialized. */
     set(value) {
         this.value = value;
         this.#initialized = true;
     }
+    /** Binds this scalar reference to a specific entity and property for lazy loading support. */
     bind(entity, property) {
         this.entity = entity;
         this.#property = property;
         Object.defineProperty(this, 'entity', { enumerable: false, value: entity });
     }
+    /** Returns the current scalar value, or undefined if not yet loaded. */
     unwrap() {
         return this.value;
     }
+    /** Returns whether the scalar value has been loaded. */
     isInitialized() {
         return this.#initialized;
     }