@mikro-orm/core 7.0.0-dev.251 → 7.0.0-dev.253

package/EntityManager.d.ts

@@ -515,7 +515,7 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
     private lockAndPopulate;
     private buildFields;
     /** @internal */
-    preparePopulate<Entity extends object>(entityName: EntityName<Entity>, options: Pick<FindOptions<Entity, any, any, any>, 'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude'>, validate?: boolean): Promise<PopulateOptions<Entity>[]>;
+    preparePopulate<Entity extends object>(entityName: EntityName<Entity>, options: Pick<FindOptions<Entity, any, any, any>, 'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude' | 'populateHints'>, validate?: boolean): Promise<PopulateOptions<Entity>[]>;
     /**
      * when the entity is found in identity map, we check if it was partially loaded or we are trying to populate
      * some additional lazy properties, if so, we reload and merge the data from database

package/EntityManager.js

@@ -17,7 +17,7 @@ import { EventType, FlushMode, LoadStrategy, LockMode, PopulateHint, PopulatePat
 import { EventManager } from './events/EventManager.js';
 import { TransactionEventBroadcaster } from './events/TransactionEventBroadcaster.js';
 import { OptimisticLockError, ValidationError } from './errors.js';
-import { getLoadingStrategy } from './entity/utils.js';
+import { applyPopulateHints, getLoadingStrategy } from './entity/utils.js';
 import { TransactionManager } from './utils/TransactionManager.js';
 /**
  * The EntityManager is the central access point to ORM functionality. It is a facade to all different ORM subsystems
@@ -1683,12 +1683,15 @@ export class EntityManager {
             throw ValidationError.invalidPropertyName(entityName, invalid.field);
         }
         await this.autoJoinRefsForFilters(meta, { ...options, populate });
-        return populate.map(field => {
+        for (const field of populate) {
             // force select-in strategy when populating all relations as otherwise we could cause infinite loops when self-referencing
             const all = field.all ?? (Array.isArray(options.populate) && options.populate.includes('*'));
             field.strategy = all ? LoadStrategy.SELECT_IN : (options.strategy ?? field.strategy);
-            return field;
-        });
+        }
+        if (options.populateHints) {
+            applyPopulateHints(populate, options.populateHints);
+        }
+        return populate;
     }
     /**
      * when the entity is found in identity map, we check if it was partially loaded or we are trying to populate

package/drivers/IDatabaseDriver.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionType, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName } from '../typings.js';
+import type { ConnectionType, EntityData, EntityMetadata, EntityProperty, FilterQuery, Primary, Dictionary, IPrimaryKey, PopulateOptions, EntityDictionary, AutoPath, ObjectQuery, FilterObject, Populate, EntityName, PopulateHintOptions, Prefixes } from '../typings.js';
 import type { 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';
@@ -107,6 +107,10 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
     populateFilter?: ObjectQuery<Entity>;
     /** Used for ordering of the populate queries. If not specified, the value of `options.orderBy` is used. */
     populateOrderBy?: OrderDefinition<Entity>;
+    /** Per-relation overrides for populate loading behavior. Keys are populate paths (same as used in `populate`). */
+    populateHints?: [Hint] extends [never] ? never : {
+        [K in Prefixes<Hint>]?: PopulateHintOptions;
+    };
     /** Ordering of the results.Can be an object or array of objects, keys are property names, values are ordering (asc/desc) */
     orderBy?: OrderDefinition<Entity>;
     /** Control result caching for this query. Result cache is by default disabled, not to be confused with the identity map. */

package/entity/utils.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMetadata, PopulateOptions } from '../typings.js';
+import type { EntityMetadata, PopulateHintOptions, PopulateOptions } from '../typings.js';
 import { LoadStrategy, ReferenceKind } from '../enums.js';
 /**
  * @internal
@@ -10,3 +10,8 @@ export declare function expandDotPaths<Entity>(meta: EntityMetadata<Entity>, pop
  * @internal
  */
 export declare function getLoadingStrategy(strategy: LoadStrategy | `${LoadStrategy}`, kind: ReferenceKind): LoadStrategy.SELECT_IN | LoadStrategy.JOINED;
+/**
+ * Applies per-relation overrides from `populateHints` to the normalized populate tree.
+ * @internal
+ */
+export declare function applyPopulateHints<Entity>(populate: PopulateOptions<Entity>[], hints: Record<string, PopulateHintOptions>): void;

package/entity/utils.js

@@ -67,3 +67,36 @@ export function getLoadingStrategy(strategy, kind) {
     }
     return strategy;
 }
+/**
+ * Applies per-relation overrides from `populateHints` to the normalized populate tree.
+ * @internal
+ */
+export function applyPopulateHints(populate, hints) {
+    for (const [path, hint] of Object.entries(hints)) {
+        const entry = findPopulateEntry(populate, path.split('.'));
+        if (!entry) {
+            continue;
+        }
+        if (hint.strategy != null) {
+            entry.strategy = hint.strategy;
+        }
+        if (hint.joinType != null) {
+            entry.joinType = hint.joinType;
+        }
+    }
+}
+function findPopulateEntry(populate, parts) {
+    let current = populate;
+    for (let i = 0; i < parts.length; i++) {
+        const entry = current.find(p => p.field.split(':')[0] === parts[i]);
+        if (!entry) {
+            return undefined;
+        }
+        if (i === parts.length - 1) {
+            return entry;
+        }
+        current = (entry.children ?? []);
+    }
+    /* v8 ignore next */
+    return undefined;
+}

package/index.d.ts

@@ -3,7 +3,7 @@
  * @module core
  */
 export { EntityMetadata, PrimaryKeyProp, EntityRepositoryType, OptionalProps, EagerProps, HiddenProps, Config } from './typings.js';
-export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, RequiredEntityData, CheckCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, 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, GeneratedColumnCallback, FilterDef, EntityCtor, Subquery, } from './typings.js';
+export type { CompiledFunctions, Constructor, ConnectionType, Dictionary, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, RequiredEntityData, CheckCallback, IndexCallback, FormulaCallback, FormulaTable, SchemaTable, SchemaColumns, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, 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, 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,7 +1,7 @@
 {
   "name": "@mikro-orm/core",
   "type": "module",
-  "version": "7.0.0-dev.251",
+  "version": "7.0.0-dev.253",
   "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.",
   "exports": {
     "./package.json": "./package.json",

package/typings.d.ts

@@ -151,7 +151,7 @@ declare const __loadHint: unique symbol;
  * This reflects that loading 'a.b.c' means 'a' and 'a.b' are also loaded.
  * Special case: '*' returns string to ensure Loaded<T, '*'> is assignable to any Loaded<T, Hint>.
  */
-type Prefixes<S extends string> = S extends '*' ? string : S extends `${infer H}.${infer T}` ? H | `${H}.${Prefixes<T>}` : S;
+export type Prefixes<S extends string> = S extends '*' ? string : S extends `${infer H}.${infer T}` ? H | `${H}.${Prefixes<T>}` : S;
 export type UnwrapPrimary<T> = T extends Scalar ? T : T extends ReferenceShape<infer U> ? Primary<U> : Primary<T>;
 type PrimaryPropToType<T, Keys extends (keyof T)[]> = {
     [Index in keyof Keys]: UnwrapPrimary<T[Keys[Index]]>;
@@ -924,6 +924,10 @@ export type PopulateOptions<T> = {
     /** When true, ignores `mapToPk` on the property and returns full entity data instead of just PKs. */
     dataOnly?: boolean;
 };
+export type PopulateHintOptions = {
+    strategy?: LoadStrategy.JOINED | LoadStrategy.SELECT_IN | 'joined' | 'select-in';
+    joinType?: 'inner join' | 'left join';
+};
 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;
 type ExtractStringKeys<T> = {
     [K in keyof T]-?: CleanKeys<T, K>;

package/utils/Utils.js

@@ -123,7 +123,7 @@ export function parseJsonSafe(value) {
 }
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.0.0-dev.251';
+    static #ORM_VERSION = '7.0.0-dev.253';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */