@mikro-orm/core 7.0.0-rc.2 → 7.0.0

package/drivers/IDatabaseDriver.d.ts

@@ -110,6 +110,22 @@ export interface FindOptions<Entity, Hint extends string = never, Fields extends
      * when nesting the condition. This is used for implementation of joined filters.
      */
     populateFilter?: ObjectQuery<Entity>;
+    /**
+     * Index-friendly alternative to `$or` for conditions that span joined relations.
+     * Each array element becomes an independent branch combined via `UNION ALL` subquery:
+     * `WHERE pk IN (branch_1 UNION ALL branch_2 ... branch_N)`.
+     * The database plans each branch independently, enabling per-table index usage
+     * (e.g. GIN trigram indexes for fuzzy search across related entities).
+     * sql only
+     */
+    unionWhere?: ObjectQuery<Entity>[];
+    /**
+     * Strategy for combining `unionWhere` branches.
+     * - `'union-all'` (default) — skips deduplication, faster for most use cases.
+     * - `'union'` — deduplicates rows between branches; useful when branch overlap is very high.
+     * sql only
+     */
+    unionWhereStrategy?: 'union-all' | 'union';
     /** Used for ordering of the populate queries. If not specified, the value of `options.orderBy` is used. */
     populateOrderBy?: OrderDefinition<Entity>;
     /** Per-relation overrides for populate loading behavior. Keys are populate paths (same as used in `populate`). */
@@ -199,6 +215,13 @@ export interface NativeInsertUpdateOptions<T> {
     /** `nativeUpdate()` only option */
     upsert?: boolean;
     loggerContext?: LogContext;
+    /** sql only */
+    unionWhere?: ObjectQuery<T>[];
+    /** sql only */
+    unionWhereStrategy?: 'union-all' | 'union';
+    filters?: FilterOptions;
+    /** @internal */
+    em?: EntityManager;
 }
 export interface NativeInsertUpdateManyOptions<T> extends NativeInsertUpdateOptions<T> {
     processCollections?: boolean;
@@ -223,6 +246,10 @@ export interface CountOptions<T extends object, P extends string = never> {
     populate?: Populate<T, P>;
     populateWhere?: ObjectQuery<T> | PopulateHint | `${PopulateHint}`;
     populateFilter?: ObjectQuery<T>;
+    /** @see FindOptions.unionWhere */
+    unionWhere?: ObjectQuery<T>[];
+    /** @see FindOptions.unionWhereStrategy */
+    unionWhereStrategy?: 'union-all' | 'union';
     ctx?: Transaction;
     connectionType?: ConnectionType;
     flushMode?: FlushMode | `${FlushMode}`;
@@ -245,12 +272,28 @@ export interface UpdateOptions<T> {
     filters?: FilterOptions;
     schema?: string;
     ctx?: Transaction;
+    /** sql only */
+    unionWhere?: ObjectQuery<T>[];
+    /** sql only */
+    unionWhereStrategy?: 'union-all' | 'union';
 }
 export interface DeleteOptions<T> extends DriverMethodOptions {
     filters?: FilterOptions;
+    /** sql only */
+    unionWhere?: ObjectQuery<T>[];
+    /** sql only */
+    unionWhereStrategy?: 'union-all' | 'union';
+    /** @internal */
+    em?: EntityManager;
 }
 export interface NativeDeleteOptions<T> extends DriverMethodOptions {
     filters?: FilterOptions;
+    /** sql only */
+    unionWhere?: ObjectQuery<T>[];
+    /** sql only */
+    unionWhereStrategy?: 'union-all' | 'union';
+    /** @internal */
+    em?: EntityManager;
 }
 export interface LockOptions extends DriverMethodOptions {
     lockMode?: LockMode;

package/entity/Collection.d.ts

@@ -9,17 +9,9 @@ export interface MatchingOptions<T extends object, P extends string = never> ext
     ctx?: Transaction;
 }
 export declare class Collection<T extends object, O extends object = object> {
+    #private;
     readonly owner: O;
     [k: number]: T;
-    protected readonly items: Set<T>;
-    protected initialized: boolean;
-    protected dirty: boolean;
-    protected partial: boolean;
-    protected snapshot: T[] | undefined;
-    private readonly?;
-    protected _count?: number;
-    private _property?;
-    private _populated?;
     constructor(owner: O, items?: T[], initialized?: boolean);
     /**
      * Creates new Collection instance, assigns it to the owning entity and sets the items to it (propagating them to their inverse sides)

package/entity/Collection.js

@@ -7,24 +7,24 @@ import { QueryHelper } from '../utils/QueryHelper.js';
 import { inspect } from '../logging/inspect.js';
 export class Collection {
     owner;
-    items = new Set();
-    initialized = true;
-    dirty = false;
-    partial = false; // mark partially loaded collections, propagation is disabled for those
-    snapshot = []; // used to create a diff of the collection at commit time, undefined marks overridden values so we need to wipe when flushing
-    readonly;
-    _count;
-    _property;
-    _populated;
+    #items = new Set();
+    #initialized = true;
+    #dirty = false;
+    #partial = false; // mark partially loaded collections, propagation is disabled for those
+    #snapshot = []; // used to create a diff of the collection at commit time, undefined marks overridden values so we need to wipe when flushing
+    #readonly;
+    #count;
+    #property;
+    #populated;
     constructor(owner, items, initialized = true) {
         this.owner = owner;
         /* v8 ignore next */
         if (items) {
             let i = 0;
-            this.items = new Set(items);
-            this.items.forEach(item => this[i++] = item);
+            this.#items = new Set(items);
+            this.#items.forEach(item => (this[i++] = item));
         }
-        this.initialized = !!items || initialized;
+        this.#initialized = !!items || initialized;
     }
     /**
      * Creates new Collection instance, assigns it to the owning entity and sets the items to it (propagating them to their inverse sides)
@@ -44,9 +44,9 @@ export class Collection {
      */
     async load(options = {}) {
         if (this.isInitialized(true) && !options.refresh) {
-            const em = this.getEntityManager(this.items, false);
+            const em = this.getEntityManager(this.#items, false);
             options = { ...options, filters: QueryHelper.mergePropertyFilters(this.property.filters, options.filters) };
-            await em?.populate(this.items, options.populate, options);
+            await em?.populate(this.#items, options.populate, options);
             this.setSerializationContext(options);
         }
         else {
@@ -58,7 +58,7 @@ export class Collection {
         helper(this.owner).setSerializationContext({
             populate: Array.isArray(options.populate)
                 ? options.populate.map(hint => `${this.property.name}.${hint}`)
-                : options.populate ?? [this.property.name],
+                : (options.populate ?? [this.property.name]),
         });
     }
     /**
@@ -75,17 +75,19 @@ export class Collection {
     async loadCount(options = {}) {
         options = typeof options === 'boolean' ? { refresh: options } : options;
         const { refresh, where, ...countOptions } = options;
-        if (!refresh && !where && this._count != null) {
-            return this._count;
+        if (!refresh && !where && this.#count != null) {
+            return this.#count;
         }
         const em = this.getEntityManager();
-        if (!em.getPlatform().usesPivotTable() && this.property.kind === ReferenceKind.MANY_TO_MANY && this.property.owner) {
-            return this._count = this.length;
+        if (!em.getPlatform().usesPivotTable() &&
+            this.property.kind === ReferenceKind.MANY_TO_MANY &&
+            this.property.owner) {
+            return (this.#count = this.length);
         }
         const cond = this.createLoadCountCondition(where ?? {});
         const count = await em.count(this.property.targetMeta.class, cond, countOptions);
         if (!where) {
-            this._count = count;
+            this.#count = count;
         }
         return count;
     }
@@ -96,22 +98,24 @@ export class Collection {
         if (this.property.kind === ReferenceKind.MANY_TO_MANY && em.getPlatform().usesPivotTable()) {
             // M:N via pivot table bypasses em.find(), so merge all 3 levels here
             opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy, this.property.targetMeta?.orderBy);
-            options.populate = await em.preparePopulate(this.property.targetMeta.class, options);
-            const cond = await em.applyFilters(this.property.targetMeta.class, where, options.filters ?? {}, 'read');
-            const map = await em.getDriver().loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, ctx, options);
+            options.populate = (await em.preparePopulate(this.property.targetMeta.class, options));
+            const cond = (await em.applyFilters(this.property.targetMeta.class, where, options.filters ?? {}, 'read'));
+            const map = await em
+                .getDriver()
+                .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, ctx, options);
             items = map[helper(this.owner).getSerializedPrimaryKey()].map((item) => em.merge(this.property.targetMeta.class, item, { convertCustomTypes: true }));
             await em.populate(items, options.populate, options);
         }
         else {
             // em.find() merges entity-level orderBy, so only merge runtime + relation here
             opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy);
-            items = await em.find(this.property.targetMeta.class, this.createCondition(where), opts);
+            items = (await em.find(this.property.targetMeta.class, this.createCondition(where), opts));
         }
         if (options.store) {
             this.hydrate(items, true);
             this.setSerializationContext(options);
             this.populated();
-            this.readonly = true;
+            this.#readonly = true;
         }
         return items;
     }
@@ -122,7 +126,7 @@ export class Collection {
         if (check) {
             this.checkInitialized();
         }
-        return [...this.items];
+        return [...this.#items];
     }
     toJSON() {
         if (!this.isInitialized()) {
@@ -140,10 +144,10 @@ export class Collection {
             const entity = Reference.unwrapReference(item);
             if (!this.contains(entity, false)) {
                 this.incrementCount(1);
-                this[this.items.size] = entity;
-                this.items.add(entity);
+                this[this.#items.size] = entity;
+                this.#items.add(entity);
                 added++;
-                this.dirty = true;
+                this.#dirty = true;
                 this.propagate(entity, 'add');
             }
         }
@@ -162,7 +166,7 @@ export class Collection {
     remove(entity, ...entities) {
         if (entity instanceof Function) {
             let removed = 0;
-            for (const item of this.items) {
+            for (const item of this.#items) {
                 if (entity(item)) {
                     removed += this.remove(item);
                 }
@@ -180,12 +184,12 @@ export class Collection {
                 continue;
             }
             const entity = Reference.unwrapReference(item);
-            if (this.items.delete(entity)) {
+            if (this.#items.delete(entity)) {
                 this.incrementCount(-1);
-                delete this[this.items.size]; // remove last item
+                delete this[this.#items.size]; // remove last item
                 this.propagate(entity, 'remove');
                 removed++;
-                this.dirty = true;
+                this.#dirty = true;
             }
             if (this.property.orphanRemoval && em) {
                 em.getUnitOfWork().scheduleOrphanRemoval(entity);
@@ -195,7 +199,7 @@ export class Collection {
             em.persist(entities);
         }
         if (removed > 0) {
-            Object.assign(this, [...this.items]); // reassign array access
+            Object.assign(this, [...this.#items]); // reassign array access
         }
         return removed;
     }
@@ -204,11 +208,11 @@ export class Collection {
             this.checkInitialized();
         }
         const entity = Reference.unwrapReference(item);
-        return this.items.has(entity);
+        return this.#items.has(entity);
     }
     count() {
         this.checkInitialized();
-        return this.items.size;
+        return this.#items.size;
     }
     isEmpty() {
         this.checkInitialized();
@@ -218,18 +222,18 @@ export class Collection {
         if (!this.isInitialized(true)) {
             return false;
         }
-        if (this._populated != null) {
-            return this._populated;
+        if (this.#populated != null) {
+            return this.#populated;
         }
         return !!populated;
     }
     populated(populated = true) {
-        this._populated = populated;
+        this.#populated = populated;
     }
     async init(options = {}) {
-        if (this.dirty) {
-            const items = [...this.items];
-            this.dirty = false;
+        if (this.#dirty) {
+            const items = [...this.#items];
+            this.#dirty = false;
             await this.init(options);
             items.forEach(i => this.add(i));
             return this;
@@ -237,36 +241,34 @@ export class Collection {
         const em = this.getEntityManager();
         options = { ...options, filters: QueryHelper.mergePropertyFilters(this.property.filters, options.filters) };
         if (options.dataloader ?? [DataloaderType.ALL, DataloaderType.COLLECTION].includes(em.config.getDataloaderType())) {
-            const order = [...this.items]; // copy order of references
+            const order = [...this.#items]; // copy order of references
             const orderBy = QueryHelper.mergeOrderBy(options.orderBy, this.property.orderBy, this.property.targetMeta?.orderBy);
             const customOrder = orderBy.length > 0;
             const pivotTable = this.property.kind === ReferenceKind.MANY_TO_MANY && em.getPlatform().usesPivotTable();
             const loader = await em.getDataLoader(pivotTable ? 'm:n' : '1:m');
             const items = await loader.load([this, { ...options, orderBy }]);
             if (this.property.kind === ReferenceKind.MANY_TO_MANY) {
-                this.initialized = true;
-                this.dirty = false;
+                this.#initialized = true;
+                this.#dirty = false;
                 if (!customOrder) {
                     this.reorderItems(items, order);
                 }
                 return this;
             }
-            this.items.clear();
+            this.#items.clear();
             let i = 0;
             for (const item of items) {
-                this.items.add(item);
+                this.#items.add(item);
                 this[i++] = item;
             }
-            this.initialized = true;
-            this.dirty = false;
+            this.#initialized = true;
+            this.#dirty = false;
             return this;
         }
         const populate = Array.isArray(options.populate)
-            ? options.populate.map(f => f === '*' ? f : `${this.property.name}.${f}`)
+            ? options.populate.map(f => (f === '*' ? f : `${this.property.name}.${f}`))
             : [`${this.property.name}${options.ref ? ':ref' : ''}`];
-        const schema = this.property.targetMeta.schema === '*'
-            ? helper(this.owner).__schema
-            : undefined;
+        const schema = this.property.targetMeta.schema === '*' ? helper(this.owner).__schema : undefined;
         await em.populate(this.owner, populate, {
             refresh: true,
             ...options,
@@ -297,7 +299,8 @@ export class Collection {
         if (this.property.kind === ReferenceKind.ONE_TO_MANY) {
             cond[this.property.mappedBy] = helper(this.owner).getPrimaryKey();
         }
-        else { // MANY_TO_MANY
+        else {
+            // MANY_TO_MANY
             this.createManyToManyCondition(cond);
         }
         return cond;
@@ -308,7 +311,7 @@ export class Collection {
             // we know there is at least one item as it was checked in load method
             const pk = this.property.targetMeta.primaryKeys[0];
             dict[pk] = { $in: [] };
-            this.items.forEach(item => dict[pk].$in.push(helper(item).getPrimaryKey()));
+            this.#items.forEach(item => dict[pk].$in.push(helper(item).getPrimaryKey()));
         }
         else {
             dict[this.property.mappedBy] = helper(this.owner).getPrimaryKey();
@@ -350,7 +353,7 @@ export class Collection {
         }
     }
     validateModification(items) {
-        if (this.readonly) {
+        if (this.#readonly) {
             throw ValidationError.cannotModifyReadonlyCollection(this.owner, this.property);
         }
         const check = (item) => {
@@ -375,7 +378,7 @@ export class Collection {
         }
     }
     toArray() {
-        if (this.items.size === 0) {
+        if (this.#items.size === 0) {
             return [];
         }
         return this.map(item => wrap(item).toJSON());
@@ -386,7 +389,9 @@ export class Collection {
         if (items.length === 0) {
             return [];
         }
-        field ??= targetMeta.compositePK ? targetMeta.primaryKeys : (targetMeta.serializedPrimaryKey ?? targetMeta.primaryKeys[0]);
+        field ??= targetMeta.compositePK
+            ? targetMeta.primaryKeys
+            : (targetMeta.serializedPrimaryKey ?? targetMeta.primaryKeys[0]);
         const cb = (i, f) => {
             if (Utils.isEntity(i[f], true)) {
                 return wrap(i[f], true).getPrimaryKey();
@@ -406,28 +411,28 @@ export class Collection {
     addWithoutPropagation(entity) {
         if (!this.contains(entity, false)) {
             this.incrementCount(1);
-            this[this.items.size] = entity;
-            this.items.add(entity);
-            this.dirty = true;
+            this[this.#items.size] = entity;
+            this.#items.add(entity);
+            this.#dirty = true;
         }
     }
     set(items) {
-        if (!this.initialized) {
-            this.initialized = true;
-            this.snapshot = undefined;
+        if (!this.#initialized) {
+            this.#initialized = true;
+            this.#snapshot = undefined;
         }
         if (this.compare(Utils.asArray(items).map(item => Reference.unwrapReference(item)))) {
             return;
         }
-        this.remove(this.items);
+        this.remove(this.#items);
         this.add(items);
     }
     compare(items) {
-        if (items.length !== this.items.size) {
+        if (items.length !== this.#items.size) {
             return false;
         }
         let idx = 0;
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (item !== items[idx++]) {
                 return false;
             }
@@ -438,13 +443,13 @@ export class Collection {
      * @internal
      */
     hydrate(items, forcePropagate, partial) {
-        for (let i = 0; i < this.items.size; i++) {
+        for (let i = 0; i < this.#items.size; i++) {
             delete this[i];
         }
-        this.initialized = true;
-        this.partial = !!partial;
-        this.items.clear();
-        this._count = 0;
+        this.#initialized = true;
+        this.#partial = !!partial;
+        this.#items.clear();
+        this.#count = 0;
         this.add(items);
         this.takeSnapshot(forcePropagate);
     }
@@ -455,24 +460,24 @@ export class Collection {
      * which tells the ORM we don't want orphaned entities to exist, so we know those should be removed.
      */
     removeAll() {
-        if (!this.initialized) {
-            this.initialized = true;
-            this.snapshot = undefined;
+        if (!this.#initialized) {
+            this.#initialized = true;
+            this.#snapshot = undefined;
         }
-        this.remove(this.items);
-        this.dirty = true;
+        this.remove(this.#items);
+        this.#dirty = true;
     }
     /**
      * @internal
      */
     removeWithoutPropagation(entity) {
-        if (!this.items.delete(entity)) {
+        if (!this.#items.delete(entity)) {
             return;
         }
         this.incrementCount(-1);
-        delete this[this.items.size];
-        Object.assign(this, [...this.items]);
-        this.dirty = true;
+        delete this[this.#items.size];
+        Object.assign(this, [...this.#items]);
+        this.#dirty = true;
     }
     /**
      * Extracts a slice of the collection items starting at position start to end (exclusive) of the collection.
@@ -481,9 +486,9 @@ export class Collection {
     slice(start = 0, end) {
         this.checkInitialized();
         let index = 0;
-        end ??= this.items.size;
+        end ??= this.#items.size;
         const items = [];
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (index === end) {
                 break;
             }
@@ -499,7 +504,7 @@ export class Collection {
      */
     exists(cb) {
         this.checkInitialized();
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (cb(item)) {
                 return true;
             }
@@ -512,7 +517,7 @@ export class Collection {
     find(cb) {
         this.checkInitialized();
         let index = 0;
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (cb(item, index++)) {
                 return item;
             }
@@ -526,7 +531,7 @@ export class Collection {
         this.checkInitialized();
         const items = [];
         let index = 0;
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (cb(item, index++)) {
                 items.push(item);
             }
@@ -540,7 +545,7 @@ export class Collection {
         this.checkInitialized();
         const items = [];
         let index = 0;
-        for (const item of this.items) {
+        for (const item of this.#items) {
             items.push(mapper(item, index++));
         }
         return items;
@@ -551,7 +556,7 @@ export class Collection {
     reduce(cb, initial = {}) {
         this.checkInitialized();
         let index = 0;
-        for (const item of this.items) {
+        for (const item of this.#items) {
             initial = cb(initial, item, index++);
         }
         return initial;
@@ -567,10 +572,10 @@ export class Collection {
         }, {});
     }
     isInitialized(fully = false) {
-        if (!this.initialized || !fully) {
-            return this.initialized;
+        if (!this.#initialized || !fully) {
+            return this.#initialized;
         }
-        for (const item of this.items) {
+        for (const item of this.#items) {
             if (!helper(item).__initialized) {
                 return false;
             }
@@ -578,13 +583,13 @@ export class Collection {
         return true;
     }
     isDirty() {
-        return this.dirty;
+        return this.#dirty;
     }
     isPartial() {
-        return this.partial;
+        return this.#partial;
     }
     setDirty(dirty = true) {
-        this.dirty = dirty;
+        this.#dirty = dirty;
     }
     get length() {
         return this.count();
@@ -598,10 +603,10 @@ export class Collection {
      * @internal
      */
     takeSnapshot(forcePropagate) {
-        this.snapshot = [...this.items];
-        this.dirty = false;
+        this.#snapshot = [...this.#items];
+        this.#dirty = false;
         if (this.property.owner || forcePropagate) {
-            this.items.forEach(item => {
+            this.#items.forEach(item => {
                 this.propagate(item, 'takeSnapshot');
             });
         }
@@ -610,27 +615,29 @@ export class Collection {
      * @internal
      */
     getSnapshot() {
-        return this.snapshot;
+        return this.#snapshot;
     }
     /**
      * @internal
      */
     get property() {
-        if (!this._property) {
+        // cannot be typed to `EntityProperty<O, T>` as it causes issues in assignability of `Loaded` type
+        if (!this.#property) {
             const meta = wrap(this.owner, true).__meta;
             /* v8 ignore next */
             if (!meta) {
                 throw MetadataError.fromUnknownEntity(this.owner.constructor.name, 'Collection.property getter, maybe you just forgot to initialize the ORM?');
             }
-            this._property = meta.relations.find(prop => this.owner[prop.name] === this);
+            this.#property = meta.relations.find(prop => this.owner[prop.name] === this);
         }
-        return this._property;
+        return this.#property;
     }
     /**
      * @internal
      */
     set property(prop) {
-        this._property = prop;
+        // cannot be typed to `EntityProperty<O, T>` as it causes issues in assignability of `Loaded` type
+        this.#property = prop;
     }
     propagate(item, method) {
         if (this.property.owner && this.property.inversedBy) {
@@ -689,22 +696,31 @@ export class Collection {
         }
     }
     incrementCount(value) {
-        if (typeof this._count === 'number' && this.initialized) {
-            this._count += value;
+        if (typeof this.#count === 'number' && this.#initialized) {
+            this.#count += value;
         }
     }
     /** @ignore */
     [Symbol.for('nodejs.util.inspect.custom')](depth = 2) {
         const object = { ...this };
-        const hidden = ['items', 'owner', '_property', '_count', 'snapshot', '_populated', '_lazyInitialized', '_em', 'readonly', 'partial'];
-        hidden.forEach(k => delete object[k]);
+        delete object.owner;
+        object.initialized = this.#initialized;
+        object.dirty = this.#dirty;
         const ret = inspect(object, { depth });
         const name = `${this.constructor.name}<${this.property?.type ?? 'unknown'}>`;
         return ret === '[Object]' ? `[${name}]` : name + ' ' + ret;
     }
 }
 Object.defineProperties(Collection.prototype, {
-    $: { get() { return this; } },
-    get: { get() { return () => this; } },
+    $: {
+        get() {
+            return this;
+        },
+    },
+    get: {
+        get() {
+            return () => this;
+        },
+    },
     __collection: { value: true, enumerable: false, writable: false },
 });