@mikro-orm/core 7.0.0-dev.9 → 7.0.0-dev.91

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);
@@ -48,7 +48,7 @@ export class EntityComparator {
      */
     getPkGetter(meta) {
         const exists = this.pkGetters.get(meta.className);
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (exists) {
             return exists;
         }
@@ -98,7 +98,7 @@ export class EntityComparator {
      */
     getPkGetterConverted(meta) {
         const exists = this.pkGettersConverted.get(meta.className);
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (exists) {
             return exists;
         }
@@ -148,13 +148,14 @@ export class EntityComparator {
      */
     getPkSerializer(meta) {
         const exists = this.pkSerializers.get(meta.className);
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (exists) {
             return exists;
         }
         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}`;
@@ -189,6 +199,7 @@ export class EntityComparator {
      * @internal Highly performance-sensitive method.
      */
     getSnapshotGenerator(entityName) {
+        entityName = Utils.className(entityName);
         const exists = this.snapshotGenerators.get(entityName);
         if (exists) {
             return exists;
@@ -274,10 +285,14 @@ export class EntityComparator {
             lines.push(`${padding}    if (${value} == null || ${value} instanceof Date) {`);
             lines.push(`${padding}      ${key} = ${value};`);
             if (!tz || tz === 'local') {
+                lines.push(`${padding}    } else if (typeof ${value} === 'bigint') {`);
+                lines.push(`${padding}      ${key} = parseDate(Number(${value}));`);
                 lines.push(`${padding}    } else {`);
                 lines.push(`${padding}      ${key} = parseDate(${value});`);
             }
             else {
+                lines.push(`${padding}    } else if (typeof ${value} === 'bigint') {`);
+                lines.push(`${padding}      ${key} = parseDate(Number(${value}));`);
                 lines.push(`${padding}    } else if (typeof ${value} === 'number' || ${value}.includes('+') || ${value}.lastIndexOf('-') > 10 || ${value}.endsWith('Z')) {`);
                 lines.push(`${padding}      ${key} = parseDate(${value});`);
                 lines.push(`${padding}    } else {`);
@@ -352,7 +367,7 @@ export class EntityComparator {
         else {
             mapEntityProperties(meta);
         }
-        lines.push(`  for (let k in result) { if (Object.hasOwn(result, k) && !mapped[k]) ret[k] = result[k]; }`);
+        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);
@@ -407,11 +422,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) {
@@ -456,7 +481,7 @@ export class EntityComparator {
     registerCustomType(prop, context) {
         const convertorKey = this.safeKey(prop.name);
         context.set(`convertToDatabaseValue_${convertorKey}`, (val) => {
-            /* v8 ignore next 3 */
+            /* v8 ignore next */
             if (RawQueryFragment.isKnownFragment(val)) {
                 return val;
             }
@@ -531,17 +556,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` +
@@ -582,10 +617,10 @@ export class EntityComparator {
         if (['buffer', 'uint8array'].includes(type)) {
             return this.getGenericComparator(this.wrap(prop.name), `!compareBuffers(last${this.wrap(prop.name)}, current${this.wrap(prop.name)})`);
         }
-        if (['date'].includes(type)) {
+        if (type === 'date') {
             return this.getGenericComparator(this.wrap(prop.name), `last${this.wrap(prop.name)}.valueOf() !== current${this.wrap(prop.name)}.valueOf()`);
         }
-        if (['objectid'].includes(type)) {
+        if (type === 'objectid') {
             // We might be comparing PK to object, in case we compare with cached data of populated entity
             // in such case we just ignore the comparison and fallback to `equals()` (which will still mark
             // it as not equal as we compare PK to plain object).
@@ -607,7 +642,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

@@ -1,9 +1,10 @@
 import { Reference } from '../entity/Reference.js';
 import { Utils } from './Utils.js';
-import { GroupOperator, ReferenceKind } from '../enums.js';
+import { ARRAY_OPERATORS, GroupOperator, JSON_KEY_OPERATORS, ReferenceKind } from '../enums.js';
 import { JsonType } from '../types/JsonType.js';
 import { helper } from '../entity/wrap.js';
-import { RawQueryFragment, isRaw } from './RawQueryFragment.js';
+import { isRaw, RawQueryFragment } 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 k in GroupOperator && 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);
                 }
             });
         }
@@ -47,7 +89,7 @@ export class QueryHelper {
         if (meta.primaryKeys.every(pk => pk in where) && Utils.getObjectKeysSize(where) === meta.primaryKeys.length) {
             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,13 +111,14 @@ 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') {
             Utils.dropUndefinedProperties(where);
         }
         where = QueryHelper.processParams(where) ?? {};
-        /* v8 ignore next 3 */
+        /* v8 ignore next */
         if (!root && Utils.isPrimaryKey(where)) {
             return where;
         }
@@ -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;
@@ -180,12 +241,12 @@ export class QueryHelper {
                 return o;
             }, {});
         }
-        if (key && Utils.isJsonKeyOperator(key)) {
+        if (key && JSON_KEY_OPERATORS.includes(key)) {
             return Array.isArray(cond)
                 ? platform.marshallArray(cond)
                 : cond;
         }
-        if (Array.isArray(cond) && !(key && Utils.isArrayOperator(key))) {
+        if (Array.isArray(cond) && !(key && ARRAY_OPERATORS.includes(key))) {
             return cond.map(v => QueryHelper.processCustomType(prop, v, platform, key, fromQuery));
         }
         if (isRaw(cond)) {

package/utils/RawQueryFragment.d.ts

@@ -1,4 +1,3 @@
-import { inspect } from 'node:util';
 import type { AnyString, Dictionary, EntityKey } from '../typings.js';
 export declare class RawQueryFragment {
     #private;
@@ -10,8 +9,6 @@ export declare class RawQueryFragment {
     valueOf(): string;
     toJSON(): string;
     toString(): string;
-    /** @internal */
-    assign(): void;
     clone(): RawQueryFragment;
     static run<T>(cb: (...args: any[]) => Promise<T>): Promise<T>;
     /**
@@ -21,14 +18,6 @@ export declare class RawQueryFragment {
     static isKnownFragment(key: string | RawQueryFragment): boolean;
     static getKnownFragment(key: string | RawQueryFragment, cleanup?: boolean): RawQueryFragment | undefined;
     static remove(key: string): void;
-    /** @ignore */
-    [inspect.custom](): {
-        sql: string;
-        params: unknown[];
-    } | {
-        sql: string;
-        params?: undefined;
-    };
 }
 export { RawQueryFragment as Raw };
 export declare function isRaw(value: unknown): value is RawQueryFragment;
@@ -72,8 +61,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 +97,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

@@ -1,5 +1,4 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { inspect } from 'node:util';
 import { Utils } from './Utils.js';
 export class RawQueryFragment {
     sql;
@@ -8,7 +7,6 @@ export class RawQueryFragment {
     static #storage = new AsyncLocalStorage();
     static #index = 0n;
     static cloneRegistry;
-    #assigned = false;
     #used = 0;
     #key;
     constructor(sql, params = []) {
@@ -17,11 +15,6 @@ export class RawQueryFragment {
         this.#key = `[raw]: ${this.sql} (#${RawQueryFragment.#index++})`;
     }
     as(alias) {
-        // TODO: to be removed in v7
-        /* istanbul ignore next */
-        if (alias.startsWith('`') || alias.startsWith('"')) {
-            return new RawQueryFragment(`${this.sql} as ${alias}`, this.params);
-        }
         return new RawQueryFragment(`${this.sql} as ??`, [...this.params, alias]);
     }
     valueOf() {
@@ -35,13 +28,6 @@ export class RawQueryFragment {
         this.#used++;
         return this.#key;
     }
-    /** @internal */
-    assign() {
-        if (this.#assigned) {
-            throw new Error(`Cannot reassign already used RawQueryFragment: '${this.sql}'`);
-        }
-        this.#assigned = true;
-    }
     clone() {
         RawQueryFragment.cloneRegistry?.add(this.#key);
         return new RawQueryFragment(this.sql, this.params);
@@ -91,9 +77,9 @@ export class RawQueryFragment {
             }
         }
     }
-    /* v8 ignore next 8 */
     /** @ignore */
-    [inspect.custom]() {
+    /* v8 ignore next */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
         if (this.params) {
             return { sql: this.sql, params: this.params };
         }
@@ -147,6 +133,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 +209,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;
+}