@mikro-orm/core 7.0.0-dev.4 → 7.0.0-dev.41

package/utils/EntityComparator.d.ts

@@ -1,6 +1,8 @@
 import type { EntityData, EntityDictionary, EntityMetadata, EntityProperty, IMetadataStorage } from '../typings.js';
 import type { Platform } from '../platforms/Platform.js';
-type Comparator<T> = (a: T, b: T) => EntityData<T>;
+type Comparator<T> = (a: T, b: T, options?: {
+    includeInverseSides?: boolean;
+}) => EntityData<T>;
 type ResultMapper<T> = (result: EntityData<T>) => EntityData<T> | null;
 type SnapshotGenerator<T> = (entity: T) => EntityData<T>;
 type CompositeKeyPart = string | CompositeKeyPart[];
@@ -18,7 +20,9 @@ export declare class EntityComparator {
     /**
      * Computes difference between two entities.
      */
-    diffEntities<T>(entityName: string, a: EntityData<T>, b: EntityData<T>): EntityData<T>;
+    diffEntities<T>(entityName: string, a: EntityData<T>, b: EntityData<T>, options?: {
+        includeInverseSides?: boolean;
+    }): EntityData<T>;
     matching<T>(entityName: string, a: EntityData<T>, b: EntityData<T>): boolean;
     /**
      * Removes ORM specific code from entities and prepares it for serializing. Used before change set computation.

package/utils/EntityComparator.js

@@ -20,9 +20,9 @@ export class EntityComparator {
     /**
      * Computes difference between two entities.
      */
-    diffEntities(entityName, a, b) {
+    diffEntities(entityName, a, b, options) {
         const comparator = this.getEntityComparator(entityName);
-        return Utils.callCompiledFunction(comparator, a, b);
+        return Utils.callCompiledFunction(comparator, a, b, options);
     }
     matching(entityName, a, b) {
         const diff = this.diffEntities(entityName, a, b);
@@ -155,6 +155,7 @@ export class EntityComparator {
         const lines = [];
         const context = new Map();
         context.set('getCompositeKeyValue', (val) => Utils.flatten(Utils.getCompositeKeyValue(val, meta, 'convertToDatabaseValue', this.platform)));
+        context.set('getPrimaryKeyHash', (val) => Utils.getPrimaryKeyHash(Utils.asArray(val)));
         if (meta.primaryKeys.length > 1) {
             lines.push(`  const pks = entity.__helper.__pk ? getCompositeKeyValue(entity.__helper.__pk) : [`);
             meta.primaryKeys.forEach(pk => {
@@ -170,14 +171,23 @@ export class EntityComparator {
         }
         else {
             const pk = meta.primaryKeys[0];
-            if (meta.properties[pk].kind !== ReferenceKind.SCALAR) {
+            const prop = meta.properties[pk];
+            if (prop.kind !== ReferenceKind.SCALAR) {
                 lines.push(`  if (entity${this.wrap(pk)} != null && (entity${this.wrap(pk)}.__entity || entity${this.wrap(pk)}.__reference)) return entity${this.wrap(pk)}.__helper.getSerializedPrimaryKey();`);
             }
             const serializedPrimaryKey = meta.props.find(p => p.serializedPrimaryKey);
             if (serializedPrimaryKey) {
                 lines.push(`  return '' + entity.${serializedPrimaryKey.name};`);
             }
-            lines.push(`  return '' + entity.${meta.primaryKeys[0]};`);
+            else if (prop.customType) {
+                const convertorKey = this.registerCustomType(meta.properties[pk], context);
+                const idx = this.tmpIndex++;
+                lines.push(`  const val_${idx} = convertToDatabaseValue_${convertorKey}(entity${this.wrap(pk)});`);
+                lines.push(`  return getPrimaryKeyHash(val_${idx});`);
+            }
+            else {
+                lines.push(`  return '' + entity${this.wrap(pk)};`);
+            }
         }
         const code = `// compiled pk serializer for entity ${meta.className}\n`
             + `return function(entity) {\n${lines.join('\n')}\n}`;
@@ -286,57 +296,73 @@ export class EntityComparator {
             lines.push(`${padding}    }`);
         };
         lines.push(`  const mapped = {};`);
-        meta.props.forEach(prop => {
-            if (!prop.fieldNames) {
-                return;
-            }
-            if (prop.targetMeta && prop.fieldNames.length > 1) {
-                lines.push(`  if (${prop.fieldNames.map(field => `typeof ${this.propName(field)} === 'undefined'`).join(' && ')}) {`);
-                lines.push(`  } else if (${prop.fieldNames.map(field => `${this.propName(field)} != null`).join(' && ')}) {`);
-                lines.push(`    ret${this.wrap(prop.name)} = ${this.createCompositeKeyArray(prop)};`);
-                lines.push(...prop.fieldNames.map(field => `    ${this.propName(field, 'mapped')} = true;`));
-                lines.push(`  } else if (${prop.fieldNames.map(field => `${this.propName(field)} == null`).join(' && ')}) {\n    ret${this.wrap(prop.name)} = null;`);
-                lines.push(...prop.fieldNames.map(field => `    ${this.propName(field, 'mapped')} = true;`), '  }');
-                return;
-            }
-            if (prop.embedded && (meta.embeddable || meta.properties[prop.embedded[0]].object)) {
-                return;
-            }
-            if (prop.runtimeType === 'boolean') {
-                lines.push(`  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
-                lines.push(`    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : !!${this.propName(prop.fieldNames[0])};`);
-                lines.push(`    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
-                lines.push(`  }`);
-            }
-            else if (prop.runtimeType === 'Date' && !this.platform.isNumericProperty(prop)) {
-                lines.push(`  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
-                context.set('parseDate', (value) => this.platform.parseDate(value));
-                parseDate('ret' + this.wrap(prop.name), this.propName(prop.fieldNames[0]));
-                lines.push(`    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
-                lines.push(`  }`);
-            }
-            else if (prop.kind === ReferenceKind.EMBEDDED && (prop.object || meta.embeddable)) {
-                const idx = this.tmpIndex++;
-                context.set(`mapEmbeddedResult_${idx}`, (data) => {
-                    const item = parseJsonSafe(data);
-                    if (Array.isArray(item)) {
-                        return item.map(row => row == null ? row : this.getResultMapper(prop.type)(row));
-                    }
-                    return item == null ? item : this.getResultMapper(prop.type)(item);
-                });
-                lines.push(`  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
-                lines.push(`    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : mapEmbeddedResult_${idx}(${this.propName(prop.fieldNames[0])});`);
-                lines.push(`    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
-                lines.push(`  }`);
+        const mapEntityProperties = (meta, padding = '') => {
+            for (const prop of meta.props) {
+                if (!prop.fieldNames) {
+                    continue;
+                }
+                if (prop.targetMeta && prop.fieldNames.length > 1) {
+                    lines.push(`${padding}  if (${prop.fieldNames.map(field => `typeof ${this.propName(field)} === 'undefined'`).join(' && ')}) {`);
+                    lines.push(`${padding}  } else if (${prop.fieldNames.map(field => `${this.propName(field)} != null`).join(' && ')}) {`);
+                    lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.createCompositeKeyArray(prop)};`);
+                    lines.push(...prop.fieldNames.map(field => `${padding}    ${this.propName(field, 'mapped')} = true;`));
+                    lines.push(`${padding}  } else if (${prop.fieldNames.map(field => `${this.propName(field)} == null`).join(' && ')}) {\n    ret${this.wrap(prop.name)} = null;`);
+                    lines.push(...prop.fieldNames.map(field => `${padding}    ${this.propName(field, 'mapped')} = true;`), '  }');
+                    continue;
+                }
+                if (prop.embedded && (meta.embeddable || meta.properties[prop.embedded[0]].object)) {
+                    continue;
+                }
+                if (prop.runtimeType === 'boolean') {
+                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : !!${this.propName(prop.fieldNames[0])};`);
+                    lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+                    lines.push(`${padding}  }`);
+                }
+                else if (prop.runtimeType === 'Date' && !this.platform.isNumericProperty(prop)) {
+                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    context.set('parseDate', (value) => this.platform.parseDate(value));
+                    parseDate('ret' + this.wrap(prop.name), this.propName(prop.fieldNames[0]), padding);
+                    lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+                    lines.push(`${padding}  }`);
+                }
+                else if (prop.kind === ReferenceKind.EMBEDDED && (prop.object || meta.embeddable)) {
+                    const idx = this.tmpIndex++;
+                    context.set(`mapEmbeddedResult_${idx}`, (data) => {
+                        const item = parseJsonSafe(data);
+                        if (Array.isArray(item)) {
+                            return item.map(row => row == null ? row : this.getResultMapper(prop.type)(row));
+                        }
+                        return item == null ? item : this.getResultMapper(prop.type)(item);
+                    });
+                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])} == null ? ${this.propName(prop.fieldNames[0])} : mapEmbeddedResult_${idx}(${this.propName(prop.fieldNames[0])});`);
+                    lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+                    lines.push(`${padding}  }`);
+                }
+                else if (prop.kind !== ReferenceKind.EMBEDDED) {
+                    lines.push(`${padding}  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
+                    lines.push(`${padding}    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])};`);
+                    lines.push(`${padding}    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+                    lines.push(`${padding}  }`);
+                }
             }
-            else if (prop.kind !== ReferenceKind.EMBEDDED) {
-                lines.push(`  if (typeof ${this.propName(prop.fieldNames[0])} !== 'undefined') {`);
-                lines.push(`    ret${this.wrap(prop.name)} = ${this.propName(prop.fieldNames[0])};`);
-                lines.push(`    ${this.propName(prop.fieldNames[0], 'mapped')} = true;`);
+        };
+        if (meta.polymorphs && meta.discriminatorColumn) {
+            for (const polymorph of meta.polymorphs) {
+                const first = polymorph === meta.polymorphs[0];
+                lines.push(`  ${first ? '' : 'else '}if (${this.propName(meta.discriminatorColumn)} == '${polymorph.discriminatorValue}') {`);
+                mapEntityProperties(polymorph, '  ');
                 lines.push(`  }`);
             }
-        });
-        lines.push(`  for (let k in result) { if (Object.hasOwn(result, k) && !mapped[k]) ret[k] = result[k]; }`);
+            lines.push(`  else {`);
+            mapEntityProperties(meta, '  ');
+            lines.push(`  }`);
+        }
+        else {
+            mapEntityProperties(meta);
+        }
+        lines.push(`  for (let k in result) { if (Object.hasOwn(result, k) && !mapped[k] && ret[k] === undefined) ret[k] = result[k]; }`);
         const code = `// compiled mapper for entity ${meta.className}\n`
             + `return function(result) {\n  const ret = {};\n${lines.join('\n')}\n  return ret;\n}`;
         const resultMapper = Utils.createFunction(context, code);
@@ -391,11 +417,21 @@ export class EntityComparator {
     }
     getEmbeddedPropertySnapshot(meta, prop, context, level, path, dataKey, object = prop.object) {
         const padding = ' '.repeat(level * 2);
+        const nullCond = `entity${path.map(k => this.wrap(k)).join('')} === null`;
         let ret = `${level === 1 ? '' : '\n'}`;
         if (object) {
-            const nullCond = `entity${path.map(k => this.wrap(k)).join('')} === null`;
             ret += `${padding}if (${nullCond}) ret${dataKey} = null;\n`;
         }
+        else {
+            ret += `${padding}if (${nullCond}) {\n`;
+            ret += meta.props.filter(p => p.embedded?.[0] === prop.name
+                // object for JSON embeddable
+                && (p.object || (p.persist !== false))).map(childProp => {
+                const childDataKey = meta.embeddable || prop.object ? dataKey + this.wrap(childProp.embedded[1]) : this.wrap(childProp.name);
+                return `${padding}  ret${childDataKey} = null;`;
+            }).join('\n') + `\n`;
+            ret += `${padding}}\n`;
+        }
         const cond = `entity${path.map(k => this.wrap(k)).join('')} != null`;
         ret += `${padding}if (${cond}) {\n`;
         if (object) {
@@ -515,17 +551,27 @@ export class EntityComparator {
         context.set('compareBuffers', compareBuffers);
         context.set('compareObjects', compareObjects);
         context.set('equals', equals);
-        meta.comparableProps.forEach(prop => {
+        for (const prop of meta.comparableProps) {
             lines.push(this.getPropertyComparator(prop, context));
-        });
+        }
+        // also compare 1:1 inverse sides, important for `factory.mergeData`
+        lines.push(`if (options?.includeInverseSides) {`);
+        for (const prop of meta.bidirectionalRelations) {
+            if (prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner && prop.hydrate !== false) {
+                lines.push(this.getPropertyComparator(prop, context));
+            }
+        }
+        lines.push(`}`);
         const code = `// compiled comparator for entity ${meta.className}\n`
-            + `return function(last, current) {\n  const diff = {};\n${lines.join('\n')}\n  return diff;\n}`;
+            + `return function(last, current, options) {\n  const diff = {};\n${lines.join('\n')}\n  return diff;\n}`;
         const comparator = Utils.createFunction(context, code);
         this.comparators.set(entityName, comparator);
         return comparator;
     }
     getGenericComparator(prop, cond) {
-        return `  if (current${prop} == null && last${prop} == null) {\n\n` +
+        return `  if (current${prop} === null && last${prop} === undefined) {\n` +
+            `    diff${prop} = current${prop};\n` +
+            `  } else if (current${prop} == null && last${prop} == null) {\n\n` +
             `  } else if ((current${prop} != null && last${prop} == null) || (current${prop} == null && last${prop} != null)) {\n` +
             `    diff${prop} = current${prop};\n` +
             `  } else if (${cond}) {\n` +
@@ -591,7 +637,7 @@ export class EntityComparator {
      * perf: used to generate list of comparable properties during discovery, so we speed up the runtime comparison
      */
     static isComparable(prop, root) {
-        const virtual = prop.persist === false || prop.generated;
+        const virtual = prop.persist === false || (prop.generated && !prop.primary);
         const inverse = prop.kind === ReferenceKind.ONE_TO_ONE && !prop.owner;
         const discriminator = prop.name === root.discriminatorColumn;
         const collection = prop.kind === ReferenceKind.ONE_TO_MANY || prop.kind === ReferenceKind.MANY_TO_MANY;

package/utils/QueryHelper.d.ts

@@ -1,13 +1,21 @@
 import type { Dictionary, EntityMetadata, EntityProperty, FilterDef, FilterQuery } from '../typings.js';
 import type { Platform } from '../platforms/Platform.js';
 import type { MetadataStorage } from '../metadata/MetadataStorage.js';
+import type { FilterOptions } from '../drivers/IDatabaseDriver.js';
+/** @internal */
 export declare class QueryHelper {
     static readonly SUPPORTED_OPERATORS: string[];
     static processParams(params: unknown): any;
     static processObjectParams<T extends object>(params?: T): T;
+    /**
+     * converts `{ account: { $or: [ [Object], [Object] ] } }`
+     * to `{ $or: [ { account: [Object] }, { account: [Object] } ] }`
+     */
+    static liftGroupOperators<T extends object>(where: Dictionary, meta: EntityMetadata<T>, metadata: MetadataStorage, key?: string): string | undefined;
     static inlinePrimaryKeyObjects<T extends object>(where: Dictionary, meta: EntityMetadata<T>, metadata: MetadataStorage, key?: string): boolean;
     static processWhere<T extends object>(options: ProcessWhereOptions<T>): FilterQuery<T>;
-    static getActiveFilters(entityName: string, options: Dictionary<boolean | Dictionary> | string[] | boolean, filters: Dictionary<FilterDef>): FilterDef[];
+    static getActiveFilters(entityName: string, options: FilterOptions | undefined, filters: Dictionary<FilterDef>): FilterDef[];
+    static mergePropertyFilters(propFilters: FilterOptions | undefined, options: FilterOptions | undefined): FilterOptions | undefined;
     static isFilterActive(entityName: string, filterName: string, filter: FilterDef, options: Dictionary<boolean | Dictionary>): boolean;
     static processCustomType<T extends object>(prop: EntityProperty<T>, cond: FilterQuery<T>, platform: Platform, key?: string, fromQuery?: boolean): FilterQuery<T>;
     private static isSupportedOperator;

package/utils/QueryHelper.js

@@ -4,6 +4,7 @@ import { GroupOperator, ReferenceKind } from '../enums.js';
 import { JsonType } from '../types/JsonType.js';
 import { helper } from '../entity/wrap.js';
 import { RawQueryFragment, isRaw } from './RawQueryFragment.js';
+/** @internal */
 export class QueryHelper {
     static SUPPORTED_OPERATORS = ['>', '<', '<=', '>=', '!', '!='];
     static processParams(params) {
@@ -33,11 +34,52 @@ export class QueryHelper {
         });
         return params;
     }
+    /**
+     * converts `{ account: { $or: [ [Object], [Object] ] } }`
+     * to `{ $or: [ { account: [Object] }, { account: [Object] } ] }`
+     */
+    static liftGroupOperators(where, meta, metadata, key) {
+        if (!Utils.isPlainObject(where)) {
+            return undefined;
+        }
+        const keys = Object.keys(where);
+        const groupOperator = keys.find(k => {
+            return Utils.isGroupOperator(k) && Array.isArray(where[k]) && where[k].every(cond => {
+                return Utils.isPlainObject(cond) && Object.keys(cond).every(k2 => {
+                    if (Utils.isOperator(k2, false)) {
+                        if (k2 === '$not') {
+                            return Object.keys(cond[k2]).every(k3 => meta.primaryKeys.includes(k3));
+                        }
+                        return true;
+                    }
+                    return meta.primaryKeys.includes(k2);
+                });
+            });
+        });
+        if (groupOperator) {
+            return groupOperator;
+        }
+        for (const k of keys) {
+            const value = where[k];
+            const prop = meta.properties[k];
+            if (!prop || ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind)) {
+                continue;
+            }
+            const op = this.liftGroupOperators(value, prop.targetMeta, metadata, k);
+            if (op) {
+                delete where[k];
+                where[op] = value[op].map((v) => {
+                    return { [k]: v };
+                });
+            }
+        }
+        return undefined;
+    }
     static inlinePrimaryKeyObjects(where, meta, metadata, key) {
         if (Array.isArray(where)) {
             where.forEach((item, i) => {
                 if (this.inlinePrimaryKeyObjects(item, meta, metadata, key)) {
-                    where[i] = Utils.getPrimaryKeyValues(item, meta.primaryKeys, false);
+                    where[i] = Utils.getPrimaryKeyValues(item, meta, false);
                 }
             });
         }
@@ -45,9 +87,9 @@ export class QueryHelper {
             return false;
         }
         if (meta.primaryKeys.every(pk => pk in where) && Utils.getObjectKeysSize(where) === meta.primaryKeys.length) {
-            return !!key && !GroupOperator[key] && Object.keys(where).every(k => !Utils.isPlainObject(where[k]) || Object.keys(where[k]).every(v => {
+            return !!key && !GroupOperator[key] && key !== '$not' && Object.keys(where).every(k => !Utils.isPlainObject(where[k]) || Object.keys(where[k]).every(v => {
                 if (Utils.isOperator(v, false)) {
-                    return false;
+                    return true;
                 }
                 if (meta.properties[k].primary && [ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(meta.properties[k].kind)) {
                     return this.inlinePrimaryKeyObjects(where[k], meta.properties[k].targetMeta, metadata, v);
@@ -58,7 +100,7 @@ export 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.getPrimaryKeyValues(where[k], meta2.primaryKeys, true);
+                where[k] = Utils.getPrimaryKeyValues(where[k], meta2, true);
             }
         });
         return false;
@@ -69,6 +111,7 @@ export class QueryHelper {
         const meta = metadata.find(entityName);
         // inline PK-only objects in M:N queries, so we don't join the target entity when not needed
         if (meta && root) {
+            QueryHelper.liftGroupOperators(where, meta, metadata);
             QueryHelper.inlinePrimaryKeyObjects(where, meta, metadata);
         }
         if (platform.getConfig().get('ignoreUndefinedInQuery') && where && typeof where === 'object') {
@@ -118,7 +161,7 @@ export class QueryHelper {
                 value = QueryHelper.processCustomType(prop, value, platform, undefined, true);
             }
             const isJsonProperty = prop?.customType instanceof JsonType && Utils.isPlainObject(value) && !isRaw(value) && Object.keys(value)[0] !== '$eq';
-            if (isJsonProperty) {
+            if (isJsonProperty && prop?.kind !== ReferenceKind.EMBEDDED) {
                 return this.processJsonCondition(o, value, [prop.fieldNames[0]], platform, aliased);
             }
             if (Array.isArray(value) && !Utils.isOperator(key) && !QueryHelper.isSupportedOperator(key) && !key.includes('?') && options.type !== 'orderBy') {
@@ -159,6 +202,24 @@ export class QueryHelper {
             return filters[f];
         });
     }
+    static mergePropertyFilters(propFilters, options) {
+        if (!options || !propFilters || options === true || propFilters === true) {
+            return options ?? propFilters;
+        }
+        if (Array.isArray(propFilters)) {
+            propFilters = propFilters.reduce((o, item) => {
+                o[item] = true;
+                return o;
+            }, {});
+        }
+        if (Array.isArray(options)) {
+            options = options.reduce((o, item) => {
+                o[item] = true;
+                return o;
+            }, {});
+        }
+        return Utils.mergeConfig({}, propFilters, options);
+    }
     static isFilterActive(entityName, filterName, filter, options) {
         if (filter.entity && !filter.entity.includes(entityName)) {
             return false;

package/utils/RawQueryFragment.d.ts

@@ -72,8 +72,26 @@ 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;
+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>): NoInfer<R>;
 /**
  * Alternative to the `raw()` helper allowing to use it as a tagged template function for the simple cases.
  *
@@ -90,9 +108,25 @@ export declare function raw<T extends object = any, R = any>(sql: EntityKey<T> |
  */
 export declare function sql(sql: readonly string[], ...values: unknown[]): any;
 export declare namespace sql {
-    var ref: <T extends object>(...keys: string[]) => RawQueryFragment;
+    var ref: <T extends object>(...keys: string[]) => NoInfer<RawQueryFragment>;
     var now: (length?: number) => string;
     var lower: <T extends object>(key: string | ((alias: string) => string)) => string;
     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

@@ -18,7 +18,7 @@ export class RawQueryFragment {
     }
     as(alias) {
         // TODO: to be removed in v7
-        /* istanbul ignore next */
+        /* v8 ignore next 3 */
         if (alias.startsWith('`') || alias.startsWith('"')) {
             return new RawQueryFragment(`${this.sql} as ${alias}`, this.params);
         }
@@ -147,6 +147,24 @@ export 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 function raw(sql, params) {
     if (sql instanceof RawQueryFragment) {
@@ -205,3 +223,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 { ... }
+ * ```
+ */
+export function quote(expParts, ...values) {
+    return raw(expParts.join('??'), values);
+}

package/utils/TransactionManager.d.ts

@@ -0,0 +1,65 @@
+import type { EntityManager } from '../EntityManager.js';
+import { type TransactionOptions } from '../enums.js';
+/**
+ * Manages transaction lifecycle and propagation for EntityManager.
+ */
+export declare class TransactionManager {
+    private readonly em;
+    constructor(em: EntityManager);
+    /**
+     * Main entry point for handling transactional operations with propagation support.
+     */
+    handle<T>(cb: (em: EntityManager) => T | Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Executes the callback with the specified propagation type.
+     */
+    private executeWithPropagation;
+    /**
+     * Suspends the current transaction and returns the suspended resources.
+     */
+    private suspendTransaction;
+    /**
+     * Resumes a previously suspended transaction.
+     */
+    private resumeTransaction;
+    /**
+     * Executes operation without transaction context.
+     */
+    private executeWithoutTransaction;
+    /**
+     * Creates new independent transaction, suspending any existing one.
+     */
+    private executeWithNewTransaction;
+    /**
+     * Creates new transaction context.
+     */
+    private createNewTransaction;
+    /**
+     * Executes nested transaction with savepoint.
+     */
+    private executeNestedTransaction;
+    /**
+     * Creates a fork of the EntityManager with the given options.
+     */
+    private createFork;
+    /**
+     * Determines if changes should be propagated to the upper context.
+     */
+    private shouldPropagateToUpperContext;
+    /**
+     * Merges entities from fork to parent EntityManager.
+     */
+    private mergeEntitiesToParent;
+    /**
+     * Registers a deletion handler to unset entity identities after flush.
+     */
+    private registerDeletionHandler;
+    /**
+     * Processes transaction execution.
+     */
+    private processTransaction;
+    /**
+     * Executes transaction workflow with entity synchronization.
+     */
+    private executeTransactionFlow;
+}