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

package/typings.js

@@ -5,14 +5,25 @@ import { helper } from './entity/wrap.js';
 import { Utils } from './utils/Utils.js';
 import { EntityComparator } from './utils/EntityComparator.js';
 import { BaseEntity } from './entity/BaseEntity.js';
+/** Symbol used to declare a custom repository type on an entity class (e.g., `[EntityRepositoryType]?: BookRepository`). */
 export const EntityRepositoryType = Symbol('EntityRepositoryType');
+/** Symbol used to declare the primary key property name(s) on an entity (e.g., `[PrimaryKeyProp]?: 'id'`). */
 export const PrimaryKeyProp = Symbol('PrimaryKeyProp');
+/** Symbol used to declare which properties are optional in `em.create()` (e.g., `[OptionalProps]?: 'createdAt'`). */
 export const OptionalProps = Symbol('OptionalProps');
+/** Symbol used to declare which relation properties should be eagerly loaded (e.g., `[EagerProps]?: 'author'`). */
 export const EagerProps = Symbol('EagerProps');
+/** Symbol used to declare which properties are hidden from serialization (e.g., `[HiddenProps]?: 'password'`). */
 export const HiddenProps = Symbol('HiddenProps');
+/** Symbol used to declare type-level configuration on an entity (e.g., `[Config]?: DefineConfig<{ forceObject: true }>`). */
 export const Config = Symbol('Config');
+/** Symbol used to declare the entity name as a string literal type (used by `defineEntity`). */
 // eslint-disable-next-line @typescript-eslint/no-redeclare
 export const EntityName = Symbol('EntityName');
+/**
+ * Runtime metadata for an entity, holding its properties, relations, indexes, hooks, and more.
+ * Created during metadata discovery and used throughout the ORM lifecycle.
+ */
 export class EntityMetadata {
     static counter = 0;
     _id = 1000 * EntityMetadata.counter++; // keep the id >= 1000 to allow computing cache keys by simple addition

package/unit-of-work/ChangeSet.d.ts

@@ -1,4 +1,5 @@
 import type { EntityData, EntityMetadata, EntityDictionary, Primary } from '../typings.js';
+/** Represents a pending change (create, update, or delete) for a single entity. */
 export declare class ChangeSet<T extends object> {
     entity: T;
     type: ChangeSetType;
@@ -7,7 +8,9 @@ export declare class ChangeSet<T extends object> {
     private primaryKey?;
     private serializedPrimaryKey?;
     constructor(entity: T, type: ChangeSetType, payload: EntityDictionary<T>, meta: EntityMetadata<T>);
+    /** Returns the primary key of the entity, optionally as an object for composite keys. */
     getPrimaryKey(object?: boolean): Primary<T> | null;
+    /** Returns the serialized (string) form of the primary key. */
     getSerializedPrimaryKey(): string | null;
 }
 export interface ChangeSet<T> {
@@ -22,6 +25,7 @@ export interface ChangeSet<T> {
     /** For TPT: changesets for parent tables, ordered from immediate parent to root */
     tptChangeSets?: ChangeSet<T>[];
 }
+/** Enumeration of change set operation types. */
 export declare enum ChangeSetType {
     CREATE = "create",
     UPDATE = "update",

package/unit-of-work/ChangeSet.js

@@ -1,6 +1,7 @@
 import { helper } from '../entity/wrap.js';
 import { Utils } from '../utils/Utils.js';
 import { inspect } from '../logging/inspect.js';
+/** Represents a pending change (create, update, or delete) for a single entity. */
 export class ChangeSet {
     entity;
     type;
@@ -17,6 +18,7 @@ export class ChangeSet {
         this.rootMeta = meta.root;
         this.schema = helper(entity).__schema ?? meta.root.schema;
     }
+    /** Returns the primary key of the entity, optionally as an object for composite keys. */
     getPrimaryKey(object = false) {
         if (!this.originalEntity) {
             this.primaryKey ??= helper(this.entity).getPrimaryKey(true);
@@ -40,6 +42,7 @@ export class ChangeSet {
         }
         return this.primaryKey ?? null;
     }
+    /** Returns the serialized (string) form of the primary key. */
     getSerializedPrimaryKey() {
         this.serializedPrimaryKey ??= helper(this.entity).getSerializedPrimaryKey();
         return this.serializedPrimaryKey;
@@ -55,6 +58,7 @@ export class ChangeSet {
         return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
     }
 }
+/** Enumeration of change set operation types. */
 export var ChangeSetType;
 (function (ChangeSetType) {
     ChangeSetType["CREATE"] = "create";

package/unit-of-work/ChangeSetComputer.d.ts

@@ -2,9 +2,11 @@ import type { AnyEntity } from '../typings.js';
 import { ChangeSet } from './ChangeSet.js';
 import { type Collection } from '../entity/Collection.js';
 import type { EntityManager } from '../EntityManager.js';
+/** @internal Computes change sets by comparing entity state against original snapshots. */
 export declare class ChangeSetComputer {
     #private;
     constructor(em: EntityManager, collectionUpdates: Set<Collection<AnyEntity>>);
+    /** Computes a change set for the given entity by diffing against its original state. */
     computeChangeSet<T extends object>(entity: T): ChangeSet<T> | null;
     /**
      * Traverses entity graph and executes `onCreate` and `onUpdate` methods, assigning the values to given properties.

package/unit-of-work/ChangeSetComputer.js

@@ -6,6 +6,7 @@ import { validateEntity } from '../entity/validators.js';
 import { Reference } from '../entity/Reference.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
 import { ReferenceKind } from '../enums.js';
+/** @internal Computes change sets by comparing entity state against original snapshots. */
 export class ChangeSetComputer {
     #comparator;
     #metadata;
@@ -21,6 +22,7 @@ export class ChangeSetComputer {
         this.#platform = this.#em.getPlatform();
         this.#comparator = this.#config.getComparator(this.#metadata);
     }
+    /** Computes a change set for the given entity by diffing against its original state. */
     computeChangeSet(entity) {
         const meta = this.#metadata.get(entity.constructor);
         if (meta.readonly) {

package/unit-of-work/ChangeSetPersister.d.ts

@@ -2,11 +2,15 @@ import type { Dictionary, EntityDictionary, EntityMetadata } from '../typings.js
 import { type ChangeSet } from './ChangeSet.js';
 import type { DriverMethodOptions } from '../drivers/IDatabaseDriver.js';
 import type { EntityManager } from '../EntityManager.js';
+/** @internal Executes change sets against the database, handling inserts, updates, and deletes. */
 export declare class ChangeSetPersister {
     #private;
     constructor(em: EntityManager);
+    /** Executes all pending INSERT change sets, using batch inserts when possible. */
     executeInserts<T extends object>(changeSets: ChangeSet<T>[], options?: DriverMethodOptions, withSchema?: boolean): Promise<void>;
+    /** Executes all pending UPDATE change sets, using batch updates when possible. */
     executeUpdates<T extends object>(changeSets: ChangeSet<T>[], batched: boolean, options?: DriverMethodOptions, withSchema?: boolean): Promise<void>;
+    /** Executes all pending DELETE change sets in batches. */
     executeDeletes<T extends object>(changeSets: ChangeSet<T>[], options?: DriverMethodOptions, withSchema?: boolean): Promise<void>;
     private runForEachSchema;
     private validateRequired;

package/unit-of-work/ChangeSetPersister.js

@@ -6,6 +6,7 @@ import { isRaw } from '../utils/RawQueryFragment.js';
 import { Utils } from '../utils/Utils.js';
 import { OptimisticLockError, ValidationError } from '../errors.js';
 import { ReferenceKind } from '../enums.js';
+/** @internal Executes change sets against the database, handling inserts, updates, and deletes. */
 export class ChangeSetPersister {
     #platform;
     #comparator;
@@ -27,6 +28,7 @@ export class ChangeSetPersister {
         this.#comparator = this.#config.getComparator(this.#metadata);
         this.#usesReturningStatement = this.#platform.usesReturningStatement() || this.#platform.usesOutputStatement();
     }
+    /** Executes all pending INSERT change sets, using batch inserts when possible. */
     async executeInserts(changeSets, options, withSchema) {
         if (!withSchema) {
             return this.runForEachSchema(changeSets, 'executeInserts', options);
@@ -40,6 +42,7 @@ export class ChangeSetPersister {
             await this.persistNewEntity(meta, changeSet, options);
         }
     }
+    /** Executes all pending UPDATE change sets, using batch updates when possible. */
     async executeUpdates(changeSets, batched, options, withSchema) {
         if (!withSchema) {
             return this.runForEachSchema(changeSets, 'executeUpdates', options, batched);
@@ -59,6 +62,7 @@ export class ChangeSetPersister {
             await this.persistManagedEntity(changeSet, options);
         }
     }
+    /** Executes all pending DELETE change sets in batches. */
     async executeDeletes(changeSets, options, withSchema) {
         if (!withSchema) {
             return this.runForEachSchema(changeSets, 'executeDeletes', options);

package/unit-of-work/IdentityMap.d.ts

@@ -1,19 +1,26 @@
 import type { AnyEntity, EntityMetadata } from '../typings.js';
+/** @internal Stores managed entity instances keyed by their primary key hash, ensuring each row is loaded once. */
 export declare class IdentityMap {
     #private;
     constructor(defaultSchema?: string);
+    /** Stores an entity in the identity map under its primary key hash. */
     store<T>(item: T): void;
     /**
      * Stores an entity under an alternate key (non-PK property).
      * This allows looking up entities by unique properties that are not the primary key.
      */
     storeByKey<T>(item: T, key: string, value: string, schema?: string): void;
+    /** Removes an entity and its alternate key entries from the identity map. */
     delete<T>(item: T): void;
+    /** Retrieves an entity by its hash key from the identity map. */
     getByHash<T>(meta: EntityMetadata<T>, hash: string): T | undefined;
+    /** Returns (or creates) the per-entity-class store within the identity map. */
     getStore<T>(meta: EntityMetadata<T>): Map<string, T>;
     clear(): void;
+    /** Returns all entities currently in the identity map. */
     values(): AnyEntity[];
     [Symbol.iterator](): IterableIterator<AnyEntity>;
+    /** Returns all hash keys currently in the identity map. */
     keys(): string[];
     /**
      * For back compatibility only.

package/unit-of-work/IdentityMap.js

@@ -1,3 +1,4 @@
+/** @internal Stores managed entity instances keyed by their primary key hash, ensuring each row is loaded once. */
 export class IdentityMap {
     #defaultSchema;
     #registry = new Map();
@@ -6,6 +7,7 @@ export class IdentityMap {
     constructor(defaultSchema) {
         this.#defaultSchema = defaultSchema;
     }
+    /** Stores an entity in the identity map under its primary key hash. */
     store(item) {
         this.getStore(item.__meta.root).set(this.getPkHash(item), item);
     }
@@ -24,6 +26,7 @@ export class IdentityMap {
         }
         keys.add(hash);
     }
+    /** Removes an entity and its alternate key entries from the identity map. */
     delete(item) {
         const meta = item.__meta.root;
         const store = this.getStore(meta);
@@ -37,10 +40,12 @@ export class IdentityMap {
             this.#alternateKeys.delete(item);
         }
     }
+    /** Retrieves an entity by its hash key from the identity map. */
     getByHash(meta, hash) {
         const store = this.getStore(meta);
         return store.has(hash) ? store.get(hash) : undefined;
     }
+    /** Returns (or creates) the per-entity-class store within the identity map. */
     getStore(meta) {
         const store = this.#registry.get(meta.class);
         if (store) {
@@ -53,6 +58,7 @@ export class IdentityMap {
     clear() {
         this.#registry.clear();
     }
+    /** Returns all entities currently in the identity map. */
     values() {
         const ret = [];
         for (const store of this.#registry.values()) {
@@ -67,6 +73,7 @@ export class IdentityMap {
             }
         }
     }
+    /** Returns all hash keys currently in the identity map. */
     keys() {
         const ret = [];
         for (const [cls, store] of this.#registry) {

package/unit-of-work/UnitOfWork.d.ts

@@ -6,9 +6,11 @@ import { ChangeSetPersister } from './ChangeSetPersister.js';
 import type { EntityManager } from '../EntityManager.js';
 import { IdentityMap } from './IdentityMap.js';
 import type { LockOptions } from '../drivers/IDatabaseDriver.js';
+/** Implements the Unit of Work pattern: tracks entity changes, computes change sets, and flushes them to the database. */
 export declare class UnitOfWork {
     #private;
     constructor(em: EntityManager);
+    /** Merges an entity into the identity map, taking a snapshot of its current state. */
     merge<T extends object>(entity: T, visited?: Set<AnyEntity>): void;
     /**
      * Entity data can wary in its shape, e.g. we might get a deep relation graph with joined strategy, but for diffing,
@@ -45,6 +47,7 @@ export declare class UnitOfWork {
      *                             If false (default), the value is assumed to be in JS format already.
      */
     storeByKey<T extends object>(entity: T, key: string, value: unknown, schema?: string, convertCustomTypes?: boolean): void;
+    /** Attempts to extract a primary key from the where condition and look up the entity in the identity map. */
     tryGetById<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, schema?: string, strict?: boolean): T | null;
     /**
      * Returns map of all managed entities.
@@ -54,10 +57,15 @@ export declare class UnitOfWork {
      * Returns stored snapshot of entity state that is used for change set computation.
      */
     getOriginalEntityData<T extends object>(entity: T): EntityData<T> | undefined;
+    /** Returns the set of entities scheduled for persistence. */
     getPersistStack(): Set<AnyEntity>;
+    /** Returns the set of entities scheduled for removal. */
     getRemoveStack(): Set<AnyEntity>;
+    /** Returns all computed change sets for the current flush. */
     getChangeSets(): ChangeSet<AnyEntity>[];
+    /** Returns all M:N collections that need synchronization. */
     getCollectionUpdates(): Collection<AnyEntity>[];
+    /** Returns extra updates needed for relations that could not be resolved in the initial pass. */
     getExtraUpdates(): Set<[
         AnyEntity,
         string | string[],
@@ -65,17 +73,24 @@ export declare class UnitOfWork {
         ChangeSet<any> | undefined,
         ChangeSetType
     ]>;
+    /** Checks whether an auto-flush is needed before querying the given entity type. */
     shouldAutoFlush<T extends object>(meta: EntityMetadata<T>): boolean;
+    /** Clears the queue of entity types that triggered auto-flush detection. */
     clearActionsQueue(): void;
+    /** Computes and registers a change set for the given entity. */
     computeChangeSet<T extends object>(entity: T, type?: ChangeSetType): void;
+    /** Recomputes and merges the change set for an already-tracked entity. */
     recomputeSingleChangeSet<T extends object>(entity: T): void;
+    /** Marks an entity for persistence, cascading to related entities. */
     persist<T extends object>(entity: T, visited?: Set<AnyEntity>, options?: {
         checkRemoveStack?: boolean;
         cascade?: boolean;
     }): void;
+    /** Marks an entity for removal, cascading to related entities. */
     remove<T extends object>(entity: T, visited?: Set<AnyEntity>, options?: {
         cascade?: boolean;
     }): void;
+    /** Flushes all pending changes to the database within a transaction. */
     commit(): Promise<void>;
     private doCommit;
     lock<T extends object>(entity: T, options: LockOptions): Promise<void>;

package/unit-of-work/UnitOfWork.js

@@ -15,6 +15,7 @@ import { IdentityMap } from './IdentityMap.js';
 import { createAsyncContext } from '../utils/AsyncContext.js';
 // to deal with validation for flush inside flush hooks and `Promise.all`
 const insideFlush = createAsyncContext();
+/** Implements the Unit of Work pattern: tracks entity changes, computes change sets, and flushes them to the database. */
 export class UnitOfWork {
     /** map of references to managed entities */
     #identityMap;
@@ -45,6 +46,7 @@ export class UnitOfWork {
         this.#changeSetComputer = new ChangeSetComputer(this.#em, this.#collectionUpdates);
         this.#changeSetPersister = new ChangeSetPersister(this.#em);
     }
+    /** Merges an entity into the identity map, taking a snapshot of its current state. */
     merge(entity, visited) {
         const wrapped = helper(entity);
         wrapped.__em = this.#em;
@@ -217,6 +219,7 @@ export class UnitOfWork {
         entity[key] = value;
         this.#identityMap.storeByKey(entity, key, '' + value, schema);
     }
+    /** Attempts to extract a primary key from the where condition and look up the entity in the identity map. */
     tryGetById(entityName, where, schema, strict = true) {
         const pk = Utils.extractPK(where, this.#metadata.find(entityName), strict);
         if (!pk) {
@@ -236,21 +239,27 @@ export class UnitOfWork {
     getOriginalEntityData(entity) {
         return helper(entity).__originalEntityData;
     }
+    /** Returns the set of entities scheduled for persistence. */
     getPersistStack() {
         return this.#persistStack;
     }
+    /** Returns the set of entities scheduled for removal. */
     getRemoveStack() {
         return this.#removeStack;
     }
+    /** Returns all computed change sets for the current flush. */
     getChangeSets() {
         return [...this.#changeSets.values()];
     }
+    /** Returns all M:N collections that need synchronization. */
     getCollectionUpdates() {
         return [...this.#collectionUpdates];
     }
+    /** Returns extra updates needed for relations that could not be resolved in the initial pass. */
     getExtraUpdates() {
         return this.#extraUpdates;
     }
+    /** Checks whether an auto-flush is needed before querying the given entity type. */
     shouldAutoFlush(meta) {
         if (insideFlush.getStore()) {
             return false;
@@ -263,9 +272,11 @@ export class UnitOfWork {
         }
         return false;
     }
+    /** Clears the queue of entity types that triggered auto-flush detection. */
     clearActionsQueue() {
         this.#queuedActions.clear();
     }
+    /** Computes and registers a change set for the given entity. */
     computeChangeSet(entity, type) {
         const wrapped = helper(entity);
         if (type === ChangeSetType.DELETE || type === ChangeSetType.DELETE_EARLY) {
@@ -285,6 +296,7 @@ export class UnitOfWork {
         this.#persistStack.delete(entity);
         wrapped.__originalEntityData = this.#comparator.prepareEntity(entity);
     }
+    /** Recomputes and merges the change set for an already-tracked entity. */
     recomputeSingleChangeSet(entity) {
         const changeSet = this.#changeSets.get(entity);
         if (!changeSet) {
@@ -296,6 +308,7 @@ export class UnitOfWork {
             helper(entity).__originalEntityData = this.#comparator.prepareEntity(entity);
         }
     }
+    /** Marks an entity for persistence, cascading to related entities. */
     persist(entity, visited, options = {}) {
         EntityHelper.ensurePropagation(entity);
         if (options.checkRemoveStack && this.#removeStack.has(entity)) {
@@ -312,6 +325,7 @@ export class UnitOfWork {
             this.cascade(entity, Cascade.PERSIST, visited, options);
         }
     }
+    /** Marks an entity for removal, cascading to related entities. */
     remove(entity, visited, options = {}) {
         // allow removing not managed entities if they are not part of the persist stack
         if (helper(entity).__managed || !this.#persistStack.has(entity)) {
@@ -342,6 +356,7 @@ export class UnitOfWork {
             this.cascade(entity, Cascade.REMOVE, visited);
         }
     }
+    /** Flushes all pending changes to the database within a transaction. */
     async commit() {
         if (this.#working) {
             if (insideFlush.getStore()) {

package/utils/Configuration.d.ts

@@ -15,14 +15,17 @@ import { DataloaderType, FlushMode, LoadStrategy, PopulateHint, type EmbeddedPre
 import { EntityComparator } from './EntityComparator.js';
 import type { Type } from '../types/Type.js';
 import type { MikroORM } from '../MikroORM.js';
+/** Holds and validates all ORM configuration options, providing access to drivers, loggers, cache adapters, and other services. */
 export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver, EM extends EntityManager<D> = D[typeof EntityManagerType] & EntityManager<D>> {
     #private;
     constructor(options: Partial<Options>, validate?: boolean);
+    /** Returns the database platform instance. */
     getPlatform(): ReturnType<D['getPlatform']>;
     /**
      * Gets specific configuration option. Falls back to specified `defaultValue` if provided.
      */
     get<T extends keyof Options<D, EM>, U extends Options<D, EM>[T]>(key: T, defaultValue?: U): U;
+    /** Returns all configuration options. */
     getAll(): Options<D, EM>;
     /**
      * Overrides specified configuration value.
@@ -41,13 +44,17 @@ export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver,
      * Falls back to the main logger if no custom slow query logger factory is configured.
      */
     getSlowQueryLogger(): Logger;
+    /** Returns the configured dataloader type, normalizing boolean values. */
     getDataloaderType(): DataloaderType;
+    /** Returns the configured schema name, optionally skipping the platform's default schema. */
     getSchema(skipDefaultSchema?: boolean): string | undefined;
     /**
      * Gets current database driver instance.
      */
     getDriver(): D;
+    /** Registers a lazily-initialized extension by name. */
     registerExtension(name: string, cb: () => unknown): void;
+    /** Returns a previously registered extension by name, initializing it on first access. */
     getExtension<T>(name: string): T | undefined;
     /**
      * Gets instance of NamingStrategy. (cached)
@@ -83,6 +90,7 @@ export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver,
     getCachedService<T extends {
         new (...args: any[]): InstanceType<T>;
     }>(cls: T, ...args: ConstructorParameters<T>): InstanceType<T>;
+    /** Clears the cached service instances, forcing re-creation on next access. */
     resetServiceCache(): void;
     private init;
     private sync;

package/utils/Configuration.js

@@ -127,6 +127,7 @@ const DEFAULTS = {
     preferReadReplicas: true,
     dynamicImportProvider: /* v8 ignore next */ (id) => import(id),
 };
+/** Holds and validates all ORM configuration options, providing access to drivers, loggers, cache adapters, and other services. */
 export class Configuration {
     #options;
     #logger;
@@ -162,6 +163,7 @@ export class Configuration {
             this.init(validate);
         }
     }
+    /** Returns the database platform instance. */
     getPlatform() {
         return this.#platform;
     }
@@ -174,6 +176,7 @@ export class Configuration {
         }
         return defaultValue;
     }
+    /** Returns all configuration options. */
     getAll() {
         return this.#options;
     }
@@ -210,12 +213,14 @@ export class Configuration {
             }) ?? this.#logger;
         return this.#slowQueryLogger;
     }
+    /** Returns the configured dataloader type, normalizing boolean values. */
     getDataloaderType() {
         if (typeof this.#options.dataloader === 'boolean') {
             return this.#options.dataloader ? DataloaderType.ALL : DataloaderType.NONE;
         }
         return this.#options.dataloader;
     }
+    /** Returns the configured schema name, optionally skipping the platform's default schema. */
     getSchema(skipDefaultSchema = false) {
         if (skipDefaultSchema && this.#options.schema === this.#platform.getDefaultSchemaName()) {
             return undefined;
@@ -228,9 +233,11 @@ export class Configuration {
     getDriver() {
         return this.#driver;
     }
+    /** Registers a lazily-initialized extension by name. */
     registerExtension(name, cb) {
         this.#extensions.set(name, cb);
     }
+    /** Returns a previously registered extension by name, initializing it on first access. */
     getExtension(name) {
         if (this.#cache.has(name)) {
             return this.#cache.get(name);
@@ -303,6 +310,7 @@ export class Configuration {
         }
         return this.#cache.get(cls.name);
     }
+    /** Clears the cached service instances, forcing re-creation on next access. */
     resetServiceCache() {
         this.#cache.clear();
     }

package/utils/EntityComparator.d.ts

@@ -9,6 +9,7 @@ type SnapshotGenerator<T> = (entity: T) => EntityData<T>;
 type PkGetter<T> = (entity: T) => Primary<T>;
 type PkSerializer<T> = (entity: T) => string;
 type CompositeKeyPart = string | CompositeKeyPart[];
+/** @internal Generates and caches JIT-compiled functions for comparing, snapshotting, and mapping entity data. */
 export declare class EntityComparator {
     #private;
     constructor(metadata: IMetadataStorage, platform: Platform, config?: Configuration);
@@ -18,6 +19,7 @@ export declare class EntityComparator {
     diffEntities<T extends object>(entityName: EntityName<T>, a: EntityData<T>, b: EntityData<T>, options?: {
         includeInverseSides?: boolean;
     }): EntityData<T>;
+    /** Returns true if two entity snapshots are identical (no differences). */
     matching<T extends object>(entityName: EntityName<T>, a: EntityData<T>, b: EntityData<T>): boolean;
     /**
      * Removes ORM specific code from entities and prepares it for serializing. Used before change set computation.

package/utils/EntityComparator.js

@@ -5,6 +5,7 @@ import { JsonType } from '../types/JsonType.js';
 import { Raw } from './RawQueryFragment.js';
 import { EntityIdentifier } from '../entity/EntityIdentifier.js';
 import { PolymorphicRef } from '../entity/PolymorphicRef.js';
+/** @internal Generates and caches JIT-compiled functions for comparing, snapshotting, and mapping entity data. */
 export class EntityComparator {
     #comparators = new Map();
     #mappers = new Map();
@@ -28,6 +29,7 @@ export class EntityComparator {
         const comparator = this.getEntityComparator(entityName);
         return Utils.callCompiledFunction(comparator, a, b, options);
     }
+    /** Returns true if two entity snapshots are identical (no differences). */
     matching(entityName, a, b) {
         const diff = this.diffEntities(entityName, a, b);
         return Utils.getObjectKeysSize(diff) === 0;

package/utils/NullHighlighter.d.ts

@@ -1,4 +1,5 @@
 import type { Highlighter } from '../typings.js';
+/** No-op highlighter that returns SQL text unchanged. Used as the default when no syntax highlighting is configured. */
 export declare class NullHighlighter implements Highlighter {
     highlight(text: string): string;
 }

package/utils/NullHighlighter.js

@@ -1,3 +1,4 @@
+/** No-op highlighter that returns SQL text unchanged. Used as the default when no syntax highlighting is configured. */
 export class NullHighlighter {
     highlight(text) {
         return text;

package/utils/RawQueryFragment.d.ts

@@ -1,8 +1,10 @@
 import type { AnyString, Dictionary, EntityKey } from '../typings.js';
 declare const rawFragmentSymbolBrand: unique symbol;
+/** Branded symbol type used as a unique key for tracking raw SQL fragments in object properties. */
 export type RawQueryFragmentSymbol = symbol & {
     readonly [rawFragmentSymbolBrand]: true;
 };
+/** Represents a raw SQL fragment with optional parameters, usable as both a value and an object key via Symbol coercion. */
 export declare class RawQueryFragment<Alias extends string = string> {
     #private;
     readonly sql: string;
@@ -10,18 +12,25 @@ export declare class RawQueryFragment<Alias extends string = string> {
     /** @internal Type-level only - used to track the alias for type inference */
     private readonly __alias?;
     constructor(sql: string, params?: unknown[]);
+    /** Returns a unique symbol key for this fragment, creating and caching it on first access. */
     get key(): RawQueryFragmentSymbol;
+    /** Creates a new fragment with an alias appended via `as ??`. */
     as<A extends string>(alias: A): RawQueryFragment<A>;
     [Symbol.toPrimitive](hint: 'string'): RawQueryFragmentSymbol;
     get [Symbol.toStringTag](): string;
     toJSON(): string;
     clone(): this;
+    /** Checks whether the given value is a symbol that maps to a known raw query fragment. */
     static isKnownFragmentSymbol(key: unknown): key is RawQueryFragmentSymbol;
+    /** Checks whether an object has any symbol keys that are known raw query fragments. */
     static hasObjectFragments(object: unknown): boolean;
+    /** Checks whether the given value is a RawQueryFragment instance or a known fragment symbol. */
     static isKnownFragment(key: unknown): key is RawQueryFragment | symbol;
+    /** Retrieves the RawQueryFragment associated with the given key (instance or symbol). */
     static getKnownFragment(key: unknown): RawQueryFragment | undefined;
 }
 export { RawQueryFragment as Raw };
+/** Checks whether the given value is a `RawQueryFragment` instance. */
 export declare function isRaw(value: unknown): value is RawQueryFragment;
 /** @internal */
 export declare const ALIAS_REPLACEMENT = "[::alias::]";
@@ -107,6 +116,7 @@ export declare namespace sql {
     var lower: <R = RawQueryFragment<string> & symbol, T extends object = any>(key: string | ((alias: string) => string)) => R;
     var upper: <R = RawQueryFragment<string> & symbol, T extends object = any>(key: string | ((alias: string) => string)) => R;
 }
+/** Creates a raw SQL function expression wrapping the given key (e.g., `lower(name)`). */
 export declare function createSqlFunction<R = RawQueryFragment & symbol, T extends object = any>(func: string, key: string | ((alias: string) => string)): R;
 /**
  * Tag function providing quoting of db identifiers (table name, columns names, index names, ...).

package/utils/RawQueryFragment.js

@@ -1,4 +1,5 @@
 import { Utils } from './Utils.js';
+/** Represents a raw SQL fragment with optional parameters, usable as both a value and an object key via Symbol coercion. */
 export class RawQueryFragment {
     sql;
     params;
@@ -8,6 +9,7 @@ export class RawQueryFragment {
         this.sql = sql;
         this.params = params;
     }
+    /** Returns a unique symbol key for this fragment, creating and caching it on first access. */
     get key() {
         if (!this.#key) {
             this.#key = Symbol(this.toJSON());
@@ -15,6 +17,7 @@ export class RawQueryFragment {
         }
         return this.#key;
     }
+    /** Creates a new fragment with an alias appended via `as ??`. */
     as(alias) {
         return new RawQueryFragment(`${this.sql} as ??`, [...this.params, alias]);
     }
@@ -35,19 +38,23 @@ export class RawQueryFragment {
     clone() {
         return this;
     }
+    /** Checks whether the given value is a symbol that maps to a known raw query fragment. */
     static isKnownFragmentSymbol(key) {
         return typeof key === 'symbol' && this.#rawQueryReferences.has(key);
     }
+    /** Checks whether an object has any symbol keys that are known raw query fragments. */
     static hasObjectFragments(object) {
         return (Utils.isPlainObject(object) &&
             Object.getOwnPropertySymbols(object).some(symbol => this.isKnownFragmentSymbol(symbol)));
     }
+    /** Checks whether the given value is a RawQueryFragment instance or a known fragment symbol. */
     static isKnownFragment(key) {
         if (key instanceof RawQueryFragment) {
             return true;
         }
         return this.isKnownFragmentSymbol(key);
     }
+    /** Retrieves the RawQueryFragment associated with the given key (instance or symbol). */
     static getKnownFragment(key) {
         if (key instanceof RawQueryFragment) {
             return key;
@@ -70,6 +77,7 @@ export { RawQueryFragment as Raw };
 Object.defineProperties(RawQueryFragment.prototype, {
     __raw: { value: true, enumerable: false },
 });
+/** Checks whether the given value is a `RawQueryFragment` instance. */
 export function isRaw(value) {
     return typeof value === 'object' && value !== null && '__raw' in value;
 }
@@ -178,6 +186,7 @@ export function raw(sql, params) {
 export function sql(sql, ...values) {
     return raw(sql.join('?'), values);
 }
+/** Creates a raw SQL function expression wrapping the given key (e.g., `lower(name)`). */
 export function createSqlFunction(func, key) {
     if (typeof key === 'string') {
         return raw(`${func}(${key})`);

package/utils/RequestContext.d.ts

@@ -35,6 +35,7 @@ export declare class RequestContext {
     static getEntityManager(name?: string): EntityManager | undefined;
     private static createContext;
 }
+/** Options for creating a new RequestContext, allowing schema and logger overrides. */
 export interface CreateContextOptions {
     schema?: string;
     loggerContext?: LoggingOptions;