typeorm-extensions 1.3.5 → 2.0.0

package/dist/utils/period.utils.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachPeriodFilter = void 0;
+const sql_utils_1 = require("./sql.utils");
+const where_utils_1 = require("./where.utils");
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** `'2024-01-31'` as a UTC midnight Date, or a `TypeError` if it is not a calendar date (`'2024-02-30'`). */
+function parseDateOnly(value, name) {
+    const day = new Date(`${value}T00:00:00.000Z`);
+    if (isNaN(day.getTime()) || day.toISOString().slice(0, 10) !== value) {
+        throw new TypeError(`Invalid ${name} "${value}": not a calendar date`);
+    }
+    return day;
+}
+/** A usable boundary, `undefined` for a missing one (`undefined`, `null`, `''`). */
+function normalizeBoundary(value, name) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    if (Object.prototype.toString.call(value) === '[object Date]') {
+        if (isNaN(value.getTime())) {
+            throw new TypeError(`Invalid ${name}: invalid Date`);
+        }
+        return value;
+    }
+    if (typeof value !== 'string') {
+        throw new TypeError(`Invalid ${name}: expected a Date or a string, got ${typeof value}`);
+    }
+    if (DATE_ONLY.test(value)) {
+        parseDateOnly(value, name);
+    }
+    return value;
+}
+/** The day after a date-only string, or `undefined` past year 9999. */
+function getNextDay(value, name) {
+    const day = parseDateOnly(value, name);
+    day.setUTCDate(day.getUTCDate() + 1);
+    const next = day.toISOString().slice(0, 10);
+    return DATE_ONLY.test(next) ? next : undefined;
+}
+/**
+ * The comparison for one end of the period. A date-only string stands for the whole day,
+ * so excluding the start or including the end moves the bound to the next day:
+ * `> '2024-01-01'` would still match timestamps later on January 1st.
+ */
+function getBoundCondition(boundary, name, include) {
+    const isFrom = name === 'periodFrom';
+    const nextDay = typeof boundary === 'string' && DATE_ONLY.test(boundary) && include !== isFrom
+        ? getNextDay(boundary, name)
+        : undefined;
+    if (nextDay !== undefined) {
+        // excluded start day: `>= next day`; included end day: `< next day`
+        return { operator: isFrom ? '>=' : '<', value: nextDay };
+    }
+    if (isFrom) {
+        return { operator: include ? '>=' : '>', value: boundary };
+    }
+    return { operator: include ? '<=' : '<', value: boundary };
+}
+/**
+ * Adds `column >= :periodFrom` and `column <= :periodTo` conditions (or their exclusive versions) with
+ * AND, so the filter narrows whatever WHERE conditions the query already has, OR ones included:
+ * `(a OR b) AND column >= …`. `column` is already quoted.
+ */
+function attachPeriodFilter(builder, column, periodFilter, options) {
+    const { includeFrom = true, includeTo = true } = options !== null && options !== void 0 ? options : {};
+    const bounds = [
+        { name: 'periodFrom', include: includeFrom },
+        { name: 'periodTo', include: includeTo },
+    ];
+    for (const { name, include } of bounds) {
+        const boundary = normalizeBoundary(periodFilter === null || periodFilter === void 0 ? void 0 : periodFilter[name], name);
+        if (boundary === undefined) {
+            continue;
+        }
+        const { operator, value } = getBoundCondition(boundary, name, include);
+        const paramName = (0, sql_utils_1.createUniqueParameterName)(name);
+        (0, where_utils_1.andWhereNarrowing)(builder, `${column} ${operator} :${paramName}`, { [paramName]: value });
+    }
+    return builder;
+}
+exports.attachPeriodFilter = attachPeriodFilter;

package/dist/utils/proxy-key.utils.d.ts

@@ -3,7 +3,7 @@ import { KeyProxyCallback } from '../types/modules/proxy-callback.types';
 export declare class KeyHolder {
     private _keys;
     constructor(_keys?: string[]);
-    toSql(length?: number, useDoubleQuotes?: boolean): string;
+    toSql(length?: number, useQuotes?: boolean): string;
     toString(length?: number): string;
     valueOf(): string;
     [Symbol.toPrimitive](): string;
@@ -19,6 +19,17 @@ export declare class KeyProxy {
     static defaultHandler: ProxyHandler<KeyHolder>;
     static create<T extends ObjectLiteral>(): T;
 }
+/** Typed keys are `column` or `alias.column`: a deeper path can't be mapped to a query alias. */
+export declare const MAX_KEY_DEPTH = 2;
 export declare const getKeyHolder: <Type extends ObjectLiteral>(callback: KeyHolder | KeyProxyCallback<Type>) => KeyHolder | Array<KeyHolder>;
 export declare const getKey: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>) => string;
-export declare const getSqlKeyFromProxyCallback: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>, addPrefix?: string, useDoubleQuotes?: boolean) => string | string[];
+/**
+ * Alias to prefix a single-level key with: a string, or a function called only when it is needed,
+ * e.g. `() => query.alias`, which throws while the query has no main alias (before `from()`).
+ */
+export type KeyPrefix = string | (() => string | undefined);
+/**
+ * SQL key of a typed callback: `(u) => u.id` → `prefix.id`, `(u) => u.images.url` → `images.url`
+ * (an `alias.column` path keeps its own alias). Strings are returned as is.
+ */
+export declare const getSqlKeyFromProxyCallback: <Type extends ObjectLiteral>(callback: string | KeyHolder | KeyProxyCallback<Type>, addPrefix?: KeyPrefix, useQuotes?: boolean) => string | string[];

package/dist/utils/proxy-key.utils.js

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSqlKeyFromProxyCallback = exports.getKey = exports.getKeyHolder = exports.KeyProxy = exports.TypedProxy = exports.KeyHolder = void 0;
+exports.getSqlKeyFromProxyCallback = exports.getKey = exports.getKeyHolder = exports.MAX_KEY_DEPTH = exports.KeyProxy = exports.TypedProxy = exports.KeyHolder = void 0;
 const sql_utils_1 = require("./sql.utils");
 class KeyHolder {
     constructor(_keys = []) {
         this._keys = _keys;
         this._keys = [..._keys];
     }
-    toSql(length = 2, useDoubleQuotes) {
+    toSql(length = 2, useQuotes) {
         const string = this.toString(length);
-        const sql = useDoubleQuotes ? (0, sql_utils_1.stringToSQLIdentifier)(string) : string;
+        const sql = useQuotes ? (0, sql_utils_1.stringToSQLIdentifier)(string) : string;
         return sql;
     }
     toString(length = 2) {
@@ -69,14 +69,26 @@ KeyProxy.defaultHandler = {
         return newLayer;
     },
 };
+/** Typed keys are `column` or `alias.column`: a deeper path can't be mapped to a query alias. */
+exports.MAX_KEY_DEPTH = 2;
+const assertKeyDepth = (keyHolder) => {
+    const keys = keyHolder.getKeys();
+    if (keys.length > exports.MAX_KEY_DEPTH) {
+        throw new TypeError(`Typed key "${keys.join('.')}" is ${keys.length} levels deep, but typed methods support only ` +
+            `"column" or "alias.column". Join the nested relation and address it by its alias ` +
+            `with an alias-keyed type, e.g. type Joins = { someAlias: SomeEntity }; (j) => j.someAlias.column`);
+    }
+    return keyHolder;
+};
 const getKeyHolder = (callback) => {
     if (typeof callback !== 'function') {
         if (callback instanceof KeyHolder) {
-            return callback;
+            return assertKeyDepth(callback);
         }
     }
     const keyHolder = callback(KeyProxy.create());
-    return keyHolder;
+    // fail loudly instead of silently dropping levels beyond `alias.column`
+    return Array.isArray(keyHolder) ? keyHolder.map(assertKeyDepth) : assertKeyDepth(keyHolder);
 };
 exports.getKeyHolder = getKeyHolder;
 const getKey = (callback) => {
@@ -86,26 +98,32 @@ const getKey = (callback) => {
     return keyHolder.toString();
 };
 exports.getKey = getKey;
-const getSqlKeyFromProxyCallback = (callback, addPrefix, useDoubleQuotes) => {
+/**
+ * SQL key of a typed callback: `(u) => u.id` → `prefix.id`, `(u) => u.images.url` → `images.url`
+ * (an `alias.column` path keeps its own alias). Strings are returned as is.
+ */
+const getSqlKeyFromProxyCallback = (callback, addPrefix, useQuotes) => {
     if (typeof callback === 'string')
         return callback;
     const keyHolder = (0, exports.getKeyHolder)(callback);
     if (Array.isArray(keyHolder)) {
-        return keyHolder.map((holder) => (0, exports.getSqlKeyFromProxyCallback)(holder, addPrefix));
+        return keyHolder.map((holder) => (0, exports.getSqlKeyFromProxyCallback)(holder, addPrefix, useQuotes));
     }
     // if select is like this: (proxy) => proxy.relation.column
     if (keyHolder.getKeys().length > 1) {
         // return unchanged
-        return keyHolder.toSql(undefined, useDoubleQuotes);
+        return keyHolder.toSql(undefined, useQuotes);
     }
     // else if select is one layer depth like this: (proxy) => proxy.column
-    // then add alias before the key
-    if (typeof addPrefix === 'string' && addPrefix.length >= 1) {
-        keyHolder.unshift(addPrefix);
+    // then add alias before the key; resolve the alias only now, a path above doesn't need it
+    const prefix = typeof addPrefix === 'function' ? addPrefix() : addPrefix;
+    if (typeof prefix === 'string' && prefix.length >= 1) {
+        // a new holder: a KeyHolder passed in by the caller must stay as it was
+        return new KeyHolder([prefix, ...keyHolder.getKeys()]).toSql(undefined, useQuotes);
     }
-    return keyHolder.toSql(undefined, useDoubleQuotes);
+    return keyHolder.toSql(undefined, useQuotes);
 };
 exports.getSqlKeyFromProxyCallback = getSqlKeyFromProxyCallback;
 // example of typed select
-// const key = getSqlKey<UserEntity>((proxy) => proxy.sessions);
-// console.log(key);
+// const key = getKey<UserEntity>((proxy) => proxy.sessions);
+// console.log(key); // "sessions"

package/dist/utils/query-builder.utils.d.ts

@@ -0,0 +1,46 @@
+import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
+import type { KeyProxyCallback } from '../types/modules/proxy-callback.types';
+/**
+ * Database name of an entity property's column (`@Column({ name })`), looked up in the metadata of
+ * a query alias (the main alias when `aliasName` is undefined). `undefined` when the alias has no
+ * entity or the property isn't a column.
+ */
+export declare function getColumnDatabaseName(builder: WhereExpressionBuilder, aliasName: string | undefined, propertyPath: string): string | undefined;
+/**
+ * SQL for a field passed as a string to the untyped methods (`whereIsIn('user.first-name', …)`).
+ *
+ * A string can't tell a column from an expression: `user.first-name` may be the column `first-name`
+ * or `user.first` minus `name`. The query builder knows its aliases and their entities, though:
+ * - `alias.column`, where `alias` is an alias of the query and `column` one of its entity's columns
+ *   (by database name or property path): the column, quoted by the driver, `"user"."first-name"`.
+ *   Property paths are mapped to their columns (`user.createdAt` → `"user"."created_at"`).
+ *   UPDATE / DELETE give the bare column, as they have no alias.
+ * - `column`, a database column name of the main entity: the quoted column, `"first-name"`. Property
+ *   names aren't mapped without an alias, as `status` may also be a column of a joined table.
+ * - anything else (unknown aliases, subqueries, expressions such as `LOWER(u.email)` or
+ *   `u.price - u.discount`): quoted only when it is a path of plain identifiers, as
+ *   `stringToSQLIdentifier` does, in the driver's quotes.
+ */
+export declare function toFieldSql(builder: WhereExpressionBuilder, field: string): string;
+/**
+ * SQL key for a typed callback on `builder`: `"alias"."column"`, or `"column"` on UPDATE / DELETE.
+ *
+ * The property is mapped to its database column name (`@Column({ name })`, embedded columns)
+ * through the metadata of the alias it belongs to (see `resolveTypedKey`). Aliases without
+ * metadata (subqueries) and unknown properties keep the property name.
+ */
+export declare function getTypedColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>): string | string[];
+/**
+ * Quoted column of a typed callback that must select exactly one column
+ * (`whereIsAnyTyped`, `whereArrayContainsTyped`, …). Throws a `TypeError` for several columns:
+ * one condition per column has no single obvious meaning (AND? OR?), so don't guess.
+ */
+export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>, methodName: string): string;
+/**
+ * Key for typed select / order / distinct on a SelectQueryBuilder.
+ *
+ * Without quotes it is `alias.propertyPath` (`user.name`, `images.url`, `p.address.city`),
+ * which TypeORM maps to the column itself. With `useQuotes` it is the quoted database column
+ * (`"t"."ticket_status"`), since TypeORM doesn't map quoted keys. Strings are kept as is.
+ */
+export declare function getTypedSelectionKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, selection: KeyProxyCallback<Type> | string, useQuotes?: boolean): string | string[];

package/dist/utils/query-builder.utils.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.getTypedColumnKey = exports.toFieldSql = exports.getColumnDatabaseName = void 0;
+const proxy_key_utils_1 = require("./proxy-key.utils");
+const sql_utils_1 = require("./sql.utils");
+/**
+ * Whether single-level typed keys are qualified with the main alias (`user.firstName`).
+ *
+ * UPDATE / DELETE builders turn alias prefixing off (`aliasNamePrefixingEnabled === false`)
+ * and render `UPDATE "users" … WHERE …` without an alias, where `"UserEntity"."firstName"`
+ * is invalid: their keys are just the column, `"firstName"`.
+ */
+function isAliasPrefixingEnabled(queryBuilder) {
+    var _a;
+    return ((_a = queryBuilder.expressionMap) === null || _a === void 0 ? void 0 : _a.aliasNamePrefixingEnabled) !== false;
+}
+/**
+ * Main alias of the query for the single-level key `key`. A query created without an entity
+ * (`dataSource.createQueryBuilder()`, `qb.subQuery()`) has none until `from()`: throw a
+ * `TypeError` that says how to fix the call, instead of TypeORM's "Main alias is not set".
+ */
+function requireMainAliasName(queryBuilder, key) {
+    var _a;
+    const mainAlias = (_a = queryBuilder.expressionMap) === null || _a === void 0 ? void 0 : _a.mainAlias;
+    if (!mainAlias) {
+        throw new TypeError(`Typed key "${key}" has no alias and the query has no main alias yet. ` +
+            `Call from() before this method, or address the column by its alias with an alias-keyed type: ` +
+            `type Q = { someAlias: SomeEntity }; (q) => q.someAlias.${key}`);
+    }
+    return mainAlias.name;
+}
+/** Entity metadata of a query alias (the main alias when `aliasName` is undefined), if it has any. */
+function getAliasMetadata(queryBuilder, aliasName) {
+    const expressionMap = queryBuilder.expressionMap;
+    const alias = aliasName === undefined
+        ? expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.mainAlias
+        : expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.aliases.find((queryAlias) => queryAlias.name === aliasName);
+    return (alias === null || alias === void 0 ? void 0 : alias.hasMetadata) ? alias.metadata : undefined;
+}
+/**
+ * Database name of an entity property's column (`@Column({ name })`), looked up in the metadata of
+ * a query alias (the main alias when `aliasName` is undefined). `undefined` when the alias has no
+ * entity or the property isn't a column.
+ */
+function getColumnDatabaseName(builder, aliasName, propertyPath) {
+    var _a;
+    const metadata = getAliasMetadata(builder, aliasName);
+    return (_a = metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath)) === null || _a === void 0 ? void 0 : _a.databaseName;
+}
+exports.getColumnDatabaseName = getColumnDatabaseName;
+/** A column of the entity by its database name (`first-name`) or its property path (`firstName`, `address.city`). */
+function findColumn(metadata, name) {
+    var _a;
+    return ((_a = metadata.columns.find((column) => column.databaseName === name)) !== null && _a !== void 0 ? _a : metadata.findColumnWithPropertyPath(name));
+}
+/**
+ * SQL for a field passed as a string to the untyped methods (`whereIsIn('user.first-name', …)`).
+ *
+ * A string can't tell a column from an expression: `user.first-name` may be the column `first-name`
+ * or `user.first` minus `name`. The query builder knows its aliases and their entities, though:
+ * - `alias.column`, where `alias` is an alias of the query and `column` one of its entity's columns
+ *   (by database name or property path): the column, quoted by the driver, `"user"."first-name"`.
+ *   Property paths are mapped to their columns (`user.createdAt` → `"user"."created_at"`).
+ *   UPDATE / DELETE give the bare column, as they have no alias.
+ * - `column`, a database column name of the main entity: the quoted column, `"first-name"`. Property
+ *   names aren't mapped without an alias, as `status` may also be a column of a joined table.
+ * - anything else (unknown aliases, subqueries, expressions such as `LOWER(u.email)` or
+ *   `u.price - u.discount`): quoted only when it is a path of plain identifiers, as
+ *   `stringToSQLIdentifier` does, in the driver's quotes.
+ */
+function toFieldSql(builder, field) {
+    var _a;
+    const queryBuilder = builder;
+    const dot = field.indexOf('.');
+    if (dot > 0) {
+        const aliasName = field.slice(0, dot);
+        const metadata = ((_a = queryBuilder.expressionMap) === null || _a === void 0 ? void 0 : _a.aliases.some((alias) => alias.name === aliasName))
+            ? getAliasMetadata(queryBuilder, aliasName)
+            : undefined;
+        const column = metadata && findColumn(metadata, field.slice(dot + 1));
+        if (column) {
+            const columnSql = queryBuilder.escape(column.databaseName);
+            return isAliasPrefixingEnabled(queryBuilder) ? `${queryBuilder.escape(aliasName)}.${columnSql}` : columnSql;
+        }
+    }
+    else {
+        // only by database name: an unqualified property name may mean another table's column
+        const metadata = getAliasMetadata(queryBuilder, undefined);
+        const column = metadata === null || metadata === void 0 ? void 0 : metadata.columns.find((candidate) => candidate.databaseName === field);
+        if (column) {
+            return queryBuilder.escape(column.databaseName);
+        }
+    }
+    return (0, sql_utils_1.stringToSQLIdentifier)(field, (0, sql_utils_1.getDriverType)(builder));
+}
+exports.toFieldSql = toFieldSql;
+/**
+ * Splits typed keys into the alias and the property path they refer to:
+ * - `t => t.status` → the query's main alias + `status` (no alias on UPDATE / DELETE);
+ * - `j => j.t.status`, `u => u.images.url` → the first key, when it is an alias of the query;
+ * - `p => p.address.city` → when the first key isn't an alias but the main entity has a column
+ *   with that path (an embedded entity), the main alias + `address.city`;
+ * - anything else → the first key as the alias (an alias the query builder doesn't know yet,
+ *   e.g. `q => q.base.chatRoomId` before `.from(…, 'base')`).
+ *
+ * Only single-level keys need the main alias, so `alias.column` keys work before `from()`.
+ * Their column names can be mapped only through aliases already known to the query, though:
+ * before `from()` the property name is used as the column name.
+ */
+function resolveTypedKey(queryBuilder, keys) {
+    const prefixing = isAliasPrefixingEnabled(queryBuilder);
+    if (keys.length === 1) {
+        const aliasName = prefixing ? requireMainAliasName(queryBuilder, keys[0]) : undefined;
+        return {
+            aliasName,
+            propertyPath: keys[0],
+            metadata: getAliasMetadata(queryBuilder, aliasName),
+        };
+    }
+    const [firstKey, ...restKeys] = keys;
+    const expressionMap = queryBuilder.expressionMap;
+    const mainAlias = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.mainAlias;
+    // UPDATE / DELETE have no alias to qualify with: `u => u.user.firstName` is `"firstName"` there
+    if (!prefixing && (mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.name) === firstKey) {
+        return {
+            aliasName: undefined,
+            propertyPath: restKeys.join('.'),
+            metadata: getAliasMetadata(queryBuilder, undefined),
+        };
+    }
+    const queryAlias = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.aliases.find((alias) => alias.name === firstKey);
+    if (!queryAlias && mainAlias) {
+        const mainMetadata = getAliasMetadata(queryBuilder, undefined);
+        const embeddedPath = keys.join('.');
+        if (mainMetadata === null || mainMetadata === void 0 ? void 0 : mainMetadata.findColumnWithPropertyPath(embeddedPath)) {
+            return {
+                aliasName: prefixing ? mainAlias.name : undefined,
+                propertyPath: embeddedPath,
+                metadata: mainMetadata,
+            };
+        }
+    }
+    return {
+        aliasName: firstKey,
+        propertyPath: restKeys.join('.'),
+        metadata: (queryAlias === null || queryAlias === void 0 ? void 0 : queryAlias.hasMetadata) ? queryAlias.metadata : undefined,
+    };
+}
+/** `"alias"."column"` (or `"column"` without an alias) with the database column name. */
+function toQuotedColumnKey(queryBuilder, { aliasName, propertyPath, metadata }) {
+    var _a, _b;
+    const column = (_b = (_a = metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath)) === null || _a === void 0 ? void 0 : _a.databaseName) !== null && _b !== void 0 ? _b : propertyPath;
+    return aliasName === undefined
+        ? queryBuilder.escape(column)
+        : `${queryBuilder.escape(aliasName)}.${queryBuilder.escape(column)}`;
+}
+/**
+ * SQL key for a typed callback on `builder`: `"alias"."column"`, or `"column"` on UPDATE / DELETE.
+ *
+ * The property is mapped to its database column name (`@Column({ name })`, embedded columns)
+ * through the metadata of the alias it belongs to (see `resolveTypedKey`). Aliases without
+ * metadata (subqueries) and unknown properties keep the property name.
+ */
+function getTypedColumnKey(builder, callback) {
+    const queryBuilder = builder;
+    const toKey = (keyHolder) => toQuotedColumnKey(queryBuilder, resolveTypedKey(queryBuilder, keyHolder.getKeys()));
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback);
+    return Array.isArray(keyHolder) ? keyHolder.map(toKey) : toKey(keyHolder);
+}
+exports.getTypedColumnKey = getTypedColumnKey;
+/**
+ * Quoted column of a typed callback that must select exactly one column
+ * (`whereIsAnyTyped`, `whereArrayContainsTyped`, …). Throws a `TypeError` for several columns:
+ * one condition per column has no single obvious meaning (AND? OR?), so don't guess.
+ */
+function getTypedSingleColumnKey(builder, callback, methodName) {
+    const key = getTypedColumnKey(builder, callback);
+    if (Array.isArray(key)) {
+        throw new TypeError(`${methodName} expects the callback to select a single column, got ${key.length}: ${key.join(', ')}`);
+    }
+    return key;
+}
+exports.getTypedSingleColumnKey = getTypedSingleColumnKey;
+/**
+ * Key for typed select / order / distinct on a SelectQueryBuilder.
+ *
+ * Without quotes it is `alias.propertyPath` (`user.name`, `images.url`, `p.address.city`),
+ * which TypeORM maps to the column itself. With `useQuotes` it is the quoted database column
+ * (`"t"."ticket_status"`), since TypeORM doesn't map quoted keys. Strings are kept as is.
+ */
+function getTypedSelectionKey(builder, selection, useQuotes) {
+    if (typeof selection === 'string') {
+        return selection;
+    }
+    const queryBuilder = builder;
+    const toKey = (keyHolder) => {
+        const resolved = resolveTypedKey(queryBuilder, keyHolder.getKeys());
+        if (useQuotes) {
+            return toQuotedColumnKey(queryBuilder, resolved);
+        }
+        return resolved.aliasName === undefined
+            ? resolved.propertyPath
+            : `${resolved.aliasName}.${resolved.propertyPath}`;
+    };
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(selection);
+    return Array.isArray(keyHolder) ? keyHolder.map(toKey) : toKey(keyHolder);
+}
+exports.getTypedSelectionKey = getTypedSelectionKey;

package/dist/utils/search.utils.d.ts

@@ -0,0 +1,27 @@
+import type { DatabaseType } from 'typeorm';
+import type { LikeMatch } from '../types/extensions/search.types';
+/**
+ * Escapes the LIKE wildcards `%` and `_`, and the escape character `\` itself, with a backslash:
+ * `50%_off` → `50\%\_off`. The default escape character of PostgreSQL and MySQL;
+ * SQLite needs `ESCAPE '\'`, which the search methods add.
+ */
+export declare function escapeLikePattern(value: string): string;
+/** LIKE pattern for `value`: `%value%`, `value%`, `%value` or `value`. */
+export declare function toLikePattern(value: string, match?: LikeMatch, escape?: boolean): string;
+/**
+ * Trimmed search term, or `undefined` when there is nothing to search for (`null`, `undefined`,
+ * an empty or blank string): search methods add no condition then.
+ */
+export declare function toSearchTerm(value: unknown, methodName: string): string | undefined;
+/** Function to wrap both sides with for `unaccent`, or `undefined` for none. */
+export declare function toUnaccentFunction(unaccent: boolean | string | undefined): string | undefined;
+/**
+ * Case-insensitive LIKE of `column` against `parameter` in the syntax of the database:
+ * - PostgreSQL (and any other driver): `column ILIKE :p`, which `gin_trgm_ops` indexes support;
+ * - MySQL / MariaDB: `column LIKE :p`, case-insensitive with the default `_ci` collations;
+ * - SQLite: `column LIKE :p ESCAPE '\'`, case-insensitive for ASCII; SQLite has no default
+ *   escape character.
+ *
+ * With `unaccentFunction`, both sides are wrapped with it: `unaccent(column) ILIKE unaccent(:p)`.
+ */
+export declare function buildILikeCondition(driver: DatabaseType | undefined, column: string, parameter: string, unaccentFunction?: string): string;

package/dist/utils/search.utils.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildILikeCondition = exports.toUnaccentFunction = exports.toSearchTerm = exports.toLikePattern = exports.escapeLikePattern = void 0;
+const sql_utils_1 = require("./sql.utils");
+/**
+ * Escapes the LIKE wildcards `%` and `_`, and the escape character `\` itself, with a backslash:
+ * `50%_off` → `50\%\_off`. The default escape character of PostgreSQL and MySQL;
+ * SQLite needs `ESCAPE '\'`, which the search methods add.
+ */
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, '\\$&');
+}
+exports.escapeLikePattern = escapeLikePattern;
+/** LIKE pattern for `value`: `%value%`, `value%`, `%value` or `value`. */
+function toLikePattern(value, match = 'contains', escape = true) {
+    const text = escape ? escapeLikePattern(value) : value;
+    switch (match) {
+        case 'contains':
+            return `%${text}%`;
+        case 'prefix':
+            return `${text}%`;
+        case 'suffix':
+            return `%${text}`;
+        case 'exact':
+            return text;
+        default:
+            throw new TypeError(`Invalid match "${match}": expected "contains", "prefix", "suffix" or "exact"`);
+    }
+}
+exports.toLikePattern = toLikePattern;
+/**
+ * Trimmed search term, or `undefined` when there is nothing to search for (`null`, `undefined`,
+ * an empty or blank string): search methods add no condition then.
+ */
+function toSearchTerm(value, methodName) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new TypeError(`${methodName} expects a string to search for, got ${typeof value}`);
+    }
+    const term = value.trim();
+    return term.length > 0 ? term : undefined;
+}
+exports.toSearchTerm = toSearchTerm;
+// `unaccent`, `public.f_unaccent`: a function name, optionally schema-qualified
+const FUNCTION_NAME = /^[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)?$/;
+/** Function to wrap both sides with for `unaccent`, or `undefined` for none. */
+function toUnaccentFunction(unaccent) {
+    if (unaccent === undefined || unaccent === false) {
+        return undefined;
+    }
+    if (unaccent === true) {
+        return 'unaccent';
+    }
+    if (typeof unaccent !== 'string' || !FUNCTION_NAME.test(unaccent)) {
+        // the name is inserted into the SQL as is
+        throw new TypeError(`Invalid unaccent function "${unaccent}": expected a function name like "unaccent"`);
+    }
+    return unaccent;
+}
+exports.toUnaccentFunction = toUnaccentFunction;
+/**
+ * Case-insensitive LIKE of `column` against `parameter` in the syntax of the database:
+ * - PostgreSQL (and any other driver): `column ILIKE :p`, which `gin_trgm_ops` indexes support;
+ * - MySQL / MariaDB: `column LIKE :p`, case-insensitive with the default `_ci` collations;
+ * - SQLite: `column LIKE :p ESCAPE '\'`, case-insensitive for ASCII; SQLite has no default
+ *   escape character.
+ *
+ * With `unaccentFunction`, both sides are wrapped with it: `unaccent(column) ILIKE unaccent(:p)`.
+ */
+function buildILikeCondition(driver, column, parameter, unaccentFunction) {
+    const left = unaccentFunction ? `${unaccentFunction}(${column})` : column;
+    const right = unaccentFunction ? `${unaccentFunction}(${parameter})` : parameter;
+    if ((0, sql_utils_1.isMysqlLikeDriver)(driver)) {
+        return `${left} LIKE ${right}`;
+    }
+    if ((0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        return `${left} LIKE ${right} ESCAPE '\\'`;
+    }
+    return `${left} ILIKE ${right}`;
+}
+exports.buildILikeCondition = buildILikeCondition;

package/dist/utils/sql.utils.d.ts

@@ -1,6 +1,32 @@
-import { DatabaseType } from 'typeorm';
+import type { DatabaseType, WhereExpressionBuilder } from 'typeorm';
 export declare const wrapWithDoubleQoutes: (str: string) => string;
 export declare const wrapWithBackQoutes: (str: string) => string;
+/** MySQL, MariaDB and Aurora MySQL: backtick identifiers, `<=>` null-safe comparison. */
+export declare const isMysqlLikeDriver: (driver?: DatabaseType) => boolean;
+/** SQLite drivers: `IS` / `IS NOT` are null-safe comparisons. */
+export declare const isSqliteLikeDriver: (driver?: DatabaseType) => boolean;
+/** Database type of the query builder's connection, e.g. `'postgres'`; undefined without one. */
+export declare function getDriverType(builder: WhereExpressionBuilder): DatabaseType | undefined;
+/**
+ * Quotes one identifier, whatever characters it has: `first-name` → `"first-name"`, a `"` inside is
+ * doubled. An already quoted identifier is kept. For names known to be identifiers (columns, aliases).
+ */
+export declare const quoteIdentifier: (name: string, driver?: DatabaseType) => string;
+/**
+ * Quotes an alias or a table: as a path when it is one (`schema.table` → `"schema"."table"`),
+ * otherwise as one identifier (`user-1` → `"user-1"`).
+ */
+export declare const quoteIdentifierPath: (path: string, driver?: DatabaseType) => string;
+/**
+ * Quotes an identifier path: `user.id` → `"user"."id"`, `user.*` → `"user".*`.
+ * Already quoted segments are kept. Anything that isn't a path of identifiers
+ * (`COALESCE(a.x, b.x)`, `LOWER(u.email)`, `u.id::text`, `*`) is returned as is.
+ */
 export declare const stringToSQLIdentifier: (str: string, driver?: DatabaseType) => string;
 export declare const stringToSQLValue: (str: string) => string;
 export declare const createUniqueParameterName: (prefix?: string) => string;
+/**
+ * Returns `arrayType` if it is a type name (`uuid[]`, `public.order_status[]`, `varchar(36)[]`),
+ * throws a `TypeError` otherwise: the type is inserted into the SQL as is.
+ */
+export declare function assertArrayType(arrayType: string): string;