@mikro-orm/core 7.0.0-dev.33 → 7.0.0-dev.331

package/utils/QueryHelper.d.ts

@@ -1,11 +1,17 @@
-import type { Dictionary, EntityMetadata, EntityProperty, FilterDef, FilterQuery } from '../typings.js';
+import type { Dictionary, EntityMetadata, EntityName, EntityProperty, FilterDef, FilterQuery } from '../typings.js';
+import { type QueryOrderMap } from '../enums.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[];
+    /**
+     * Finds the discriminator value (key) for a given entity class in a discriminator map.
+     */
+    static findDiscriminatorValue<T>(discriminatorMap: Dictionary<T>, targetClass: T): string | undefined;
     static processParams(params: unknown): any;
-    static processObjectParams<T extends object>(params?: T): T;
+    static processObjectParams<T extends Dictionary>(params?: T): T;
     /**
      * converts `{ account: { $or: [ [Object], [Object] ] } }`
      * to `{ $or: [ { account: [Object] }, { account: [Object] } ] }`
@@ -13,21 +19,42 @@ export declare class QueryHelper {
     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 isFilterActive(entityName: string, filterName: string, filter: FilterDef, options: Dictionary<boolean | Dictionary>): boolean;
+    static getActiveFilters<T>(meta: EntityMetadata<T>, options: FilterOptions | undefined, filters: Dictionary<FilterDef>): FilterDef[];
+    static mergePropertyFilters(propFilters: FilterOptions | undefined, options: FilterOptions | undefined): FilterOptions | undefined;
+    static isFilterActive<T>(meta: EntityMetadata<T>, 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;
     private static processJsonCondition;
-    private static getValueType;
     static findProperty<T>(fieldName: string, options: ProcessWhereOptions<T>): EntityProperty<T> | undefined;
+    /**
+     * Converts entity references for composite FK properties into flat arrays
+     * of correctly-ordered join column values, before processParams flattens them
+     * incorrectly due to shared FK columns.
+     */
+    private static convertCompositeEntityRefs;
+    /**
+     * Extracts values for a FK's join columns from an entity by traversing the FK chain.
+     * Handles shared FK columns (e.g., tenant_id referenced by multiple FKs) correctly.
+     */
+    private static extractJoinColumnValues;
+    /**
+     * Extracts the value for a specific column from an entity by finding which PK property
+     * owns that column and recursively traversing FK references.
+     */
+    private static extractColumnValue;
+    /**
+     * Merges multiple orderBy sources with key-level deduplication (first-seen key wins).
+     * RawQueryFragment symbol keys are never deduped (each is unique).
+     */
+    static mergeOrderBy<T>(...sources: (QueryOrderMap<T> | QueryOrderMap<T>[] | undefined)[]): QueryOrderMap<T>[];
 }
 interface ProcessWhereOptions<T> {
     where: FilterQuery<T>;
-    entityName: string;
+    entityName: EntityName<T>;
     metadata: MetadataStorage;
     platform: Platform;
     aliased?: boolean;
-    aliasMap?: Dictionary<string>;
+    aliasMap?: Dictionary<EntityName>;
     convertCustomTypes?: boolean;
     root?: boolean;
     type?: 'where' | 'orderBy';

package/utils/QueryHelper.js

@@ -1,12 +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();
@@ -29,7 +35,7 @@ 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;
@@ -44,17 +50,21 @@ export class QueryHelper {
         }
         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);
-                });
-            });
+            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));
+                                }
+                                /* v8 ignore next */
+                                return true;
+                            }
+                            return meta.primaryKeys.includes(k2);
+                        }));
+                }));
         });
         if (groupOperator) {
             return groupOperator;
@@ -62,7 +72,10 @@ export class QueryHelper {
         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)) {
+            // 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);
@@ -87,18 +100,24 @@ export class QueryHelper {
             return false;
         }
         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 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);
-                }
-                return true;
-            }));
+            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 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);
+                        }
+                        /* v8 ignore next */
+                        return true;
+                    })));
         }
         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, true);
             }
@@ -114,11 +133,14 @@ export class QueryHelper {
             QueryHelper.liftGroupOperators(where, meta, metadata);
             QueryHelper.inlinePrimaryKeyObjects(where, meta, metadata);
         }
+        if (meta && root) {
+            QueryHelper.convertCompositeEntityRefs(where, meta);
+        }
         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;
         }
@@ -126,11 +148,13 @@ 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
-            if (meta && !where.every(c => Utils.isPrimaryKey(c) || (Array.isArray(c) && c.length === meta.primaryKeys.length && c.every(i => Utils.isPrimaryKey(i))))) {
+            if (meta &&
+                !where.every(c => Utils.isPrimaryKey(c) ||
+                    (Array.isArray(c) && c.length === meta.primaryKeys.length && c.every(i => Utils.isPrimaryKey(i))))) {
                 cond = { $or: where };
             }
             return QueryHelper.processWhere({ ...options, where: cond, root: false });
@@ -138,12 +162,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;
             }
@@ -157,14 +179,19 @@ 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';
+            // oxfmt-ignore
+            const isJsonProperty = prop?.customType instanceof JsonType && !isRaw(value) && (Utils.isPlainObject(value) ? Object.keys(value)[0] !== '$eq' : !Array.isArray(value));
             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') {
+            // oxfmt-ignore
+            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 };
@@ -174,7 +201,7 @@ export class QueryHelper {
                 o[key] = QueryHelper.processWhere({
                     ...options,
                     where: value,
-                    entityName: prop?.type ?? entityName,
+                    entityName: prop?.targetMeta?.class ?? entityName,
                     root: false,
                 });
             }
@@ -184,26 +211,44 @@ export class QueryHelper {
             return o;
         }, {});
     }
-    static getActiveFilters(entityName, options, filters) {
+    static getActiveFilters(meta, options, filters) {
         if (options === false) {
             return [];
         }
         const opts = {};
         if (Array.isArray(options)) {
-            options.forEach(filter => opts[filter] = true);
+            options.forEach(filter => (opts[filter] = true));
         }
         else if (Utils.isPlainObject(options)) {
-            Object.keys(options).forEach(filter => opts[filter] = options[filter]);
+            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) {
@@ -213,8 +258,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 {
@@ -223,12 +268,10 @@ export class QueryHelper {
                 return o;
             }, {});
         }
-        if (key && Utils.isJsonKeyOperator(key)) {
-            return Array.isArray(cond)
-                ? platform.marshallArray(cond)
-                : cond;
+        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)) {
@@ -240,29 +283,7 @@ export class QueryHelper {
         return !!QueryHelper.SUPPORTED_OPERATORS.find(op => key === op);
     }
     static processJsonCondition(o, value, path, platform, alias) {
-        if (Utils.isPlainObject(value) && !Object.keys(value).some(k => Utils.isOperator(k))) {
-            Utils.keys(value).forEach(k => {
-                this.processJsonCondition(o, value[k], [...path, k], platform, alias);
-            });
-            return o;
-        }
-        if (path.length === 1) {
-            o[path[0]] = value;
-            return o;
-        }
-        const type = this.getValueType(value);
-        const k = platform.getSearchJsonPropertyKey(path, type, alias, value);
-        o[k] = value;
-        return o;
-    }
-    static getValueType(value) {
-        if (Array.isArray(value)) {
-            return typeof value[0];
-        }
-        if (Utils.isPlainObject(value) && Object.keys(value).every(k => Utils.isOperator(k))) {
-            return this.getValueType(Object.values(value)[0]);
-        }
-        return typeof value;
+        return platform.processJsonCondition(o, value, path, alias);
     }
     static findProperty(fieldName, options) {
         const parts = fieldName.split('.');
@@ -272,4 +293,94 @@ export class QueryHelper {
         const meta = entityName ? options.metadata.find(entityName) : undefined;
         return meta?.properties[propName];
     }
+    /**
+     * Converts entity references for composite FK properties into flat arrays
+     * of correctly-ordered join column values, before processParams flattens them
+     * incorrectly due to shared FK columns.
+     */
+    static convertCompositeEntityRefs(where, meta) {
+        if (!Utils.isPlainObject(where)) {
+            return;
+        }
+        for (const k of Object.keys(where)) {
+            if (k in GroupOperator) {
+                if (Array.isArray(where[k])) {
+                    where[k].forEach((sub) => this.convertCompositeEntityRefs(sub, meta));
+                }
+                continue;
+            }
+            if (k === '$not') {
+                this.convertCompositeEntityRefs(where[k], meta);
+                continue;
+            }
+            const prop = meta.properties[k];
+            if (!prop?.joinColumns || prop.joinColumns.length <= 1) {
+                continue;
+            }
+            const w = where[k];
+            if (Utils.isEntity(w)) {
+                where[k] = this.extractJoinColumnValues(w, prop);
+            }
+            else if (Utils.isPlainObject(w)) {
+                for (const op of Object.keys(w)) {
+                    if (Utils.isOperator(op, false) && Array.isArray(w[op])) {
+                        w[op] = w[op].map((item) => Utils.isEntity(item) ? this.extractJoinColumnValues(item, prop) : item);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Extracts values for a FK's join columns from an entity by traversing the FK chain.
+     * Handles shared FK columns (e.g., tenant_id referenced by multiple FKs) correctly.
+     */
+    static extractJoinColumnValues(entity, prop) {
+        return prop.referencedColumnNames.map(refCol => {
+            return this.extractColumnValue(entity, prop.targetMeta, refCol);
+        });
+    }
+    /**
+     * Extracts the value for a specific column from an entity by finding which PK property
+     * owns that column and recursively traversing FK references.
+     */
+    static extractColumnValue(entity, meta, columnName) {
+        for (const pk of meta.primaryKeys) {
+            const pkProp = meta.properties[pk];
+            const colIdx = pkProp.fieldNames.indexOf(columnName);
+            if (colIdx !== -1) {
+                const value = entity[pk];
+                if (pkProp.targetMeta && Utils.isEntity(value, true)) {
+                    const refCol = pkProp.referencedColumnNames[colIdx];
+                    return this.extractColumnValue(value, pkProp.targetMeta, refCol);
+                }
+                return value;
+            }
+        }
+        return null;
+    }
+    /**
+     * 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 | undefined;
 }
 export { RawQueryFragment as Raw };
 export declare function isRaw(value: unknown): value is RawQueryFragment;
@@ -91,7 +82,7 @@ export declare const ALIAS_REPLACEMENT_RE = "\\[::alias::\\]";
  * 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.
  *
@@ -104,16 +95,19 @@ 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 & symbol;
+    var now: (length?: number) => RawQueryFragment & 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, ...).
  *
@@ -122,11 +116,11 @@ export declare function createSqlFunction<T extends object, R = string>(func: st
  * ```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})` })
+ * @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;
-})[]): any;
+})[]): RawQueryFragment & symbol;