typeorm-extensions 1.3.5 → 2.1.0

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

@@ -0,0 +1,257 @@
+"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 json_path_utils_1 = require("./json-path.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;
+/**
+ * The column that `keys` name in an entity: the longest prefix of the keys that is a column's property path
+ * (`address.city` for an embedded entity). The keys after it are a path inside the column, allowed only in a
+ * JSON column (`details` + `['meta', 'endTs']`). `undefined` when no prefix is a column, or a column that isn't
+ * JSON is followed by more keys (a relation's join column, `user` in `user.email`).
+ */
+function findColumnPath(metadata, keys) {
+    for (let length = keys.length; metadata && length >= 1; length--) {
+        const propertyPath = keys.slice(0, length).join('.');
+        const column = metadata.findColumnWithPropertyPath(propertyPath);
+        if (!column) {
+            continue;
+        }
+        if (length === keys.length) {
+            return { propertyPath, column };
+        }
+        return (0, json_path_utils_1.isJsonColumn)(column) ? { propertyPath, column, jsonPath: keys.slice(length) } : undefined;
+    }
+    return undefined;
+}
+/**
+ * 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`;
+ * - `e => e.details.meta.endTs`, `j => j.e.details.outcome` → a JSON column of the alias' entity
+ *   followed by the keys inside it (`jsonPath`), at any depth;
+ * - 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 resolved = resolveTypedKeyPath(queryBuilder, keys);
+    // deeper than `alias.column` only inside a JSON column: a nested relation can't be mapped to an alias
+    if (!resolved.jsonPath && keys.length > proxy_key_utils_1.MAX_KEY_DEPTH) {
+        throw (0, proxy_key_utils_1.createKeyTooDeepError)(keys);
+    }
+    return resolved;
+}
+function resolveTypedKeyPath(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) {
+        const metadata = getAliasMetadata(queryBuilder, undefined);
+        return {
+            aliasName: undefined,
+            propertyPath: restKeys.join('.'),
+            metadata,
+            ...findColumnPath(metadata, restKeys),
+        };
+    }
+    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 columnPath = findColumnPath(mainMetadata, keys);
+        if (columnPath) {
+            return {
+                aliasName: prefixing ? mainAlias.name : undefined,
+                metadata: mainMetadata,
+                ...columnPath,
+            };
+        }
+    }
+    const metadata = (queryAlias === null || queryAlias === void 0 ? void 0 : queryAlias.hasMetadata) ? queryAlias.metadata : undefined;
+    return {
+        aliasName: firstKey,
+        propertyPath: restKeys.join('.'),
+        metadata,
+        ...findColumnPath(metadata, restKeys),
+    };
+}
+/**
+ * `"alias"."column"` (or `"column"` without an alias) with the database column name, followed by the path
+ * inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'` (see `toJsonPathSql`).
+ */
+function toQuotedColumnKey(queryBuilder, { aliasName, propertyPath, metadata, column, jsonPath }, jsonOptions) {
+    var _a, _b;
+    const columnName = (_b = (_a = (column !== null && column !== void 0 ? column : metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath))) === null || _a === void 0 ? void 0 : _a.databaseName) !== null && _b !== void 0 ? _b : propertyPath;
+    const columnSql = aliasName === undefined
+        ? queryBuilder.escape(columnName)
+        : `${queryBuilder.escape(aliasName)}.${queryBuilder.escape(columnName)}`;
+    if (!column || !jsonPath) {
+        return columnSql;
+    }
+    const driver = (0, sql_utils_1.getDriverType)(queryBuilder);
+    return (0, json_path_utils_1.toJsonPathSql)(driver, columnSql, column, jsonPath, jsonOptions);
+}
+/**
+ * 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. A path into a JSON column
+ * gives its JSON accessor, cast on PostgreSQL to the type of `jsonOptions.value`.
+ */
+function getTypedColumnKey(builder, callback, jsonOptions) {
+    const queryBuilder = builder;
+    const toKey = (keyHolder) => toQuotedColumnKey(queryBuilder, resolveTypedKey(queryBuilder, keyHolder.getKeys()), jsonOptions);
+    // the depth is checked against the query's metadata, where a JSON column may be deeper
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback, true);
+    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, jsonOptions) {
+    const key = getTypedColumnKey(builder, callback, jsonOptions);
+    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 (resolved.jsonPath) {
+            throw new TypeError(`Typed key "${keyHolder.getKeys().join('.')}" points into the JSON column "${resolved.propertyPath}": ` +
+                `select, order and distinct take columns only. For an expression use tableHelper().jsonColumn()`);
+        }
+        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,34 @@
-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;
+/** PostgreSQL and the databases speaking its dialect. */
+export declare const isPostgresLikeDriver: (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;

package/dist/utils/sql.utils.js

@@ -1,19 +1,85 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.wrapWithBackQoutes = exports.wrapWithDoubleQoutes = void 0;
+exports.assertArrayType = exports.createUniqueParameterName = exports.stringToSQLValue = exports.stringToSQLIdentifier = exports.quoteIdentifierPath = exports.quoteIdentifier = exports.getDriverType = exports.isSqliteLikeDriver = exports.isPostgresLikeDriver = exports.isMysqlLikeDriver = exports.wrapWithBackQoutes = exports.wrapWithDoubleQoutes = void 0;
 const common_utils_1 = require("./common.utils");
 const wrapWithDoubleQoutes = (str) => str.includes('"') ? str : `"${str}"`;
 exports.wrapWithDoubleQoutes = wrapWithDoubleQoutes;
 const wrapWithBackQoutes = (str) => str.includes('`') ? str : '`' + str + '`';
 exports.wrapWithBackQoutes = wrapWithBackQoutes;
-const stringToSQLIdentifier = (str, driver) => str.includes('.')
-    ? str
-        .split('.')
-        .map((val) => (driver === null || driver === void 0 ? void 0 : driver.includes('mysql'))
-        ? (0, exports.wrapWithBackQoutes)(val)
-        : (0, exports.wrapWithDoubleQoutes)(val))
-        .join('.')
-    : (0, exports.wrapWithDoubleQoutes)(str);
+const BACKTICK = '`';
+// one identifier: unquoted (user, firstName) or already quoted ("user", `user`, "a""b")
+const UNQUOTED_IDENTIFIER = '[\\p{L}_][\\p{L}\\p{N}_$]*';
+const DOUBLE_QUOTED_IDENTIFIER = '"(?:[^"]|"")+"';
+const BACK_QUOTED_IDENTIFIER = `${BACKTICK}(?:[^${BACKTICK}]|${BACKTICK}${BACKTICK})+${BACKTICK}`;
+const IDENTIFIER = `(?:${UNQUOTED_IDENTIFIER}|${DOUBLE_QUOTED_IDENTIFIER}|${BACK_QUOTED_IDENTIFIER})`;
+// `id`, `user.id`, `"user"."id"`, `schema.table.column`, optionally ending with `.*`
+const IDENTIFIER_PATH = new RegExp(`^${IDENTIFIER}(?:\\.${IDENTIFIER})*(?:\\.\\*)?$`, 'u');
+const IDENTIFIER_PATH_SEGMENT = new RegExp(`${IDENTIFIER}|\\*`, 'gu');
+/** MySQL, MariaDB and Aurora MySQL: backtick identifiers, `<=>` null-safe comparison. */
+const isMysqlLikeDriver = (driver) => driver === 'mysql' || driver === 'mariadb' || driver === 'aurora-mysql';
+exports.isMysqlLikeDriver = isMysqlLikeDriver;
+// `string[]`: TypeORM 1.0 removed the `sqlite` driver from `DatabaseType`, 0.3.x still has it
+const SQLITE_LIKE_DRIVERS = [
+    'sqlite',
+    'better-sqlite3',
+    'sqljs',
+    'capacitor',
+    'cordova',
+    'expo',
+    'nativescript',
+    'react-native',
+];
+const POSTGRES_LIKE_DRIVERS = ['postgres', 'aurora-postgres', 'cockroachdb'];
+/** PostgreSQL and the databases speaking its dialect. */
+const isPostgresLikeDriver = (driver) => driver !== undefined && POSTGRES_LIKE_DRIVERS.includes(driver);
+exports.isPostgresLikeDriver = isPostgresLikeDriver;
+/** SQLite drivers: `IS` / `IS NOT` are null-safe comparisons. */
+const isSqliteLikeDriver = (driver) => driver !== undefined && SQLITE_LIKE_DRIVERS.includes(driver);
+exports.isSqliteLikeDriver = isSqliteLikeDriver;
+/** Database type of the query builder's connection, e.g. `'postgres'`; undefined without one. */
+function getDriverType(builder) {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = builder.connection) === null || _a === void 0 ? void 0 : _a.driver) === null || _b === void 0 ? void 0 : _b.options) === null || _c === void 0 ? void 0 : _c.type;
+}
+exports.getDriverType = getDriverType;
+/**
+ * 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).
+ */
+const quoteIdentifier = (name, driver) => {
+    const mysql = (0, exports.isMysqlLikeDriver)(driver);
+    const quote = mysql ? BACKTICK : '"';
+    if (name.length >= 2 && name.startsWith(quote) && name.endsWith(quote)) {
+        return name;
+    }
+    return `${quote}${name.split(quote).join(quote + quote)}${quote}`;
+};
+exports.quoteIdentifier = quoteIdentifier;
+/**
+ * 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"`).
+ */
+const quoteIdentifierPath = (path, driver) => IDENTIFIER_PATH.test(path) ? (0, exports.stringToSQLIdentifier)(path, driver) : (0, exports.quoteIdentifier)(path, driver);
+exports.quoteIdentifierPath = quoteIdentifierPath;
+/**
+ * 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.
+ */
+const stringToSQLIdentifier = (str, driver) => {
+    var _a;
+    if (!IDENTIFIER_PATH.test(str)) {
+        return str;
+    }
+    const quote = (0, exports.isMysqlLikeDriver)(driver)
+        ? exports.wrapWithBackQoutes
+        : exports.wrapWithDoubleQoutes;
+    return ((_a = str.match(IDENTIFIER_PATH_SEGMENT)) !== null && _a !== void 0 ? _a : [])
+        .map((segment) => segment === '*' || segment.startsWith('"') || segment.startsWith(BACKTICK)
+        ? segment
+        : quote(segment))
+        .join('.');
+};
 exports.stringToSQLIdentifier = stringToSQLIdentifier;
 const stringToSQLValue = (str) => `'${str}'`;
 exports.stringToSQLValue = stringToSQLValue;
@@ -22,3 +88,19 @@ const createUniqueParameterName = (prefix) => {
     return `${prefix || 'param'}_${uniqueCode}`;
 };
 exports.createUniqueParameterName = createUniqueParameterName;
+// a type name, optionally schema-qualified, multi-word (`character varying`), with a
+// modifier (`varchar(255)`) and array brackets: `uuid[]`, `public.order_status[]`, `"MyEnum"[]`
+const TYPE_NAME_PART = '(?:[A-Za-z_][\\w$]*|"(?:[^"]|"")+")';
+const ARRAY_TYPE_PATTERN = new RegExp(`^${TYPE_NAME_PART}(?:\\.${TYPE_NAME_PART})*(?: ${TYPE_NAME_PART})*` +
+    `(?:\\(\\d+(?:, ?\\d+)?\\))?(?:\\[\\d*\\])*$`);
+/**
+ * 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.
+ */
+function assertArrayType(arrayType) {
+    if (typeof arrayType !== 'string' || !ARRAY_TYPE_PATTERN.test(arrayType)) {
+        throw new TypeError(`Invalid array type "${arrayType}": expected a type name like "uuid[]"`);
+    }
+    return arrayType;
+}
+exports.assertArrayType = assertArrayType;

package/dist/utils/table.utils.d.ts

@@ -0,0 +1,86 @@
+import { ObjectLiteral } from "typeorm";
+export type TableHelperOptions = {
+    useQuotes?: boolean;
+};
+type JsonFieldTuple<T, Depth extends 0[] = []> = Depth['length'] extends 4 ? [string, ...string[]] : {
+    [K in keyof T & string]: [NonNullable<T[K]>] extends [Record<string, unknown>] ? [K, ...JsonFieldTuple<NonNullable<T[K]>, [...Depth, 0]>] | [K] : [K];
+}[keyof T & string];
+export type TableHelperCountOptions = {
+    /** `COUNT(DISTINCT column)`: count the different values of the column. Needs a column. */
+    distinct?: boolean;
+    /** Count only the rows that match this condition, e.g. `t.where('status', "= 'active'")`. */
+    filter?: string;
+    /**
+     * How `filter` is written:
+     * - `'case'` (default): `COUNT(CASE WHEN filter THEN column END)`, in every database;
+     * - `'filter'`: `COUNT(column) FILTER (WHERE filter)`, PostgreSQL and SQLite 3.30+ only, a few percent faster on PostgreSQL.
+     */
+    syntax?: 'case' | 'filter';
+};
+export type JsonFieldRest<V> = [NonNullable<V>] extends [Record<string, unknown>] ? JsonFieldTuple<NonNullable<V>> : string[];
+/**
+ * Creates a type-safe SQL helper for building column references, WHERE expressions,
+ * JOIN clauses, and JSONB accessors for a given entity type.
+ *
+ * @example
+ * const t = tableHelper<UserEntity>('user');
+ * t.column('email')              // → "user"."email"
+ * t.where('id', '= :id')        // → "user"."id" = :id
+ * t.jsonColumn('metadata', '->>', 'role')  // → "user"."metadata" ->> 'role'
+ */
+export declare const tableHelper: <T extends ObjectLiteral>(alias?: string, options?: TableHelperOptions) => {
+    alias: string | undefined;
+    /**
+     * Returns a quoted SQL column identifier, e.g. `"alias"."column"`. The column is always quoted as one
+     * identifier, so names with other characters work too: `"user"."first-name"`.
+     */
+    column(columnName: keyof T, alias?: string): string;
+    /** Returns a column identifier optionally followed by an expression, e.g. `"user"."id" = :id`. */
+    where(columnName: keyof T, expression?: string): string;
+    /** Returns an unquoted join path, e.g. `user.images`. Needs the helper's alias, or `alias`. */
+    join(relation: keyof T, alias?: string): string;
+    /**
+     * Returns a column with a JOIN ON expression, e.g. `"user"."id" = "images"."userId"`.
+     * The expression is inserted as is: build its columns with another `tableHelper`
+     * (`t.joinOn('id', '= ' + images.column('userId'))`), since unquoted camelCase names
+     * like `images.userId` are folded to lowercase by PostgreSQL unless TypeORM rewrites them.
+     */
+    joinOn(thisColumn: keyof T, expression: string): string;
+    /** Returns `"alias"."column" IS NULL`. */
+    isNull(columnName: keyof T): string;
+    /** Returns `"alias"."column" IS NOT NULL`. */
+    isNotNull(columnName: keyof T): string;
+    /**
+     * Returns `CAST(COUNT("alias"."column") AS integer)`: the rows where the column isn't `NULL`.
+     * Without a column it is `COUNT(*)`, all the rows of the result, in every database. To count the rows
+     * of a table joined with LEFT JOIN, count one of its non-null columns: `images.count('id')`.
+     * @example
+     * t.count('email', { distinct: true })              // CAST(COUNT(DISTINCT "user"."email") AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'") })
+     * // CAST(COUNT(CASE WHEN "user"."status" = 'active' THEN 1 END) AS integer)
+     * t.count(undefined, { filter: t.where('status', "= 'active'"), syntax: 'filter' })
+     * // CAST(COUNT(*) FILTER (WHERE "user"."status" = 'active') AS integer)
+     */
+    count(columnName?: keyof T | undefined, countOptions?: TableHelperCountOptions): string;
+    /** Returns `CAST(expression AS type)`. */
+    cast(expression: string, type: string): string;
+    /**
+     * Returns a full JSONB column access expression.
+     * @example
+     * t.jsonColumn('metadata', '->>', 'role')             // → "user"."metadata" ->> 'role'
+     * t.jsonColumn('metadata', '->>', 'settings', 'theme') // → "user"."metadata" -> 'settings' ->> 'theme'
+     */
+    jsonColumn<K extends keyof T>(columnName: K, jsonOperator: '->>' | '->', ...fieldNames: JsonFieldRest<T[K]>): string;
+    /**
+     * Returns only the JSONB operator fragment (without the column).
+     * Useful inside `whereTyped` conditions strings.
+     * @example
+     * t.jsonPath('metadata', '->>', 'role')              // → ->> 'role'
+     * t.jsonPath('metadata', '->>', 'settings', 'theme') // → -> 'settings' ->> 'theme'
+     *
+     * // Combined with whereTyped:
+     * qb.whereTyped(u => u.metadata, `${t.jsonPath('metadata', '->>', 'role')} =`, 'admin')
+     */
+    jsonPath<K_1 extends keyof T>(_columnName: K_1, jsonOperator: '->>' | '->', ...fieldNames: JsonFieldRest<T[K_1]>): string;
+};
+export {};