@mikro-orm/core 7.1.0-dev.9 → 7.1.1-dev.0

package/unit-of-work/UnitOfWork.js

@@ -36,6 +36,13 @@ export class UnitOfWork {
     #flushQueue = [];
     #working = false;
     #em;
+    /**
+     * UoW lives in `@mikro-orm/core` alongside `EntityManager` and reaches `getAbortOptions`
+     * (TS-protected) via cast — TS has no `friend` keyword, so this is the documented escape hatch.
+     */
+    get #abortOptions() {
+        return this.#em.getAbortOptions();
+    }
     constructor(em) {
         this.#em = em;
         this.#metadata = this.#em.getMetadata();
@@ -371,16 +378,43 @@ export class UnitOfWork {
             this.#identityMap.delete(entity);
         }
         // remove from referencing relations that are nullable
-        for (const prop of helper(entity).__meta.bidirectionalRelations) {
+        const entityMeta = helper(entity).__meta;
+        for (const prop of entityMeta.bidirectionalRelations) {
             const inverseProp = prop.mappedBy || prop.inversedBy;
             const relation = Reference.unwrapReference(entity[prop.name]);
             const prop2 = prop.targetMeta.properties[inverseProp];
+            // skip relations that this entity's class can't actually participate in.
+            // happens with STI: a child meta picks up a sibling's inverse-side relation via the root,
+            // but the owning side targets the sibling — no collection can reference this entity.
+            const inverseTarget = prop2.targetMeta;
+            if (inverseTarget.abstract
+                ? inverseTarget.root.class !== entityMeta.root.class
+                : inverseTarget.class !== entityMeta.class) {
+                continue;
+            }
             if (prop.kind === ReferenceKind.ONE_TO_MANY && prop2.nullable && Utils.isCollection(relation)) {
                 for (const item of relation.getItems(false)) {
                     delete item[inverseProp];
                 }
                 continue;
             }
+            // inlined pivot M:N: scrub the deleted entity from each owning-side document's array;
+            // the owner's collection update rides along inside its UPDATE changeset in the same flush
+            if (prop.kind === ReferenceKind.MANY_TO_MANY &&
+                prop.mappedBy &&
+                !this.#platform.usesPivotTable() &&
+                Utils.isCollection(relation)) {
+                if (!relation.isInitialized(true)) {
+                    throw ValidationError.cannotModifyInverseCollection(entity, prop);
+                }
+                for (const owner of relation.getItems(false)) {
+                    const ownerColl = owner[inverseProp];
+                    if (Utils.isCollection(ownerColl)) {
+                        ownerColl.removeWithoutPropagation(entity);
+                    }
+                }
+                continue;
+            }
             const target = relation?.[inverseProp];
             if (relation && Utils.isCollection(target)) {
                 target.removeWithoutPropagation(entity);
@@ -463,7 +497,7 @@ export class UnitOfWork {
         if (options.lockMode === LockMode.OPTIMISTIC) {
             await this.lockOptimistic(entity, meta, options.lockVersion);
         }
-        else if (options.lockMode != null) {
+        else if (options.lockMode != null && options.lockMode !== LockMode.NONE) {
             await this.lockPessimistic(entity, options);
         }
     }
@@ -474,6 +508,9 @@ export class UnitOfWork {
     }
     unsetIdentity(entity) {
         this.#identityMap.delete(entity);
+        this.#persistStack.delete(entity);
+        this.#removeStack.delete(entity);
+        this.#orphanRemoveStack.delete(entity);
         const wrapped = helper(entity);
         const serializedPK = wrapped.getSerializedPrimaryKey();
         // remove references of this entity in all managed entities, otherwise flushing could reinsert the entity
@@ -999,7 +1036,7 @@ export class UnitOfWork {
             this.findExtraUpdates(changeSet, props);
             await this.runHooks(EventType.beforeCreate, changeSet, true);
         }
-        await this.#changeSetPersister.executeInserts(changeSets, { ctx });
+        await this.#changeSetPersister.executeInserts(changeSets, { ctx, ...this.#abortOptions });
         for (const changeSet of changeSets) {
             // For TPT entities, use the full entity snapshot instead of the partial changeset payload,
             // since each table's changeset only contains its own properties. Without this, the snapshot
@@ -1068,7 +1105,7 @@ export class UnitOfWork {
         for (const changeSet of changeSets) {
             await this.runHooks(EventType.beforeUpdate, changeSet, true);
         }
-        await this.#changeSetPersister.executeUpdates(changeSets, batched, { ctx });
+        await this.#changeSetPersister.executeUpdates(changeSets, batched, { ctx, ...this.#abortOptions });
         for (const changeSet of changeSets) {
             const wrapped = helper(changeSet.entity);
             wrapped.__originalEntityData = this.#comparator.prepareEntity(changeSet.entity);
@@ -1091,7 +1128,7 @@ export class UnitOfWork {
         for (const changeSet of changeSets) {
             await this.runHooks(EventType.beforeDelete, changeSet, true);
         }
-        await this.#changeSetPersister.executeDeletes(changeSets, { ctx });
+        await this.#changeSetPersister.executeDeletes(changeSets, { ctx, ...this.#abortOptions });
         for (const changeSet of changeSets) {
             this.unsetIdentity(changeSet.entity);
             await this.runHooks(EventType.afterDelete, changeSet);
@@ -1129,6 +1166,7 @@ export class UnitOfWork {
             ctx,
             schema: this.#em.schema,
             loggerContext,
+            ...this.#abortOptions,
         });
         for (const coll of this.#collectionUpdates) {
             coll.takeSnapshot();

package/utils/AbstractMigrator.d.ts

@@ -5,14 +5,15 @@ import type { EntityManagerType, IDatabaseDriver } from '../drivers/IDatabaseDri
 interface RunnableMigration {
     name: string;
     path?: string;
-    up: () => MaybePromise<void>;
-    down: () => MaybePromise<void>;
+    up: (afterRun?: (tx?: Transaction) => Promise<void>) => MaybePromise<void>;
+    down: (afterRun?: (tx?: Transaction) => Promise<void>) => MaybePromise<void>;
 }
 type MigrateOptions = {
     from?: string | number;
     to?: string | number;
     migrations?: string[];
     transaction?: Transaction;
+    schema?: string;
 };
 export declare abstract class AbstractMigrator<D extends IDatabaseDriver> implements IMigrator {
     #private;
@@ -57,11 +58,15 @@ export declare abstract class AbstractMigrator<D extends IDatabaseDriver> implem
     /**
      * @inheritDoc
      */
-    getExecuted(): Promise<MigrationRow[]>;
+    getExecuted(options?: {
+        schema?: string;
+    }): Promise<MigrationRow[]>;
     /**
      * @inheritDoc
      */
-    getPending(): Promise<MigrationInfo[]>;
+    getPending(options?: {
+        schema?: string;
+    }): Promise<MigrationInfo[]>;
     /**
      * @inheritDoc
      */

package/utils/AbstractMigrator.js

@@ -38,18 +38,32 @@ export class AbstractMigrator {
     /**
      * @inheritDoc
      */
-    async getExecuted() {
+    async getExecuted(options) {
         await this.init();
-        return this.storage.getExecutedMigrations();
+        const schema = options?.schema ?? this.options.schema;
+        this.storage.setRunSchema?.(schema);
+        try {
+            return await this.storage.getExecutedMigrations();
+        }
+        finally {
+            this.storage.unsetRunSchema?.();
+        }
     }
     /**
      * @inheritDoc
      */
-    async getPending() {
+    async getPending(options) {
         await this.init();
-        const all = await this.discoverMigrations();
-        const executed = new Set(await this.storage.executed());
-        return all.filter(m => !executed.has(m.name)).map(m => ({ name: m.name, path: m.path }));
+        const schema = options?.schema ?? this.options.schema;
+        this.storage.setRunSchema?.(schema);
+        try {
+            const all = await this.discoverMigrations();
+            const executed = new Set(await this.storage.executed());
+            return all.filter(m => !executed.has(m.name)).map(m => ({ name: m.name, path: m.path }));
+        }
+        finally {
+            this.storage.unsetRunSchema?.();
+        }
     }
     /**
      * @inheritDoc
@@ -317,26 +331,26 @@ export class AbstractMigrator {
         }
     }
     resolve(params) {
-        const createMigrationHandler = async (method) => {
+        const createMigrationHandler = async (method, afterRun) => {
             const { fs } = await import('@mikro-orm/core/fs-utils');
             const migration = await fs.dynamicImport(params.path);
             const MigrationClass = Object.values(migration).find(cls => typeof cls === 'function' && typeof cls.constructor === 'function');
             const instance = new MigrationClass(this.driver, this.config);
-            await this.runner.run(instance, method);
+            await this.runner.run(instance, method, afterRun);
         };
         return {
             name: this.storage.getMigrationName(params.name),
             path: params.path,
-            up: () => createMigrationHandler('up'),
-            down: () => createMigrationHandler('down'),
+            up: afterRun => createMigrationHandler('up', afterRun),
+            down: afterRun => createMigrationHandler('down', afterRun),
         };
     }
     initialize(MigrationClass, name) {
         const instance = new MigrationClass(this.driver, this.config);
         return {
             name: this.storage.getMigrationName(name),
-            up: () => this.runner.run(instance, 'up'),
-            down: () => this.runner.run(instance, 'down'),
+            up: afterRun => this.runner.run(instance, 'up', afterRun),
+            down: afterRun => this.runner.run(instance, 'down', afterRun),
         };
     }
     /**
@@ -415,13 +429,15 @@ export class AbstractMigrator {
         for (const migration of toRun) {
             const event = { name: migration.name, path: migration.path };
             await this.emit(eventBefore, event);
-            await migration[method]();
-            if (method === 'up') {
-                await this.storage.logMigration({ name: migration.name });
-            }
-            else {
-                await this.storage.unlogMigration({ name: migration.name });
-            }
+            // log inside the runner's tx (if any) so a logMigration failure rolls the migration back
+            await migration[method](async (tx) => {
+                if (method === 'up') {
+                    await this.storage.logMigration({ name: migration.name }, tx);
+                }
+                else {
+                    await this.storage.unlogMigration({ name: migration.name }, tx);
+                }
+            });
             await this.emit(eventAfter, event);
             result.push(event);
         }
@@ -487,13 +503,17 @@ export class AbstractMigrator {
         return /^\d{14}$/.exec(name) ? this.options.fileName(name) : name;
     }
     prefix(options) {
+        const base = {};
+        if (this.options.schema) {
+            base.schema = this.options.schema;
+        }
         if (typeof options === 'string' || Array.isArray(options)) {
-            return { migrations: Utils.asArray(options).map(name => this.getMigrationFilename(name)) };
+            return { ...base, migrations: Utils.asArray(options).map(name => this.getMigrationFilename(name)) };
         }
         if (!options) {
-            return {};
+            return base;
         }
-        const result = {};
+        const result = base;
         if (options.migrations) {
             result.migrations = options.migrations.map(name => this.getMigrationFilename(name));
         }
@@ -506,23 +526,35 @@ export class AbstractMigrator {
         else if (options.to === 0) {
             result.to = 0;
         }
+        if (options.schema !== undefined) {
+            result.schema = options.schema;
+        }
         return result;
     }
     async runMigrations(method, options) {
         await this.init();
-        if (!this.options.transactional || !this.options.allOrNothing) {
-            return this.executeMigrations(method, this.prefix(options));
+        const normalized = this.prefix(options);
+        this.runner.setRunSchema?.(normalized.schema);
+        this.storage.setRunSchema?.(normalized.schema);
+        try {
+            if (!this.options.transactional || !this.options.allOrNothing) {
+                return await this.executeMigrations(method, normalized);
+            }
+            if (Utils.isObject(options) && options.transaction) {
+                return await this.runInTransaction(options.transaction, method, normalized);
+            }
+            return await this.driver.getConnection().transactional(trx => this.runInTransaction(trx, method, normalized));
         }
-        if (Utils.isObject(options) && options.transaction) {
-            return this.runInTransaction(options.transaction, method, options);
+        finally {
+            this.runner.unsetRunSchema?.();
+            this.storage.unsetRunSchema?.();
         }
-        return this.driver.getConnection().transactional(trx => this.runInTransaction(trx, method, options));
     }
     async runInTransaction(trx, method, options) {
         this.runner.setMasterMigration(trx);
         this.storage.setMasterMigration(trx);
         try {
-            return await this.executeMigrations(method, this.prefix(options));
+            return await this.executeMigrations(method, options);
         }
         finally {
             this.runner.unsetMasterMigration();

package/utils/AbstractSchemaGenerator.d.ts

@@ -34,6 +34,6 @@ export declare abstract class AbstractSchemaGenerator<D extends IDatabaseDriver>
     dropDatabase(name?: string): Promise<void>;
     execute(query: string): Promise<void>;
     ensureIndexes(): Promise<void>;
-    protected getOrderedMetadata(schema?: string): EntityMetadata[];
+    protected getOrderedMetadata(schema?: string, includeWildcardSchema?: boolean): EntityMetadata[];
     protected notImplemented(): never;
 }

package/utils/AbstractSchemaGenerator.js

@@ -89,7 +89,7 @@ export class AbstractSchemaGenerator {
     async ensureIndexes() {
         this.notImplemented();
     }
-    getOrderedMetadata(schema) {
+    getOrderedMetadata(schema, includeWildcardSchema = false) {
         const metadata = [...this.metadata.getAll().values()].filter(meta => {
             const isRootEntity = meta.root.class === meta.class;
             const isTPTChild = meta.inheritanceType === 'tpt' && meta.tptParent;
@@ -116,6 +116,9 @@ export class AbstractSchemaGenerator {
             .sort()
             .map(cls => this.metadata.getById(cls))
             .filter(meta => {
+            if (includeWildcardSchema && meta.schema === '*') {
+                return true;
+            }
             const targetSchema = meta.schema ?? this.config.get('schema', this.platform.getDefaultSchemaName());
             return schema ? [schema, '*'].includes(targetSchema) : meta.schema !== '*';
         });

package/utils/Configuration.d.ts

@@ -6,6 +6,7 @@ import { type Logger, type LoggerNamespace, type LoggerOptions } from '../loggin
 import type { EntityManager } from '../EntityManager.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { EntitySchema } from '../metadata/EntitySchema.js';
+import { Routine } from '../metadata/Routine.js';
 import { MetadataProvider } from '../metadata/MetadataProvider.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
 import type { EventSubscriber } from '../events/EventSubscriber.js';
@@ -27,6 +28,10 @@ export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver,
     get<T extends keyof Options<D, EM>, U extends Options<D, EM>[T]>(key: T, defaultValue?: U): U;
     /** Returns all configuration options. */
     getAll(): Options<D, EM>;
+    /** Validates the `routines` config option on first access and throws on duplicate `(schema, name)` pairs or non-Routine entries. */
+    getRoutines(): readonly Routine[];
+    hasRoutine(routine: Routine): boolean;
+    private normaliseRoutines;
     /**
      * Overrides specified configuration value.
      */
@@ -238,6 +243,24 @@ export type MigrationsOptions = {
     fileName?: (timestamp: string, name?: string) => string;
     /** List of migration classes or objects to use instead of file-based discovery. */
     migrationsList?: (MigrationObject | Constructor<Migration>)[];
+    /**
+     * Target schema used when running migrations. When set, the driver's "set current schema" statement
+     * (e.g. `SET search_path` on PostgreSQL) is issued before each migration, and the migration tracking
+     * table lives in this schema. Can be overridden per call via `migrator.up({ schema })`.
+     *
+     * Intended for per-deployment-one-schema setups (e.g. PR previews) and for applying a single
+     * unqualified migration to multiple schemas (see `includeWildcardSchema`). Not supported on MSSQL.
+     */
+    schema?: string;
+    /**
+     * When set, entities with a wildcard schema (`schema: '*'`) are included in generated migrations.
+     * The emitted SQL is unqualified — and therefore safe to apply against any schema at runtime via
+     * `migrator.up({ schema })` — only when neither `options.schema` nor the ORM's `config.schema`
+     * is set. If `config.schema` is set, wildcard tables are qualified with it (useful for local
+     * dev runs); in that case, generate migrations from an environment where `config.schema` is unset.
+     * @default false
+     */
+    includeWildcardSchema?: boolean;
 };
 /**
  * Configuration options for database seeders.
@@ -390,6 +413,13 @@ export interface Options<Driver extends IDatabaseDriver = IDatabaseDriver, EM ex
      * Can be class references or instances.
      */
     subscribers: Iterable<EventSubscriber | Constructor<EventSubscriber>>;
+    /**
+     * Stored procedures and functions, declared as {@link Routine} instances.
+     *
+     * @example
+     * routines: [HashUser, AddRecord]
+     */
+    routines: Iterable<Routine>;
     /**
      * Global entity filters to apply.
      * Filters are applied by default unless explicitly disabled.

package/utils/Configuration.js

@@ -4,6 +4,8 @@ import { NullHighlighter } from '../utils/NullHighlighter.js';
 import { DefaultLogger } from '../logging/DefaultLogger.js';
 import { colors } from '../logging/colors.js';
 import { Utils } from '../utils/Utils.js';
+import { Routine } from '../metadata/Routine.js';
+import { MetadataValidator } from '../metadata/MetadataValidator.js';
 import { MetadataProvider } from '../metadata/MetadataProvider.js';
 import { NotFoundError } from '../errors.js';
 import { RequestContext } from './RequestContext.js';
@@ -17,6 +19,7 @@ const DEFAULTS = {
     entitiesTs: [],
     extensions: [],
     subscribers: [],
+    routines: [],
     filters: {},
     discovery: {
         warnWhenNoEntities: true,
@@ -137,6 +140,8 @@ export class Configuration {
     #platform;
     #cache = new Map();
     #extensions = new Map();
+    #routines = [];
+    #routinesNormalised = false;
     constructor(options, validate = true) {
         if (options.dynamicImportProvider) {
             globalThis.dynamicImportProvider = options.dynamicImportProvider;
@@ -181,6 +186,42 @@ export class Configuration {
     getAll() {
         return this.#options;
     }
+    /** Validates the `routines` config option on first access and throws on duplicate `(schema, name)` pairs or non-Routine entries. */
+    getRoutines() {
+        this.normaliseRoutines();
+        return this.#routines;
+    }
+    hasRoutine(routine) {
+        this.normaliseRoutines();
+        return this.#routines.includes(routine);
+    }
+    normaliseRoutines() {
+        if (this.#routinesNormalised) {
+            return;
+        }
+        const validator = new MetadataValidator();
+        const seenKeys = new Set();
+        // Stage in a local array so a mid-loop throw doesn't leave `#routines` partially populated;
+        // a retry after the user fixes the offending entry would otherwise duplicate earlier ones.
+        const collected = [];
+        for (const item of this.#options.routines ?? []) {
+            if (!Routine.is(item)) {
+                throw new Error(`'routines' entry is not a stored routine declaration. Use a Routine class instance.`);
+            }
+            validator.validateRoutineDefinition(item);
+            // Case-fold to match `SchemaComparator.compareRoutines`, which lower-cases the key so
+            // dialect-specific folding (Oracle uppercases, PG lowercases) round-trips; otherwise a
+            // user could register `'Foo'` and `'foo'` here and have the comparator silently collapse them.
+            const key = ((item.schema ? `${item.schema}.` : '') + item.name).toLowerCase();
+            if (seenKeys.has(key)) {
+                throw new Error(`Duplicate routine '${key}' declared more than once in the 'routines' config. Routine names must be unique within a schema.`);
+            }
+            seenKeys.add(key);
+            collected.push(item);
+        }
+        this.#routines.push(...collected);
+        this.#routinesNormalised = true;
+    }
     /**
      * Overrides specified configuration value.
      */
@@ -324,6 +365,10 @@ export class Configuration {
         metadataCache.enabled ??= useCache;
         this.#options.clientUrl ??= this.#platform.getDefaultClientUrl();
         this.#options.implicitTransactions ??= this.#platform.usesImplicitTransactions();
+        // Eagerly trigger routine validation so errors surface at init time, not on first call.
+        if (validate) {
+            this.getRoutines();
+        }
         if (validate && metadataCache.enabled && !metadataCache.adapter) {
             throw new Error('No metadata cache adapter specified, please fill in `metadataCache.adapter` option or use the async MikroORM.init() method which can autoload it.');
         }

package/utils/EntityComparator.js

@@ -536,7 +536,7 @@ export class EntityComparator {
             ret += ` && entity${path.map(k => this.wrap(k)).join('')}?.isInitialized()`;
         }
         ret += `) {\n`;
-        if (['number', 'string', 'boolean'].includes(prop.type.toLowerCase())) {
+        if (!prop.array && ['number', 'string', 'boolean'].includes(prop.type.toLowerCase())) {
             return ret + `    ret${dataKey} = entity${entityKey}${unwrap};\n  }\n`;
         }
         if (prop.kind === ReferenceKind.EMBEDDED) {

package/utils/TransactionManager.js

@@ -136,6 +136,8 @@ export class TransactionManager {
             cloneEventManager: true,
             disableTransactions: options.ignoreNestedTransactions,
             loggerContext: options.loggerContext,
+            signal: options.signal,
+            inflightQueryAbortStrategy: options.inflightQueryAbortStrategy,
         });
     }
     /**

package/utils/Utils.js

@@ -141,7 +141,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.1.0-dev.9';
+    static #ORM_VERSION = '7.1.1-dev.0';
     /**
      * Checks if the argument is instance of `Object`. Returns false for arrays.
      */

package/utils/index.d.ts

@@ -10,3 +10,4 @@ export * from './EntityComparator.js';
 export * from './RawQueryFragment.js';
 export * from './env-vars.js';
 export * from './upsert-utils.js';
+export * from './partition-utils.js';

package/utils/index.js

@@ -10,3 +10,4 @@ export * from './EntityComparator.js';
 export * from './RawQueryFragment.js';
 export * from './env-vars.js';
 export * from './upsert-utils.js';
+export * from './partition-utils.js';

package/utils/partition-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a partition name for collision detection. Mirrors PostgreSQL identifier
+ * resolution: unquoted segments fold to lower case, quoted segments preserve case and
+ * un-escape embedded `""`. Returns a canonical `schema.name` form so both schema-qualified
+ * and bare names compare consistently (`.name` vs `schema.name` stay distinguishable).
+ *
+ * `Part_1`, `part_1`, and `"part_1"` all normalize to the same value, catching collisions
+ * that would otherwise only surface as runtime PG "relation already exists" errors.
+ */
+export declare function normalizePartitionNameForComparison(name: string): string;
+/**
+ * Split a comma-list of identifiers, respecting double-quoted identifiers (which may contain
+ * commas and use `""` to escape embedded quotes). Returns `null` when the input is not a clean
+ * comma-list of identifiers (e.g. contains function calls or literals), so callers treat it
+ * as an opaque expression.
+ */
+export declare function splitCommaSeparatedIdentifiers(value: string): string[] | null;

package/utils/partition-utils.js

@@ -0,0 +1,79 @@
+function normalizeIdentifierSegment(segment) {
+    const trimmed = segment.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1).replaceAll('""', '"');
+    }
+    return trimmed.toLowerCase();
+}
+/**
+ * Normalize a partition name for collision detection. Mirrors PostgreSQL identifier
+ * resolution: unquoted segments fold to lower case, quoted segments preserve case and
+ * un-escape embedded `""`. Returns a canonical `schema.name` form so both schema-qualified
+ * and bare names compare consistently (`.name` vs `schema.name` stay distinguishable).
+ *
+ * `Part_1`, `part_1`, and `"part_1"` all normalize to the same value, catching collisions
+ * that would otherwise only surface as runtime PG "relation already exists" errors.
+ */
+export function normalizePartitionNameForComparison(name) {
+    const trimmed = name.trim();
+    let depth = 0;
+    for (let i = 0; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (ch === '"') {
+            if (trimmed[i + 1] === '"') {
+                i++;
+                continue;
+            }
+            depth = depth === 0 ? 1 : 0;
+            continue;
+        }
+        if (ch === '.' && depth === 0) {
+            return `${normalizeIdentifierSegment(trimmed.slice(0, i))}.${normalizeIdentifierSegment(trimmed.slice(i + 1))}`;
+        }
+    }
+    return `.${normalizeIdentifierSegment(trimmed)}`;
+}
+/**
+ * Split a comma-list of identifiers, respecting double-quoted identifiers (which may contain
+ * commas and use `""` to escape embedded quotes). Returns `null` when the input is not a clean
+ * comma-list of identifiers (e.g. contains function calls or literals), so callers treat it
+ * as an opaque expression.
+ */
+export function splitCommaSeparatedIdentifiers(value) {
+    const segments = [];
+    let buffer = '';
+    let inQuote = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === '"') {
+            if (inQuote && value[i + 1] === '"') {
+                buffer += '""';
+                i++;
+                continue;
+            }
+            inQuote = !inQuote;
+            buffer += ch;
+            continue;
+        }
+        if (!inQuote) {
+            if (ch === ',') {
+                segments.push(buffer);
+                buffer = '';
+                continue;
+            }
+            if (!/[\w.\s]/.test(ch)) {
+                return null;
+            }
+        }
+        buffer += ch;
+    }
+    if (inQuote) {
+        return null;
+    }
+    segments.push(buffer);
+    const trimmed = segments.map(s => s.trim());
+    if (trimmed.some(s => s === '')) {
+        return null;
+    }
+    return trimmed;
+}

package/utils/upsert-utils.d.ts

@@ -10,3 +10,5 @@ export declare function getWhereCondition<T extends object>(meta: EntityMetadata
     where: FilterQuery<T>;
     propIndex: number | false;
 };
+/** @internal */
+export declare function resetUntouchedCollections<Entity extends object>(meta: EntityMetadata<Entity>, entity: Entity): void;

package/utils/upsert-utils.js

@@ -1,5 +1,8 @@
 import { isRaw } from '../utils/RawQueryFragment.js';
 import { Utils } from './Utils.js';
+import { ReferenceKind } from '../enums.js';
+import { Collection } from '../entity/Collection.js';
+import { helper } from '../entity/wrap.js';
 function expandEmbeddedProperties(prop, key) {
     if (prop.object) {
         return [prop.name];
@@ -52,7 +55,9 @@ export function getOnConflictFields(meta, data, uniqueFields, options) {
         });
     }
     const keys = Object.keys(data).flatMap(f => {
-        if (!(Array.isArray(uniqueFields) && !uniqueFields.includes(f))) {
+        // skip explicitly listed unique fields; for raw onConflictFields we can't introspect the
+        // fragment, so merge all data keys (the user is responsible for not corrupting them).
+        if (Array.isArray(uniqueFields) && uniqueFields.includes(f)) {
             return [];
         }
         const prop = meta?.properties[f];
@@ -142,3 +147,23 @@ export function getWhereCondition(meta, onConflictFields, data, where) {
     }
     return { where, propIndex };
 }
+/** @internal */
+export function resetUntouchedCollections(meta, entity) {
+    // for entities passed in via `em.create()` and then upserted, collection-kind relations
+    // were initialized as empty-but-initialized by the hydrator (newEntity=true). once the
+    // upsert resolves the entity to a possibly existing row, that state is stale and would
+    // cause `em.populate()` to skip those collections. replace them with a fresh
+    // uninitialized collection so populate can load them.
+    if (helper(entity).__originalEntityData) {
+        return;
+    }
+    for (const prop of meta.relations) {
+        if (prop.kind !== ReferenceKind.MANY_TO_MANY && prop.kind !== ReferenceKind.ONE_TO_MANY) {
+            continue;
+        }
+        const collection = entity[prop.name];
+        if (Utils.isCollection(collection) && collection.isInitialized() && !collection.isDirty()) {
+            Collection.create(entity, prop.name, undefined, false);
+        }
+    }
+}