@mikro-orm/core 7.0.0-dev.3 → 7.0.0-dev.300

package/utils/QueryHelper.js

@@ -1,11 +1,18 @@
 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, Raw } from './RawQueryFragment.js';
+/** @internal */
 export class QueryHelper {
     static SUPPORTED_OPERATORS = ['>', '<', '<=', '>=', '!', '!='];
+    /**
+     * Finds the discriminator value (key) for a given entity class in a discriminator map.
+     */
+    static findDiscriminatorValue(discriminatorMap, targetClass) {
+        return Object.entries(discriminatorMap).find(([, cls]) => cls === targetClass)?.[0];
+    }
     static processParams(params) {
         if (Reference.isReference(params)) {
             params = params.unwrap();
@@ -28,16 +35,60 @@ export class QueryHelper {
         return params;
     }
     static processObjectParams(params = {}) {
-        Utils.keys(params).forEach(k => {
+        Utils.getObjectQueryKeys(params).forEach(k => {
             params[k] = QueryHelper.processParams(params[k]);
         });
         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];
+            // Polymorphic relations use multiple columns (discriminator + FK), so they cannot
+            // participate in the standard single-column FK expansion. Query by discriminator
+            // column directly instead, e.g. { likeableType: 'post', likeableId: 1 }.
+            if (!prop || ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) || prop.polymorphic) {
+                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 +96,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);
@@ -56,9 +107,9 @@ export class QueryHelper {
             }));
         }
         Object.keys(where).forEach(k => {
-            const meta2 = metadata.find(meta.properties[k]?.type) || meta;
+            const meta2 = metadata.find(meta.properties[k]?.targetMeta?.class) || 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 +120,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;
         }
@@ -83,7 +135,7 @@ export class QueryHelper {
             where = { [Utils.getPrimaryKeyHash(meta.primaryKeys)]: where };
         }
         if (Array.isArray(where) && root) {
-            const rootPrimaryKey = meta ? Utils.getPrimaryKeyHash(meta.primaryKeys) : entityName;
+            const rootPrimaryKey = meta ? Utils.getPrimaryKeyHash(meta.primaryKeys) : Utils.className(entityName);
             let cond = { [rootPrimaryKey]: { $in: where } };
             // @ts-ignore
             // detect tuple comparison, use `$or` in case the number of constituents don't match
@@ -95,12 +147,10 @@ export class QueryHelper {
         if (!Utils.isPlainObject(where)) {
             return where;
         }
-        return Object.keys(where).reduce((o, key) => {
+        return Utils.getObjectQueryKeys(where).reduce((o, key) => {
             let value = where[key];
-            const prop = this.findProperty(key, options);
-            const keys = prop?.joinColumns?.length ?? 0;
-            const composite = keys > 1;
-            if (Array.isArray(value) && value.length === 0 && RawQueryFragment.isKnownFragment(key)) {
+            const customExpression = Raw.isKnownFragmentSymbol(key);
+            if (Array.isArray(value) && value.length === 0 && customExpression) {
                 o[key] = value;
                 return o;
             }
@@ -114,14 +164,17 @@ export class QueryHelper {
                 o[rootPrimaryKey] = { [key]: QueryHelper.processWhere({ ...options, where: value, root: false }) };
                 return o;
             }
+            const prop = customExpression ? null : this.findProperty(key, options);
+            const keys = prop?.joinColumns?.length ?? 0;
+            const composite = keys > 1;
             if (prop?.customType && convertCustomTypes && !isRaw(value)) {
                 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') {
+            if (Array.isArray(value) && !Utils.isOperator(key) && !QueryHelper.isSupportedOperator(key) && !(customExpression && Raw.getKnownFragment(key).params.length > 0) && options.type !== 'orderBy') {
                 // comparing single composite key - use $eq instead of $in
                 const op = composite && !value.every(v => Array.isArray(v)) ? '$eq' : '$in';
                 o[key] = { [op]: value };
@@ -131,7 +184,7 @@ export class QueryHelper {
                 o[key] = QueryHelper.processWhere({
                     ...options,
                     where: value,
-                    entityName: prop?.type ?? entityName,
+                    entityName: prop?.targetMeta?.class ?? entityName,
                     root: false,
                 });
             }
@@ -141,7 +194,7 @@ export class QueryHelper {
             return o;
         }, {});
     }
-    static getActiveFilters(entityName, options, filters) {
+    static getActiveFilters(meta, options, filters) {
         if (options === false) {
             return [];
         }
@@ -153,14 +206,32 @@ export class QueryHelper {
             Object.keys(options).forEach(filter => opts[filter] = options[filter]);
         }
         return Object.keys(filters)
-            .filter(f => QueryHelper.isFilterActive(entityName, f, filters[f], opts))
+            .filter(f => QueryHelper.isFilterActive(meta, f, filters[f], opts))
             .map(f => {
             filters[f].name = f;
             return filters[f];
         });
     }
-    static isFilterActive(entityName, filterName, filter, options) {
-        if (filter.entity && !filter.entity.includes(entityName)) {
+    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(meta, filterName, filter, options) {
+        if (filter.entity && !filter.entity.includes(meta.className)) {
             return false;
         }
         if (options[filterName] === false) {
@@ -170,8 +241,8 @@ export class QueryHelper {
     }
     static processCustomType(prop, cond, platform, key, fromQuery) {
         if (Utils.isPlainObject(cond)) {
-            return Utils.keys(cond).reduce((o, k) => {
-                if (Utils.isOperator(k, true) || prop.referencedPKs?.includes(k)) {
+            return Utils.getObjectQueryKeys(cond).reduce((o, k) => {
+                if (!Raw.isKnownFragmentSymbol(k) && (Utils.isOperator(k, true) || prop.referencedPKs?.includes(k))) {
                     o[k] = QueryHelper.processCustomType(prop, cond[k], platform, k, fromQuery);
                 }
                 else {
@@ -180,12 +251,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)) {
@@ -229,4 +300,29 @@ export class QueryHelper {
         const meta = entityName ? options.metadata.find(entityName) : undefined;
         return meta?.properties[propName];
     }
+    /**
+     * Merges multiple orderBy sources with key-level deduplication (first-seen key wins).
+     * RawQueryFragment symbol keys are never deduped (each is unique).
+     */
+    static mergeOrderBy(...sources) {
+        const result = [];
+        const seenKeys = new Set();
+        for (const source of sources) {
+            if (source == null) {
+                continue;
+            }
+            for (const item of Utils.asArray(source)) {
+                for (const key of Utils.getObjectQueryKeys(item)) {
+                    if (typeof key === 'symbol') {
+                        result.push({ [key]: item[key] });
+                    }
+                    else if (!seenKeys.has(key)) {
+                        seenKeys.add(key);
+                        result.push({ [key]: item[key] });
+                    }
+                }
+            }
+        }
+        return result;
+    }
 }

package/utils/RawQueryFragment.d.ts

@@ -1,34 +1,25 @@
-import { inspect } from 'node:util';
 import type { AnyString, Dictionary, EntityKey } from '../typings.js';
-export declare class RawQueryFragment {
+declare const rawFragmentSymbolBrand: unique symbol;
+export type RawQueryFragmentSymbol = symbol & {
+    readonly [rawFragmentSymbolBrand]: true;
+};
+export declare class RawQueryFragment<Alias extends string = string> {
     #private;
     readonly sql: string;
     readonly params: unknown[];
-    static cloneRegistry?: Set<string>;
+    /** @internal Type-level only - used to track the alias for type inference */
+    private readonly __alias?;
     constructor(sql: string, params?: unknown[]);
-    as(alias: string): RawQueryFragment;
-    valueOf(): string;
+    get key(): RawQueryFragmentSymbol;
+    as<A extends string>(alias: A): RawQueryFragment<A>;
+    [Symbol.toPrimitive](hint: 'string'): RawQueryFragmentSymbol;
+    get [Symbol.toStringTag](): string;
     toJSON(): string;
-    toString(): string;
-    /** @internal */
-    assign(): void;
-    clone(): RawQueryFragment;
-    static run<T>(cb: (...args: any[]) => Promise<T>): Promise<T>;
-    /**
-     * @internal allows testing we don't leak memory, as the raw fragments cache needs to be cleared automatically
-     */
-    static checkCacheSize(): number;
-    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;
-    };
+    clone(): this;
+    static isKnownFragmentSymbol(key: unknown): key is RawQueryFragmentSymbol;
+    static hasObjectFragments(object: unknown): boolean;
+    static isKnownFragment(key: unknown): key is RawQueryFragment | symbol;
+    static getKnownFragment(key: unknown): RawQueryFragment<any> | undefined;
 }
 export { RawQueryFragment as Raw };
 export declare function isRaw(value: unknown): value is RawQueryFragment;
@@ -72,8 +63,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<R = RawQueryFragment & symbol, T extends object = any>(sql: EntityKey<T> | EntityKey<T>[] | AnyString | ((alias: string) => string) | RawQueryFragment, params?: readonly unknown[] | Dictionary<unknown>): R;
 /**
  * Alternative to the `raw()` helper allowing to use it as a tagged template function for the simple cases.
  *
@@ -86,13 +95,32 @@ export declare function raw<T extends object = any, R = any>(sql: EntityKey<T> |
  *
  * // value can be empty array
  * await em.find(User, { [sql`(select 1 = 1)`]: [] });
+ *
+ * // with type parameter for assignment without casting
+ * entity.date = sql<Date>`now()`;
  * ```
  */
-export declare function sql(sql: readonly string[], ...values: unknown[]): any;
+export declare function sql<R = RawQueryFragment & symbol>(sql: readonly string[], ...values: unknown[]): R;
 export declare namespace sql {
-    var ref: <T extends object>(...keys: string[]) => 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;
+    var ref: <T extends object = any>(...keys: string[]) => RawQueryFragment<string> & symbol;
+    var now: (length?: number) => RawQueryFragment<string> & symbol;
+    var lower: <R = RawQueryFragment<string> & symbol, T extends object = any>(key: string | ((alias: string) => string)) => R;
+    var upper: <R = RawQueryFragment<string> & symbol, T extends object = any>(key: string | ((alias: string) => string)) => R;
 }
-export declare function createSqlFunction<T extends object, R = string>(func: string, key: string | ((alias: string) => string)): R;
+export declare function createSqlFunction<R = RawQueryFragment & symbol, T extends object = any>(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, indexName) => quote`create index ${indexName} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export declare function quote(expParts: readonly string[], ...values: (string | {
+    toString(): string;
+})[]): RawQueryFragment<string> & symbol;

package/utils/RawQueryFragment.js

@@ -1,94 +1,64 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { inspect } from 'node:util';
 import { Utils } from './Utils.js';
 export class RawQueryFragment {
     sql;
     params;
-    static #rawQueryCache = new Map();
-    static #storage = new AsyncLocalStorage();
-    static #index = 0n;
-    static cloneRegistry;
-    #assigned = false;
-    #used = 0;
+    static #rawQueryReferences = new WeakMap();
     #key;
     constructor(sql, params = []) {
         this.sql = sql;
         this.params = params;
-        this.#key = `[raw]: ${this.sql} (#${RawQueryFragment.#index++})`;
+    }
+    get key() {
+        if (!this.#key) {
+            this.#key = Symbol(this.toJSON());
+            RawQueryFragment.#rawQueryReferences.set(this.#key, this);
+        }
+        return this.#key;
     }
     as(alias) {
-        return new RawQueryFragment(`${this.sql} as ${alias}`, this.params);
+        return new RawQueryFragment(`${this.sql} as ??`, [...this.params, alias]);
     }
-    valueOf() {
+    [Symbol.toPrimitive](hint) {
+        // if a fragment is converted to string (used as an object key), return a unique symbol
+        // and save a weak reference to map so we can retrieve it when compiling the query
+        if (hint === 'string') {
+            return this.key;
+        }
         throw new Error(`Trying to modify raw SQL fragment: '${this.sql}'`);
     }
+    get [Symbol.toStringTag]() {
+        return this.toJSON();
+    }
     toJSON() {
-        return this.#key;
+        return `raw('${this.sql}')`;
     }
-    toString() {
-        RawQueryFragment.#rawQueryCache.set(this.#key, this);
-        this.#used++;
-        return this.#key;
+    clone() {
+        return this;
     }
-    /** @internal */
-    assign() {
-        if (this.#assigned) {
-            throw new Error(`Cannot reassign already used RawQueryFragment: '${this.sql}'`);
-        }
-        this.#assigned = true;
+    static isKnownFragmentSymbol(key) {
+        return typeof key === 'symbol' && this.#rawQueryReferences.has(key);
     }
-    clone() {
-        RawQueryFragment.cloneRegistry?.add(this.#key);
-        return new RawQueryFragment(this.sql, this.params);
-    }
-    static async run(cb) {
-        const removeStack = new Set();
-        const res = await this.#storage.run(removeStack, cb);
-        removeStack.forEach(key => RawQueryFragment.remove(key));
-        removeStack.clear();
-        return res;
-    }
-    /**
-     * @internal allows testing we don't leak memory, as the raw fragments cache needs to be cleared automatically
-     */
-    static checkCacheSize() {
-        return this.#rawQueryCache.size;
+    static hasObjectFragments(object) {
+        return Utils.isPlainObject(object) && Object.getOwnPropertySymbols(object).some(symbol => this.isKnownFragmentSymbol(symbol));
     }
     static isKnownFragment(key) {
         if (key instanceof RawQueryFragment) {
             return true;
         }
-        return this.#rawQueryCache.has(key);
+        return this.isKnownFragmentSymbol(key);
     }
-    static getKnownFragment(key, cleanup = true) {
+    static getKnownFragment(key) {
         if (key instanceof RawQueryFragment) {
             return key;
         }
-        const raw = this.#rawQueryCache.get(key);
-        if (raw && cleanup) {
-            this.remove(key);
-        }
-        return raw;
-    }
-    static remove(key) {
-        const raw = this.#rawQueryCache.get(key);
-        if (!raw) {
+        if (typeof key !== 'symbol') {
             return;
         }
-        raw.#used--;
-        if (raw.#used <= 0) {
-            const removeStack = this.#storage.getStore();
-            if (removeStack) {
-                removeStack.add(key);
-            }
-            else {
-                this.#rawQueryCache.delete(key);
-            }
-        }
+        return this.#rawQueryReferences.get(key);
     }
-    /* 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 };
         }
@@ -142,6 +112,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) {
@@ -181,14 +169,13 @@ export function raw(sql, params) {
  *
  * // value can be empty array
  * await em.find(User, { [sql`(select 1 = 1)`]: [] });
+ *
+ * // with type parameter for assignment without casting
+ * entity.date = sql<Date>`now()`;
  * ```
  */
 export function sql(sql, ...values) {
-    return raw(sql.reduce((query, queryPart, i) => {
-        const valueExists = i < values.length;
-        const text = query + queryPart;
-        return valueExists ? text + '?' : text;
-    }, ''), values);
+    return raw(sql.join('?'), values);
 }
 export function createSqlFunction(func, key) {
     if (typeof key === 'string') {
@@ -200,3 +187,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, indexName) => quote`create index ${indexName} on ${table} (${columns.name})` })
+ * @Entity({ schema: 'library' })
+ * export class Author { ... }
+ * ```
+ */
+export function quote(expParts, ...values) {
+    return raw(expParts.join('??'), values);
+}

package/utils/RequestContext.js

@@ -1,10 +1,10 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { createAsyncContext } from './AsyncContext.js';
 /**
  * Uses `AsyncLocalStorage` to create async context that holds the current EM fork.
  */
 export class RequestContext {
     map;
-    static storage = new AsyncLocalStorage();
+    static storage = createAsyncContext();
     static counter = 1;
     id = RequestContext.counter++;
     constructor(map) {

package/utils/TransactionContext.js

@@ -1,7 +1,7 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
+import { createAsyncContext } from './AsyncContext.js';
 export class TransactionContext {
     em;
-    static storage = new AsyncLocalStorage();
+    static storage = createAsyncContext();
     id;
     constructor(em) {
         this.em = em;

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;
+}