@mikro-orm/core 7.1.0-dev.9 → 7.1.0

package/drivers/IDatabaseDriver.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionType, Constructor, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName, PopulateHintOptions, Prefixes, IndexName } from '../typings.js';
-import type { Connection, QueryResult, Transaction } from '../connections/Connection.js';
+import type { AbortQueryOptions, Connection, QueryResult, Transaction } from '../connections/Connection.js';
 import type { FlushMode, LockMode, QueryOrderMap, QueryFlag, LoadStrategy, PopulateHint, PopulatePath } from '../enums.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
@@ -110,6 +110,20 @@ export interface FindAllOptions<T, P extends string = never, F extends string =
 }
 /** Options for streaming query results via `em.stream()`. */
 export interface StreamOptions<Entity, Populate extends string = never, Fields extends string = never, Exclude extends string = never> extends Omit<FindAllOptions<Entity, Populate, Fields, Exclude>, 'cache' | 'before' | 'after' | 'first' | 'last' | 'overfetch' | 'strategy'> {
+    /**
+     * How many rows to fetch in one round-trip.
+     * Lower values will result in more queries and network bandwidth, but less memory usage.
+     * Higher values will result in fewer queries and network bandwidth, but higher memory usage.
+     * Note that the results are iterated one row at a time regardless of this value.
+     *
+     * Honored on PostgreSQL (cursor-based fetch), MSSQL (tedious stream chunk size),
+     * Oracle (mapped to `fetchArraySize`) and MongoDB (mapped to `batchSize`). Ignored
+     * on MySQL, MariaDB, SQLite and libSQL, where the underlying driver already streams
+     * row-by-row with no batching knob.
+     *
+     * @default 100 (on dialects that honor it)
+     */
+    chunkSize?: number;
     /**
      * When populating to-many relations, the ORM streams fully merged entities instead of yielding every row.
      * You can opt out of this behavior by specifying `mergeResults: false`. This will yield every row from
@@ -130,7 +144,7 @@ export interface LoadHint<Entity, Hint extends string = never, Fields extends st
     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 = never, Excludes extends string = never> extends LoadHint<Entity, Hint, Fields, Excludes> {
+export interface FindOptions<Entity, Hint extends string = never, Fields extends string = never, Excludes extends string = never> extends LoadHint<Entity, Hint, Fields, Excludes>, AbortQueryOptions {
     /**
      * Where condition for populated relations. This will have no effect on the root entity.
      * With `select-in` strategy, this is applied only to the populate queries.
@@ -260,7 +274,7 @@ export interface FindOneOrFailOptions<T extends object, P extends string = never
     strict?: boolean;
 }
 /** Options for native insert and update operations. */
-export interface NativeInsertUpdateOptions<T> {
+export interface NativeInsertUpdateOptions<T> extends AbortQueryOptions {
     convertCustomTypes?: boolean;
     ctx?: Transaction;
     schema?: string;
@@ -294,7 +308,7 @@ export interface UpsertManyOptions<Entity, Fields extends string = never> extend
     batchSize?: number;
 }
 /** Options for `em.count()` queries. */
-export interface CountOptions<T extends object, P extends string = never> {
+export interface CountOptions<T extends object, P extends string = never> extends AbortQueryOptions {
     filters?: FilterOptions;
     schema?: string;
     groupBy?: string | readonly string[];
@@ -336,7 +350,7 @@ export interface CountByOptions<T extends object> {
     logging?: LoggingOptions;
 }
 /** Options for `em.qb().update()` operations. */
-export interface UpdateOptions<T> {
+export interface UpdateOptions<T> extends AbortQueryOptions {
     filters?: FilterOptions;
     schema?: string;
     ctx?: Transaction;
@@ -375,7 +389,7 @@ export interface LockOptions extends DriverMethodOptions {
     logging?: LoggingOptions;
 }
 /** Base options shared by all driver methods (transaction context, schema, logging). */
-export interface DriverMethodOptions {
+export interface DriverMethodOptions extends AbortQueryOptions {
     ctx?: Transaction;
     schema?: string;
     loggerContext?: LogContext;

package/entity/BaseEntity.d.ts

@@ -1,4 +1,4 @@
-import { type Ref } from './Reference.js';
+import { type LoadReferenceOptions, type LoadReferenceOrFailOptions, type Ref } from './Reference.js';
 import type { AutoPath, EntityData, EntityDTO, ExtractFieldsHint, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected, ResolveSerializeFields, SerializeDTO, SerializeFieldsKeepPK } from '../typings.js';
 import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
@@ -90,3 +90,70 @@ export declare abstract class BaseEntity {
     /** Sets the database schema for this entity. */
     setSchema(schema?: string): void;
 }
+type EntityConstructor<T extends object = object> = abstract new (...args: any[]) => T;
+/**
+ * The `load()` / `loadOrFail()` methods added by the {@link Loadable} mixin. Declared as an interface so the
+ * mixin function can have an explicit return type (required by JSR fast-check).
+ */
+export interface LoadableEntity {
+    /**
+     * Ensures this entity is loaded (without reloading it if it already is). Returns the entity, or `null` if it
+     * was not found in the database (e.g. it was deleted in the meantime, or active filters disallow loading it).
+     * Use `loadOrFail()` if you want an error to be thrown in such a case.
+     */
+    load<Entity extends this = this, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: LoadReferenceOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes> | null>;
+    /**
+     * Ensures this entity is loaded (without reloading it if it already is). Returns the entity, or throws an error
+     * just like `em.findOneOrFail()` (and respects the same config options) if it was not found.
+     */
+    loadOrFail<Entity extends this = this, Hint extends string = never, Fields extends string = never, Excludes extends string = never>(options?: LoadReferenceOrFailOptions<Entity, Hint, Fields, Excludes>): Promise<Loaded<Entity, Hint, Fields, Excludes>>;
+}
+/** Return-type shape of {@link Loadable} — a constructor that produces instances of `TBase` enriched with {@link LoadableEntity}. */
+export type LoadableConstructor<TBase extends EntityConstructor> = abstract new (...args: any[]) => InstanceType<TBase> & LoadableEntity;
+/** Internal: rejects a base class that already defines `load` or `loadOrFail` to prevent silent override. */
+type EnsureNoLoadConflict<TBase extends EntityConstructor> = InstanceType<TBase> extends {
+    load: any;
+} ? 'Loadable: base class already defines `load` — remove it or do not apply the mixin' : InstanceType<TBase> extends {
+    loadOrFail: any;
+} ? 'Loadable: base class already defines `loadOrFail` — remove it or do not apply the mixin' : TBase;
+/** Empty base for {@link Loadable} when called without arguments — standalone mixin, no inherited base. */
+declare abstract class EmptyBase {
+}
+/**
+ * Mixin that adds `load()` / `loadOrFail()` methods to an entity class. These methods ensure the entity is loaded
+ * from the database without reloading it if it already is — unlike `init()`, which always refreshes.
+ *
+ * Useful when migrating from a non-`Ref`-based codebase where lazy loading support is desired without the
+ * `.$` / `.get()` indirection that the `Reference` wrapper requires. Opt-in so it does not conflict with entities
+ * that already define a `load` or `loadOrFail` property — applying the mixin to a base class that already has
+ * either method is a compile error to prevent silent override.
+ *
+ * Call without arguments (`Loadable()`) for a standalone base with no other inheritance, or pass a base class
+ * (`Loadable(BaseEntity)`) to compose. The convenience alias {@link LoadableBaseEntity} is shorthand for the
+ * latter.
+ *
+ * @example
+ * ```ts
+ * // compose with BaseEntity
+ * class User extends Loadable(BaseEntity) {
+ *   ＠PrimaryKey()
+ *   id!: number;
+ * }
+ *
+ * // standalone — no inherited base
+ * class Product extends Loadable() {
+ *   ＠PrimaryKey()
+ *   id!: number;
+ * }
+ *
+ * const user = orm.em.getReference(User, 1);
+ * await user.load();
+ * ```
+ */
+export declare function Loadable(): LoadableConstructor<typeof EmptyBase> & typeof EmptyBase;
+export declare function Loadable<TBase extends EntityConstructor>(Base: EnsureNoLoadConflict<TBase> extends TBase ? TBase : never): LoadableConstructor<TBase> & TBase;
+declare const LoadableBaseEntityBase: LoadableConstructor<typeof BaseEntity> & typeof BaseEntity;
+/** Convenience: `BaseEntity` pre-composed with the `Loadable` mixin. */
+export declare abstract class LoadableBaseEntity extends LoadableBaseEntityBase {
+}
+export {};

package/entity/BaseEntity.js

@@ -49,3 +49,21 @@ export class BaseEntity {
     }
 }
 Object.defineProperty(BaseEntity.prototype, '__baseEntity', { value: true, writable: false, enumerable: false });
+/** Empty base for {@link Loadable} when called without arguments — standalone mixin, no inherited base. */
+class EmptyBase {
+}
+export function Loadable(Base = EmptyBase) {
+    class LoadableMixin extends Base {
+        async load(options) {
+            return Reference.create(this).load(options);
+        }
+        async loadOrFail(options) {
+            return Reference.create(this).loadOrFail(options);
+        }
+    }
+    return LoadableMixin;
+}
+const LoadableBaseEntityBase = Loadable(BaseEntity);
+/** Convenience: `BaseEntity` pre-composed with the `Loadable` mixin. */
+export class LoadableBaseEntity extends LoadableBaseEntityBase {
+}

package/entity/Collection.d.ts

@@ -94,7 +94,7 @@ export declare class Collection<T extends object, O extends object = object> {
     /**
      * @internal
      */
-    hydrate(items: T[], forcePropagate?: boolean, partial?: boolean): void;
+    hydrate(items: T[], forcePropagate?: boolean, partial?: boolean, readonly?: boolean): void;
     /**
      * Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity,
      * it means we are disconnecting the relation - removing items from collection, not removing entities from database - `Collection.remove()`

package/entity/Collection.js

@@ -470,7 +470,7 @@ export class Collection {
     /**
      * @internal
      */
-    hydrate(items, forcePropagate, partial) {
+    hydrate(items, forcePropagate, partial, readonly) {
         for (let i = 0; i < this.#items.size; i++) {
             delete this[i];
         }
@@ -480,6 +480,9 @@ export class Collection {
         this.#count = 0;
         this.add(items);
         this.takeSnapshot(forcePropagate);
+        if (readonly) {
+            this.#readonly = true;
+        }
     }
     /**
      * Remove all items from the collection. Note that removing items from collection does not necessarily imply deleting the target entity,

package/entity/EntityAssigner.js

@@ -99,6 +99,14 @@ export class EntityAssigner {
             return EntityAssigner.assignReference(entity, value, prop, options.em, options);
         }
         if (prop.kind === ReferenceKind.SCALAR && SCALAR_TYPES.has(prop.runtimeType) && (prop.setter || !prop.getter)) {
+            // mirror the hydrator (used by `em.create`) and coerce string/number inputs to `Date` instances,
+            // since `EntityData` already permits `string | Date` for `Date`-typed properties at the type level
+            if (prop.runtimeType === 'Date' &&
+                value != null &&
+                !(value instanceof Date) &&
+                (typeof value === 'string' || typeof value === 'number')) {
+                value = new Date(value);
+            }
             validateProperty(prop, value, entity);
             return (entity[prop.name] = value);
         }

package/entity/EntityFactory.js

@@ -161,13 +161,15 @@ export class EntityFactory {
             return diff2[key] === undefined;
         })
             .forEach(key => delete diff2[key]);
-        // but always add collection properties, formulas, generated columns, and version properties if they
-        // are part of the `data`, as these are excluded from `comparableProps` and won't appear in the diff
+        // but always add collection properties, formulas, generated columns, version properties, and the
+        // user-declared STI discriminator if they are part of the `data`, as these are excluded from
+        // `comparableProps` and won't appear in the diff
         Utils.keys(data)
             .filter(key => meta.properties[key]?.formula ||
             meta.properties[key]?.version ||
             (meta.properties[key]?.generated && !meta.properties[key]?.primary) ||
-            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind))
+            [ReferenceKind.ONE_TO_MANY, ReferenceKind.MANY_TO_MANY].includes(meta.properties[key]?.kind) ||
+            (key === meta.root.discriminatorColumn && meta.properties[key]?.userDefined !== false))
             .forEach(key => (diff2[key] = data[key]));
         // rehydrated with the new values, skip those changed by user
         // use full hydration if the entity is already initialized, even if the caller used `initialized: false`

package/entity/EntityLoader.d.ts

@@ -1,6 +1,7 @@
-import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateOptions } from '../typings.js';
+import type { AnyEntity, AutoPath, ConnectionType, EntityName, EntityProperty, FilterQuery, PopulateHintOptions, PopulateOptions } from '../typings.js';
 import type { EntityManager } from '../EntityManager.js';
 import { LoadStrategy, type LockMode, type PopulateHint, PopulatePath, type QueryOrderMap } from '../enums.js';
+import type { InflightQueryAbortStrategy } from '../connections/Connection.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. */
@@ -37,6 +38,12 @@ export interface EntityLoaderOptions<Entity, Fields extends string = never, Excl
     connectionType?: ConnectionType;
     /** Logging options for the query. */
     logging?: LoggingOptions;
+    /** Per-relation populate overrides (limit, offset, orderBy). */
+    populateHints?: Record<string, PopulateHintOptions>;
+    /** AbortSignal forwarded to populated relation queries. */
+    signal?: AbortSignal;
+    /** Cancellation strategy paired with {@link signal}. */
+    inflightQueryAbortStrategy?: InflightQueryAbortStrategy;
 }
 /** Responsible for batch-loading entity relations using either select-in or joined loading strategies. */
 export declare class EntityLoader {

package/entity/EntityLoader.js

@@ -177,8 +177,9 @@ export class EntityLoader {
             Utils.isObject(orderBy[prop.name]))
             .flatMap(orderBy => orderBy[prop.name]);
         const where = await this.extractChildCondition(options, prop);
+        const mergedOrderBy = populate.orderBy ? Utils.asArray(populate.orderBy) : innerOrderBy;
         if (prop.kind === ReferenceKind.MANY_TO_MANY && this.#driver.getPlatform().usesPivotTable()) {
-            const pivotOrderBy = QueryHelper.mergeOrderBy(innerOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
+            const pivotOrderBy = QueryHelper.mergeOrderBy(mergedOrderBy, prop.orderBy, prop.targetMeta?.orderBy);
             const res = await this.findChildrenFromPivotTable(filtered, prop, options, pivotOrderBy, populate, !!ref);
             return Utils.flatten(res);
         }
@@ -188,10 +189,12 @@ export class EntityLoader {
         const { items, partial } = await this.findChildren(options.filtered ?? entities, prop, populate, {
             ...options,
             where,
-            orderBy: innerOrderBy,
+            orderBy: mergedOrderBy,
         }, !!(ref || prop.mapToPk));
-        const customOrder = innerOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
-        this.initializeCollections(filtered, prop, field, items, customOrder, partial);
+        const hasLimit = populate.limit != null;
+        const isPartial = partial || hasLimit;
+        const customOrder = mergedOrderBy.length > 0 || !!prop.orderBy || !!prop.targetMeta?.orderBy;
+        this.initializeCollections(filtered, prop, field, items, customOrder, isPartial, hasLimit);
         return items;
     }
     async populateScalar(meta, filtered, options) {
@@ -269,15 +272,15 @@ export class EntityLoader {
         }));
         return allItems;
     }
-    initializeCollections(filtered, prop, field, children, customOrder, partial) {
+    initializeCollections(filtered, prop, field, children, customOrder, partial, readonly) {
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
-            this.initializeOneToMany(filtered, children, prop, field, partial);
+            this.initializeOneToMany(filtered, children, prop, field, partial, readonly);
         }
         if (prop.kind === ReferenceKind.MANY_TO_MANY && !this.#driver.getPlatform().usesPivotTable()) {
-            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial);
+            this.initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly);
         }
     }
-    initializeOneToMany(filtered, children, prop, field, partial) {
+    initializeOneToMany(filtered, children, prop, field, partial, readonly) {
         const mapToPk = prop.targetMeta.properties[prop.mappedBy].mapToPk;
         const map = {};
         for (const entity of filtered) {
@@ -293,14 +296,14 @@ export class EntityLoader {
         }
         for (const entity of filtered) {
             const key = helper(entity).getSerializedPrimaryKey();
-            entity[field].hydrate(map[key], undefined, partial);
+            entity[field].hydrate(map[key], undefined, partial, readonly);
         }
     }
-    initializeManyToMany(filtered, children, prop, field, customOrder, partial) {
+    initializeManyToMany(filtered, children, prop, field, customOrder, partial, readonly) {
         if (prop.mappedBy) {
             for (const entity of filtered) {
                 const items = children.filter(child => child[prop.mappedBy].contains(entity, false));
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
         else {
@@ -311,12 +314,12 @@ export class EntityLoader {
                 if (!customOrder) {
                     items.sort((a, b) => order.indexOf(a) - order.indexOf(b));
                 }
-                entity[field].hydrate(items, true, partial);
+                entity[field].hydrate(items, true, partial, readonly);
             }
         }
     }
     async findChildren(entities, prop, populate, options, ref) {
-        const children = Utils.unique(this.getChildReferences(entities, prop, options, ref));
+        const children = Utils.unique(this.getChildReferences(entities, prop, options, ref, populate));
         const meta = prop.targetMeta;
         // When targetKey is set, use it for FK lookup instead of the PK
         let fk = prop.targetKey ?? Utils.getPrimaryKeyHash(meta.primaryKeys);
@@ -334,10 +337,10 @@ export class EntityLoader {
                 fk = ownerProp.name;
             }
         }
-        if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && !ref) {
+        if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && (!ref || (!prop.mapToPk && !populate.filter))) {
             children.length = 0;
             fk = meta.properties[prop.mappedBy].name;
-            children.push(...this.filterByReferences(entities, prop.name, options.refresh));
+            children.push(...this.filterByReferences(entities, prop, options, ref));
         }
         if (children.length === 0) {
             return { items: [], partial };
@@ -366,8 +369,11 @@ export class EntityLoader {
         }
         const fields = this.buildFields(options.fields, prop, ref);
         /* eslint-disable prefer-const */
-        let { refresh, filters, convertCustomTypes, lockMode, strategy, populateWhere = 'infer', connectionType, logging, } = options;
+        let { refresh, filters, convertCustomTypes, lockMode, strategy, populateWhere, connectionType, logging } = options;
         /* eslint-enable prefer-const */
+        // `populateWhere` is typed as required via `Required<EntityLoaderOptions>`, but `em.populate(...)`
+        // forwards user-supplied options without filling it in — keep the runtime default.
+        populateWhere ??= 'infer';
         if (typeof populateWhere === 'object') {
             populateWhere = await this.extractChildCondition({ where: populateWhere }, prop);
         }
@@ -375,7 +381,7 @@ export class EntityLoader {
             where = { $and: [where, prop.where] };
         }
         const orderBy = QueryHelper.mergeOrderBy(options.orderBy, prop.orderBy);
-        const items = await this.#em.find(meta.class, where, {
+        const findOptions = {
             filters,
             convertCustomTypes,
             lockMode,
@@ -390,11 +396,21 @@ export class EntityLoader {
             fields,
             schema,
             connectionType,
+            signal: options.signal,
+            inflightQueryAbortStrategy: options.inflightQueryAbortStrategy,
             // @ts-ignore not a public option, will be propagated to the populate call
             refresh: refresh && !children.every(item => options.visited.has(item)),
             // @ts-ignore not a public option, will be propagated to the populate call
             visited: options.visited,
-        });
+        };
+        if (populate.limit != null) {
+            findOptions._partitionLimit = {
+                partitionBy: fk,
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
+        const items = await this.#em.find(meta.class, where, findOptions);
         // For targetKey relations, wire up loaded entities to parent references
         // This is needed because the references were created under alternate key,
         // but loaded entities are stored under PK, so they don't automatically merge
@@ -582,6 +598,12 @@ export class EntityLoader {
         const options2 = { ...options, fields, exclude, populateFilter };
         ['limit', 'offset', 'first', 'last', 'before', 'after', 'overfetch'].forEach(prop => delete options2[prop]);
         options2.populate = populate?.children ?? [];
+        if (populate?.limit != null) {
+            options2._partitionLimit = {
+                limit: populate.limit,
+                offset: populate.offset,
+            };
+        }
         if (!Utils.isEmpty(prop.where)) {
             where = { $and: [where, prop.where] };
         }
@@ -609,7 +631,8 @@ export class EntityLoader {
                 });
                 return this.#em.getUnitOfWork().register(entity, item, { refresh, loaded: true });
             });
-            entity[prop.name].hydrate(items, true);
+            const hasLimit = populate?.limit != null;
+            entity[prop.name].hydrate(items, true, hasLimit, hasLimit);
             children.push(items);
         }
         return children;
@@ -670,8 +693,11 @@ export class EntityLoader {
             }
             return ret;
         }, []);
-        // we need to automatically select the FKs too, e.g. for 1:m relations to be able to wire them with the items
-        if (prop.kind === ReferenceKind.ONE_TO_MANY || prop.kind === ReferenceKind.MANY_TO_MANY) {
+        // we need to automatically select the FKs too, e.g. for 1:m and inverse 1:1 relations
+        // to be able to wire them with the items
+        if (prop.kind === ReferenceKind.ONE_TO_MANY ||
+            prop.kind === ReferenceKind.MANY_TO_MANY ||
+            (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner)) {
             const owner = prop.targetMeta.properties[prop.mappedBy];
             // when the owning FK is lazy, we need to explicitly select it even without user-provided fields,
             // otherwise the driver will exclude it and we won't be able to map children to their parent collections
@@ -684,7 +710,7 @@ export class EntityLoader {
         }
         return ret;
     }
-    getChildReferences(entities, prop, options, ref) {
+    getChildReferences(entities, prop, options, ref, populate) {
         const filtered = this.filterCollections(entities, prop.name, options, ref);
         if (prop.kind === ReferenceKind.ONE_TO_MANY) {
             return filtered.map(e => e[prop.name].owner);
@@ -700,7 +726,7 @@ export class EntityLoader {
             return filtered;
         }
         // MANY_TO_ONE or ONE_TO_ONE
-        return this.filterReferences(entities, prop.name, options, ref);
+        return this.filterReferences(entities, prop.name, options, ref, populate);
     }
     filterCollections(entities, field, options, ref) {
         if (options.refresh) {
@@ -714,7 +740,16 @@ export class EntityLoader {
         }
         const wrapped = helper(entity);
         if (!field.includes('.')) {
-            return wrapped.__loadedProperties.has(field);
+            if (wrapped.__loadedProperties.has(field)) {
+                return true;
+            }
+            // Inlined embeddables track each leaf child separately, not the parent property,
+            // so we need to recurse for nested inline embeddables.
+            const prop = wrapped.__meta.properties[field];
+            if (prop?.kind === ReferenceKind.EMBEDDED && !prop.object) {
+                return Object.values(prop.embeddedProps).every(child => this.isPropertyLoaded(entity, child.name));
+            }
+            return false;
         }
         const [f, ...r] = field.split('.');
         /* v8 ignore next */
@@ -726,7 +761,7 @@ export class EntityLoader {
         }
         return this.isPropertyLoaded(entity[f], r.join('.'));
     }
-    filterReferences(entities, field, options, ref) {
+    filterReferences(entities, field, options, ref, populate) {
         if (ref) {
             return [];
         }
@@ -735,13 +770,19 @@ export class EntityLoader {
             return children.map(e => Reference.unwrapReference(e[field]));
         }
         if (options.fields) {
+            // `:ref` populate children are satisfied by FK/PK and will be loaded lazily — they don't force a parent reload
+            const refChildren = new Set((populate?.children ?? [])
+                .map(c => c.field.split(':'))
+                .filter(parts => parts[1] === 'ref')
+                .map(parts => parts[0]));
             return children
                 .map(e => Reference.unwrapReference(e[field]))
                 .filter(target => {
                 const wrapped = helper(target);
                 const childFields = options.fields
                     .filter(f => f.startsWith(`${field}.`))
-                    .map(f => f.substring(field.length + 1));
+                    .map(f => f.substring(field.length + 1))
+                    .filter(cf => !refChildren.has(cf.split('.')[0]));
                 return !wrapped.__initialized || !childFields.every(cf => this.isPropertyLoaded(target, cf));
             });
         }
@@ -749,12 +790,39 @@ export class EntityLoader {
             .filter(e => !e[field].__helper.__initialized)
             .map(e => Reference.unwrapReference(e[field]));
     }
-    filterByReferences(entities, field, refresh) {
+    filterByReferences(entities, prop, options, ref) {
         /* v8 ignore next */
-        if (refresh) {
+        if (options.refresh) {
             return entities;
         }
-        return entities.filter(e => e[field] !== null && !e[field]?.__helper?.__initialized);
+        const field = prop.name;
+        return entities.filter(e => {
+            const value = e[field];
+            if (value === null) {
+                return false;
+            }
+            if (value === undefined || !Utils.isEntity(value, true)) {
+                return true;
+            }
+            const target = Reference.unwrapReference(value);
+            const wrapped = helper(target);
+            if (!wrapped.__initialized) {
+                return true;
+            }
+            if (ref) {
+                return false;
+            }
+            if (options.fields) {
+                const childFields = options.fields
+                    .filter(f => f.startsWith(`${prop.name}.`))
+                    .map(f => f.substring(prop.name.length + 1));
+                return childFields.length > 0 && !childFields.every(f => this.isPropertyLoaded(target, f));
+            }
+            return prop.targetMeta.comparableProps.some(targetProp => {
+                const inlineEmbedded = targetProp.kind === ReferenceKind.EMBEDDED && !targetProp.object;
+                return !inlineEmbedded && !targetProp.lazy && !wrapped.__loadedProperties.has(targetProp.name);
+            });
+        });
     }
     lookupAllRelationships(entityName) {
         const ret = [];

package/entity/Reference.d.ts

@@ -1,4 +1,4 @@
-import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, Loaded, LoadedReference, Primary, Ref } from '../typings.js';
+import type { AddEager, AddOptional, Dictionary, EntityClass, EntityKey, EntityProperty, LazyRef, 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> {
@@ -98,6 +98,47 @@ export declare function ref<I extends unknown | Ref<unknown> | undefined | null,
  * shortcut for `Reference.createFromPK(entityType, pk)`
  */
 export declare function ref<I extends unknown | undefined | null, T, PKV extends Primary<T> = Primary<T>>(entityType: EntityClass<T>, pk: I): Ref<T> | AddOptional<typeof pk>;
+/**
+ * Unwraps a reference to its underlying value, returning the entity or scalar. Works on any of:
+ *
+ * - `Ref<T>` / `Reference<T>` (entity) — calls `.unwrap()` to extract the wrapped entity, returns `T`.
+ * - `LazyRef<T>` — type-only marker; runtime value is already `T`, so returned as-is.
+ * - plain entity `T` — returned as-is.
+ * - `ScalarReference<V>` / `ScalarRef<V>` — calls `.unwrap()` to extract the scalar value, returns `V | undefined`
+ *   (a scalar reference may be bound without an initial value).
+ *
+ * Inverse of the {@link ref} helper. Use as a typed escape hatch when you know a relation is populated
+ * but don't want to (or can't) thread `Loaded<T, 'relation'>` through a function signature.
+ *
+ * ```ts
+ * function logAuthor(book: Book) {
+ *   // `book.author` is typed as `LazyRef<Author>`, so `.name` is not directly accessible
+ *   console.log(unref(book.author).name);
+ * }
+ *
+ * // Scalar reference:
+ * const scalar = ref('hello');
+ * unref(scalar); // 'hello' (type: string | undefined)
+ * ```
+ *
+ * Note: `unref` is a compile-time narrowing only for entity refs. On a `LazyRef<T>` or plain entity
+ * relation that is a stub (PK only, never populated), reads of non-PK properties will still return
+ * `undefined` at runtime — same footgun as a plain non-`Ref` relation.
+ */
+export declare function unref<V>(value: ScalarReference<V>): V | undefined;
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T): T;
+/**
+ * Unwraps a reference to its underlying value. Nullable variant — returns `null` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | null): T | null;
+/**
+ * Unwraps a reference to its underlying value. Optional variant — returns `undefined` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | undefined): T | undefined;
+/**
+ * Unwraps a reference to its underlying value. Nullable variant — returns `null`/`undefined` unchanged.
+ */
+export declare function unref<T extends object>(value: Ref<T> | LazyRef<T> | T | null | undefined): T | null | undefined;
 /**
  * shortcut for `Reference.createNakedFromPK(entityType, pk)`
  */

package/entity/Reference.js

@@ -303,6 +303,15 @@ export function ref(entityOrType, pk) {
     }
     return Reference.createFromPK(entityOrType, pk);
 }
+export function unref(value) {
+    if (value == null) {
+        return value;
+    }
+    if (ScalarReference.isScalarReference(value)) {
+        return value.unwrap();
+    }
+    return Reference.unwrapReference(value);
+}
 /**
  * shortcut for `Reference.createNakedFromPK(entityType, pk)`
  */