@mikro-orm/core 7.0.2-dev.9 → 7.0.3-dev.0

package/connections/Connection.d.ts

@@ -5,6 +5,7 @@ import type { ConnectionType, Dictionary, MaybePromise, Primary } from '../typin
 import type { Platform } from '../platforms/Platform.js';
 import type { TransactionEventBroadcaster } from '../events/TransactionEventBroadcaster.js';
 import type { IsolationLevel } from '../enums.js';
+/** Abstract base class for database connections, providing transaction and query execution support. */
 export declare abstract class Connection {
     #private;
     protected readonly config: Configuration;
@@ -49,6 +50,7 @@ export declare abstract class Connection {
      */
     executeDump(dump: string): Promise<void>;
     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?: {
         isolationLevel?: IsolationLevel | `${IsolationLevel}`;
         readOnly?: boolean;
@@ -56,6 +58,7 @@ export declare abstract class Connection {
         eventBroadcaster?: TransactionEventBroadcaster;
         loggerContext?: LogContext;
     }): Promise<T>;
+    /** Begins a new database transaction and returns the transaction context. */
     begin(options?: {
         isolationLevel?: IsolationLevel | `${IsolationLevel}`;
         readOnly?: boolean;
@@ -63,16 +66,24 @@ export declare abstract class Connection {
         eventBroadcaster?: TransactionEventBroadcaster;
         loggerContext?: LogContext;
     }): Promise<Transaction>;
+    /** Commits the given transaction. */
     commit(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
+    /** Rolls back the given transaction. */
     rollback(ctx: Transaction, eventBroadcaster?: TransactionEventBroadcaster, loggerContext?: LogContext): Promise<void>;
+    /** Executes a raw query and returns the result. */
     abstract execute<T>(query: string, params?: any[], method?: 'all' | 'get' | 'run', ctx?: Transaction): Promise<QueryResult<T> | any | any[]>;
+    /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
     getConnectionOptions(): ConnectionConfig;
+    /** Sets the metadata storage on this connection. */
     setMetadata(metadata: MetadataStorage): void;
+    /** Sets the platform abstraction on this connection. */
     setPlatform(platform: Platform): void;
+    /** Returns the platform abstraction for this connection. */
     getPlatform(): Platform;
     protected executeQuery<T>(query: string, cb: () => Promise<T>, context?: LogContext): Promise<T>;
     protected logQuery(query: string, context?: LogContext): void;
 }
+/** Result of a native database query (insert, update, delete). */
 export interface QueryResult<T = {
     id: number;
 }> {
@@ -82,6 +93,7 @@ export interface QueryResult<T = {
     rows?: Dictionary[];
     insertedIds?: Primary<T>[];
 }
+/** Resolved database connection parameters. */
 export interface ConnectionConfig {
     host?: string;
     port?: number;
@@ -90,4 +102,5 @@ export interface ConnectionConfig {
     database?: string;
     schema?: string;
 }
+/** Opaque transaction context type, wrapping the driver-specific transaction object. */
 export type Transaction<T = any> = T & {};

package/connections/Connection.js

@@ -1,4 +1,5 @@
 import { Utils } from '../utils/Utils.js';
+/** Abstract base class for database connections, providing transaction and query execution support. */
 export class Connection {
     config;
     type;
@@ -75,18 +76,23 @@ export class Connection {
             }
         }
     }
+    /** Executes a callback inside a transaction, committing on success and rolling back on failure. */
     async transactional(cb, options) {
         throw new Error(`Transactions are not supported by current driver`);
     }
+    /** Begins a new database transaction and returns the transaction context. */
     async begin(options) {
         throw new Error(`Transactions are not supported by current driver`);
     }
+    /** Commits the given transaction. */
     async commit(ctx, eventBroadcaster, loggerContext) {
         throw new Error(`Transactions are not supported by current driver`);
     }
+    /** Rolls back the given transaction. */
     async rollback(ctx, eventBroadcaster, loggerContext) {
         throw new Error(`Transactions are not supported by current driver`);
     }
+    /** Parses and returns the resolved connection configuration (host, port, user, etc.). */
     getConnectionOptions() {
         const ret = {};
         if (this.options.clientUrl) {
@@ -113,12 +119,15 @@ export class Connection {
         }
         return ret;
     }
+    /** Sets the metadata storage on this connection. */
     setMetadata(metadata) {
         this.metadata = metadata;
     }
+    /** Sets the platform abstraction on this connection. */
     setPlatform(platform) {
         this.platform = platform;
     }
+    /** Returns the platform abstraction for this connection. */
     getPlatform() {
         return this.platform;
     }

package/drivers/DatabaseDriver.d.ts

@@ -10,6 +10,7 @@ import type { Collection } from '../entity/Collection.js';
 import { EntityManager } from '../EntityManager.js';
 import { DriverException } from '../exceptions.js';
 import { MikroORM } from '../MikroORM.js';
+/** Abstract base class for all database drivers, implementing common driver logic. */
 export declare abstract class DatabaseDriver<C extends Connection> implements IDatabaseDriver<C> {
     readonly config: Configuration;
     protected readonly dependencies: string[];
@@ -28,24 +29,34 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
     abstract nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: DeleteOptions<T>): Promise<QueryResult<T>>;
     abstract count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
+    /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];
     findVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
     countVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: CountOptions<T, any>): Promise<number>;
     aggregate(entityName: EntityName, pipeline: any[]): Promise<any[]>;
     loadFromPivotTable<T extends object, O extends object>(prop: EntityProperty, owners: Primary<O>[][], where?: FilterQuery<any>, orderBy?: OrderDefinition<T>, ctx?: Transaction, options?: FindOptions<T, any, any, any>, pivotJoin?: boolean): Promise<Dictionary<T[]>>;
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
+    /** Maps raw database result to entity data, converting column names to property names. */
     mapResult<T extends object>(result: EntityDictionary<T>, meta?: EntityMetadata<T>, populate?: PopulateOptions<T>[]): EntityData<T> | null;
+    /** Opens the primary connection and all read replicas. */
     connect(options?: {
         skipOnConnect?: boolean;
     }): Promise<C>;
+    /** Closes all connections and re-establishes them. */
     reconnect(options?: {
         skipOnConnect?: boolean;
     }): Promise<C>;
+    /** Returns the write connection or a random read replica. */
     getConnection(type?: ConnectionType): C;
+    /** Closes the primary connection and all read replicas. */
     close(force?: boolean): Promise<void>;
+    /** Returns the database platform abstraction for this driver. */
     getPlatform(): Platform;
+    /** Sets the metadata storage and initializes the comparator for all connections. */
     setMetadata(metadata: MetadataStorage): void;
+    /** Returns the metadata storage used by this driver. */
     getMetadata(): MetadataStorage;
+    /** Returns the names of native database dependencies required by this driver. */
     getDependencies(): string[];
     protected isPopulated<T extends object>(meta: EntityMetadata<T>, prop: EntityProperty<T>, hint: PopulateOptions<T>, name?: string): boolean;
     protected processCursorOptions<T extends object, P extends string>(meta: EntityMetadata<T>, options: FindOptions<T, P, any, any>, orderBy: OrderDefinition<T>): {
@@ -58,6 +69,7 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     protected inlineEmbeddables<T extends object>(meta: EntityMetadata<T>, data: T, where?: boolean): void;
     protected getPrimaryKeyFields<T>(meta: EntityMetadata<T>): string[];
     protected createReplicas(cb: (c: ConnectionOptions) => C): C[];
+    /** Acquires a pessimistic lock on the given entity. */
     lockPessimistic<T extends object>(entity: T, options: LockOptions): Promise<void>;
     abstract stream<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: StreamOptions<T>): AsyncIterableIterator<T>;
     /**

package/drivers/DatabaseDriver.js

@@ -11,6 +11,7 @@ import { helper } from '../entity/wrap.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { JsonType } from '../types/JsonType.js';
 import { MikroORM } from '../MikroORM.js';
+/** Abstract base class for all database drivers, implementing common driver logic. */
 export class DatabaseDriver {
     config;
     dependencies;
@@ -27,6 +28,7 @@ export class DatabaseDriver {
     async nativeUpdateMany(entityName, where, data, options) {
         throw new Error(`Batch updates are not supported by ${this.constructor.name} driver`);
     }
+    /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext) {
         const EntityManagerClass = this.config.get('entityManager', EntityManager);
         return new EntityManagerClass(this.config, this, this.metadata, useContext);
@@ -62,22 +64,26 @@ export class DatabaseDriver {
             }
         }
     }
+    /** Maps raw database result to entity data, converting column names to property names. */
     mapResult(result, meta, populate = []) {
         if (!result || !meta) {
             return result ?? null;
         }
         return this.comparator.mapResult(meta, result);
     }
+    /** Opens the primary connection and all read replicas. */
     async connect(options) {
         await this.connection.connect(options);
         await Promise.all(this.replicas.map(replica => replica.connect()));
         return this.connection;
     }
+    /** Closes all connections and re-establishes them. */
     async reconnect(options) {
         await this.close(true);
         await this.connect(options);
         return this.connection;
     }
+    /** Returns the write connection or a random read replica. */
     getConnection(type = 'write') {
         if (type === 'write' || this.replicas.length === 0) {
             return this.connection;
@@ -85,13 +91,16 @@ export class DatabaseDriver {
         const rand = Utils.randomInt(0, this.replicas.length - 1);
         return this.replicas[rand];
     }
+    /** Closes the primary connection and all read replicas. */
     async close(force) {
         await Promise.all(this.replicas.map(replica => replica.close(force)));
         await this.connection.close(force);
     }
+    /** Returns the database platform abstraction for this driver. */
     getPlatform() {
         return this.platform;
     }
+    /** Sets the metadata storage and initializes the comparator for all connections. */
     setMetadata(metadata) {
         this.metadata = metadata;
         this.comparator = new EntityComparator(this.metadata, this.platform);
@@ -102,9 +111,11 @@ export class DatabaseDriver {
             replica.setPlatform(this.platform);
         });
     }
+    /** Returns the metadata storage used by this driver. */
     getMetadata() {
         return this.metadata;
     }
+    /** Returns the names of native database dependencies required by this driver. */
     getDependencies() {
         return this.dependencies;
     }
@@ -426,6 +437,7 @@ export class DatabaseDriver {
         }
         return ret;
     }
+    /** Acquires a pessimistic lock on the given entity. */
     async lockPessimistic(entity, options) {
         throw new Error(`Pessimistic locks are not supported by ${this.constructor.name} driver`);
     }

package/drivers/IDatabaseDriver.d.ts

@@ -10,18 +10,25 @@ import type { Configuration } from '../utils/Configuration.js';
 import type { MikroORM } from '../MikroORM.js';
 import type { LoggingOptions, LogContext } from '../logging/Logger.js';
 import type { Raw } from '../utils/RawQueryFragment.js';
+/** Symbol used to extract the EntityManager type from a driver instance. */
 export declare const EntityManagerType: unique symbol;
+/** Interface defining the contract for all database drivers. */
 export interface IDatabaseDriver<C extends Connection = Connection> {
     [EntityManagerType]: EntityManager<this>;
     readonly config: Configuration;
+    /** Creates a new EntityManager instance for this driver. */
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];
+    /** Opens a connection to the database. */
     connect(options?: {
         skipOnConnect?: boolean;
     }): Promise<C>;
+    /** Closes the database connection. */
     close(force?: boolean): Promise<void>;
+    /** Closes and re-establishes the database connection. */
     reconnect(options?: {
         skipOnConnect?: boolean;
     }): Promise<C>;
+    /** Returns the underlying database connection (write or read replica). */
     getConnection(type?: ConnectionType): C;
     /**
      * Finds selection of entities
@@ -31,29 +38,44 @@ export interface IDatabaseDriver<C extends Connection = Connection> {
      * Finds single entity (table row, document)
      */
     findOne<T extends object, P extends string = never, F extends string = '*', E extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: FindOneOptions<T, P, F, E>): Promise<EntityData<T> | null>;
+    /** Finds entities backed by a virtual (expression-based) definition. */
     findVirtual<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: FindOptions<T, any, any, any>): Promise<EntityData<T>[]>;
+    /** Returns an async iterator that streams query results one entity at a time. */
     stream<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options: StreamOptions<T>): AsyncIterableIterator<T>;
+    /** Inserts a single row into the database. */
     nativeInsert<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    /** Inserts multiple rows into the database in a single batch operation. */
     nativeInsertMany<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
+    /** Updates rows matching the given condition. */
     nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
+    /** Updates multiple rows with different payloads in a single batch operation. */
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
+    /** Deletes rows matching the given condition. */
     nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: NativeDeleteOptions<T>): Promise<QueryResult<T>>;
+    /** Persists changes to M:N collections (inserts/deletes pivot table rows). */
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
+    /** Counts entities matching the given condition. */
     count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
+    /** Executes a MongoDB aggregation pipeline (MongoDB driver only). */
     aggregate(entityName: EntityName, pipeline: any[]): Promise<any[]>;
+    /** Maps raw database result to entity data, converting column names to property names. */
     mapResult<T extends object>(result: EntityDictionary<T>, meta: EntityMetadata<T>, populate?: PopulateOptions<T>[]): EntityData<T> | null;
     /**
      * When driver uses pivot tables for M:N, this method will load identifiers for given collections from them
      */
     loadFromPivotTable<T extends object, O extends object>(prop: EntityProperty, owners: Primary<O>[][], where?: FilterQuery<T>, orderBy?: OrderDefinition<T>, ctx?: Transaction, options?: FindOptions<T, any, any, any>, pivotJoin?: boolean): Promise<Dictionary<T[]>>;
+    /** Returns the database platform abstraction for this driver. */
     getPlatform(): Platform;
+    /** Sets the metadata storage used by this driver. */
     setMetadata(metadata: MetadataStorage): void;
+    /** Returns the metadata storage used by this driver. */
     getMetadata(): MetadataStorage;
     /**
      * Returns name of the underlying database dependencies (e.g. `mongodb` or `mysql2`)
      * for SQL drivers it also returns `knex` in the array as connectors are not used directly there
      */
     getDependencies(): string[];
+    /** Acquires a pessimistic lock on the given entity. */
     lockPessimistic<T extends object>(entity: T, options: LockOptions): Promise<void>;
     /**
      * Converts native db errors to standardized driver exceptions
@@ -71,13 +93,17 @@ export interface IDatabaseDriver<C extends Connection = Connection> {
      */
     getORMClass(): Constructor<MikroORM>;
 }
+/** Represents a field selector for entity queries (property name or wildcard). */
 export type EntityField<T, P extends string = PopulatePath.ALL> = keyof T | PopulatePath.ALL | AutoPath<T, P, `${PopulatePath.ALL}`>;
+/** Defines the ordering for query results, either a single order map or an array of them. */
 export type OrderDefinition<T> = (QueryOrderMap<T> & {
     0?: never;
 }) | QueryOrderMap<T>[];
+/** Options for `em.findAll()`, extends FindOptions with an optional `where` clause. */
 export interface FindAllOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends FindOptions<T, P, F, E> {
     where?: FilterQuery<T>;
 }
+/** Options for streaming query results via `em.stream()`. */
 export interface StreamOptions<Entity, Populate extends string = never, Fields extends string = '*', Exclude extends string = never> extends Omit<FindAllOptions<Entity, Populate, Fields, Exclude>, 'cache' | 'before' | 'after' | 'first' | 'last' | 'overfetch' | 'strategy'> {
     /**
      * When populating to-many relations, the ORM streams fully merged entities instead of yielding every row.
@@ -90,12 +116,15 @@ export interface StreamOptions<Entity, Populate extends string = never, Fields e
      */
     mergeResults?: boolean;
 }
+/** Configuration for enabling/disabling named filters on a query. */
 export type FilterOptions = Dictionary<boolean | Dictionary> | string[] | boolean;
+/** Specifies which relations to populate and which fields to select or exclude. */
 export interface LoadHint<Entity, Hint extends string = never, Fields extends string = PopulatePath.ALL, Excludes extends string = never> {
     populate?: Populate<Entity, Hint>;
     fields?: readonly AutoPath<Entity, Fields, `${PopulatePath.ALL}`>[];
     exclude?: readonly AutoPath<Entity, Excludes>[];
 }
+/** Options for `em.find()` queries, including population, ordering, pagination, and locking. */
 export interface FindOptions<Entity, Hint extends string = never, Fields extends string = PopulatePath.ALL, Excludes extends string = never> extends LoadHint<Entity, Hint, Fields, Excludes> {
     /**
      * Where condition for populated relations. This will have no effect on the root entity.
@@ -197,17 +226,21 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     /** @internal used to apply filters to the auto-joined relations */
     em?: EntityManager;
 }
+/** Options for cursor-based pagination via `em.findByCursor()`. */
 export interface FindByCursorOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never, I extends boolean = true> extends Omit<FindAllOptions<T, P, F, E>, 'limit' | 'offset'> {
     includeCount?: I;
 }
+/** Options for `em.findOne()`, extends FindOptions with optimistic lock version support. */
 export interface FindOneOptions<T, P extends string = never, F extends string = '*', E extends string = never> extends Omit<FindOptions<T, P, F, E>, 'limit' | 'lockMode'> {
     lockMode?: LockMode;
     lockVersion?: number | Date;
 }
+/** Options for `em.findOneOrFail()`, adds a custom error handler for missing entities. */
 export interface FindOneOrFailOptions<T extends object, P extends string = never, F extends string = '*', E extends string = never> extends FindOneOptions<T, P, F, E> {
     failHandler?: (entityName: string, where: Dictionary | IPrimaryKey | any) => Error;
     strict?: boolean;
 }
+/** Options for native insert and update operations. */
 export interface NativeInsertUpdateOptions<T> {
     convertCustomTypes?: boolean;
     ctx?: Transaction;
@@ -223,9 +256,11 @@ export interface NativeInsertUpdateOptions<T> {
     /** @internal */
     em?: EntityManager;
 }
+/** Options for batch native insert and update operations. */
 export interface NativeInsertUpdateManyOptions<T> extends NativeInsertUpdateOptions<T> {
     processCollections?: boolean;
 }
+/** Options for `em.upsert()`, controlling conflict resolution behavior. */
 export interface UpsertOptions<Entity, Fields extends string = never> extends Omit<NativeInsertUpdateOptions<Entity>, 'upsert'> {
     onConflictFields?: (keyof Entity)[] | Raw;
     onConflictAction?: 'ignore' | 'merge';
@@ -234,9 +269,11 @@ export interface UpsertOptions<Entity, Fields extends string = never> extends Om
     onConflictWhere?: FilterQuery<Entity>;
     disableIdentityMap?: boolean;
 }
+/** Options for `em.upsertMany()`, adds batch size control. */
 export interface UpsertManyOptions<Entity, Fields extends string = never> extends UpsertOptions<Entity, Fields> {
     batchSize?: number;
 }
+/** Options for `em.count()` queries. */
 export interface CountOptions<T extends object, P extends string = never> {
     filters?: FilterOptions;
     schema?: string;
@@ -268,6 +305,7 @@ export interface CountOptions<T extends object, P extends string = never> {
     /** @internal used to apply filters to the auto-joined relations */
     em?: EntityManager;
 }
+/** Options for `em.qb().update()` operations. */
 export interface UpdateOptions<T> {
     filters?: FilterOptions;
     schema?: string;
@@ -277,6 +315,7 @@ export interface UpdateOptions<T> {
     /** sql only */
     unionWhereStrategy?: 'union-all' | 'union';
 }
+/** Options for `em.qb().delete()` operations. */
 export interface DeleteOptions<T> extends DriverMethodOptions {
     filters?: FilterOptions;
     /** sql only */
@@ -286,6 +325,7 @@ export interface DeleteOptions<T> extends DriverMethodOptions {
     /** @internal */
     em?: EntityManager;
 }
+/** Options for `em.nativeDelete()` operations. */
 export interface NativeDeleteOptions<T> extends DriverMethodOptions {
     filters?: FilterOptions;
     /** sql only */
@@ -295,17 +335,20 @@ export interface NativeDeleteOptions<T> extends DriverMethodOptions {
     /** @internal */
     em?: EntityManager;
 }
+/** Options for pessimistic and optimistic lock operations. */
 export interface LockOptions extends DriverMethodOptions {
     lockMode?: LockMode;
     lockVersion?: number | Date;
     lockTableAliases?: string[];
     logging?: LoggingOptions;
 }
+/** Base options shared by all driver methods (transaction context, schema, logging). */
 export interface DriverMethodOptions {
     ctx?: Transaction;
     schema?: string;
     loggerContext?: LogContext;
 }
+/** MongoDB-style collation options for locale-aware string comparison. */
 export interface CollationOptions {
     locale: string;
     caseLevel?: boolean;
@@ -316,6 +359,7 @@ export interface CollationOptions {
     maxVariable?: string;
     backwards?: boolean;
 }
+/** Options for `em.getReference()`, controlling wrapping and type conversion. */
 export interface GetReferenceOptions {
     wrapped?: boolean;
     convertCustomTypes?: boolean;

package/drivers/IDatabaseDriver.js

@@ -1 +1,2 @@
+/** Symbol used to extract the EntityManager type from a driver instance. */
 export const EntityManagerType = Symbol('EntityManagerType');

package/entity/BaseEntity.d.ts

@@ -5,10 +5,15 @@ 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';
+/** Base class for entities providing convenience methods like `assign()`, `toObject()`, and `populate()`. */
 export declare abstract class BaseEntity {
+    /** Returns whether the entity has been fully loaded from the database. */
     isInitialized(): boolean;
+    /** Marks the entity as populated or not for serialization purposes. */
     populated(populated?: boolean): void;
+    /** Loads the specified relations on this entity. */
     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>>;
+    /** Returns a Reference wrapper for this entity. */
     toReference<Entity extends this = this>(): Ref<Entity> & LoadedReference<Loaded<Entity, AddEager<Entity>>>;
     /**
      * Converts the entity to a plain object representation.
@@ -72,10 +77,16 @@ export declare abstract class BaseEntity {
      * @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>;
+    /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO<Entity extends this = this>(): EntityDTO<Entity>;
+    /** Serializes the entity with control over which relations and fields to include or exclude. */
     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>;
+    /** Assigns the given data to this entity, updating its properties and relations. */
     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>;
+    /** Initializes (refreshes) the entity by reloading it from the database. Returns null if not found. */
     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>;
+    /** Returns the database schema this entity belongs to. */
     getSchema(): string | undefined;
+    /** Sets the database schema for this entity. */
     setSchema(schema?: string): void;
 }

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