@mikro-orm/core 7.1.0-dev.10 → 7.1.0-dev.11

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/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)`
  */

package/entity/defineEntity.d.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '../EntityManager.js';
 import type { ColumnType, PropertyOptions, ReferenceOptions, EnumOptions, EmbeddedOptions, ManyToOneOptions, OneToManyOptions, OneToOneOptions, ManyToManyOptions, IndexColumnOptions } from '../metadata/types.js';
-import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, IndexCallback, TriggerCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise, IndexHints } from '../typings.js';
+import type { AnyString, GeneratedColumnCallback, Constructor, CheckCallback, FilterQuery, EntityName, Dictionary, EntityMetadata, PrimaryKeyProp, EntityRepositoryType, Hidden, Opt, Primary, EntityClass, EntitySchemaWithMeta, InferEntity, MaybeReturnType, Ref, LazyRef, IndexCallback, TriggerCallback, FormulaCallback, EntityCtor, IsNever, IWrappedEntity, DefineConfig, Config, MaybePromise, IndexHints } from '../typings.js';
 import type { Raw } from '../utils/RawQueryFragment.js';
 import type { ScalarReference } from './Reference.js';
 import type { SerializeOptions } from '../serialization/EntitySerializer.js';
@@ -12,7 +12,7 @@ import type { Collection } from './Collection.js';
 import type { FilterOptions, FindOptions, FindOneOptions } from '../drivers/IDatabaseDriver.js';
 /** Union of all option keys supported across all property definition types (scalar, enum, embedded, relations). */
 export type UniversalPropertyKeys = keyof PropertyOptions<any> | keyof EnumOptions<any> | keyof EmbeddedOptions<any, any> | keyof ReferenceOptions<any, any> | keyof ManyToOneOptions<any, any> | keyof OneToManyOptions<any, any> | keyof OneToOneOptions<any, any> | keyof ManyToManyOptions<any, any>;
-type BuilderExtraKeys = '~options' | '~type' | '$type' | 'strictNullable';
+type BuilderExtraKeys = '~options' | '~type' | '$type' | 'strictNullable' | 'lazyRef';
 type ExcludeKeys = 'entity' | 'items';
 type BuilderKeys = Exclude<UniversalPropertyKeys, ExcludeKeys> | BuilderExtraKeys;
 type IncludeKeysForProperty = Exclude<keyof PropertyOptions<any>, ExcludeKeys> | BuilderExtraKeys;
@@ -36,9 +36,23 @@ export interface PropertyChain<Value, Options> {
         nullable: true;
         strictNullable: true;
     }>;
-    ref(): PropertyChain<Value, Omit<Options, 'ref'> & {
+    ref(): Options extends {
+        lazyRef: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'ref'> & {
         ref: true;
     }>;
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — direct entity at runtime, type-restricted
+     * until `Loaded<>` narrows it. Type-level only, no `ref: true` wrapping. Not compatible with `.ref()` or
+     * `.mapToPk()` — those chains are rejected in both directions at compile time.
+     */
+    lazyRef(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        ref: true;
+    } | {
+        mapToPk: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'lazyRef'> & {
+        lazyRef: true;
+    }> : never;
     primary(): PropertyChain<Value, Omit<Options, 'primary'> & {
         primary: true;
     }>;
@@ -125,7 +139,9 @@ export interface PropertyChain<Value, Options> {
     owner(): HasKind<Options, '1:1' | 'm:n'> extends true ? PropertyChain<Value, Omit<Options, 'owner'> & {
         owner: true;
     }> : never;
-    mapToPk(): HasKind<Options, 'm:1' | '1:1'> extends true ? PropertyChain<Value, Omit<Options, 'mapToPk'> & {
+    mapToPk(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        lazyRef: true;
+    } ? never : PropertyChain<Value, Omit<Options, 'mapToPk'> & {
         mapToPk: true;
     }> : never;
     orphanRemoval(orphanRemoval?: boolean): HasKind<Options, '1:m' | '1:1'> extends true ? PropertyChain<Value, Options> : never;
@@ -325,9 +341,24 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     /**
      * Enable `ScalarReference` wrapper for lazy values. Use this in combination with `lazy: true` to have a type-safe accessor object in place of the value.
      */
-    ref(): UniversalPropertyOptionsBuilder<Value, Omit<Options, 'ref'> & {
+    ref(): Options extends {
+        lazyRef: true;
+    } ? never : UniversalPropertyOptionsBuilder<Value, Omit<Options, 'ref'> & {
         ref: true;
     }, IncludeKeys>;
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — the runtime value stays a plain entity
+     * (no `Reference` wrapper) but the TypeScript type restricts access to the primary key until `Loaded<>`
+     * narrows it. Type-level only; does not set `ref: true`. Not compatible with `.ref()` or `.mapToPk()` —
+     * those chains are rejected in both directions at compile time.
+     */
+    lazyRef(): HasKind<Options, 'm:1' | '1:1'> extends true ? Options extends {
+        ref: true;
+    } | {
+        mapToPk: true;
+    } ? never : UniversalPropertyOptionsBuilder<Value, Omit<Options, 'lazyRef'> & {
+        lazyRef: true;
+    }, IncludeKeys> : never;
     /**
      * Set to true to omit the property when {@link https://mikro-orm.io/docs/serializing Serializing}.
      */
@@ -512,7 +543,9 @@ export declare class UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys
     /** What to do when the reference to the target entity gets updated. */
     updateRule(updateRule: 'cascade' | 'no action' | 'set null' | 'set default' | AnyString): Pick<UniversalPropertyOptionsBuilder<Value, Options, IncludeKeys>, IncludeKeys>;
     /** Map this relation to the primary key value instead of an entity. */
-    mapToPk(): Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'mapToPk'> & {
+    mapToPk(): Options extends {
+        lazyRef: true;
+    } ? never : Pick<UniversalPropertyOptionsBuilder<Value, Omit<Options, 'mapToPk'> & {
         mapToPk: true;
     }, IncludeKeys>, IncludeKeys>;
     /** Set the constraint type. Immediate constraints are checked for each statement, while deferred ones are only checked at the end of the transaction. Only for postgres unique constraints. */
@@ -738,6 +771,9 @@ type MaybeNullable<Value, Options> = Options extends {
 type MaybeRelationRef<Value, Options> = Options extends {
     mapToPk: true;
 } ? Value : Options extends {
+    lazyRef: true;
+    kind: '1:1' | 'm:1';
+} ? Value extends object ? LazyRef<Value> : never : Options extends {
     ref: true;
     kind: '1:1';
 } ? Value extends object ? Ref<Value> : never : Options extends {

package/entity/defineEntity.js

@@ -173,6 +173,16 @@ export class UniversalPropertyOptionsBuilder {
     ref() {
         return this.assignOptions({ ref: true });
     }
+    /**
+     * Mark a to-one relation (`m:1`/`1:1`) as a {@apilink LazyRef} — the runtime value stays a plain entity
+     * (no `Reference` wrapper) but the TypeScript type restricts access to the primary key until `Loaded<>`
+     * narrows it. Type-level only; does not set `ref: true`. Not compatible with `.ref()` or `.mapToPk()` —
+     * those chains are rejected in both directions at compile time.
+     */
+    lazyRef() {
+        // purely type-level — no runtime metadata change
+        return this;
+    }
     /**
      * Set to true to omit the property when {@link https://mikro-orm.io/docs/serializing Serializing}.
      */

package/index.d.ts

@@ -3,7 +3,7 @@
  * @module core
  */
 export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config, EntityName, IndexHints, } from './typings.js';
-export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, InferEntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, EntityDTOFlat, EntityDTOProp, SerializeDTO, MigrationDiff, GenerateOptions, FilterObject, IndexFilterQuery, ExtractIndexHints, IndexName, IndexColumns, WithUsingOptions, IMigrationRunner, IEntityGenerator, ISeedManager, SeederObject, IMigratorStorage, RequiredEntityData, CheckCallback, TriggerCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, LazyRef, ScalarRef, EntityRef, ISchemaGenerator, MigrationInfo, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, EntityType, FromEntityType, Selected, IsSubset, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, FilterValue, MergeLoaded, MergeSelected, TypeConfig, AnyString, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, RequiredNullable, DefineConfig, Opt, Hidden, EntitySchemaWithMeta, InferEntity, CheckConstraint, TriggerDef, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, PopulateHintOptions, Prefixes, } from './typings.js';
 export * from './enums.js';
 export * from './errors.js';
 export * from './exceptions.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.1.0-dev.10",
+  "version": "7.1.0-dev.11",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/typings.d.ts

@@ -113,7 +113,7 @@ type LoadedReferenceShape<T = any> = ReferenceShape & {
  * Using this instead of `Loadable<any>` in conditional type checks prevents
  * TypeScript from evaluating the full Collection/Reference interfaces.
  */
-type LoadableShape = CollectionShape | ReferenceShape | readonly any[];
+type LoadableShape = CollectionShape | ReferenceShape | LazyRef.Brand<any> | readonly any[];
 /** Gets all keys from all members of a union type (distributes over the union). */
 export type UnionKeys<T> = T extends any ? keyof T : never;
 /** Gets the type of a property from all union members that have it (distributes over the union). */
@@ -467,12 +467,12 @@ type NonArrayObject = object & {
 export type EntityDataProp<T, C extends boolean> = T extends Date ? string | Date : T extends Scalar ? T : T extends ScalarReference<infer U> ? EntityDataProp<U, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? C extends true ? Raw : Runtime : T extends ReferenceShape<infer U> ? EntityDataNested<U, C> : T extends CollectionShape<infer U> ? U | U[] | EntityDataNested<U & object, C> | EntityDataNested<U & object, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? EntityDataNested<U, C> : T extends ReferenceShape<infer U> ? EntityDataNested<U, C> : T extends CollectionShape<infer U> ? U | U[] | EntityDataNested<U & object, C> | EntityDataNested<U & object, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | EntityDataNested<U, C> | EntityDataNested<U, C>[] : U[] | EntityDataNested<U, C>[] : EntityDataNested<T, C>;
 /** Like `EntityDataProp` but used in `RequiredEntityData` context with required/optional key distinction. */
 export type RequiredEntityDataProp<T, O, C extends boolean> = T extends Date ? string | Date : Exclude<T, null> extends RequiredNullable.Brand ? T | null : T extends Scalar ? T : T extends ScalarReference<infer U> ? RequiredEntityDataProp<U, O, C> : T extends {
     __runtime?: infer Runtime;
     __raw?: infer Raw;
-} ? C extends true ? Raw : Runtime : T extends ReferenceShape<infer U> ? RequiredEntityDataNested<U, O, C> : T extends CollectionShape<infer U> ? U | U[] | RequiredEntityDataNested<U & object, O, C> | RequiredEntityDataNested<U & object, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
+} ? C extends true ? Raw : Runtime : T extends LazyRef.Brand<infer U> ? RequiredEntityDataNested<U, O, C> : T extends ReferenceShape<infer U> ? RequiredEntityDataNested<U, O, C> : T extends CollectionShape<infer U> ? U | U[] | RequiredEntityDataNested<U & object, O, C> | RequiredEntityDataNested<U & object, O, C>[] : T extends readonly (infer U)[] ? U extends NonArrayObject ? U | U[] | RequiredEntityDataNested<U, O, C> | RequiredEntityDataNested<U, O, C>[] : U[] | RequiredEntityDataNested<U, O, C>[] : RequiredEntityDataNested<T, O, C>;
 /** Nested entity data shape for embedded or related entities within `EntityData`. */
 export type EntityDataNested<T, C extends boolean = false> = T extends undefined ? never : T extends any[] ? Readonly<T> : EntityData<T, C> | ExpandEntityProp<T, C>;
 type UnwrapScalarRef<T> = T extends ScalarReference<infer U> ? U : T;
@@ -521,6 +521,35 @@ type Relation<T> = {
 export type Rel<T> = T;
 /** Alias for `ScalarReference` (see {@apilink Ref}). */
 export type ScalarRef<T> = ScalarReference<T>;
+/**
+ * Type-level marker for a to-one relation that is **direct at runtime** (no `Reference` wrapper) but
+ * **restricted at compile time** until narrowed via `Loaded<>`.
+ *
+ * Use as the property type on a `@ManyToOne`/`@OneToOne` relation that does **not** have `ref: true`:
+ *
+ * ```ts
+ * @ManyToOne(() => User)
+ * author!: LazyRef<User>;
+ * ```
+ *
+ * Semantics:
+ * - **Runtime**: identical to a plain direct relation — `article.author` is a `User` instance (stub or hydrated),
+ *   `article.author instanceof User` is `true`, no `Reference` object is created.
+ * - **Type (unloaded view)**: only the primary key is accessible. Accessing other properties is a compile error.
+ * - **Type (loaded view)**: once the relation is in the populate hint of a `Loaded<Entity, 'author'>`, it narrows
+ *   back to the full entity — no `.$` or `.get()` indirection needed.
+ *
+ * Note: the safety is purely compile-time. JS code or `as any` casts bypass it.
+ */
+export type LazyRef<T extends object> = IsAny<T> extends true ? LazyRef.Brand<T> : {
+    [K in PrimaryProperty<T> & keyof T]: T[K];
+} & LazyRef.Brand<T>;
+export declare namespace LazyRef {
+    const __lazyRef: unique symbol;
+    interface Brand<T> {
+        [__lazyRef]?: (arg: T) => T;
+    }
+}
 /** Alias for `Reference<T> & { id: number }` (see {@apilink Ref}). */
 export type EntityRef<T extends object> = true extends IsUnknown<PrimaryProperty<T>> ? Reference<T> : IsAny<T> extends true ? Reference<T> : {
     [K in PrimaryProperty<T> & keyof T]: T[K];
@@ -1236,6 +1265,13 @@ export type PopulateHintOptions = {
     orderBy?: QueryOrderMap<any>;
 };
 type ExtractType<T> = T extends CollectionShape<infer U> ? U : T extends ReferenceShape<infer U> ? U : T extends Ref<infer U> ? U : T extends readonly (infer U)[] ? U : T;
+/**
+ * Like {@link ExtractType} but also unwraps {@link LazyRef}. Kept separate so {@link ExtractType}'s
+ * hot path (used by `IsOptional`, `EntityData`, `RequiredEntityData`) doesn't pay the cost of the
+ * extra branch — those contexts handle `LazyRef` in their own earlier branches (see
+ * `EntityDataProp` / `RequiredEntityDataProp`) before delegating to `ExtractType`.
+ */
+type ExtractTypeWithLazyRef<T> = T extends LazyRef.Brand<infer U> ? U : ExtractType<T>;
 type ExtractStringKeys<T> = {
     [K in keyof T]-?: CleanKeys<T, K>;
 }[keyof T] & {};
@@ -1243,8 +1279,8 @@ type ExtractStringKeys<T> = {
  * Extracts string keys from an entity type, handling Collection/Reference wrappers.
  * Simplified to just check `T extends object` since ExtractType handles the unwrapping.
  */
-type StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractType<T>> | E : never;
-type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractType<T[K]> : K extends E ? keyof T : never;
+type StringKeys<T, E extends string = never> = T extends object ? ExtractStringKeys<ExtractTypeWithLazyRef<T>> | E : never;
+type GetStringKey<T, K extends StringKeys<T, string>, E extends string> = K extends keyof T ? ExtractTypeWithLazyRef<T[K]> : K extends E ? keyof T : never;
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 type RelationKeys<T> = T extends object ? {
     [K in keyof T]-?: CleanKeys<T, K, true>;
@@ -1259,8 +1295,8 @@ export type UnboxArray<T> = T extends any[] ? ArrayElement<T> : T;
 /** Extracts the element type from an array type. */
 export type ArrayElement<ArrayType extends unknown[]> = ArrayType extends (infer ElementType)[] ? ElementType : never;
 /** Unwraps a property type from its wrapper (Reference, Collection, or array) to the inner entity type. */
-export type ExpandProperty<T> = T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
-type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
+export type ExpandProperty<T> = T extends LazyRef.Brand<infer U> ? NonNullable<U> : T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
+type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends LazyRef.Brand<any> ? E : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
 type IsTrue<T> = IsNever<T> extends true ? false : T extends boolean ? (T extends true ? true : false) : false;
 type StringLiteral<T> = T extends string ? (string extends T ? never : T) : never;
 type Prefix<T, K> = K extends `${infer S}.${string}` ? S : K extends '*' ? keyof T : K;
@@ -1294,7 +1330,7 @@ export type MergeSelected<T, U, F extends string> = IsLoadedType<T> extends true
 export type MergeLoaded<T, U, P extends string, F extends string, E extends string, R extends boolean = false> = IsLoadedType<T> extends true ? T & Loaded<U, P, F, E> : Loaded<T, P, F, E>;
 /** Extracts the nullability modifiers (`null`, `undefined`, or both) from a type `T`. */
 export type AddOptional<T> = undefined | null extends T ? null | undefined : null extends T ? null : undefined extends T ? undefined : never;
-type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractType<T>, L, F, E>>;
+type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractTypeWithLazyRef<T>, L, F, E>>;
 /** Extracts the eager-loaded property names declared via `[EagerProps]` as a string union. */
 export type AddEager<T> = ExtractEagerProps<T> & string;
 /** Combines an explicit populate hint `L` with the entity's eagerly loaded properties. */

package/utils/Utils.js

@@ -141,7 +141,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.1.0-dev.10';
+    static #ORM_VERSION = '7.1.0-dev.11';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */