@mikro-orm/core 6.4.17-dev.6 → 6.4.17-dev.60

package/entity/index.js

@@ -27,3 +27,4 @@ __exportStar(require("./Reference"), exports);
 __exportStar(require("./BaseEntity"), exports);
 __exportStar(require("./WrappedEntity"), exports);
 __exportStar(require("./wrap"), exports);
+__exportStar(require("./defineEntity"), exports);

package/hydration/ObjectHydrator.js

@@ -65,7 +65,7 @@ class ObjectHydrator extends Hydrator_1.Hydrator {
             const ret = [];
             const idx = this.tmpIndex++;
             const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
-            if (prop.getter && !prop.setter) {
+            if (prop.getter && !prop.setter && prop.persist === false) {
                 return [];
             }
             if (prop.ref) {

package/index.d.ts

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * @module core
  */
-export { Constructor, ConnectionType, Dictionary, PrimaryKeyProp, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, EntityMetadata, QBFilterQuery, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, EntityRepositoryType, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, EntityClassGroup, OptionalProps, EagerProps, HiddenProps, RequiredEntityData, CheckCallback, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, Opt, EntityType, FromEntityType, Selected, IsSubset, NoInfer, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, Hidden, FilterValue, MergeLoaded, MergeSelected, Config, DefineConfig, TypeConfig, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, } from './typings';
+export { Constructor, ConnectionType, Dictionary, PrimaryKeyProp, Primary, IPrimaryKey, ObjectQuery, FilterQuery, IWrappedEntity, EntityName, EntityData, Highlighter, MaybePromise, AnyEntity, EntityClass, EntityProperty, EntityMetadata, QBFilterQuery, PopulateOptions, Populate, Loaded, New, LoadedReference, LoadedCollection, IMigrator, IMigrationGenerator, MigratorEvent, GetRepository, EntityRepositoryType, MigrationObject, DeepPartial, PrimaryProperty, Cast, IsUnknown, EntityDictionary, EntityDTO, MigrationDiff, GenerateOptions, FilterObject, IEntityGenerator, ISeedManager, EntityClassGroup, OptionalProps, EagerProps, HiddenProps, RequiredEntityData, CheckCallback, IndexCallback, SimpleColumnMeta, Rel, Ref, ScalarRef, EntityRef, ISchemaGenerator, UmzugMigration, MigrateOptions, MigrationResult, MigrationRow, EntityKey, EntityValue, EntityDataValue, FilterKey, Opt, EntityType, FromEntityType, Selected, IsSubset, NoInfer, EntityProps, ExpandProperty, ExpandScalar, FilterItemValue, ExpandQuery, Scalar, ExpandHint, Hidden, FilterValue, MergeLoaded, MergeSelected, Config, DefineConfig, TypeConfig, ClearDatabaseOptions, CreateSchemaOptions, EnsureDatabaseOptions, UpdateSchemaOptions, DropSchemaOptions, RefreshDatabaseOptions, AutoPath, UnboxArray, MetadataProcessor, ImportsResolver, } from './typings';
 export * from './enums';
 export * from './errors';
 export * from './exceptions';

package/index.mjs

@@ -182,11 +182,13 @@ export const compareBuffers = mod.compareBuffers;
 export const compareObjects = mod.compareObjects;
 export const createSqlFunction = mod.createSqlFunction;
 export const defineConfig = mod.defineConfig;
+export const defineEntity = mod.defineEntity;
 export const equals = mod.equals;
 export const getOnConflictFields = mod.getOnConflictFields;
 export const getOnConflictReturningFields = mod.getOnConflictReturningFields;
 export const helper = mod.helper;
 export const parseJsonSafe = mod.parseJsonSafe;
+export const quote = mod.quote;
 export const raw = mod.raw;
 export const ref = mod.ref;
 export const rel = mod.rel;

package/metadata/MetadataDiscovery.d.ts

@@ -54,7 +54,6 @@ export declare class MetadataDiscovery {
     private initAutoincrement;
     private initCheckConstraints;
     private initGeneratedColumn;
-    private createColumnMappingObject;
     private getDefaultVersionValue;
     private inferDefaultValue;
     private initDefaultValue;

package/metadata/MetadataDiscovery.js

@@ -969,7 +969,7 @@ class MetadataDiscovery {
         }
     }
     initCheckConstraints(meta) {
-        const map = this.createColumnMappingObject(meta);
+        const map = meta.createColumnMappingObject();
         for (const check of meta.checks) {
             const columns = check.property ? meta.properties[check.property].fieldNames : [];
             check.name ??= this.namingStrategy.indexName(meta.tableName, columns, 'check');
@@ -992,19 +992,11 @@ class MetadataDiscovery {
             }
             return;
         }
-        const map = this.createColumnMappingObject(meta);
+        const map = meta.createColumnMappingObject();
         if (prop.generated instanceof Function) {
             prop.generated = prop.generated(map);
         }
     }
-    createColumnMappingObject(meta) {
-        return Object.values(meta.properties).reduce((o, prop) => {
-            if (prop.fieldNames) {
-                o[prop.name] = prop.fieldNames[0];
-            }
-            return o;
-        }, {});
-    }
     getDefaultVersionValue(meta, prop) {
         if (typeof prop.defaultRaw !== 'undefined') {
             return prop.defaultRaw;
@@ -1058,7 +1050,7 @@ class MetadataDiscovery {
             prop.defaultRaw = this.platform.formatQuery(raw.sql, raw.params);
             return;
         }
-        if (prop.customType instanceof types_1.ArrayType && Array.isArray(prop.default)) {
+        if (Array.isArray(prop.default) && prop.customType) {
             val = prop.customType.convertToDatabaseValue(prop.default, this.platform);
         }
         prop.defaultRaw = typeof val === 'string' ? `'${val}'` : '' + val;
@@ -1112,6 +1104,9 @@ class MetadataDiscovery {
         if (prop.kind === enums_1.ReferenceKind.SCALAR && !prop.customType && prop.columnTypes && ['json', 'jsonb'].includes(prop.columnTypes[0])) {
             prop.customType = new types_1.JsonType();
         }
+        if (prop.kind === enums_1.ReferenceKind.EMBEDDED && !prop.customType && (prop.object || prop.array)) {
+            prop.customType = new types_1.JsonType();
+        }
         if (!prop.customType && prop.array && prop.items) {
             prop.customType = new types_1.EnumArrayType(`${meta.className}.${prop.name}`, prop.items);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "6.4.17-dev.6",
+  "version": "6.4.17-dev.60",
   "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.",
   "main": "index.js",
   "module": "index.mjs",
@@ -60,11 +60,11 @@
   },
   "dependencies": {
     "dataloader": "2.2.3",
-    "dotenv": "16.5.0",
+    "dotenv": "17.2.1",
     "esprima": "4.0.1",
     "fs-extra": "11.3.0",
     "globby": "11.1.0",
-    "mikro-orm": "6.4.17-dev.6",
+    "mikro-orm": "6.4.17-dev.60",
     "reflect-metadata": "0.2.2"
   }
 }

package/platforms/Platform.d.ts

@@ -173,7 +173,9 @@ export declare abstract class Platform {
     getExtension<T>(extensionName: string, extensionKey: string, moduleName: string, em: EntityManager): T;
     getSchemaGenerator(driver: IDatabaseDriver, em?: EntityManager): ISchemaGenerator;
     processDateProperty(value: unknown): string | number | Date;
-    quoteIdentifier(id: string, quote?: string): string;
+    quoteIdentifier(id: string | {
+        toString: () => string;
+    }, quote?: string): string;
     quoteValue(value: any): string;
     escape(value: any): string;
     formatQuery(sql: string, params: readonly any[]): string;

package/types/BooleanType.d.ts

@@ -1,7 +1,7 @@
 import { Type } from './Type';
 import type { Platform } from '../platforms';
 import type { EntityProperty } from '../typings';
-export declare class BooleanType extends Type<number | null | undefined, number | null | undefined> {
+export declare class BooleanType extends Type<boolean | null | undefined, boolean | null | undefined> {
     getColumnType(prop: EntityProperty, platform: Platform): string;
     compareAsType(): string;
     ensureComparable(): boolean;

package/typings.d.ts

@@ -6,7 +6,7 @@ import type { SerializationContext, SerializeOptions } from './serialization';
 import type { EntitySchema, MetadataStorage } from './metadata';
 import type { Type, types } from './types';
 import type { Platform } from './platforms';
-import type { Configuration } from './utils';
+import type { Configuration, RawQueryFragment } from './utils';
 import type { EntityManager } from './EntityManager';
 import type { EmbeddedPrefixMode } from './decorators/Embedded';
 import type { EventSubscriber } from './events';
@@ -73,6 +73,7 @@ export type Primary<T> = IsAny<T> extends true ? any : T extends {
 } ? ReadonlyPrimary<PK> : T extends {
     id?: infer PK;
 } ? ReadonlyPrimary<PK> : T;
+/** @internal */
 export type PrimaryProperty<T> = T extends {
     [PrimaryKeyProp]?: infer PK;
 } ? (PK extends keyof T ? PK : (PK extends any[] ? PK[number] : never)) : T extends {
@@ -287,8 +288,14 @@ export type EntityDTO<T, C extends TypeConfig = never> = {
 } & {
     [K in keyof T as DTOOptionalKeys<T, K>]?: EntityDTOProp<T, T[K], C> | AddOptional<T[K]>;
 };
-type CheckKey<T> = IsUnknown<T> extends false ? keyof T : string;
-export type CheckCallback<T> = (columns: Record<CheckKey<T>, string>) => string;
+type PropertyName<T> = IsUnknown<T> extends false ? keyof T : string;
+type TableName = {
+    name: string;
+    schema?: string;
+    toString: () => string;
+};
+export type IndexCallback<T> = (table: TableName, columns: Record<PropertyName<T>, string>) => string | RawQueryFragment;
+export type CheckCallback<T> = (columns: Record<PropertyName<T>, string>) => string;
 export type GeneratedColumnCallback<T> = (columns: Record<keyof T, string>) => string;
 export interface CheckConstraint<T = any> {
     name?: string;
@@ -396,6 +403,7 @@ export declare class EntityMetadata<T = any> {
     removeProperty(name: string, sync?: boolean): void;
     getPrimaryProps(): EntityProperty<T>[];
     getPrimaryProp(): EntityProperty<T>;
+    createColumnMappingObject(): Dictionary<any>;
     get tableName(): string;
     set tableName(name: string);
     sync(initIndexes?: boolean): void;
@@ -447,18 +455,18 @@ export interface EntityMetadata<T = any> {
     uniqueProps: EntityProperty<T>[];
     getterProps: EntityProperty<T>[];
     indexes: {
-        properties: EntityKey<T> | EntityKey<T>[];
+        properties?: EntityKey<T> | EntityKey<T>[];
         name?: string;
         type?: string;
         options?: Dictionary;
-        expression?: string;
+        expression?: string | IndexCallback<T>;
     }[];
     uniques: {
-        properties: EntityKey<T> | EntityKey<T>[];
+        properties?: EntityKey<T> | EntityKey<T>[];
         name?: string;
         options?: Dictionary;
-        expression?: string;
-        deferMode?: DeferMode;
+        expression?: string | IndexCallback<T>;
+        deferMode?: DeferMode | `${DeferMode}`;
     }[];
     checks: CheckConstraint<T>[];
     repositoryClass?: string;

package/typings.js

@@ -53,6 +53,14 @@ class EntityMetadata {
     getPrimaryProp() {
         return this.properties[this.primaryKeys[0]];
     }
+    createColumnMappingObject() {
+        return Object.values(this.properties).reduce((o, prop) => {
+            if (prop.fieldNames) {
+                o[prop.name] = prop.fieldNames[0];
+            }
+            return o;
+        }, {});
+    }
     get tableName() {
         return this.collection;
     }
@@ -72,7 +80,7 @@ class EntityMetadata {
             // `prop.userDefined` is either `undefined` or `false`
             const discriminator = this.root.discriminatorColumn === prop.name && prop.userDefined === false;
             // even if we don't have a setter, do not ignore value from database!
-            const onlyGetter = prop.getter && !prop.setter;
+            const onlyGetter = prop.getter && !prop.setter && prop.persist === false;
             return !prop.inherited && prop.hydrate !== false && !discriminator && !prop.embedded && !onlyGetter;
         });
         this.trackingProps = this.hydrateProps
@@ -115,7 +123,7 @@ class EntityMetadata {
                         wrapped.__data[prop.name] = entity_1.Reference.wrapReference(val, prop);
                         // when propagation from inside hydration, we set the FK to the entity data immediately
                         if (val && hydrator.isRunning() && wrapped.__originalEntityData && prop.owner) {
-                            wrapped.__originalEntityData[prop.name] = Utils_1.Utils.getPrimaryKeyValues(val, prop.targetMeta.primaryKeys, true);
+                            wrapped.__originalEntityData[prop.name] = Utils_1.Utils.getPrimaryKeyValues(val, prop.targetMeta, true);
                         }
                         else {
                             wrapped.__touched = !hydrator.isRunning();

package/unit-of-work/ChangeSetComputer.js

@@ -144,7 +144,9 @@ class ChangeSetComputer {
         if (!target.isDirty() && changeSet.type !== ChangeSet_1.ChangeSetType.CREATE) {
             return;
         }
-        this.collectionUpdates.add(target);
+        if (target.isDirty()) {
+            this.collectionUpdates.add(target);
+        }
         if (prop.owner && !this.platform.usesPivotTable()) {
             changeSet.payload[prop.name] = target.getItems(false).map((item) => item.__helper.__identifier ?? item.__helper.getPrimaryKey());
         }

package/unit-of-work/UnitOfWork.d.ts

@@ -102,6 +102,7 @@ export declare class UnitOfWork {
     private commitDeleteChangeSets;
     private commitExtraUpdates;
     private commitCollectionUpdates;
+    private filterCollectionUpdates;
     /**
      * Orders change sets so FK constrains are maintained, ensures stable order (needed for node < 11)
      */

package/unit-of-work/UnitOfWork.js

@@ -88,7 +88,7 @@ class UnitOfWork {
                 }
                 wrapped.__loadedProperties.add(key);
                 if ([enums_1.ReferenceKind.MANY_TO_ONE, enums_1.ReferenceKind.ONE_TO_ONE].includes(prop.kind) && Utils_1.Utils.isPlainObject(data[prop.name])) {
-                    data[prop.name] = Utils_1.Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta.primaryKeys, true);
+                    data[prop.name] = Utils_1.Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
                 }
                 else if (prop.kind === enums_1.ReferenceKind.EMBEDDED && !prop.object && Utils_1.Utils.isPlainObject(data[prop.name])) {
                     for (const p of prop.targetMeta.props) {
@@ -96,7 +96,7 @@ class UnitOfWork {
                         const prefix = prop.prefix === false ? '' : prop.prefix === true ? prop.name + '_' : prop.prefix;
                         data[prefix + p.name] = data[prop.name][p.name];
                     }
-                    data[prop.name] = Utils_1.Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta.primaryKeys, true);
+                    data[prop.name] = Utils_1.Utils.getPrimaryKeyValues(data[prop.name], prop.targetMeta, true);
                 }
                 if (forceUndefined) {
                     if (data[key] === null) {
@@ -303,6 +303,7 @@ class UnitOfWork {
                 cs.entity.__helper.__processing = true;
             }
             await this.eventManager.dispatchEvent(enums_1.EventType.onFlush, { em: this.em, uow: this });
+            this.filterCollectionUpdates();
             // nothing to do, do not start transaction
             if (this.changeSets.size === 0 && this.collectionUpdates.size === 0 && this.extraUpdates.size === 0) {
                 return void await this.eventManager.dispatchEvent(enums_1.EventType.afterFlush, { em: this.em, uow: this });
@@ -886,23 +887,29 @@ class UnitOfWork {
         }
     }
     async commitCollectionUpdates(ctx) {
-        const collectionUpdates = [];
+        this.filterCollectionUpdates();
+        await this.em.getDriver().syncCollections(this.collectionUpdates, { ctx, schema: this.em.schema });
         for (const coll of this.collectionUpdates) {
+            coll.takeSnapshot();
+        }
+    }
+    filterCollectionUpdates() {
+        for (const coll of this.collectionUpdates) {
+            let skip = true;
             if (coll.property.owner || coll.getItems(false).filter(item => !item.__helper.__initialized).length > 0) {
                 if (this.platform.usesPivotTable()) {
-                    collectionUpdates.push(coll);
+                    skip = false;
                 }
             }
             else if (coll.property.kind === enums_1.ReferenceKind.ONE_TO_MANY && coll.getSnapshot() === undefined) {
-                collectionUpdates.push(coll);
+                skip = false;
             }
             else if (coll.property.kind === enums_1.ReferenceKind.MANY_TO_MANY && !coll.property.owner) {
-                collectionUpdates.push(coll);
+                skip = false;
+            }
+            if (skip) {
+                this.collectionUpdates.delete(coll);
             }
-        }
-        await this.em.getDriver().syncCollections(collectionUpdates, { ctx, schema: this.em.schema });
-        for (const coll of this.collectionUpdates) {
-            coll.takeSnapshot();
         }
     }
     /**

package/utils/Configuration.d.ts

@@ -77,6 +77,7 @@ export declare class Configuration<D extends IDatabaseDriver = IDatabaseDriver,
         upsertManaged: true;
         forceEntityConstructor: false;
         forceUndefined: false;
+        processOnCreateHooksEarly: false;
         ensureDatabase: true;
         ensureIndexes: false;
         batchSize: number;
@@ -345,6 +346,11 @@ export interface MikroORMOptions<D extends IDatabaseDriver = IDatabaseDriver, EM
     upsertManaged: boolean;
     forceEntityConstructor: boolean | (Constructor<AnyEntity> | string)[];
     forceUndefined: boolean;
+    /**
+     * Property `onCreate` hooks are normally executed during `flush` operation.
+     * With this option, they will be processed early inside `em.create()` method.
+     */
+    processOnCreateHooksEarly: boolean;
     forceUtcTimezone?: boolean;
     timezone?: string;
     ensureDatabase: boolean | EnsureDatabaseOptions;

package/utils/Configuration.js

@@ -71,6 +71,7 @@ class Configuration {
         upsertManaged: true,
         forceEntityConstructor: false,
         forceUndefined: false,
+        processOnCreateHooksEarly: false,
         ensureDatabase: true,
         ensureIndexes: false,
         batchSize: 300,

package/utils/ConfigurationLoader.js

@@ -213,7 +213,7 @@ class ConfigurationLoader {
         const baseDir = options instanceof Configuration_1.Configuration ? options.get('baseDir') : options?.baseDir;
         const path = process.env.MIKRO_ORM_ENV ?? ((baseDir ?? process.cwd()) + '/.env');
         const env = {};
-        dotenv_1.default.config({ path, processEnv: env });
+        dotenv_1.default.config({ path, processEnv: env, quiet: true });
         // only propagate known env vars
         for (const key of Object.keys(env)) {
             if (key.startsWith('MIKRO_ORM_')) {

package/utils/EntityComparator.js

@@ -534,9 +534,12 @@ class EntityComparator {
         context.set('compareBuffers', Utils_1.compareBuffers);
         context.set('compareObjects', Utils_1.compareObjects);
         context.set('equals', Utils_1.equals);
-        meta.comparableProps.forEach(prop => {
-            lines.push(this.getPropertyComparator(prop, context));
-        });
+        for (const prop of meta.comparableProps) {
+            // skip properties that are not hydrated
+            if (prop.hydrate !== false) {
+                lines.push(this.getPropertyComparator(prop, context));
+            }
+        }
         const code = `// compiled comparator for entity ${meta.className}\n`
             + `return function(last, current) {\n  const diff = {};\n${lines.join('\n')}\n  return diff;\n}`;
         const comparator = Utils_1.Utils.createFunction(context, code);

package/utils/QueryHelper.js

@@ -40,7 +40,7 @@ class QueryHelper {
         if (Array.isArray(where)) {
             where.forEach((item, i) => {
                 if (this.inlinePrimaryKeyObjects(item, meta, metadata, key)) {
-                    where[i] = Utils_1.Utils.getPrimaryKeyValues(item, meta.primaryKeys, false);
+                    where[i] = Utils_1.Utils.getPrimaryKeyValues(item, meta, false);
                 }
             });
         }
@@ -61,7 +61,7 @@ class QueryHelper {
         Object.keys(where).forEach(k => {
             const meta2 = metadata.find(meta.properties[k]?.type) || meta;
             if (this.inlinePrimaryKeyObjects(where[k], meta2, metadata, k)) {
-                where[k] = Utils_1.Utils.getPrimaryKeyValues(where[k], meta2.primaryKeys, true);
+                where[k] = Utils_1.Utils.getPrimaryKeyValues(where[k], meta2, true);
             }
         });
         return false;
@@ -121,7 +121,7 @@ class QueryHelper {
                 value = QueryHelper.processCustomType(prop, value, platform, undefined, true);
             }
             const isJsonProperty = prop?.customType instanceof JsonType_1.JsonType && Utils_1.Utils.isPlainObject(value) && !platform.isRaw(value) && Object.keys(value)[0] !== '$eq';
-            if (isJsonProperty) {
+            if (isJsonProperty && prop?.kind !== enums_1.ReferenceKind.EMBEDDED) {
                 return this.processJsonCondition(o, value, [prop.fieldNames[0]], platform, aliased);
             }
             if (Array.isArray(value) && !Utils_1.Utils.isOperator(key) && !QueryHelper.isSupportedOperator(key) && !key.includes('?') && options.type !== 'orderBy') {

package/utils/RawQueryFragment.d.ts

@@ -70,6 +70,24 @@ export declare const ALIAS_REPLACEMENT_RE = "\\[::alias::\\]";
  * ```ts
  * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
  * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
  */
 export declare function raw<T extends object = any, R = any>(sql: EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): R;
 /**
@@ -94,3 +112,19 @@ export declare namespace sql {
     var upper: <T extends object>(key: string | ((alias: string) => string)) => string;
 }
 export declare function createSqlFunction<T extends object, R = string>(func: string, key: string | ((alias: string) => string)): R;
+/**
+ * Tag function providing quoting of db identifiers (table name, columns names, index names, ...).
+ *
+ * Within the template literal on which the tag function is applied, all placeholders are considered to be database identifiers, and will thus be quoted as so according to the database in use.
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("name")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`name`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export declare function quote(expParts: readonly string[], ...values: (string | {
+    toString(): string;
+})[]): any;

package/utils/RawQueryFragment.js

@@ -4,6 +4,7 @@ exports.ALIAS_REPLACEMENT_RE = exports.ALIAS_REPLACEMENT = exports.RawQueryFragm
 exports.raw = raw;
 exports.sql = sql;
 exports.createSqlFunction = createSqlFunction;
+exports.quote = quote;
 const node_async_hooks_1 = require("node:async_hooks");
 const node_util_1 = require("node:util");
 const Utils_1 = require("./Utils");
@@ -150,6 +151,24 @@ exports.ALIAS_REPLACEMENT_RE = '\\[::alias::\\]';
  * ```ts
  * @Filter({ name: 'long', cond: () => ({ [raw('length(perex)')]: { $gt: 10000 } }) })
  * ```
+ *
+ * The `raw` helper can be used within indexes and uniques to write database-agnostic SQL expressions. In that case, you can use `'??'` to tag your database identifiers (table name, column names, index name, ...) inside your expression, and pass those identifiers as a second parameter to the `raw` helper. Internally, those will automatically be quoted according to the database in use:
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("country")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`country`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => raw(`create index ?? on ?? (??)`, ['custom_idx_on_name', table, columns.name]) })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ *
+ * You can also use the `quote` tag function to write database-agnostic SQL expressions. The end-result is the same as using the `raw` function regarding database identifiers quoting, only to have a more elegant expression syntax:
+ *
+ * ```ts
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
  */
 function raw(sql, params) {
     if (sql instanceof RawQueryFragment) {
@@ -207,3 +226,19 @@ sql.ref = (...keys) => raw('??', [keys.join('.')]);
 sql.now = (length) => raw('current_timestamp' + (length == null ? '' : `(${length})`));
 sql.lower = (key) => createSqlFunction('lower', key);
 sql.upper = (key) => createSqlFunction('upper', key);
+/**
+ * Tag function providing quoting of db identifiers (table name, columns names, index names, ...).
+ *
+ * Within the template literal on which the tag function is applied, all placeholders are considered to be database identifiers, and will thus be quoted as so according to the database in use.
+ *
+ * ```ts
+ * // On postgres, will produce: create index "index custom_idx_on_name" on "library.author" ("name")
+ * // On mysql, will produce: create index `index custom_idx_on_name` on `library.author` (`name`)
+ * @Index({ name: 'custom_idx_on_name', expression: (table, columns) => quote`create index ${'custom_idx_on_name'} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+function quote(expParts, ...values) {
+    return raw(expParts.join('??'), values);
+}

package/utils/Utils.d.ts

@@ -134,14 +134,14 @@ export declare class Utils {
     static getCompositeKeyHash<T>(data: EntityData<T>, meta: EntityMetadata<T>, convertCustomTypes?: boolean, platform?: Platform, flat?: boolean): string;
     static getPrimaryKeyHash(pks: (string | Buffer | Date)[]): string;
     static splitPrimaryKeys<T extends object>(key: string): EntityKey<T>[];
-    static getPrimaryKeyValues<T>(entity: T, primaryKeys: string[], allowScalar?: boolean, convertCustomTypes?: boolean): any;
+    static getPrimaryKeyValues<T>(entity: T, primaryKeys: string[] | EntityMetadata<T>, allowScalar?: boolean, convertCustomTypes?: boolean): any;
     static getPrimaryKeyCond<T>(entity: T, primaryKeys: EntityKey<T>[]): Record<string, Primary<T>> | null;
     /**
      * Maps nested FKs from `[1, 2, 3]` to `[1, [2, 3]]`.
      */
     static mapFlatCompositePrimaryKey(fk: Primary<any>[], prop: EntityProperty, fieldNames?: string[], idx?: number): Primary<any> | Primary<any>[];
     static getPrimaryKeyCondFromArray<T extends object>(pks: Primary<T>[], meta: EntityMetadata<T>): Record<string, Primary<T>>;
-    static getOrderedPrimaryKeys<T>(id: Primary<T> | Record<string, Primary<T>>, meta: EntityMetadata<T>, platform?: Platform, convertCustomTypes?: boolean): Primary<T>[];
+    static getOrderedPrimaryKeys<T>(id: Primary<T> | Record<string, Primary<T>>, meta: EntityMetadata<T>, platform?: Platform, convertCustomTypes?: boolean, allowScalar?: boolean): Primary<T>[];
     /**
      * Checks whether given object is an entity instance.
      */

package/utils/Utils.js

@@ -498,6 +498,7 @@ class Utils {
     static splitPrimaryKeys(key) {
         return key.split(this.PK_SEPARATOR);
     }
+    // TODO v7: remove support for `primaryKeys: string[]`
     static getPrimaryKeyValues(entity, primaryKeys, allowScalar = false, convertCustomTypes = false) {
         /* istanbul ignore next */
         if (entity == null) {
@@ -509,9 +510,24 @@ class Utils {
             }
             return val;
         }
-        const pk = Utils.isEntity(entity, true)
-            ? (0, wrap_1.helper)(entity).getPrimaryKey(convertCustomTypes)
-            : primaryKeys.reduce((o, pk) => { o[pk] = entity[pk]; return o; }, {});
+        const meta = Array.isArray(primaryKeys) ? undefined : primaryKeys;
+        primaryKeys = Array.isArray(primaryKeys) ? primaryKeys : meta.primaryKeys;
+        let pk;
+        if (Utils.isEntity(entity, true)) {
+            pk = (0, wrap_1.helper)(entity).getPrimaryKey(convertCustomTypes);
+        }
+        else {
+            pk = primaryKeys.reduce((o, pk) => {
+                const targetMeta = meta?.properties[pk].targetMeta;
+                if (targetMeta && Utils.isPlainObject(entity[pk])) {
+                    o[pk] = Utils.getPrimaryKeyValues(entity[pk], targetMeta, allowScalar, convertCustomTypes);
+                }
+                else {
+                    o[pk] = entity[pk];
+                }
+                return o;
+            }, {});
+        }
         if (primaryKeys.length > 1) {
             return toArray(pk);
         }
@@ -561,7 +577,7 @@ class Utils {
             return o;
         }, {});
     }
-    static getOrderedPrimaryKeys(id, meta, platform, convertCustomTypes = false) {
+    static getOrderedPrimaryKeys(id, meta, platform, convertCustomTypes = false, allowScalar = false) {
         const data = (Utils.isPrimaryKey(id) ? { [meta.primaryKeys[0]]: id } : id);
         const pks = meta.primaryKeys.map((pk, idx) => {
             const prop = meta.properties[pk];
@@ -571,11 +587,14 @@ class Utils {
                 value = prop.customType.convertToJSValue(value, platform);
             }
             if (prop.kind !== enums_1.ReferenceKind.SCALAR && prop.targetMeta) {
-                const value2 = this.getOrderedPrimaryKeys(value, prop.targetMeta, platform, convertCustomTypes);
+                const value2 = this.getOrderedPrimaryKeys(value, prop.targetMeta, platform, convertCustomTypes, allowScalar);
                 value = value2.length > 1 ? value2 : value2[0];
             }
             return value;
         });
+        if (allowScalar && pks.length === 1) {
+            return pks[0];
+        }
         // we need to flatten the PKs as composite PKs can be build from another composite PKs
         // and this method is used to get the PK hash in identity map, that expects flat array
         return Utils.flatten(pks);

package/utils/upsert-utils.js

@@ -75,7 +75,15 @@ function getOnConflictReturningFields(meta, data, uniqueFields, options) {
     if (!meta) {
         return '*';
     }
-    const keys = meta.comparableProps.filter(p => !p.lazy && !p.embeddable && Array.isArray(uniqueFields) && !uniqueFields.includes(p.name)).map(p => p.name);
+    const keys = meta.comparableProps.filter(p => {
+        if (p.lazy || p.embeddable) {
+            return false;
+        }
+        if (p.autoincrement) {
+            return true;
+        }
+        return Array.isArray(uniqueFields) && !uniqueFields.includes(p.name);
+    }).map(p => p.name);
     if (meta.versionProperty) {
         keys.push(meta.versionProperty);
     }