@mikro-orm/core 7.3.0-dev.16 → 7.3.0-dev.18

package/metadata/MetadataDiscovery.js

@@ -183,10 +183,11 @@ export class MetadataDiscovery {
         }
         discovered.forEach(meta => meta.sync(true));
         this.#metadataProvider.combineCache();
+        const referencingProperties = this.indexReferencingProperties(filtered);
         return discovered.map(meta => {
             meta = this.#metadata.get(meta.class);
             meta.sync(true);
-            this.findReferencingProperties(meta, filtered);
+            this.findReferencingProperties(meta, referencingProperties);
             if (meta.inheritanceType === 'tpt') {
                 this.computeTPTOwnProps(meta);
             }
@@ -217,18 +218,20 @@ export class MetadataDiscovery {
             .replace(/Array<(.*)>/, '$1') // unwrap array
             .replace(/\[]$/, '') // remove array suffix
             .replace(/\((.*)\)/, '$1'); // unwrap union types
+        const discoveredNames = new Set(this.#discovered.map(m => m.className));
         // Names can be ambiguous when a minifier mangles two classes to the same name,
         // so class references also need to be checked by identity.
+        const discoveredClasses = new Set(this.#discovered.map(m => m.class));
         const discoveredByIdentity = (target) => {
             const cls = EntitySchema.is(target) ? target.meta.class : target;
-            return typeof cls !== 'function' || this.#discovered.some(m => m.class === cls);
+            return typeof cls !== 'function' || discoveredClasses.has(cls);
         };
         const missing = [];
         this.#discovered.forEach(meta => Object.values(meta.properties).forEach(prop => {
             const indirect = (prop.kind === ReferenceKind.MANY_TO_MANY ? prop.pivotEntity : prop.through);
             if (indirect) {
                 const target = typeof indirect === 'function' && !indirect.prototype ? indirect() : indirect;
-                if (!this.#discovered.find(m => m.className === Utils.className(target)) || !discoveredByIdentity(target)) {
+                if (!discoveredNames.has(Utils.className(target)) || !discoveredByIdentity(target)) {
                     missing.push(target);
                 }
             }
@@ -236,7 +239,7 @@ export class MetadataDiscovery {
                 const target = typeof prop.entity === 'function' && !prop.entity.prototype ? prop.entity() : prop.type;
                 if (!unwrap(prop.type)
                     .split(/ ?\| ?/)
-                    .every(type => this.#discovered.find(m => m.className === type)) ||
+                    .every(type => discoveredNames.has(type)) ||
                     !Utils.asArray(target).every(discoveredByIdentity)) {
                     missing.push(...Utils.asArray(target));
                 }
@@ -302,7 +305,8 @@ export class MetadataDiscovery {
         if (validate) {
             this.#validator.validateDiscovered(this.#discovered, this.#config.get('discovery'));
         }
-        return this.#discovered.filter(meta => found.find(m => m.name === meta.className));
+        const foundNames = new Set(found.map(m => m.name));
+        return this.#discovered.filter(meta => foundNames.has(meta.className));
     }
     reset(entityName) {
         const exists = this.#discovered.findIndex(m => m.class === entityName || m.className === Utils.className(entityName));
@@ -463,7 +467,8 @@ export class MetadataDiscovery {
         }
     }
     initManyToOneFieldName(prop, name) {
-        const meta2 = prop.targetMeta;
+        // STI property renaming runs before `initRelation` populates `targetMeta`
+        const meta2 = prop.targetMeta ?? this.#metadata.getByClassName(prop.type);
         const ret = [];
         // with `targetKey` on a composite PK target, derive the FK field name from that property
         // instead of the PKs (simple PK targets keep the PK based naming for backwards compatibility)
@@ -667,20 +672,47 @@ export class MetadataDiscovery {
         }
         return [];
     }
-    findReferencingProperties(meta, metadata) {
+    /**
+     * Groups the relations of all entities by target class name in one pass, so `findReferencingProperties()`
+     * does not go over the relations of every entity for each entity. Lists keep the order of `metadata` and `relations`.
+     */
+    indexReferencingProperties(metadata) {
+        const index = { byType: new Map(), withTargetKey: new Map() };
+        const add = (map, key, value) => {
+            const list = map.get(key);
+            if (list) {
+                list.push(value);
+            }
+            else {
+                map.set(key, [value]);
+            }
+        };
         for (const meta2 of metadata) {
             for (const prop2 of meta2.relations) {
-                if (prop2.kind !== ReferenceKind.SCALAR && prop2.type === meta.className) {
-                    meta.referencingProperties.push({ meta: meta2, prop: prop2 });
+                if (prop2.kind !== ReferenceKind.SCALAR) {
+                    add(index.byType, prop2.type, [meta2, prop2]);
                 }
-                if (prop2.targetKey &&
-                    (prop2.type === meta.className || prop2.polymorphTargets?.some(t => t.className === meta.className)) &&
-                    !(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === prop2.targetKey) &&
-                    !meta.root.targetKeys?.includes(prop2.targetKey)) {
-                    (meta.root.targetKeys ??= []).push(prop2.targetKey);
+                if (prop2.targetKey) {
+                    const targets = new Set([prop2.type, ...(prop2.polymorphTargets?.map(t => t.className) ?? [])]);
+                    for (const target of targets) {
+                        add(index.withTargetKey, target, prop2);
+                    }
                 }
             }
         }
+        return index;
+    }
+    findReferencingProperties(meta, index) {
+        for (const [meta2, prop2] of index.byType.get(meta.className) ?? []) {
+            meta.referencingProperties.push({ meta: meta2, prop: prop2 });
+        }
+        for (const prop2 of index.withTargetKey.get(meta.className) ?? []) {
+            const targetKey = prop2.targetKey;
+            if (!(meta.primaryKeys.length === 1 && meta.primaryKeys[0] === targetKey) &&
+                !meta.root.targetKeys?.includes(targetKey)) {
+                (meta.root.targetKeys ??= []).push(targetKey);
+            }
+        }
     }
     initFactoryField(meta, prop) {
         ['mappedBy', 'inversedBy', 'pivotEntity'].forEach(type => {
@@ -785,11 +817,14 @@ export class MetadataDiscovery {
         else {
             pivotMeta2.compositePK = true;
         }
+        // STI entities share one table, so any m:n within the hierarchy is self-referencing, named after the root
+        const stiRoot = meta.root.inheritanceType === 'sti' ? meta.root : undefined;
+        const baseMeta = stiRoot ?? meta;
         // handle self-referenced m:n with same default field names
-        if (meta.className === targetType &&
+        if ((meta.className === targetType || stiRoot === targetMeta.root) &&
             prop.joinColumns.every((joinColumn, idx) => joinColumn === prop.inverseJoinColumns[idx])) {
             // use tableName only when explicitly provided by user, otherwise use className for backwards compatibility
-            const baseName = this.isExplicitTableName(meta) ? meta.tableName : meta.className;
+            const baseName = this.isExplicitTableName(baseMeta) ? baseMeta.tableName : baseMeta.className;
             prop.joinColumns = prop.referencedColumnNames.map(name => this.#namingStrategy.joinKeyColumnName(baseName + '_1', name, meta.compositePK));
             prop.inverseJoinColumns = prop.referencedColumnNames.map(name => this.#namingStrategy.joinKeyColumnName(baseName + '_2', name, meta.compositePK));
             if (prop.inversedBy) {
@@ -797,13 +832,18 @@ export class MetadataDiscovery {
                 prop2.inverseJoinColumns = prop.joinColumns;
                 prop2.joinColumns = prop.inverseJoinColumns;
             }
-            // propagate updated joinColumns to all child entities that inherit this property (STI)
-            for (const childMeta of this.#discovered.filter(m => m.root === meta && m !== meta)) {
+            // propagate updated joinColumns to all entities of the hierarchy that inherit this property or its inverse (STI)
+            for (const childMeta of this.#discovered.filter(m => m.root === baseMeta)) {
                 const childProp = childMeta.properties[prop.name];
                 if (childProp) {
                     childProp.joinColumns = prop.joinColumns;
                     childProp.inverseJoinColumns = prop.inverseJoinColumns;
                 }
+                const childProp2 = prop.inversedBy ? childMeta.properties[prop.inversedBy] : undefined;
+                if (childProp2) {
+                    childProp2.inverseJoinColumns = prop.joinColumns;
+                    childProp2.joinColumns = prop.inverseJoinColumns;
+                }
             }
         }
         // Union-target polymorphic M:N: discriminator + target FK share the pivot across multiple target types
@@ -1281,16 +1321,37 @@ export class MetadataDiscovery {
         // the prefix of the parent cannot be a boolean; it already passed here
         const prefix = this.getPrefix(embeddedProp, parentProperty);
         const glue = object ? '~' : '_';
-        for (const prop of Object.values(embeddable.properties)) {
-            const name = (embeddedProp.embeddedPath?.join(glue) ?? embeddedProp.fieldNames[0] + glue) + prop.name;
+        const props = Object.values(embeddable.properties);
+        // variants can declare a same-named property of a different kind, the virtual entity lacks it when the variants are shared with another union
+        for (const prop of embeddable.polymorphs?.flatMap(m => Object.values(m.properties)) ?? []) {
+            const same = props.find(p => p.name === prop.name && Utils.isSameKind(p, prop));
+            if (!same && !prop.embedded) {
+                props.push({ ...prop }); // a copy, the variant's metadata is shared with its other owners
+            }
+            else if (same && same.kind !== ReferenceKind.SCALAR && same.type !== prop.type) {
+                // a column shared by relations to different targets cannot have a FK constraint
+                same.createForeignKeyConstraint = false;
+            }
+        }
+        for (const prop of props) {
+            const sameName = props.filter(p => p.name === prop.name);
+            // same-kind variants of a conflicting property share one owner property, as they share the column
+            const first = sameName.find(p => Utils.isSameKind(p, prop));
+            const conflict = first !== sameName[0];
+            const name = (embeddedProp.embeddedPath?.join(glue) ?? embeddedProp.fieldNames[0] + glue) +
+                prop.name +
+                (conflict ? `_${props.indexOf(first)}` : '');
             meta.properties[name] = Utils.copy(prop);
             meta.properties[name].name = name;
+            // STI column tracking between the variants does not apply to the owner's columns
+            delete meta.properties[name].stiFieldNames;
             meta.properties[name].embedded = [embeddedProp.name, prop.name];
             meta.propertyOrder.set(name, (order += 0.01));
-            embeddedProp.embeddedProps[prop.name] = meta.properties[name];
+            embeddedProp.embeddedProps[conflict ? name : prop.name] = meta.properties[name];
             meta.properties[name].persist ??= embeddedProp.persist;
             const refInArray = array && [ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) && prop.owner;
-            if (embeddedProp.nullable || refInArray) {
+            // each variant fills only its own column of a conflicting property
+            if (embeddedProp.nullable || refInArray || sameName.some(p => !Utils.isSameKind(p, prop))) {
                 meta.properties[name].nullable = true;
             }
             // polymorphic relations derive their column names from the discriminator, so prefix it too
@@ -1463,6 +1524,13 @@ export class MetadataDiscovery {
                 rootProp.stiFieldNameMap[meta.discriminatorValue] = prop.fieldNames[0];
                 // subtypes that only differ in type share the column
                 rootProp.stiFieldNames = Utils.unique([...rootProp.stiFieldNames, ...prop.fieldNames]);
+                // a column shared by relations to different targets cannot have a FK constraint
+                for (const p of Object.values(meta.root.properties)) {
+                    const shared = p.type !== newProp.type && compareArrays(p.fieldNames ?? [], newProp.fieldNames);
+                    if (shared && p.kind !== ReferenceKind.SCALAR && Utils.isSameKind(p, newProp)) {
+                        p.createForeignKeyConstraint = newProp.createForeignKeyConstraint = false;
+                    }
+                }
                 newProp.nullable = true;
                 newProp.name = name;
                 newProp.hydrate = false;
@@ -1507,6 +1575,9 @@ export class MetadataDiscovery {
             if (isInverseSideRelation && rootProp && rootProp.type !== prop.type) {
                 return;
             }
+            // a sibling matching the root property must not drop the column variants of already renamed siblings
+            newProp.stiFieldNames ??= rootProp?.stiFieldNames;
+            newProp.stiFieldNameMap ??= rootProp?.stiFieldNameMap;
             meta.root.addProperty(newProp);
         });
         meta.tableName = meta.root.tableName;
@@ -1627,7 +1698,7 @@ export class MetadataDiscovery {
         if (meta.inheritanceType !== 'tpt') {
             return;
         }
-        const belongsToTable = (prop) => prop.persist !== false || prop.primary;
+        const belongsToTable = (prop) => prop.persist !== false || prop.primary || !!prop.formula;
         // Use meta.properties (object) since meta.props (array) may not be populated yet
         const allProps = Object.values(meta.properties);
         if (!meta.tptParent) {
@@ -1873,9 +1944,9 @@ export class MetadataDiscovery {
         // guard preserves the legacy convention where JSON defaults are passed pre-stringified.
         // Array defaults are converted unconditionally (e.g. `default: []` on a JSON-backed embedded array).
         if (prop.customType && (Array.isArray(prop.default) || prop.customType.compareAsType() !== 'any')) {
-            val = prop.customType.convertToDatabaseValue(prop.default, this.#platform);
+            val = prop.customType.convertToDatabaseValue(prop.default, this.#platform, { mode: 'discovery' });
         }
-        prop.defaultRaw = typeof val === 'string' ? `'${val}'` : '' + val;
+        prop.defaultRaw = typeof val === 'string' ? this.#platform.quoteDefaultValue(val) : '' + val;
     }
     inferTypeFromDefault(prop) {
         if ((prop.defaultRaw == null && prop.default == null) || prop.type !== 'any') {

package/metadata/MetadataStorage.d.ts

@@ -9,6 +9,7 @@ export declare class MetadataStorage {
     /** Returns the global metadata dictionary, or a specific entry by entity name and path (keyed by the class reference when `target` is provided). */
     static getMetadata(): Dictionary<EntityMetadata>;
     static getMetadata<T = any>(entity: string, path: string, target?: EntityCtor): EntityMetadata<T>;
+    private static hashPath;
     /** Checks whether an entity with the given class name exists in the global metadata. */
     static isKnownEntity(name: string): boolean;
     /** Clears all entries from the global metadata registry. */

package/metadata/MetadataStorage.js

@@ -13,6 +13,10 @@ export class MetadataStorage {
     static PATH_SYMBOL = Symbol.for('@mikro-orm/core/MetadataStorage.PATH_SYMBOL');
     static META_SYMBOL = Symbol.for('@mikro-orm/core/MetadataStorage.META_SYMBOL');
     static #metadata = getGlobalStorage('metadata');
+    /** Lives in the global storage next to the registry, so it stays in sync when several copies of this module share it (e.g. after `vi.resetModules()`). */
+    static #classNames = getGlobalStorage('metadata-class-names');
+    /** Hashes of entity file paths, decorators call `getMetadata()` with the same path for every decorated member. */
+    static #pathHashes = new Map();
     #metadataMap = new Map();
     #idMap;
     #classNameMap;
@@ -31,7 +35,7 @@ export class MetadataStorage {
         }
     }
     static getMetadata(entity, path, target) {
-        const key = entity && path ? entity + '-' + Utils.hash(path) : null;
+        const key = entity && path ? entity + '-' + MetadataStorage.hashPath(path) : null;
         // Key the registry by the class reference when available, so two classes minified
         // to the same mangled name don't collide on the `className-path` key.
         if (key && target) {
@@ -43,23 +47,36 @@ export class MetadataStorage {
             }
             // Keep the name-keyed entry in sync, the class-keyed metadata survives `MetadataStorage.clear()`.
             MetadataStorage.#metadata[key] = target[MetadataStorage.META_SYMBOL];
+            MetadataStorage.#classNames.names?.add(target[MetadataStorage.META_SYMBOL].className);
             return target[MetadataStorage.META_SYMBOL];
         }
         if (key && !MetadataStorage.#metadata[key]) {
-            MetadataStorage.#metadata[key] = new EntityMetadata({ className: entity, path });
+            const meta = new EntityMetadata({ className: entity, path });
+            MetadataStorage.#metadata[key] = meta;
+            MetadataStorage.#classNames.names?.add(meta.className);
         }
         if (key) {
             return MetadataStorage.#metadata[key];
         }
         return MetadataStorage.#metadata;
     }
+    static hashPath(path) {
+        let hash = MetadataStorage.#pathHashes.get(path);
+        if (hash === undefined) {
+            hash = Utils.hash(path);
+            MetadataStorage.#pathHashes.set(path, hash);
+        }
+        return hash;
+    }
     /** Checks whether an entity with the given class name exists in the global metadata. */
     static isKnownEntity(name) {
-        return !!Object.values(this.#metadata).find(meta => meta.className === name);
+        this.#classNames.names ??= new Set(Object.values(this.#metadata).map(meta => meta.className));
+        return this.#classNames.names.has(name);
     }
     /** Clears all entries from the global metadata registry. */
     static clear() {
         Object.keys(this.#metadata).forEach(k => delete this.#metadata[k]);
+        delete this.#classNames.names;
     }
     /** Returns the map of all registered entity metadata. */
     getAll() {

package/metadata/MetadataValidator.js

@@ -118,12 +118,13 @@ export class MetadataValidator {
             return Utils.className(p);
         };
         const pivotProps = new Map();
+        const discoveredNames = new Set(discovered.map(m => m.className));
         // check for not discovered entities
         discovered.forEach(meta => Object.values(meta.properties).forEach(prop => {
             if (prop.kind !== ReferenceKind.SCALAR &&
                 !unwrap(prop.type)
                     .split(/ ?\| ?/)
-                    .every(type => discovered.find(m => m.className === type))) {
+                    .every(type => discoveredNames.has(type))) {
                 throw MetadataError.fromUnknownEntity(prop.type, `${meta.className}.${prop.name}`);
             }
             if (prop.pivotEntity) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.3.0-dev.16",
+  "version": "7.3.0-dev.18",
   "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

@@ -204,6 +204,8 @@ export declare abstract class Platform {
     supportsUnionWhere(): boolean;
     /** Returns the SQL type declaration used for array storage. */
     getArrayDeclarationSQL(): string;
+    /** Whether array columns support the `&&` (overlap) operator. */
+    supportsArrayOverlap(): boolean;
     /** Serializes a string array into its database storage format. */
     marshallArray(values: string[]): string;
     /** Deserializes a database-stored array string back into a string array. */
@@ -274,6 +276,8 @@ export declare abstract class Platform {
     }, quote?: string): string;
     /** Quotes a literal value for safe embedding in SQL. */
     quoteValue(value: any): string;
+    /** Quotes a string default value for DDL; dialects that escape with backslashes override this. */
+    quoteDefaultValue(value: string): string;
     escape(value: any): string;
     /** Replaces `?` placeholders in SQL with quoted parameter values. */
     formatQuery(sql: string, params: readonly any[]): string;

package/platforms/Platform.js

@@ -360,6 +360,10 @@ export class Platform {
     getArrayDeclarationSQL() {
         return 'text';
     }
+    /** Whether array columns support the `&&` (overlap) operator. */
+    supportsArrayOverlap() {
+        return false;
+    }
     /** Serializes a string array into its database storage format. */
     marshallArray(values) {
         return values.map(v => (/[,",\\]/.test(v) ? JSON.stringify(v) : v)).join(',');
@@ -573,6 +577,10 @@ export class Platform {
     quoteValue(value) {
         return value;
     }
+    /** Quotes a string default value for DDL; dialects that escape with backslashes override this. */
+    quoteDefaultValue(value) {
+        return `'${value.replaceAll("'", "''")}'`;
+    }
     /* v8 ignore next */
     escape(value) {
         return value;

package/serialization/EntitySerializer.js

@@ -4,20 +4,50 @@ 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 + '.'));
+// Keyed by option objects created for a single `serialize()` call, so caller-owned options are never cached.
+const preparedOptions = new WeakMap();
+function createPathLookup(items) {
+    const heads = new Set();
+    let all = false;
+    for (const item of items) {
+        const dot = item.indexOf('.');
+        heads.add(dot === -1 ? item : item.substring(0, dot));
+        all ||= item === '*';
+    }
+    return { all, heads };
+}
+/**
+ * Copies caller options once per `serialize()` call, so the derived child options and path lookups can be cached
+ * for every entity of the call without ever caching an options object the caller might mutate later.
+ */
+function prepareOptions(options) {
+    if (preparedOptions.has(options)) {
+        return options;
+    }
+    const prepared = {
+        ...options,
+        populate: options.populate ? Utils.asArray(options.populate) : options.populate,
+    };
+    preparedOptions.set(prepared, { children: new Map() });
+    return prepared;
+}
+function pathLookup(options, key) {
+    return (preparedOptions.get(options)[key] ??= createPathLookup(options[key]));
+}
+/** Returns true when any entry in `options[key]` is `propName`, the wildcard `*`, or a dot-path under `propName`. */
+function matchesPath(options, key, propName) {
+    const lookup = pathLookup(options, key);
+    return lookup.all || lookup.heads.has(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.fields) && options.fields.length > 0 && !matchesPath(options.fields, propName)) {
+    if (Array.isArray(options.fields) && options.fields.length > 0 && !matchesPath(options, 'fields', propName)) {
         return false;
     }
-    if (Array.isArray(options.populate) &&
-        options.populate.find(item => item === propName || item.startsWith(propName + '.'))) {
+    if (Array.isArray(options.populate) && pathLookup(options, 'populate').heads.has(propName)) {
         return true;
     }
     if (options.exclude?.find(item => item === propName)) {
@@ -30,7 +60,7 @@ function isVisible(meta, propName, options) {
 function isPopulated(propName, options) {
     if (typeof options.populate !== 'boolean' &&
         Array.isArray(options.populate) &&
-        matchesPath(options.populate, propName)) {
+        matchesPath(options, 'populate', propName)) {
         return true;
     }
     if (typeof options.populate === 'boolean') {
@@ -45,10 +75,10 @@ export class EntitySerializer {
         const wrapped = helper(entity);
         const meta = wrapped.__meta;
         let contextCreated = false;
+        options = prepareOptions(options);
         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;
@@ -145,7 +175,8 @@ export class EntitySerializer {
         if (entity[prop] instanceof Function) {
             const returnValue = entity[prop]();
             if (!options.ignoreSerializers && serializer) {
-                return serializer(returnValue, this.extractChildOptions(options, prop));
+                // copy, so a serializer mutating its options cannot leak into the cached child options
+                return serializer(returnValue, { ...this.extractChildOptions(options, prop) });
             }
             return returnValue;
         }
@@ -186,7 +217,12 @@ export class EntitySerializer {
         return prop.customType.toJSON(value, platform);
     }
     static extractChildOptions(options, prop) {
-        return {
+        const prepared = preparedOptions.get(options);
+        const cached = prepared.children.get(prop);
+        if (cached) {
+            return cached;
+        }
+        const child = {
             ...options,
             populate: Array.isArray(options.populate)
                 ? Utils.extractChildElements(options.populate, prop, '*')
@@ -194,6 +230,9 @@ export class EntitySerializer {
             exclude: Array.isArray(options.exclude) ? Utils.extractChildElements(options.exclude, prop) : options.exclude,
             fields: Array.isArray(options.fields) ? this.extractChildFields(options.fields, prop) : options.fields,
         };
+        prepared.children.set(prop, child);
+        preparedOptions.set(child, { children: new Map() });
+        return child;
     }
     /**
      * Extracts the nested `fields` whitelist for a child property. A bare parent name (`fields: ['books']`) or a
@@ -269,8 +308,9 @@ export class EntitySerializer {
  * ```
  */
 export function serialize(entities, options) {
+    const prepared = prepareOptions(options ?? {});
     if (Array.isArray(entities)) {
-        return entities.map(e => EntitySerializer.serialize(e, options));
+        return entities.map(e => EntitySerializer.serialize(e, prepared));
     }
-    return EntitySerializer.serialize(entities, options);
+    return EntitySerializer.serialize(entities, prepared);
 }

package/types/DoubleType.d.ts

@@ -2,10 +2,14 @@ import { Type } from './Type.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { EntityProperty } from '../typings.js';
 /**
- * Type that maps an SQL DOUBLE to a JS string or number.
+ * Type that maps an SQL DOUBLE to a JS number (default) or string.
  */
-export declare class DoubleType extends Type<number | string, string> {
-    convertToJSValue(value: string): number | string;
+export declare class DoubleType<Mode extends 'number' | 'string' = 'number'> extends Type<JSTypeByMode<Mode>, string> {
+    mode?: Mode | undefined;
+    constructor(mode?: Mode | undefined);
+    convertToJSValue(value: string): JSTypeByMode<Mode>;
     getColumnType(prop: EntityProperty, platform: Platform): string;
     compareAsType(): string;
 }
+type JSTypeByMode<Mode extends 'number' | 'string'> = Mode extends 'number' ? number : string;
+export {};

package/types/DoubleType.js

@@ -1,11 +1,16 @@
 import { Type } from './Type.js';
 /**
- * Type that maps an SQL DOUBLE to a JS string or number.
+ * Type that maps an SQL DOUBLE to a JS number (default) or string.
  */
 export class DoubleType extends Type {
+    mode;
+    constructor(mode) {
+        super();
+        this.mode = mode;
+    }
     /* v8 ignore next */
     convertToJSValue(value) {
-        if (this.prop?.runtimeType === 'number') {
+        if ((this.mode ?? this.prop?.runtimeType) === 'number') {
             return +value;
         }
         return String(value);
@@ -14,6 +19,6 @@ export class DoubleType extends Type {
         return platform.getDoubleDeclarationSQL();
     }
     compareAsType() {
-        return this.prop?.runtimeType ?? 'number';
+        return this.mode ?? this.prop?.runtimeType ?? 'number';
     }
 }

package/typings.d.ts

@@ -358,12 +358,15 @@ type ElemMatchCondition<T extends Record<string, any>> = {
     $and?: ElemMatchCondition<T>[];
     $not?: ElemMatchCondition<T>;
 };
-type ElemMatchFilter<T> = T extends readonly (infer E)[] ? E extends Record<string, any> ? {
+type ArrayFilter<T> = T extends readonly (infer E)[] ? [E] extends [Scalar] ? {
+    $in?: readonly (readonly ExpandScalar<E>[])[];
+    $nin?: readonly (readonly ExpandScalar<E>[])[];
+} : E extends Record<string, any> ? {
     $elemMatch: ElemMatchCondition<E>;
 } : never : never;
 /** Object form of a filter query, mapping entity keys to their filter conditions. */
 export type FilterObject<T> = {
-    -readonly [K in EntityKey<T>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | ElemMatchFilter<FilterObjectProp<T, K>> | null;
+    -readonly [K in EntityKey<T>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | ArrayFilter<FilterObjectProp<T, K>> | null;
 };
 /** Recursively expands a type into its `FilterQuery` form for nested object filtering. */
 export type ExpandQuery<T> = T extends object ? (T extends Scalar ? never : FilterQuery<T>) : FilterValue<T>;
@@ -383,7 +386,7 @@ export type FilterQuery<T> = ObjectQuery<T> | NonNullable<ExpandScalar<Primary<T
  * Used when `using` option is set in `FindOptions` to enforce type-safe index usage.
  */
 export type IndexFilterQuery<T, Using extends string> = [Using] extends [never] ? FilterQuery<T> : (OperatorMap<T> & {
-    -readonly [K in Extract<EntityKey<T>, IndexColumns<T, Using>>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | ElemMatchFilter<FilterObjectProp<T, K>> | null;
+    -readonly [K in Extract<EntityKey<T>, IndexColumns<T, Using>>]?: ExpandQuery<ExpandProperty<FilterObjectProp<T, K>>> | ExpandQueryMerged<ExpandProperty<FilterObjectProp<T, K>>> | FilterValue<ExpandProperty<FilterObjectProp<T, K>>> | ArrayFilter<FilterObjectProp<T, K>> | null;
 }) | NonNullable<ExpandScalar<Primary<T>>> | IndexFilterQuery<T, Using>[];
 /** Replaces `where` and `using` on an options type with index-aware variants when `Using` is specified. */
 export type WithUsingOptions<Opts, Entity, Using extends string> = Omit<Opts, 'where' | 'using'> & {
@@ -564,6 +567,13 @@ export declare namespace LazyRef {
         [__lazyRef]?: (arg: T) => T;
     }
 }
+/**
+ * The brand's only key is optional, so an object type without named properties (like `Record<string, number>`)
+ * extends `LazyRef.Brand<infer U>` too, with `U` inferred as `unknown`. `LazyRef<T>` needs `T extends object`,
+ * so an `unknown` target means the type is not a `LazyRef` and resolves to `Fallback`. `any` stays `any`.
+ * Only checked once `unknown extends U` holds, so a real `LazyRef` skips it.
+ */
+type NotLazyRef<U, Fallback> = IsAny<U> extends true ? U : Fallback;
 /** Alias for `Reference<T> & { id: number }` (see {@apilink Ref}). */
 export type EntityRef<T extends object> = true extends IsUnknown<PrimaryProperty<T>> ? Reference<T> : IsAny<T> extends true ? Reference<T> : {
     [K in PrimaryProperty<T> & keyof T]: T[K];
@@ -1620,7 +1630,8 @@ export type UnboxArray<T> = T extends any[] ? ArrayElement<T> : T;
 /** Extracts the element type from an array type. */
 export type ArrayElement<ArrayType extends unknown[]> = ArrayType extends (infer ElementType)[] ? ElementType : never;
 /** Unwraps a property type from its wrapper (Reference, Collection, or array) to the inner entity type. */
-export type ExpandProperty<T> = T extends LazyRef.Brand<infer U> ? NonNullable<U> : T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
+export type ExpandProperty<T> = ExpandPropertyOf<T, T>;
+type ExpandPropertyOf<T, R> = T extends LazyRef.Brand<infer U> ? unknown extends U ? NotLazyRef<U, NonNullable<R>> : NonNullable<U> : T extends ReferenceShape<infer U> ? NonNullable<U> : T extends CollectionShape<infer U> ? NonNullable<U> : T extends (infer U)[] ? NonNullable<U> : NonNullable<T>;
 type LoadedLoadable<T, E extends object> = T extends CollectionShape ? LoadedCollection<E> : T extends ScalarReference<infer U> ? LoadedScalarReference<U> : T extends LazyRef.Brand<any> ? E : T extends ReferenceShape ? T & LoadedReference<E> : T extends Scalar ? T : T extends (infer U)[] ? U extends Scalar ? T : E[] : E;
 type IsTrue<T> = IsNever<T> extends true ? false : T extends boolean ? (T extends true ? true : false) : false;
 type StringLiteral<T> = T extends string ? (string extends T ? never : T) : never;
@@ -1655,7 +1666,12 @@ export type MergeSelected<T, U, F extends string> = IsLoadedType<T> extends true
 export type MergeLoaded<T, U, P extends string, F extends string, E extends string, R extends boolean = false> = IsLoadedType<T> extends true ? T & Loaded<U, P, F, E> : Loaded<T, P, F, E>;
 /** Extracts the nullability modifiers (`null`, `undefined`, or both) from a type `T`. */
 export type AddOptional<T> = undefined | null extends T ? null | undefined : null extends T ? null : undefined extends T ? undefined : never;
-type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractTypeWithLazyRef<T>, L, F, E>>;
+/**
+ * Like {@link ExtractTypeWithLazyRef}, but a record type that matched `LazyRef.Brand` resolves to itself (see
+ * {@link NotLazyRef}). `AutoPath` keeps the unguarded version, as it is on its hot path.
+ */
+type ExtractLoadedType<T> = T extends LazyRef.Brand<infer U> ? (unknown extends U ? NotLazyRef<U, ExtractType<T>> : U) : ExtractType<T>;
+type LoadedProp<T, L extends string = never, F extends string = '*', E extends string = never> = LoadedLoadable<T, Loaded<ExtractLoadedType<T>, L, F, E>>;
 /** Extracts the eager-loaded property names declared via `[EagerProps]` as a string union. */
 export type AddEager<T> = ExtractEagerProps<T> & string;
 /** Combines an explicit populate hint `L` with the entity's eagerly loaded properties. */

package/typings.js

@@ -304,8 +304,11 @@ export class EntityMetadata {
         }, { __gettersDefined: { value: true, enumerable: false } });
     }
     initIndexes(prop) {
-        const simpleIndex = this.indexes.find(index => index.properties === prop.name && !index.options && !index.type && !index.expression && index.where == null);
-        const simpleUnique = this.uniques.find(index => index.properties === prop.name && !index.options && !index.expression && index.where == null);
+        // `prop.index`/`prop.unique` keep only the name, so an index with any other option must stay in `meta.indexes`
+        const isSimple = (index) => index.properties === prop.name &&
+            Object.entries(index).every(([key, value]) => key === 'name' || key === 'properties' || value == null);
+        const simpleIndex = this.indexes.find(isSimple);
+        const simpleUnique = this.uniques.find(isSimple);
         const owner = prop.kind === ReferenceKind.MANY_TO_ONE;
         if (!prop.index && simpleIndex) {
             Utils.defaultValue(simpleIndex, 'name', true);