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

package/metadata/MetadataDiscovery.js

@@ -159,6 +159,7 @@ export class MetadataDiscovery {
         forEachProp((m, p) => this.initGeneratedColumn(m, p));
         filtered.forEach(meta => this.initAutoincrement(meta)); // once again after we init custom types
         filtered.forEach(meta => this.initCheckConstraints(meta));
+        filtered.forEach(meta => this.initTriggers(meta));
         forEachProp((_m, p) => {
             this.initDefaultValue(p);
             this.inferTypeFromDefault(p);
@@ -479,17 +480,28 @@ export class MetadataDiscovery {
             prop.polymorphic = prop2.polymorphic;
             prop.discriminator = prop2.discriminator;
             prop.discriminatorColumn = prop2.discriminatorColumn;
-            prop.discriminatorValue = prop2.discriminatorValue;
+            // For a union-target pivot each inverse side sits on one specific target class, so its
+            // discriminator value is that class's tableName. For Rails-style, prop2 has a single fixed value.
+            prop.discriminatorValue = QueryHelper.isUnionTargetPolymorphic(prop2) ? meta.tableName : prop2.discriminatorValue;
         }
         prop.referencedColumnNames ??= Utils.flatten(meta.primaryKeys.map(primaryKey => meta.properties[primaryKey].fieldNames));
-        // For polymorphic M:N, use discriminator base name for FK column (e.g., taggable_id instead of post_id)
-        if (prop.polymorphic && prop.discriminator) {
+        // Union-target polymorphic M:N: owner side is fixed (real FK), target side uses discriminator-derived names.
+        const isUnionTargetMN = QueryHelper.isUnionTargetPolymorphic(prop);
+        if (prop.polymorphic && prop.discriminator && !isUnionTargetMN) {
+            // Rails-style: owner side is polymorphic, uses discriminator base name (e.g. taggable_id instead of post_id)
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, referencedColumnName, prop.referencedColumnNames.length > 1));
         }
         else {
             prop.joinColumns ??= prop.referencedColumnNames.map(referencedColumnName => this.#namingStrategy.joinKeyColumnName(meta.root.className, referencedColumnName, meta.compositePK));
         }
-        prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        if (isUnionTargetMN) {
+            // Target side uses discriminator base name (e.g. attachable_id — shared across Image/Video)
+            const targetPkCols = Utils.flatten(meta2.primaryKeys.map(pk => meta2.properties[pk].fieldNames));
+            prop.inverseJoinColumns ??= targetPkCols.map(fieldName => this.#namingStrategy.joinKeyColumnName(prop.discriminator, fieldName, targetPkCols.length > 1));
+        }
+        else {
+            prop.inverseJoinColumns ??= this.initManyToOneFieldName(prop, meta2.root.className);
+        }
     }
     isExplicitTableName(meta) {
         return meta.tableName !== this.#namingStrategy.classToTableName(meta.className);
@@ -583,6 +595,24 @@ export class MetadataDiscovery {
                 if (prop.inversedBy) {
                     prop.targetMeta.properties[prop.inversedBy].pivotEntity = pivotMeta.class;
                 }
+                // Propagate pivotEntity to ALL inverse collections using mappedBy pointing at this
+                // owner prop. Covers three cases:
+                //   - regular inverse (Tag.posts mappedBy Post.tags) — handled by inversedBy above
+                //   - union-target inverse (Image.posts mappedBy Post.attachments) — on each polymorph target
+                //   - merged inverse (Tag.owners mappedBy [Post,Video].tags) — union collection on the target
+                const inverseCandidates = QueryHelper.isUnionTargetPolymorphic(prop)
+                    ? prop.polymorphTargets
+                    : [prop.targetMeta];
+                for (const targetMeta of inverseCandidates) {
+                    for (const inverseProp of Object.values(targetMeta.properties)) {
+                        if (inverseProp.kind === ReferenceKind.MANY_TO_MANY &&
+                            inverseProp.mappedBy === prop.name &&
+                            !inverseProp.pivotEntity) {
+                            inverseProp.pivotEntity = pivotMeta.class;
+                            inverseProp.pivotTable = pivotMeta.tableName;
+                        }
+                    }
+                }
                 return pivotMeta;
             });
         }
@@ -721,8 +751,12 @@ export class MetadataDiscovery {
                 }
             }
         }
-        // For polymorphic M:N, create discriminator column and polymorphic FK
-        if (prop.polymorphic && prop.discriminatorColumn) {
+        // Union-target polymorphic M:N: discriminator + target FK share the pivot across multiple target types
+        if (prop.discriminatorColumn && QueryHelper.isUnionTargetPolymorphic(prop)) {
+            this.defineUnionTargetPolymorphicPivotProperties(pivotMeta2, meta, prop);
+        }
+        else if (prop.polymorphic && prop.discriminatorColumn) {
+            // Rails-style polymorphic M:N: multiple owners share the pivot, single target type
             this.definePolymorphicPivotProperties(pivotMeta2, meta, prop, targetMeta);
         }
         else {
@@ -809,6 +843,33 @@ export class MetadataDiscovery {
         pivotMeta.polymorphicDiscriminatorMap ??= {};
         pivotMeta.polymorphicDiscriminatorMap[prop.discriminatorValue] = meta.class;
     }
+    /**
+     * Mirror of definePolymorphicPivotProperties for union-target M:N
+     * (e.g. Post.attachments -> Image | Video via shared pivot with a target-side discriminator).
+     *
+     * Pivot shape:
+     *   (owner_fk..., discriminator_column, target_fk...)
+     *   - owner side is a normal M:1 to the single owner entity
+     *   - target side is a discriminator column + per-target-type virtual M:1 relations
+     */
+    defineUnionTargetPolymorphicPivotProperties(pivotMeta, meta, prop) {
+        const discriminatorColumn = prop.discriminatorColumn;
+        const targets = prop.polymorphTargets;
+        pivotMeta.properties[meta.name + '_owner'] = this.definePivotProperty(prop, meta.name + '_owner', meta.class, prop.discriminator, true, false);
+        const discriminatorProp = this.createPivotScalarProperty(discriminatorColumn, [this.#platform.getVarcharTypeDeclarationSQL(prop)], [discriminatorColumn], { type: 'string', primary: true, nullable: false });
+        this.initFieldName(discriminatorProp);
+        pivotMeta.properties[discriminatorColumn] = discriminatorProp;
+        const firstTargetColumnTypes = this.getPrimaryKeyColumnTypes(targets[0]);
+        pivotMeta.properties[prop.discriminator] = this.createPivotScalarProperty(prop.discriminator, firstTargetColumnTypes, [...prop.inverseJoinColumns], { type: targets[0].className, primary: true, nullable: false });
+        pivotMeta.polymorphicDiscriminatorMap ??= {};
+        for (const targetMeta of targets) {
+            const relationName = `${prop.discriminator}_${targetMeta.tableName}`;
+            const relation = this.definePolymorphicOwnerRelation(prop, relationName, targetMeta);
+            relation.joinColumns = relation.fieldNames = relation.ownColumns = [...prop.inverseJoinColumns];
+            pivotMeta.properties[relationName] = relation;
+            pivotMeta.polymorphicDiscriminatorMap[targetMeta.tableName] = targetMeta.class;
+        }
+    }
     /**
      * Create a virtual M:1 relation from pivot to a polymorphic owner entity.
      * This enables single-query join loading for inverse-side polymorphic M:N.
@@ -961,6 +1022,7 @@ export class MetadataDiscovery {
         meta.indexes = Utils.unique([...base.indexes, ...meta.indexes]);
         meta.uniques = Utils.unique([...base.uniques, ...meta.uniques]);
         meta.checks = Utils.unique([...base.checks, ...meta.checks]);
+        meta.triggers = Utils.unique([...base.triggers, ...meta.triggers]);
         const pks = Object.values(meta.properties)
             .filter(p => p.primary)
             .map(p => p.name);
@@ -1045,11 +1107,15 @@ export class MetadataDiscovery {
         prop.discriminatorColumn ??= this.#namingStrategy.discriminatorColumnName(prop.discriminator);
         prop.createForeignKeyConstraint = false;
         const isToOne = [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind);
-        if (isToOne) {
+        const isUnionTargetMN = prop.kind === ReferenceKind.MANY_TO_MANY && Array.isArray(prop.target);
+        if (isToOne || isUnionTargetMN) {
             const types = prop.type.split(/ ?\| ?/);
             prop.polymorphTargets = discovered.filter(m => types.includes(m.className) && !m.embeddable);
             prop.targetMeta = prop.polymorphTargets[0];
             prop.referencedPKs = prop.targetMeta?.primaryKeys;
+            if (isUnionTargetMN && prop.polymorphTargets.length < 2) {
+                throw new MetadataError(`${meta.className}.${prop.name} union-target polymorphic M:N requires at least two target entity types; use a regular M:N relation for a single target.`);
+            }
         }
         if (prop.discriminatorMap) {
             const normalizedMap = {};
@@ -1065,7 +1131,7 @@ export class MetadataDiscovery {
             }
             prop.discriminatorMap = normalizedMap;
         }
-        else if (isToOne) {
+        else if (isToOne || isUnionTargetMN) {
             prop.discriminatorMap = {};
             const tableNameToTarget = new Map();
             for (const target of prop.polymorphTargets) {
@@ -1520,6 +1586,27 @@ export class MetadataDiscovery {
             }
         }
     }
+    initTriggers(meta) {
+        if (meta.triggers.length === 0) {
+            return;
+        }
+        const columns = meta.createSchemaColumnMappingObject();
+        const table = this.createSchemaTable(meta);
+        for (const trigger of meta.triggers) {
+            if (trigger.body && trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} defines both 'body' and 'expression'. Use one or the other.`);
+            }
+            if (!trigger.body && !trigger.expression) {
+                throw new MetadataError(`Trigger "${trigger.name ?? '(unnamed)'}" on entity ${meta.className} must define either 'body' or 'expression'.`);
+            }
+            trigger.name ??= this.#namingStrategy.indexName(meta.tableName, trigger.events, 'trigger');
+            trigger.forEach ??= 'row';
+            if (trigger.body instanceof Function) {
+                trigger.body = trigger.body(columns, table);
+            }
+        }
+        meta.hasTriggers = true;
+    }
     initGeneratedColumn(meta, prop) {
         if (!prop.generated && prop.columnTypes) {
             const match = /(.*) generated always as (.*)/i.exec(prop.columnTypes[0]);
@@ -1646,7 +1733,14 @@ export class MetadataDiscovery {
                 return (!Type.getType(t[type]).ensureComparable(meta, prop) && (prop.type === t[type] || brand === type));
             });
             if (type) {
-                prop.type = type === 'datetime' ? 'Date' : type;
+                if (prop.array) {
+                    // built-in type + array: true — force-create instance for ArrayType wrapping
+                    prop.customType = new prop.type();
+                    prop.type = prop.customType.constructor.name;
+                }
+                else {
+                    prop.type = type === 'datetime' ? 'Date' : type;
+                }
             }
             else {
                 prop.customType = new prop.type();
@@ -1656,6 +1750,30 @@ export class MetadataDiscovery {
         if (simple) {
             return;
         }
+        if (prop.array &&
+            prop.customType &&
+            !(prop.customType instanceof t.array) &&
+            !(prop.customType instanceof t.enumArray) &&
+            prop.kind === ReferenceKind.SCALAR) {
+            const innerType = prop.customType;
+            innerType.platform = this.#platform;
+            innerType.meta = meta;
+            innerType.prop = prop;
+            if (!prop.columnTypes) {
+                const arrayDecl = this.#platform.getArrayDeclarationSQL();
+                if (arrayDecl.endsWith('[]')) {
+                    // native array support (e.g. postgres) — use inner type's column type with [] suffix
+                    prop.columnTypes = [innerType.getColumnType(prop, this.#platform) + '[]'];
+                }
+                else {
+                    // non-native (e.g. mysql, sqlite) — store as text/clob
+                    prop.columnTypes = [arrayDecl];
+                }
+            }
+            const platform = this.#platform;
+            prop.customType = new t.array(v => innerType.convertToJSValue(v, platform), v => innerType.convertToDatabaseValue(v, platform));
+            prop.type = prop.customType.constructor.name;
+        }
         if (!prop.customType && ['json', 'jsonb'].includes(prop.type?.toLowerCase())) {
             prop.customType = new t.json();
         }

package/metadata/MetadataValidator.js

@@ -171,6 +171,15 @@ export class MetadataValidator {
     }
     validatePolymorphicTargets(meta, prop) {
         const targets = prop.polymorphTargets;
+        // Union-target M:N stores one scalar target FK per pivot row, so composite-PK targets
+        // can't round-trip through this schema.
+        if (prop.kind === ReferenceKind.MANY_TO_MANY && targets.length > 1) {
+            for (const target of targets) {
+                if (target.compositePK) {
+                    throw MetadataError.incompatiblePolymorphicTargets(meta, prop, targets[0], target, `${target.className} has a composite primary key; union-target polymorphic M:N does not support composite-PK targets.`);
+                }
+            }
+        }
         // Validate targetKey exists and is compatible across all targets
         if (prop.targetKey) {
             for (const target of targets) {

package/metadata/types.d.ts

@@ -1,4 +1,4 @@
-import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw } from '../typings.js';
+import type { AnyEntity, Constructor, EntityName, AnyString, CheckCallback, GeneratedColumnCallback, FormulaCallback, FilterQuery, Dictionary, AutoPath, EntityClass, IndexCallback, ObjectQuery, Raw, TriggerDef } from '../typings.js';
 import type { Cascade, LoadStrategy, DeferMode, QueryOrderMap, EmbeddedPrefixMode } from '../enums.js';
 import type { Type, types } from '../types/index.js';
 import type { EntityManager } from '../EntityManager.js';
@@ -57,6 +57,8 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     };
     /** Used to make ORM aware of externally defined triggers. This is needed for MS SQL Server multi inserts, ignored in other dialects. */
     hasTriggers?: boolean;
+    /** Database triggers to create for this entity's table. (SQL drivers only) */
+    triggers?: TriggerDef<E>[];
     /** SQL query that maps to a {@doclink virtual-entities | virtual entity}, or for view entities, the view definition. */
     expression?: string | ((em: any, where: ObjectQuery<E>, options: FindOptions<E, any, any, any>, stream?: boolean) => object);
     /** Set {@doclink repositories#custom-repository | custom repository class}. */
@@ -202,6 +204,12 @@ export interface PropertyOptions<Owner> {
      * @see https://mikro-orm.io/docs/defining-entities#lazy-scalar-properties
      */
     lazy?: boolean;
+    /**
+     * Marks this property as an array. When used with a custom type, the type is automatically
+     * wrapped in an `ArrayType` that delegates element conversion to the inner type.
+     * The column type is inferred as `innerType[]` (e.g. `int[]`, `time[]`).
+     */
+    array?: boolean;
     /**
      * Set true to define entity's unique primary key identifier.
      * Alias for `@PrimaryKey()` decorator
@@ -334,7 +342,7 @@ export interface PropertyOptions<Owner> {
 }
 export interface ReferenceOptions<Owner, Target> extends PropertyOptions<Owner> {
     /** Set target entity type. For polymorphic relations, pass an array of entity types. */
-    entity?: () => EntityName<Target> | EntityName<Target>[];
+    entity?: () => EntityName<Target> | EntityName[];
     /** Set what actions on owning entity should be cascaded to the relationship. Defaults to [Cascade.PERSIST, Cascade.MERGE] (see {@doclink cascading}). */
     cascade?: Cascade[];
     /** Always load the relationship. Discouraged for use with to-many relations for performance reasons. */

package/naming-strategy/AbstractNamingStrategy.d.ts

@@ -4,7 +4,7 @@ import { type ReferenceKind } from '../enums.js';
 export declare abstract class AbstractNamingStrategy implements NamingStrategy {
     getClassName(file: string, separator?: string): string;
     classToMigrationName(timestamp: string, customMigrationName?: string): string;
-    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default'): string;
+    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default' | 'trigger'): string;
     /**
      * @inheritDoc
      */

package/naming-strategy/NamingStrategy.d.ts

@@ -75,7 +75,7 @@ export interface NamingStrategy {
     /**
      * Returns key/constraint name for the given type. Some drivers might not support all the types (e.g. mysql and sqlite enforce the PK name).
      */
-    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default'): string;
+    indexName(tableName: string, columns: string[], type: 'primary' | 'foreign' | 'unique' | 'index' | 'sequence' | 'check' | 'default' | 'trigger'): string;
     /**
      * Returns alias name for given entity. The alias needs to be unique across the query, which is by default
      * ensured via appended index parameter. It is optional to use it as long as you ensure it will be unique.

package/package.json

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

@@ -211,6 +211,11 @@ export declare abstract class Platform {
     getFullTextWhereClause(prop: EntityProperty): string;
     supportsCreatingFullTextIndex(): boolean;
     getFullTextIndexExpression(indexName: string, schemaName: string | undefined, tableName: string, columns: SimpleColumnMeta[]): string;
+    /**
+     * Generates the SQL index hint clause for the given index names.
+     * Returns `undefined` when the platform does not support index hints (e.g. PostgreSQL, SQLite).
+     */
+    formatIndexHint(indexNames: string[]): string | undefined;
     /** Whether the driver automatically parses JSON columns into JS objects. */
     convertsJsonAutomatically(): boolean;
     /** Converts a JS value to its JSON database representation (typically JSON.stringify). */

package/platforms/Platform.js

@@ -415,6 +415,13 @@ export class Platform {
     getFullTextIndexExpression(indexName, schemaName, tableName, columns) {
         throw new Error('Full text searching is not supported by this driver.');
     }
+    /**
+     * Generates the SQL index hint clause for the given index names.
+     * Returns `undefined` when the platform does not support index hints (e.g. PostgreSQL, SQLite).
+     */
+    formatIndexHint(indexNames) {
+        return undefined;
+    }
     /** Whether the driver automatically parses JSON columns into JS objects. */
     convertsJsonAutomatically() {
         return true;

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);