@mikro-orm/core 7.1.0-dev.1 → 7.1.0-dev.3

package/EntityManager.d.ts

@@ -307,6 +307,25 @@ export declare class EntityManager<Driver extends IDatabaseDriver = IDatabaseDri
      * Fires native insert query. Calling this has no side effects on the context (identity map).
      */
     insert<Entity extends object>(entityNameOrEntity: EntityName<Entity> | Entity, data?: RequiredEntityData<Entity> | Entity, options?: NativeInsertUpdateOptions<Entity>): Promise<Primary<Entity>>;
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     * Returns the cloned entity, registered in the identity map.
+     *
+     * @example
+     * ```ts
+     * // Clone by entity class + where + overrides
+     * const cloned = await em.clone(Author, { id: 1 }, { email: 'new@email.com' });
+     *
+     * // Pure clone (all non-PK fields copied)
+     * const cloned = await em.clone(Author, { id: 1 });
+     *
+     * // Clone a loaded entity
+     * const author = await em.findOneOrFail(Author, 1);
+     * const cloned = await em.clone(author, { email: 'new@email.com' });
+     * ```
+     */
+    clone<Entity extends object>(entityNameOrEntity: EntityName<Entity> | Entity, whereOrOverrides?: FilterQuery<NoInfer<Entity>> | EntityData<Entity>, overridesOrOptions?: EntityData<Entity> | NativeInsertUpdateOptions<Entity>, options?: NativeInsertUpdateOptions<Entity>): Promise<Entity>;
     /**
      * Fires native multi-insert query. Calling this has no side effects on the context (identity map).
      */

package/EntityManager.js

@@ -1211,6 +1211,54 @@ export class EntityManager {
         });
         return res.insertId;
     }
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     * Returns the cloned entity, registered in the identity map.
+     *
+     * @example
+     * ```ts
+     * // Clone by entity class + where + overrides
+     * const cloned = await em.clone(Author, { id: 1 }, { email: 'new@email.com' });
+     *
+     * // Pure clone (all non-PK fields copied)
+     * const cloned = await em.clone(Author, { id: 1 });
+     *
+     * // Clone a loaded entity
+     * const author = await em.findOneOrFail(Author, 1);
+     * const cloned = await em.clone(author, { email: 'new@email.com' });
+     * ```
+     */
+    async clone(entityNameOrEntity, whereOrOverrides, overridesOrOptions, options) {
+        const em = this.getContext(false);
+        let entityName;
+        let where;
+        let overrides;
+        if (Utils.isEntity(entityNameOrEntity)) {
+            // clone(entity, overrides?, options?)
+            entityName = entityNameOrEntity.constructor;
+            where = helper(entityNameOrEntity).getPrimaryKey();
+            overrides = whereOrOverrides;
+            options = overridesOrOptions;
+        }
+        else {
+            // clone(EntityClass, where, overrides?, options?)
+            entityName = entityNameOrEntity;
+            where = whereOrOverrides;
+            overrides = overridesOrOptions;
+        }
+        options ??= {};
+        em.prepareOptions(options);
+        const meta = em.metadata.get(entityName);
+        const res = await em.driver.nativeClone(entityName, where, overrides, {
+            ctx: em.#transactionContext,
+            ...options,
+        });
+        const pk = res.insertId ?? res.row?.[meta.primaryKeys[0]];
+        return em.findOneOrFail(entityName, pk, {
+            schema: options.schema,
+        });
+    }
     /**
      * Fires native multi-insert query. Calling this has no side effects on the context (identity map).
      */

package/drivers/DatabaseDriver.d.ts

@@ -28,6 +28,7 @@ export declare abstract class DatabaseDriver<C extends Connection> implements ID
     abstract nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
     abstract nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: DeleteOptions<T>): Promise<QueryResult<T>>;
+    nativeClone<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, overrides?: EntityData<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     abstract count<T extends object, P extends string = never>(entityName: EntityName<T>, where: FilterQuery<T>, options?: CountOptions<T, P>): Promise<number>;
     /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext?: boolean): this[typeof EntityManagerType];

package/drivers/DatabaseDriver.js

@@ -27,6 +27,9 @@ export class DatabaseDriver {
     async nativeUpdateMany(entityName, where, data, options) {
         throw new Error(`Batch updates are not supported by ${this.constructor.name} driver`);
     }
+    async nativeClone(entityName, where, overrides, options) {
+        throw new Error(`${this.constructor.name} does not support nativeClone`);
+    }
     /** Creates a new EntityManager instance bound to this driver. */
     createEntityManager(useContext) {
         const EntityManagerClass = this.config.get('entityManager', EntityManager);

package/drivers/IDatabaseDriver.d.ts

@@ -52,6 +52,11 @@ export interface IDatabaseDriver<C extends Connection = Connection> {
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>): Promise<QueryResult<T>>;
     /** Deletes rows matching the given condition. */
     nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, options?: NativeDeleteOptions<T>): Promise<QueryResult<T>>;
+    /**
+     * Clones rows matching the condition at the database level via INSERT...SELECT.
+     * Automatically excludes auto-increment PKs, generated columns, and resets version properties.
+     */
+    nativeClone<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, overrides?: EntityData<T>, options?: NativeInsertUpdateOptions<T>): Promise<QueryResult<T>>;
     /** Persists changes to M:N collections (inserts/deletes pivot table rows). */
     syncCollections<T extends object, O extends object>(collections: Iterable<Collection<T, O>>, options?: DriverMethodOptions): Promise<void>;
     /** Counts entities matching the given condition. */

package/entity/BaseEntity.d.ts

@@ -1,5 +1,5 @@
 import { type Ref } from './Reference.js';
-import type { AutoPath, EntityData, EntityDTO, Loaded, LoadedReference, AddEager, EntityKey, FromEntityType, IsSubset, MergeSelected, SerializeDTO } from '../typings.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';
 import { type SerializeOptions } from '../serialization/EntitySerializer.js';
@@ -80,7 +80,7 @@ export declare abstract class BaseEntity {
     /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO<Entity extends this = this>(): EntityDTO<Entity>;
     /** Serializes the entity with control over which relations and fields to include or exclude. */
-    serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude>): SerializeDTO<Naked, Hint, Exclude>;
+    serialize<Entity extends this = this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never, Fields extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude, Fields>): SerializeDTO<Naked, Hint, Exclude, never, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;
     /** Assigns the given data to this entity, updating its properties and relations. */
     assign<Entity extends this, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(data: Data & IsSubset<EntityData<Naked>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
     /** Initializes (refreshes) the entity by reloading it from the database. Returns null if not found. */

package/entity/WrappedEntity.d.ts

@@ -1,6 +1,6 @@
 import type { PopulatePath } from '../enums.js';
 import type { EntityManager } from '../EntityManager.js';
-import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, SerializeDTO, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
+import type { Dictionary, EntityData, EntityDictionary, EntityMetadata, IHydrator, EntityKey, PopulateOptions, Primary, AutoPath, Ref, AddEager, LoadedReference, EntityDTO, Loaded, ExtractFieldsHint, ResolveSerializeFields, SerializeDTO, SerializeFieldsKeepPK, FromEntityType, IsSubset, MergeSelected } from '../typings.js';
 import { Reference } from './Reference.js';
 import { type AssignOptions } from './EntityAssigner.js';
 import type { EntityLoaderOptions } from './EntityLoader.js';
@@ -54,7 +54,7 @@ export declare class WrappedEntity<Entity extends object> {
     /** Converts the entity to a plain object representation, optionally excluding specified fields. */
     toObject<Ignored extends EntityKey<Entity> = never>(ignoreFields?: Ignored[]): Omit<EntityDTO<Entity>, Ignored>;
     /** Serializes the entity with control over which relations and fields to include or exclude. */
-    serialize<Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Entity, Hint, Exclude>): SerializeDTO<Entity, Hint, Exclude>;
+    serialize<Hint extends string = never, Exclude extends string = never, Fields extends string = never>(options?: SerializeOptions<FromEntityType<Entity>, Hint, Exclude, Fields>): SerializeDTO<FromEntityType<Entity>, Hint, Exclude, never, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;
     /** Converts the entity to a plain object, including all properties regardless of serialization rules. */
     toPOJO(): EntityDTO<Entity>;
     /** Serializes the entity using its `toJSON` method (supports `JSON.stringify`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.1.0-dev.1",
+  "version": "7.1.0-dev.3",
   "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/serialization/EntitySerializer.d.ts

@@ -1,21 +1,33 @@
-import type { ArrayElement, AutoPath, CleanTypeConfig, ExtractFieldsHint, FromEntityType, SerializeDTO, TypeConfig, UnboxArray } from '../typings.js';
+import type { ArrayElement, AutoPath, CleanTypeConfig, ExtractFieldsHint, FromEntityType, ResolveSerializeFields, SerializeDTO, SerializeFieldsKeepPK, TypeConfig, UnboxArray } from '../typings.js';
 import { type PopulatePath } from '../enums.js';
-/** Converts entity instances to plain DTOs via `serialize()`, with fine-grained control over populate, exclude, and serialization groups. */
+/** Converts entity instances to plain DTOs via `serialize()`, with fine-grained control over populate, exclude, fields, and serialization groups. */
 export declare class EntitySerializer {
-    /** Serializes an entity to a plain DTO, with fine-grained control over population, exclusion, groups, and custom types. */
-    static serialize<T extends object, P extends string = never, E extends string = never>(entity: T, options?: SerializeOptions<T, P, E>): SerializeDTO<T, P, E>;
+    /** Serializes an entity to a plain DTO, with fine-grained control over population, exclusion, fields, groups, and custom types. */
+    static serialize<T extends object, P extends string = never, E extends string = never, F extends string = never>(entity: T, options?: SerializeOptions<T, P, E, F>): SerializeDTO<T, P, E, never, ResolveSerializeFields<F>, SerializeFieldsKeepPK<F>>;
     private static propertyName;
     private static processProperty;
     private static processCustomType;
     private static extractChildOptions;
+    /**
+     * Extracts the nested `fields` whitelist for a child property. A bare parent name (`fields: ['books']`) or a
+     * wildcard removes the whitelist on the sub-tree (everything is included), so consumers don't have to repeat
+     * every field of the child. Otherwise dot-paths are stripped of the parent prefix and passed down.
+     */
+    private static extractChildFields;
     private static processEntity;
     private static processCollection;
 }
-export interface SerializeOptions<T, P extends string = never, E extends string = never> {
+export interface SerializeOptions<T, P extends string = never, E extends string = never, F extends string = never> {
     /** Specify which relation should be serialized as populated and which as a FK. */
     populate?: readonly AutoPath<T, P, `${PopulatePath.ALL}`>[];
     /** Specify which properties should be omitted. */
     exclude?: readonly AutoPath<T, E>[];
+    /**
+     * Whitelist of properties to serialize, supports dot-paths (e.g. `['name', 'books.title']`). When set, only the
+     * listed properties end up in the output, including primary keys. A bare property name keeps its entire sub-tree;
+     * a dot-path additionally narrows the nested object to the listed sub-keys. `exclude` takes precedence on conflict.
+     */
+    fields?: readonly AutoPath<T, F, `${PopulatePath.ALL}`>[];
     /** Enforce unpopulated references to be returned as objects, e.g. `{ author: { id: 1 } }` instead of `{ author: 1 }`. */
     forceObject?: boolean;
     /** Ignore custom property serializers. */
@@ -41,4 +53,4 @@ export interface SerializeOptions<T, P extends string = never, E extends string
  * const dto2 = wrap(user).serialize({ exclude: ['id', 'email'], forceObject: true });
  * ```
  */
-export declare function serialize<Entity extends object, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Populate extends string = never, Exclude extends string = never, Config extends TypeConfig = never>(entity: Entity, options?: Config & SerializeOptions<UnboxArray<Entity>, Populate, Exclude>): Naked extends object[] ? SerializeDTO<ArrayElement<Naked>, Populate, Exclude, CleanTypeConfig<Config>>[] : SerializeDTO<Naked, Populate, Exclude, CleanTypeConfig<Config>, ExtractFieldsHint<Entity>>;
+export declare function serialize<Entity extends object, Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Populate extends string = never, Exclude extends string = never, Fields extends string = never, Config extends TypeConfig = never>(entity: Entity, options?: Config & SerializeOptions<UnboxArray<Entity>, Populate, Exclude, Fields>): Naked extends object[] ? SerializeDTO<ArrayElement<Naked>, Populate, Exclude, CleanTypeConfig<Config>, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>[] : SerializeDTO<Naked, Populate, Exclude, CleanTypeConfig<Config>, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;

package/serialization/EntitySerializer.js

@@ -4,13 +4,19 @@ import { ReferenceKind } from '../enums.js';
 import { Reference } from '../entity/Reference.js';
 import { SerializationContext } from './SerializationContext.js';
 import { isRaw } from '../utils/RawQueryFragment.js';
+/** Returns true when any entry in `items` is `propName`, the wildcard `*`, or a dot-path under `propName`. */
+function matchesPath(items, propName) {
+    return items.some(item => item === propName || item === '*' || item.startsWith(propName + '.'));
+}
 function isVisible(meta, propName, options) {
     const prop = meta.properties[propName];
     if (options.groups && prop?.groups) {
         return prop.groups.some(g => options.groups.includes(g));
     }
-    if (Array.isArray(options.populate) &&
-        options.populate?.find(item => item === propName || item.startsWith(propName + '.') || item === '*')) {
+    if (Array.isArray(options.fields) && options.fields.length > 0 && !matchesPath(options.fields, propName)) {
+        return false;
+    }
+    if (Array.isArray(options.populate) && matchesPath(options.populate, propName)) {
         return true;
     }
     if (options.exclude?.find(item => item === propName)) {
@@ -22,7 +28,8 @@ function isVisible(meta, propName, options) {
 }
 function isPopulated(propName, options) {
     if (typeof options.populate !== 'boolean' &&
-        options.populate?.find(item => item === propName || item.startsWith(propName + '.') || item === '*')) {
+        Array.isArray(options.populate) &&
+        matchesPath(options.populate, propName)) {
         return true;
     }
     if (typeof options.populate === 'boolean') {
@@ -30,9 +37,9 @@ function isPopulated(propName, options) {
     }
     return false;
 }
-/** Converts entity instances to plain DTOs via `serialize()`, with fine-grained control over populate, exclude, and serialization groups. */
+/** Converts entity instances to plain DTOs via `serialize()`, with fine-grained control over populate, exclude, fields, and serialization groups. */
 export class EntitySerializer {
-    /** Serializes an entity to a plain DTO, with fine-grained control over population, exclusion, groups, and custom types. */
+    /** Serializes an entity to a plain DTO, with fine-grained control over population, exclusion, fields, groups, and custom types. */
     static serialize(entity, options = {}) {
         const wrapped = helper(entity);
         const meta = wrapped.__meta;
@@ -184,8 +191,27 @@ export class EntitySerializer {
                 ? Utils.extractChildElements(options.populate, prop, '*')
                 : options.populate,
             exclude: Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop) : options.exclude,
+            fields: Array.isArray(options.fields) ? this.extractChildFields(options.fields, prop) : options.fields,
         };
     }
+    /**
+     * Extracts the nested `fields` whitelist for a child property. A bare parent name (`fields: ['books']`) or a
+     * wildcard removes the whitelist on the sub-tree (everything is included), so consumers don't have to repeat
+     * every field of the child. Otherwise dot-paths are stripped of the parent prefix and passed down.
+     */
+    static extractChildFields(fields, prop) {
+        const out = [];
+        const dotPrefix = prop + '.';
+        for (const field of fields) {
+            if (field === prop || field === '*') {
+                return undefined;
+            }
+            if (field.startsWith(dotPrefix)) {
+                out.push(field.substring(dotPrefix.length));
+            }
+        }
+        return out;
+    }
     static processEntity(prop, entity, platform, options) {
         const child = Reference.unwrapReference(entity[prop.name]);
         const wrapped = helper(child);

package/typings.d.ts

@@ -341,7 +341,7 @@ export interface IWrappedEntity<Entity extends object> {
     toObject<Ignored extends EntityKey<Entity>>(ignoreFields: Ignored[]): Omit<EntityDTO<Entity>, Ignored>;
     toJSON(...args: any[]): EntityDTO<Entity>;
     toPOJO(): EntityDTO<Entity>;
-    serialize<Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude>): SerializeDTO<Naked, Hint, Exclude>;
+    serialize<Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Hint extends string = never, Exclude extends string = never, Fields extends string = never>(options?: SerializeOptions<Naked, Hint, Exclude, Fields>): SerializeDTO<Naked, Hint, Exclude, never, ResolveSerializeFields<Fields, ExtractFieldsHint<Entity>>, SerializeFieldsKeepPK<Fields>>;
     setSerializationContext<Hint extends string = never, Fields extends string = never, Exclude extends string = never>(options: LoadHint<Entity, Hint, Fields, Exclude>): void;
     assign<Naked extends FromEntityType<Entity> = FromEntityType<Entity>, Convert extends boolean = false, Data extends EntityData<Naked, Convert> | Partial<EntityDTO<Naked>> = EntityData<Naked, Convert> | Partial<EntityDTO<Naked>>>(data: Data & IsSubset<EntityData<Naked, Convert>, Data>, options?: AssignOptions<Convert>): MergeSelected<Entity, Naked, keyof Data & string>;
     getSchema(): string | undefined;
@@ -534,17 +534,32 @@ export type EntityDTOFlat<T, C extends TypeConfig = never> = {
 type SerializeTopHints<H extends string> = H extends `${infer Top}.${string}` ? Top : H;
 type SerializeSubHints<K extends string, H extends string> = H extends `${K}.${infer Rest}` ? Rest : never;
 type SerializeSubFields<K extends string, F extends string> = K extends F ? '*' : [F extends `${K & string}.${infer Rest}` ? Rest : never] extends [never] ? '*' : F extends `${K & string}.${infer Rest}` ? Rest : never;
-type SerializeFieldsFilter<T, K extends keyof T, F extends string> = K extends Prefix<T, F> | PrimaryProperty<T> ? K : never;
+type SerializeFieldsFilter<T, K extends keyof T, F extends string, KeepPK extends boolean = true> = K extends Prefix<T, F> | (KeepPK extends true ? PrimaryProperty<T> : never) ? K : never;
 type SerializePropValue<T, K extends keyof T, H extends string, C extends TypeConfig = never> = K & string extends SerializeTopHints<H> ? NonNullable<T[K]> extends CollectionShape<infer U> ? SerializeDTO<U & object, SerializeSubHints<K & string, H>, never, C>[] : SerializeDTO<ExpandProperty<T[K]>, SerializeSubHints<K & string, H>, never, C> | Extract<T[K], null | undefined> : EntityDTOProp<T, T[K], C>;
-type SerializePropValueWithFields<T, K extends keyof T, H extends string, C extends TypeConfig, F extends string> = K & string extends SerializeTopHints<H> ? NonNullable<T[K]> extends CollectionShape<infer U> ? SerializeDTO<U & object, SerializeSubHints<K & string, H>, never, C, SerializeSubFields<K & string, F>>[] : SerializeDTO<ExpandProperty<T[K]>, SerializeSubHints<K & string, H>, never, C, SerializeSubFields<K & string, F>> | Extract<T[K], null | undefined> : EntityDTOProp<T, T[K], C>;
+type SerializePropValueWithFields<T, K extends keyof T, H extends string, C extends TypeConfig, F extends string, KeepPK extends boolean = true> = K & string extends SerializeTopHints<H> ? NonNullable<T[K]> extends CollectionShape<infer U> ? SerializeDTO<U & object, SerializeSubHints<K & string, H>, never, C, SerializeSubFields<K & string, F>, KeepPK>[] : SerializeDTO<ExpandProperty<T[K]>, SerializeSubHints<K & string, H>, never, C, SerializeSubFields<K & string, F>, KeepPK> | Extract<T[K], null | undefined> : EntityDTOProp<T, T[K], C>;
+/**
+ * Resolves a user-provided `Fields` generic to the value passed to `SerializeDTO`'s `F` parameter:
+ * `never` (no `fields` option) falls back to `Default` (typically `'*'` or the entity's `ExtractFieldsHint`).
+ */
+export type ResolveSerializeFields<Fields extends string, Default extends string = '*'> = [Fields] extends [never] ? Default : Fields;
+/**
+ * Whether the explicit `serialize()` path should keep primary keys in the output. When the user does not provide
+ * a `fields` option (`Fields = never`), behave like `toObject()` and keep PKs; when they do, treat it as a strict
+ * whitelist so PKs are dropped unless listed.
+ */
+export type SerializeFieldsKeepPK<Fields extends string> = [Fields] extends [never] ? true : false;
 /**
  * Return type of `serialize()`. Combines Loaded + EntityDTO in a single pass for better performance.
  * Respects populate hints (`H`), exclude hints (`E`), and fields hints (`F`).
+ *
+ * `KeepPK` controls whether primary keys are auto-included when narrowing by `F`. The `toObject()` path keeps the
+ * default `true` (PKs always present); the explicit `serialize()` path passes `false` so the user-provided `fields`
+ * option is a strict whitelist that can drop PKs from the output.
  */
-export type SerializeDTO<T, H extends string = never, E extends string = never, C extends TypeConfig = never, F extends string = '*'> = string extends H ? EntityDTOFlat<T, C> : [F] extends ['*'] ? {
+export type SerializeDTO<T, H extends string = never, E extends string = never, C extends TypeConfig = never, F extends string = '*', KeepPK extends boolean = true> = string extends H ? EntityDTOFlat<T, C> : [F] extends ['*'] ? {
     [K in keyof T as ExcludeHidden<T, K> & CleanKeys<T, K> & (IsNever<E> extends true ? K : Exclude<K, E>)]: SerializePropValue<T, K, H, C> | Extract<T[K], null | undefined>;
 } : {
-    [K in keyof T as ExcludeHidden<T, K> & CleanKeys<T, K> & (IsNever<E> extends true ? K : Exclude<K, E>) & SerializeFieldsFilter<T, K, F>]: SerializePropValueWithFields<T, K, H, C, F> | Extract<T[K], null | undefined>;
+    [K in keyof T as ExcludeHidden<T, K> & CleanKeys<T, K> & (IsNever<E> extends true ? K : Exclude<K, E>) & SerializeFieldsFilter<T, K, F, KeepPK>]: SerializePropValueWithFields<T, K, H, C, F, KeepPK> | Extract<T[K], null | undefined>;
 };
 type TargetKeys<T> = T extends EntityClass<infer P> ? keyof P : keyof T;
 type PropertyName<T> = IsUnknown<T> extends false ? TargetKeys<T> : string;

package/utils/Utils.d.ts

@@ -117,7 +117,7 @@ export declare class Utils {
      * Gets string name of given class.
      */
     static className<T>(classOrName: string | EntityName<T>): string;
-    static extractChildElements(items: string[], prefix: string, allSymbol?: string): string[];
+    static extractChildElements(items: readonly string[], prefix: string, allSymbol?: string): string[];
     /**
      * Tries to detect TypeScript support.
      */

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.1';
+    static #ORM_VERSION = '7.1.0-dev.3';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */