@mikro-orm/core 7.0.2-dev.8 → 7.0.2

package/serialization/EntitySerializer.d.ts

@@ -1,31 +1,44 @@
-import type { ArrayElement, AutoPath, CleanTypeConfig, SerializeDTO, FromEntityType, TypeConfig, UnboxArray } from '../typings.js';
+import type {
+  ArrayElement,
+  AutoPath,
+  CleanTypeConfig,
+  SerializeDTO,
+  FromEntityType,
+  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. */
 export declare class EntitySerializer {
-    static serialize<T extends object, P extends string = never, E extends string = never>(entity: T, options?: SerializeOptions<T, P, E>): SerializeDTO<T, P, E>;
-    private static propertyName;
-    private static processProperty;
-    private static processCustomType;
-    private static extractChildOptions;
-    private static processEntity;
-    private static processCollection;
+  /** 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>;
+  private static propertyName;
+  private static processProperty;
+  private static processCustomType;
+  private static extractChildOptions;
+  private static processEntity;
+  private static processCollection;
 }
 export interface SerializeOptions<T, P extends string = never, E 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>[];
-    /** Enforce unpopulated references to be returned as objects, e.g. `{ author: { id: 1 } }` instead of `{ author: 1 }`. */
-    forceObject?: boolean;
-    /** Ignore custom property serializers. */
-    ignoreSerializers?: boolean;
-    /** Include properties marked as `hidden`. */
-    includeHidden?: boolean;
-    /** Skip properties with `null` value. */
-    skipNull?: boolean;
-    /** Only include properties for a specific group. If a property does not specify any group, it will be included, otherwise only properties with a matching group are included. */
-    groups?: string[];
-    /** Convert custom types to their database representation. By default, the `Type.toJSON` method is invoked instead. */
-    convertCustomTypes?: boolean;
+  /** 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>[];
+  /** Enforce unpopulated references to be returned as objects, e.g. `{ author: { id: 1 } }` instead of `{ author: 1 }`. */
+  forceObject?: boolean;
+  /** Ignore custom property serializers. */
+  ignoreSerializers?: boolean;
+  /** Include properties marked as `hidden`. */
+  includeHidden?: boolean;
+  /** Skip properties with `null` value. */
+  skipNull?: boolean;
+  /** Only include properties for a specific group. If a property does not specify any group, it will be included, otherwise only properties with a matching group are included. */
+  groups?: string[];
+  /** Convert custom types to their database representation. By default, the `Type.toJSON` method is invoked instead. */
+  convertCustomTypes?: boolean;
 }
 /**
  * Converts entity instance to POJO, converting the `Collection`s to arrays and unwrapping the `Reference` wrapper, while respecting the serialization options.
@@ -39,4 +52,15 @@ 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>>;
+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>>;

package/serialization/EntitySerializer.js

@@ -5,227 +5,235 @@ import { Reference } from '../entity/Reference.js';
 import { SerializationContext } from './SerializationContext.js';
 import { isRaw } from '../utils/RawQueryFragment.js';
 function isVisible(meta, propName, options) {
-    const prop = meta.properties[propName];
-    if (options.groups && prop?.groups) {
-        return prop.groups.some(g => options.groups.includes(g));
+  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 === '*')
+  ) {
+    return true;
+  }
+  if (options.exclude?.find(item => item === propName)) {
+    return false;
+  }
+  const visible = prop && !(prop.hidden && !options.includeHidden);
+  const prefixed = prop && !prop.primary && !prop.accessor && propName.startsWith('_'); // ignore prefixed properties, if it's not a PK
+  return visible && !prefixed;
+}
+function isPopulated(propName, options) {
+  if (
+    typeof options.populate !== 'boolean' &&
+    options.populate?.find(item => item === propName || item.startsWith(propName + '.') || item === '*')
+  ) {
+    return true;
+  }
+  if (typeof options.populate === 'boolean') {
+    return options.populate;
+  }
+  return false;
+}
+/** Converts entity instances to plain DTOs via `serialize()`, with fine-grained control over populate, exclude, and serialization groups. */
+export class EntitySerializer {
+  /** Serializes an entity to a plain DTO, with fine-grained control over population, exclusion, groups, and custom types. */
+  static serialize(entity, options = {}) {
+    const wrapped = helper(entity);
+    const meta = wrapped.__meta;
+    let contextCreated = false;
+    if (!wrapped.__serializationContext.root) {
+      const root = new SerializationContext();
+      SerializationContext.propagate(
+        root,
+        entity,
+        (meta, prop) => meta.properties[prop]?.kind !== ReferenceKind.SCALAR,
+      );
+      options.populate = options.populate ? Utils.asArray(options.populate) : options.populate;
+      contextCreated = true;
     }
-    if (Array.isArray(options.populate) &&
-        options.populate?.find(item => item === propName || item.startsWith(propName + '.') || item === '*')) {
-        return true;
+    const root = wrapped.__serializationContext.root;
+    const ret = {};
+    const props = new Set();
+    if (meta.serializedPrimaryKey && !meta.compositePK) {
+      props.add(meta.serializedPrimaryKey);
+    } else {
+      meta.primaryKeys.forEach(pk => props.add(pk));
     }
-    if (options.exclude?.find(item => item === propName)) {
-        return false;
+    if (wrapped.isInitialized() || !wrapped.hasPrimaryKey()) {
+      const entityKeys = new Set(Object.keys(entity));
+      for (const prop of meta.props) {
+        if (entityKeys.has(prop.name) || (prop.getter && prop.accessor === prop.name)) {
+          props.add(prop.name);
+        }
+      }
+      for (const key of entityKeys) {
+        if (!meta.properties[key]) {
+          props.add(key);
+        }
+      }
     }
-    const visible = prop && !(prop.hidden && !options.includeHidden);
-    const prefixed = prop && !prop.primary && !prop.accessor && propName.startsWith('_'); // ignore prefixed properties, if it's not a PK
-    return visible && !prefixed;
-}
-function isPopulated(propName, options) {
-    if (typeof options.populate !== 'boolean' &&
-        options.populate?.find(item => item === propName || item.startsWith(propName + '.') || item === '*')) {
-        return true;
+    const visited = root.visited.has(entity);
+    if (!visited) {
+      root.visited.add(entity);
     }
-    if (typeof options.populate === 'boolean') {
-        return options.populate;
+    for (const prop of props) {
+      if (!isVisible(meta, prop, options)) {
+        continue;
+      }
+      const cycle = root.visit(meta.class, prop);
+      if (cycle && visited) {
+        continue;
+      }
+      const val = this.processProperty(prop, entity, options);
+      if (!cycle) {
+        root.leave(meta.class, prop);
+      }
+      if (options.skipNull && Utils.isPlainObject(val)) {
+        Utils.dropUndefinedProperties(val, null);
+      }
+      if (isRaw(val)) {
+        throw new Error(`Trying to serialize raw SQL fragment: '${val.sql}'`);
+      }
+      const visible = typeof val !== 'undefined' && !(val === null && options.skipNull);
+      if (visible) {
+        ret[this.propertyName(meta, prop)] = val;
+      }
     }
-    return false;
-}
-export class EntitySerializer {
-    static serialize(entity, options = {}) {
-        const wrapped = helper(entity);
-        const meta = wrapped.__meta;
-        let contextCreated = false;
-        if (!wrapped.__serializationContext.root) {
-            const root = new SerializationContext();
-            SerializationContext.propagate(root, entity, (meta, prop) => meta.properties[prop]?.kind !== ReferenceKind.SCALAR);
-            options.populate = (options.populate ? Utils.asArray(options.populate) : options.populate);
-            contextCreated = true;
-        }
-        const root = wrapped.__serializationContext.root;
-        const ret = {};
-        const props = new Set();
-        if (meta.serializedPrimaryKey && !meta.compositePK) {
-            props.add(meta.serializedPrimaryKey);
-        }
-        else {
-            meta.primaryKeys.forEach(pk => props.add(pk));
-        }
-        if (wrapped.isInitialized() || !wrapped.hasPrimaryKey()) {
-            const entityKeys = new Set(Object.keys(entity));
-            for (const prop of meta.props) {
-                if (entityKeys.has(prop.name) || (prop.getter && prop.accessor === prop.name)) {
-                    props.add(prop.name);
-                }
-            }
-            for (const key of entityKeys) {
-                if (!meta.properties[key]) {
-                    props.add(key);
-                }
-            }
-        }
-        const visited = root.visited.has(entity);
-        if (!visited) {
-            root.visited.add(entity);
-        }
-        for (const prop of props) {
-            if (!isVisible(meta, prop, options)) {
-                continue;
-            }
-            const cycle = root.visit(meta.class, prop);
-            if (cycle && visited) {
-                continue;
-            }
-            const val = this.processProperty(prop, entity, options);
-            if (!cycle) {
-                root.leave(meta.class, prop);
-            }
-            if (options.skipNull && Utils.isPlainObject(val)) {
-                Utils.dropUndefinedProperties(val, null);
-            }
-            if (isRaw(val)) {
-                throw new Error(`Trying to serialize raw SQL fragment: '${val.sql}'`);
-            }
-            const visible = typeof val !== 'undefined' && !(val === null && options.skipNull);
-            if (visible) {
-                ret[this.propertyName(meta, prop)] = val;
-            }
-        }
-        if (contextCreated) {
-            root.close();
-        }
-        if (!wrapped.isInitialized()) {
-            return ret;
-        }
-        for (const prop of meta.getterProps) {
-            // decorated get methods
-            if (prop.getterName != null) {
-                const visible = entity[prop.getterName] instanceof Function && isVisible(meta, prop.name, options);
-                if (visible) {
-                    ret[this.propertyName(meta, prop.name)] = this.processProperty(prop.getterName, entity, options);
-                }
-            }
-            else {
-                // decorated getters
-                const visible = typeof entity[prop.name] !== 'undefined' && isVisible(meta, prop.name, options);
-                if (visible) {
-                    ret[this.propertyName(meta, prop.name)] = this.processProperty(prop.name, entity, options);
-                }
-            }
-        }
-        return ret;
+    if (contextCreated) {
+      root.close();
     }
-    static propertyName(meta, prop) {
-        /* v8 ignore next */
-        if (meta.properties[prop]?.serializedName) {
-            return meta.properties[prop].serializedName;
-        }
-        if (meta.properties[prop]?.primary && meta.serializedPrimaryKey) {
-            return meta.serializedPrimaryKey;
-        }
-        return prop;
-    }
-    static processProperty(prop, entity, options) {
-        const parts = prop.split('.');
-        prop = parts[0];
-        const wrapped = helper(entity);
-        const property = wrapped.__meta.properties[prop] ?? { name: prop };
-        const serializer = property?.serializer;
-        const value = entity[prop];
-        // getter method
-        if (entity[prop] instanceof Function) {
-            const returnValue = entity[prop]();
-            if (!options.ignoreSerializers && serializer) {
-                return serializer(returnValue, this.extractChildOptions(options, prop));
-            }
-            return returnValue;
-        }
-        /* v8 ignore next */
-        if (!options.ignoreSerializers && serializer) {
-            return serializer(value);
-        }
-        if (Utils.isCollection(value)) {
-            return this.processCollection(property, entity, options);
-        }
-        if (Utils.isEntity(value, true)) {
-            return this.processEntity(property, entity, wrapped.__platform, options);
-        }
-        if (Utils.isScalarReference(value)) {
-            return value.unwrap();
-        }
-        /* v8 ignore next */
-        if (property?.kind === ReferenceKind.EMBEDDED) {
-            if (Array.isArray(value)) {
-                return value.map(item => helper(item).toJSON());
-            }
-            if (Utils.isObject(value)) {
-                return helper(value).toJSON();
-            }
-        }
-        if (property.customType) {
-            return this.processCustomType(value, property, wrapped.__platform, options.convertCustomTypes);
-        }
-        return wrapped.__platform.normalizePrimaryKey(value);
+    if (!wrapped.isInitialized()) {
+      return ret;
     }
-    static processCustomType(value, prop, platform, convertCustomTypes) {
-        if (!prop.customType) {
-            return value;
-        }
-        if (convertCustomTypes) {
-            return prop.customType.convertToDatabaseValue(value, platform, { mode: 'serialization' });
-        }
-        return prop.customType.toJSON(value, platform);
-    }
-    static extractChildOptions(options, prop) {
-        return {
-            ...options,
-            populate: Array.isArray(options.populate)
-                ? Utils.extractChildElements(options.populate, prop, '*')
-                : options.populate,
-            exclude: Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop) : options.exclude,
-        };
-    }
-    static processEntity(prop, entity, platform, options) {
-        const child = Reference.unwrapReference(entity[prop.name]);
-        const wrapped = helper(child);
-        const populated = isPopulated(prop.name, options) && wrapped.isInitialized();
-        const expand = populated || !wrapped.__managed;
-        const meta = wrapped.__meta;
-        const childOptions = this.extractChildOptions(options, prop.name);
-        const visible = meta.primaryKeys.filter(prop => isVisible(meta, prop, childOptions));
-        if (expand) {
-            return this.serialize(child, childOptions);
-        }
-        const pk = this.processCustomType(wrapped.getPrimaryKey(), prop, wrapped.__platform, options.convertCustomTypes);
-        if (options.forceObject || wrapped.__config.get('serialization').forceObject) {
-            return Utils.primaryKeyToObject(meta, pk, visible);
-        }
-        if (Utils.isPlainObject(pk)) {
-            const pruned = Utils.primaryKeyToObject(meta, pk, visible);
-            if (visible.length === 1) {
-                return platform.normalizePrimaryKey(pruned[visible[0]]);
-            }
-            return pruned;
-        }
-        return platform.normalizePrimaryKey(pk);
+    for (const prop of meta.getterProps) {
+      // decorated get methods
+      if (prop.getterName != null) {
+        const visible = entity[prop.getterName] instanceof Function && isVisible(meta, prop.name, options);
+        if (visible) {
+          ret[this.propertyName(meta, prop.name)] = this.processProperty(prop.getterName, entity, options);
+        }
+      } else {
+        // decorated getters
+        const visible = typeof entity[prop.name] !== 'undefined' && isVisible(meta, prop.name, options);
+        if (visible) {
+          ret[this.propertyName(meta, prop.name)] = this.processProperty(prop.name, entity, options);
+        }
+      }
     }
-    static processCollection(prop, entity, options) {
-        const col = entity[prop.name];
-        if (!col.isInitialized()) {
-            return undefined;
-        }
-        return col.getItems(false).map(item => {
-            const populated = isPopulated(prop.name, options);
-            const wrapped = helper(item);
-            if (populated || !wrapped.__managed) {
-                return this.serialize(item, this.extractChildOptions(options, prop.name));
-            }
-            const pk = this.processCustomType(wrapped.getPrimaryKey(), prop, wrapped.__platform, options.convertCustomTypes);
-            if (options.forceObject || wrapped.__config.get('serialization').forceObject) {
-                return Utils.primaryKeyToObject(wrapped.__meta, pk);
-            }
-            return pk;
-        });
+    return ret;
+  }
+  static propertyName(meta, prop) {
+    /* v8 ignore next */
+    if (meta.properties[prop]?.serializedName) {
+      return meta.properties[prop].serializedName;
+    }
+    if (meta.properties[prop]?.primary && meta.serializedPrimaryKey) {
+      return meta.serializedPrimaryKey;
+    }
+    return prop;
+  }
+  static processProperty(prop, entity, options) {
+    const parts = prop.split('.');
+    prop = parts[0];
+    const wrapped = helper(entity);
+    const property = wrapped.__meta.properties[prop] ?? { name: prop };
+    const serializer = property?.serializer;
+    const value = entity[prop];
+    // getter method
+    if (entity[prop] instanceof Function) {
+      const returnValue = entity[prop]();
+      if (!options.ignoreSerializers && serializer) {
+        return serializer(returnValue, this.extractChildOptions(options, prop));
+      }
+      return returnValue;
+    }
+    /* v8 ignore next */
+    if (!options.ignoreSerializers && serializer) {
+      return serializer(value);
     }
+    if (Utils.isCollection(value)) {
+      return this.processCollection(property, entity, options);
+    }
+    if (Utils.isEntity(value, true)) {
+      return this.processEntity(property, entity, wrapped.__platform, options);
+    }
+    if (Utils.isScalarReference(value)) {
+      return value.unwrap();
+    }
+    /* v8 ignore next */
+    if (property?.kind === ReferenceKind.EMBEDDED) {
+      if (Array.isArray(value)) {
+        return value.map(item => helper(item).toJSON());
+      }
+      if (Utils.isObject(value)) {
+        return helper(value).toJSON();
+      }
+    }
+    if (property.customType) {
+      return this.processCustomType(value, property, wrapped.__platform, options.convertCustomTypes);
+    }
+    return wrapped.__platform.normalizePrimaryKey(value);
+  }
+  static processCustomType(value, prop, platform, convertCustomTypes) {
+    if (!prop.customType) {
+      return value;
+    }
+    if (convertCustomTypes) {
+      return prop.customType.convertToDatabaseValue(value, platform, { mode: 'serialization' });
+    }
+    return prop.customType.toJSON(value, platform);
+  }
+  static extractChildOptions(options, prop) {
+    return {
+      ...options,
+      populate: Array.isArray(options.populate)
+        ? Utils.extractChildElements(options.populate, prop, '*')
+        : options.populate,
+      exclude: Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop) : options.exclude,
+    };
+  }
+  static processEntity(prop, entity, platform, options) {
+    const child = Reference.unwrapReference(entity[prop.name]);
+    const wrapped = helper(child);
+    const populated = isPopulated(prop.name, options) && wrapped.isInitialized();
+    const expand = populated || !wrapped.__managed;
+    const meta = wrapped.__meta;
+    const childOptions = this.extractChildOptions(options, prop.name);
+    const visible = meta.primaryKeys.filter(prop => isVisible(meta, prop, childOptions));
+    if (expand) {
+      return this.serialize(child, childOptions);
+    }
+    const pk = this.processCustomType(wrapped.getPrimaryKey(), prop, wrapped.__platform, options.convertCustomTypes);
+    if (options.forceObject || wrapped.__config.get('serialization').forceObject) {
+      return Utils.primaryKeyToObject(meta, pk, visible);
+    }
+    if (Utils.isPlainObject(pk)) {
+      const pruned = Utils.primaryKeyToObject(meta, pk, visible);
+      if (visible.length === 1) {
+        return platform.normalizePrimaryKey(pruned[visible[0]]);
+      }
+      return pruned;
+    }
+    return platform.normalizePrimaryKey(pk);
+  }
+  static processCollection(prop, entity, options) {
+    const col = entity[prop.name];
+    if (!col.isInitialized()) {
+      return undefined;
+    }
+    return col.getItems(false).map(item => {
+      const populated = isPopulated(prop.name, options);
+      const wrapped = helper(item);
+      if (populated || !wrapped.__managed) {
+        return this.serialize(item, this.extractChildOptions(options, prop.name));
+      }
+      const pk = this.processCustomType(wrapped.getPrimaryKey(), prop, wrapped.__platform, options.convertCustomTypes);
+      if (options.forceObject || wrapped.__config.get('serialization').forceObject) {
+        return Utils.primaryKeyToObject(wrapped.__meta, pk);
+      }
+      return pk;
+    });
+  }
 }
 /**
  * Converts entity instance to POJO, converting the `Collection`s to arrays and unwrapping the `Reference` wrapper, while respecting the serialization options.
@@ -240,8 +248,8 @@ export class EntitySerializer {
  * ```
  */
 export function serialize(entities, options) {
-    if (Array.isArray(entities)) {
-        return entities.map(e => EntitySerializer.serialize(e, options));
-    }
-    return EntitySerializer.serialize(entities, options);
+  if (Array.isArray(entities)) {
+    return entities.map(e => EntitySerializer.serialize(e, options));
+  }
+  return EntitySerializer.serialize(entities, options);
 }

package/serialization/EntityTransformer.d.ts

@@ -1,8 +1,14 @@
 import type { EntityDTO, EntityKey } from '../typings.js';
+/** Converts entity instances to plain objects via `toObject()`, respecting populate hints, hidden fields, and serialization context. */
 export declare class EntityTransformer {
-    static toObject<Entity extends object, Ignored extends EntityKey<Entity> = never>(entity: Entity, ignoreFields?: Ignored[], raw?: boolean): Omit<EntityDTO<Entity>, Ignored>;
-    private static propertyName;
-    private static processProperty;
-    private static processEntity;
-    private static processCollection;
+  /** Converts an entity to a plain object, respecting populate hints, hidden fields, and custom serializers. */
+  static toObject<Entity extends object, Ignored extends EntityKey<Entity> = never>(
+    entity: Entity,
+    ignoreFields?: Ignored[],
+    raw?: boolean,
+  ): Omit<EntityDTO<Entity>, Ignored>;
+  private static propertyName;
+  private static processProperty;
+  private static processEntity;
+  private static processCollection;
 }