typeorm-extensions 2.2.0-rc.1 → 2.2.0-rc.10

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

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = void 0;
+exports.getQueryRunner = exports.withoutPaging = exports.getAppliedOrderBy = exports.getTypedSelectionKey = exports.resolveTypedProperty = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.findTypedCalculatedProperty = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = exports.resolveDeferredKeys = exports.listQueryAliases = void 0;
+const typeorm_1 = require("typeorm");
+const QueryExpressionMap_1 = require("typeorm/query-builder/QueryExpressionMap");
 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");
+const calculated_column_utils_1 = require("./calculated-column.utils");
 /**
  * Whether single-level typed keys are qualified with the main alias (`user.firstName`).
  *
@@ -30,13 +33,131 @@ function requireMainAliasName(queryBuilder, key) {
     }
     return mainAlias.name;
 }
+/**
+ * The aliases of the query and of the queries it is part of, its own first. The builder of a `Brackets` callback
+ * has the outer query's main alias but an empty alias list: the aliases, joins included, are on its parent. A
+ * subquery sees the aliases of the outer query too.
+ */
+function listQueryAliases(builder) {
+    var _a;
+    const aliases = [];
+    // parentQueryBuilder is protected in TypeORM's types
+    for (let query = builder; query; query = query.parentQueryBuilder) {
+        const { aliases: own = [], mainAlias } = (_a = query.expressionMap) !== null && _a !== void 0 ? _a : {};
+        aliases.push(...own, ...(mainAlias ? [mainAlias] : []));
+    }
+    return aliases;
+}
+exports.listQueryAliases = listQueryAliases;
+/** An alias of the query by name, or of a query it is part of (see `listQueryAliases`). */
+function findQueryAlias(queryBuilder, aliasName) {
+    return listQueryAliases(queryBuilder).find((candidate) => candidate.name === aliasName);
+}
+// private-use characters: no identifier or SQL that TypeORM builds contains them
+const DEFERRED_KEY_START = '\uE000';
+const DEFERRED_PROPERTY = '\uE001';
+const DEFERRED_FIELD = '\uE002';
+const DEFERRED_UNQUOTED = '\uE004';
+const DEFERRED_KEY_END = '\uE003';
+const DEFERRED_KEY = /\uE000([^\uE000-\uE004]+)([\uE001\uE002\uE004])([^\uE000-\uE004]+)\uE003/g;
+const TWO_PART_FIELD = /^([A-Za-z_][\w$]*)\.([A-Za-z_][\w$]*)$/;
+/**
+ * Placeholder for a column of an alias the query doesn't have yet, e.g. a join added after the call: resolved when
+ * the alias is added (`resolveAliasKeys`) or, at the latest, when the SQL is built (`resolveDeferredKeys`).
+ */
+function deferColumnKey(aliasName, separator, name) {
+    return `${DEFERRED_KEY_START}${aliasName}${separator}${name}${DEFERRED_KEY_END}`;
+}
+/**
+ * SQL of a deferred key for `alias`, undefined while the query doesn't have it:
+ * - a quoted key: the database column through the alias' entity, quoted, `"usr"."receipts_email"`; the name
+ *   quoted without an entity;
+ * - an unquoted one (select, order, group by, distinct without `useQuotes`): `alias.property` on an alias with an
+ *   entity, which TypeORM maps and reads as a column of the entity; quoted on an alias without one (a subquery, a
+ *   CTE), as on an alias known at the call, and on an alias the query never has, which only raw SQL adds (a LATERAL
+ *   subquery in the condition of a raw join): TypeORM can't map it, and PostgreSQL would fold it to lower case.
+ */
+function toDeferredKeySql(alias, aliasName, separator, name, escape) {
+    const metadata = metadataOf(alias);
+    if (separator === DEFERRED_UNQUOTED) {
+        return metadata ? `${aliasName}.${name}` : `${escape(aliasName)}.${escape(name)}`;
+    }
+    const column = metadata && (separator === DEFERRED_FIELD ? findColumn(metadata, name) : metadata.findColumnWithPropertyPath(name));
+    const columnName = column && !column.isVirtualProperty ? column.databaseName : name;
+    return `${escape(aliasName)}.${escape(columnName)}`;
+}
+/** Replaces placeholders of `deferColumnKey` in SQL built by `builder`, through the aliases it has by then. */
+function resolveDeferredKeys(builder, statement) {
+    if (typeof statement !== 'string' || !statement.includes(DEFERRED_KEY_START)) {
+        return statement;
+    }
+    const queryBuilder = builder;
+    const escape = (identifier) => queryBuilder.escape(identifier);
+    return statement.replace(DEFERRED_KEY, (_match, aliasName, separator, name) => toDeferredKeySql(findQueryAlias(queryBuilder, aliasName), aliasName, separator, name, escape));
+}
+exports.resolveDeferredKeys = resolveDeferredKeys;
+/**
+ * Resolves the placeholders of a new alias in select, order, group by and distinct on, which TypeORM reads before it
+ * builds the SQL: a select of `alias.property` is how it knows to fill the property of a joined entity.
+ */
+function resolveAliasKeys(expressionMap, alias) {
+    var _a;
+    // `connection` (TypeORM 0.3) or `dataSource` (1.x), protected in its types; read only when a key is found
+    const { connection, dataSource } = expressionMap;
+    const escape = (identifier) => (connection !== null && connection !== void 0 ? connection : dataSource).driver.escape(identifier);
+    const hasKey = (statement) => typeof statement === 'string' && statement.includes(DEFERRED_KEY_START);
+    const resolve = (statement) => hasKey(statement)
+        ? statement.replace(DEFERRED_KEY, (match, aliasName, separator, name) => aliasName === alias.name ? toDeferredKeySql(alias, aliasName, separator, name, escape) : match)
+        : statement;
+    // new objects and arrays: a clone shares them with the query it was cloned from
+    if (expressionMap.selects.some((select) => hasKey(select.selection))) {
+        expressionMap.selects = expressionMap.selects.map((select) => hasKey(select.selection) ? { ...select, selection: resolve(select.selection) } : select);
+    }
+    if (expressionMap.groupBys.some(hasKey)) {
+        expressionMap.groupBys = expressionMap.groupBys.map(resolve);
+    }
+    if ((_a = expressionMap.selectDistinctOn) === null || _a === void 0 ? void 0 : _a.some(hasKey)) {
+        expressionMap.selectDistinctOn = expressionMap.selectDistinctOn.map(resolve);
+    }
+    if (Object.keys(expressionMap.orderBys).some(hasKey)) {
+        expressionMap.orderBys = Object.fromEntries(Object.entries(expressionMap.orderBys).map(([key, order]) => [resolve(key), order]));
+    }
+}
+const DEFERRED_KEYS_INSTALLED = Symbol.for('typeorm-extensions.deferredKeys');
+function installDeferredKeyResolution() {
+    const builderPrototype = typeorm_1.QueryBuilder.prototype;
+    const mapPrototype = QueryExpressionMap_1.QueryExpressionMap.prototype;
+    if (builderPrototype[DEFERRED_KEYS_INSTALLED]) {
+        return;
+    }
+    builderPrototype[DEFERRED_KEYS_INSTALLED] = true;
+    // TypeORM 0.3.12 maps property names in each part of the query, later versions once in the whole query; keys are
+    // resolved first, so an unquoted `alias.property` is mapped too
+    for (const method of ['replacePropertyNames', 'replacePropertyNamesForTheWholeQuery']) {
+        const original = builderPrototype[method];
+        if (typeof original === 'function') {
+            builderPrototype[method] = function (statement) {
+                return original.call(this, resolveDeferredKeys(this, statement));
+            };
+        }
+    }
+    const createAlias = mapPrototype.createAlias;
+    if (typeof createAlias === 'function') {
+        mapPrototype.createAlias = function (...args) {
+            const alias = createAlias.apply(this, args);
+            if (alias === null || alias === void 0 ? void 0 : alias.name) {
+                resolveAliasKeys(this, alias);
+            }
+            return alias;
+        };
+    }
+}
+installDeferredKeyResolution();
+const metadataOf = (alias) => (alias === null || alias === void 0 ? void 0 : alias.hasMetadata) ? alias.metadata : undefined;
 /** 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;
+    var _a;
+    return metadataOf(aliasName === undefined ? (_a = queryBuilder.expressionMap) === null || _a === void 0 ? void 0 : _a.mainAlias : findQueryAlias(queryBuilder, aliasName));
 }
 /**
  * Database name of an entity property's column (`@Column({ name })`), looked up in the metadata of
@@ -66,6 +187,7 @@ function findFieldColumn(builder, field) {
         const metadata = getAliasMetadata(queryBuilder, field.slice(0, dot));
         return metadata && findColumn(metadata, field.slice(dot + 1));
     }
+    // only by database name: an unqualified property name may mean another table's column
     return (_a = getAliasMetadata(queryBuilder, undefined)) === null || _a === void 0 ? void 0 : _a.columns.find((column) => column.databaseName === field);
 }
 exports.findFieldColumn = findFieldColumn;
@@ -85,27 +207,18 @@ exports.findFieldColumn = findFieldColumn;
  *   `stringToSQLIdentifier` does, in the driver's quotes.
  */
 function toFieldSql(builder, field) {
-    var _a;
     const queryBuilder = builder;
+    const column = findFieldColumn(builder, field);
     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;
-        }
+    if (column) {
+        const columnSql = queryBuilder.escape(column.databaseName);
+        return dot > 0 && isAliasPrefixingEnabled(queryBuilder)
+            ? `${queryBuilder.escape(field.slice(0, dot))}.${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);
-        }
+    const parts = dot > 0 ? TWO_PART_FIELD.exec(field) : null;
+    if (parts && !findQueryAlias(queryBuilder, parts[1])) {
+        return deferColumnKey(parts[1], DEFERRED_FIELD, parts[2]);
     }
     return (0, sql_utils_1.stringToSQLIdentifier)(field, (0, sql_utils_1.getDriverType)(builder));
 }
@@ -146,27 +259,33 @@ function findColumnPath(metadata, keys) {
  * before `from()` the property name is used as the column name.
  */
 function resolveTypedKey(queryBuilder, keys) {
-    var _a, _b;
     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);
     }
-    const column = (_a = resolved.column) !== null && _a !== void 0 ? _a : (_b = resolved.metadata) === null || _b === void 0 ? void 0 : _b.findColumnWithPropertyPath(resolved.propertyPath);
     // a @CalculatedColumn: TypeORM would write "alias"."property", a column the table doesn't have
-    if ((column === null || column === void 0 ? void 0 : column.isVirtualProperty) && !column.query) {
+    if ((0, calculated_column_utils_1.isCalculated)(resolved.column)) {
         throw new TypeError(`${keys.join('.')} is a @CalculatedColumn, not a column of the table: use the SQL expression that fills it`);
     }
     return resolved;
 }
+/** The alias and property of the `@CalculatedColumn` a typed key picks; undefined for any other key. */
+function findTypedCalculatedProperty(builder, keyHolder) {
+    const resolved = resolveTypedKeyPath(builder, keyHolder.getKeys());
+    return (0, calculated_column_utils_1.isCalculated)(resolved.column) ? { aliasName: resolved.aliasName, propertyPath: resolved.propertyPath } : undefined;
+}
+exports.findTypedCalculatedProperty = findTypedCalculatedProperty;
 function resolveTypedKeyPath(queryBuilder, keys) {
     const prefixing = isAliasPrefixingEnabled(queryBuilder);
     if (keys.length === 1) {
         const aliasName = prefixing ? requireMainAliasName(queryBuilder, keys[0]) : undefined;
+        const metadata = getAliasMetadata(queryBuilder, aliasName);
         return {
             aliasName,
             propertyPath: keys[0],
-            metadata: getAliasMetadata(queryBuilder, aliasName),
+            metadata,
+            column: metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(keys[0]),
         };
     }
     const [firstKey, ...restKeys] = keys;
@@ -182,7 +301,7 @@ function resolveTypedKeyPath(queryBuilder, keys) {
             ...findColumnPath(metadata, restKeys),
         };
     }
-    const queryAlias = expressionMap === null || expressionMap === void 0 ? void 0 : expressionMap.aliases.find((alias) => alias.name === firstKey);
+    const queryAlias = findQueryAlias(queryBuilder, firstKey);
     if (!queryAlias && mainAlias) {
         const mainMetadata = getAliasMetadata(queryBuilder, undefined);
         const columnPath = findColumnPath(mainMetadata, keys);
@@ -194,7 +313,7 @@ function resolveTypedKeyPath(queryBuilder, keys) {
             };
         }
     }
-    const metadata = (queryAlias === null || queryAlias === void 0 ? void 0 : queryAlias.hasMetadata) ? queryAlias.metadata : undefined;
+    const metadata = metadataOf(queryAlias);
     return {
         aliasName: firstKey,
         propertyPath: restKeys.join('.'),
@@ -207,8 +326,11 @@ function resolveTypedKeyPath(queryBuilder, keys) {
  * 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;
+    var _a;
+    if (aliasName !== undefined && !metadata && !findQueryAlias(queryBuilder, aliasName)) {
+        return deferColumnKey(aliasName, DEFERRED_PROPERTY, propertyPath);
+    }
+    const columnName = (_a = column === null || column === void 0 ? void 0 : column.databaseName) !== null && _a !== void 0 ? _a : propertyPath;
     const columnSql = aliasName === undefined
         ? queryBuilder.escape(columnName)
         : `${queryBuilder.escape(aliasName)}.${queryBuilder.escape(columnName)}`;
@@ -255,13 +377,51 @@ function getTypedSingleColumnKey(builder, callback, methodName, jsonOptions) {
 }
 exports.getTypedSingleColumnKey = getTypedSingleColumnKey;
 /**
- * Key for typed select / order / distinct on a SelectQueryBuilder.
+ * The alias and the entity property a typed callback picks, for methods that take a property rather than a column
+ * (a `@CalculatedColumn`): `u => u.imagesCount` is on the main alias, `q => q.owner.imagesCount` on `owner`.
+ */
+function resolveTypedProperty(builder, callback, methodName) {
+    const keyHolder = (0, proxy_key_utils_1.getKeyHolder)(callback);
+    if (Array.isArray(keyHolder)) {
+        throw new TypeError(`${methodName} expects the callback to pick a single property, got ${keyHolder.length}`);
+    }
+    const { aliasName, propertyPath } = resolveTypedKeyPath(builder, keyHolder.getKeys());
+    return { aliasName, propertyPath };
+}
+exports.resolveTypedProperty = resolveTypedProperty;
+/**
+ * Throws for a key that names no column of its table: a relation whose join column is on the other side
+ * (one-to-many, many-to-many, the inverse side of a one-to-one) or an embedded entity. TypeORM leaves such a key
+ * as written, and the database rejects it.
+ */
+function assertTableColumnKey({ metadata, propertyPath }, keys, methodName) {
+    const relation = metadata === null || metadata === void 0 ? void 0 : metadata.findRelationWithPropertyPath(propertyPath);
+    if (relation && !relation.isManyToOne && !relation.isOneToOneOwner) {
+        throw new TypeError(`${methodName}: "${keys.join('.')}" is a relation without a join column in its table. ` +
+            `Join it and address its columns by the join alias`);
+    }
+    if (!relation && (metadata === null || metadata === void 0 ? void 0 : metadata.findEmbeddedWithPropertyPath(propertyPath))) {
+        throw new TypeError(`${methodName}: "${keys.join('.')}" is an embedded entity, not a column: address its columns, e.g. ` +
+            `"${keys.join('.')}.someColumn"`);
+    }
+}
+// an alias the query doesn't know yet is resolved when it is added (`resolveAliasKeys`)
+function isAliasWithoutMetadata(queryBuilder, aliasName) {
+    const alias = aliasName === undefined ? undefined : findQueryAlias(queryBuilder, aliasName);
+    return alias !== undefined && !alias.hasMetadata;
+}
+/**
+ * Key for typed select / order / distinct / group by 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.
+ * (`"t"."ticket_status"`), since TypeORM doesn't map quoted keys. An alias of the query without
+ * metadata (a subquery or a CTE in FROM or a join), or one the query still doesn't have when the SQL
+ * is built, is quoted unless `useQuotes` is `false`: TypeORM leaves its keys as written, and
+ * PostgreSQL folds an unquoted `cte.firstName` to `firstname`.
+ * Strings are kept as is.
  */
-function getTypedSelectionKey(builder, selection, useQuotes) {
+function getTypedSelectionKey(builder, selection, useQuotes, columnsFor) {
     if (typeof selection === 'string') {
         return selection;
     }
@@ -272,9 +432,20 @@ function getTypedSelectionKey(builder, selection, useQuotes) {
             throw new TypeError(`Typed key "${keyHolder.getKeys().join('.')}" points into the JSON column "${resolved.propertyPath}": ` +
                 `select, order, distinct and group by take columns only. For an expression use tableHelper().jsonColumn()`);
         }
-        if (useQuotes) {
+        if (columnsFor !== undefined) {
+            assertTableColumnKey(resolved, keyHolder.getKeys(), columnsFor);
+        }
+        if (useQuotes !== null && useQuotes !== void 0 ? useQuotes : isAliasWithoutMetadata(queryBuilder, resolved.aliasName)) {
             return toQuotedColumnKey(queryBuilder, resolved);
         }
+        // an alias added later decides then: TypeORM maps an entity's keys, a subquery's are quoted
+        if (useQuotes === undefined &&
+            columnsFor !== undefined &&
+            resolved.aliasName !== undefined &&
+            !resolved.metadata &&
+            !findQueryAlias(queryBuilder, resolved.aliasName)) {
+            return deferColumnKey(resolved.aliasName, DEFERRED_UNQUOTED, resolved.propertyPath);
+        }
         return resolved.aliasName === undefined
             ? resolved.propertyPath
             : `${resolved.aliasName}.${resolved.propertyPath}`;
@@ -283,3 +454,35 @@ function getTypedSelectionKey(builder, selection, useQuotes) {
     return Array.isArray(keyHolder) ? keyHolder.map(toKey) : toKey(keyHolder);
 }
 exports.getTypedSelectionKey = getTypedSelectionKey;
+/**
+ * The ORDER BY a query is built with, in the order it was applied. `allOrderBys`, not `orderBys`: it is what the SQL
+ * is built from, so without an explicit order it falls back to the `orderBy` of @Entity, and respects the
+ * `disable-global-order` option.
+ */
+function getAppliedOrderBy(builder) {
+    var _a;
+    return Object.entries((_a = builder.expressionMap.allOrderBys) !== null && _a !== void 0 ? _a : {}).map(([key, value]) => {
+        const selector = resolveDeferredKeys(builder, key);
+        return typeof value === 'string'
+            ? { selector, order: value }
+            : { selector, order: value.order, nulls: value.nulls };
+    });
+}
+exports.getAppliedOrderBy = getAppliedOrderBy;
+/** The query without paging: no ORDER BY (nor the entity's default one), LIMIT, OFFSET, take or skip. */
+function withoutPaging(query) {
+    return query
+        .orderBy()
+        .offset(undefined)
+        .limit(undefined)
+        .skip(undefined)
+        .take(undefined)
+        .setOption('disable-global-order');
+}
+exports.withoutPaging = withoutPaging;
+/** The query runner a builder was created with, from a transactional manager; `undefined` for one from the pool. */
+function getQueryRunner(builder) {
+    // queryRunner is protected in TypeORM's types
+    return builder.queryRunner;
+}
+exports.getQueryRunner = getQueryRunner;

package/dist/utils/reserved-qualifier-guard.utils.d.ts

@@ -0,0 +1,36 @@
+import { ReservedQualifier } from './reserved-qualifier.utils';
+/** The SQL of a query names a reserved word as a qualifier without quotes; see `enableReservedQualifierGuard`. */
+export declare class ReservedQualifierError extends Error {
+    /** The SQL of the query, as the driver gets it. */
+    readonly sql: string;
+    /** Each reserved word used as a qualifier, in the order of the SQL. */
+    readonly qualifiers: ReservedQualifier[];
+    constructor(sql: string, qualifiers: ReservedQualifier[]);
+}
+type GuardWordsOption = {
+    /**
+     * The words to report, instead of the default list of the database (`POSTGRES_RESERVED_KEY_WORDS`,
+     * `COCKROACHDB_RESERVED_KEY_WORDS` on CockroachDB). Spread a default list to extend it.
+     */
+    words?: readonly string[];
+};
+export type ReservedQualifierGuardOptions = GuardWordsOption & ({
+    /** `'throw'` (the default): the query rejects with a `ReservedQualifierError` before it runs. */
+    mode?: 'throw';
+} | {
+    /** `'warn'`: the query runs, and the error is passed to `onViolation`. */
+    mode: 'warn';
+    /** Reports the error the query would throw in `'throw'` mode; `console.warn` by default. */
+    onViolation?: (violation: ReservedQualifierError) => void;
+});
+/**
+ * Checks the SQL of every query builder on PostgreSQL and CockroachDB for a reserved word used as a qualifier
+ * without quotes, such as `order."userId"` or `user.id` (`findBareReservedQualifiers`), before the query runs.
+ * TypeORM quotes the aliases it writes, so such a word comes from SQL written by hand, which PostgreSQL rejects.
+ *
+ * Off by default. A second call replaces the options. Other databases aren't checked.
+ */
+export declare function enableReservedQualifierGuard(options?: ReservedQualifierGuardOptions): void;
+/** Turns the check of `enableReservedQualifierGuard` off. */
+export declare function disableReservedQualifierGuard(): void;
+export {};

package/dist/utils/reserved-qualifier-guard.utils.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disableReservedQualifierGuard = exports.enableReservedQualifierGuard = exports.ReservedQualifierError = void 0;
+const typeorm_1 = require("typeorm");
+const reserved_qualifier_utils_1 = require("./reserved-qualifier.utils");
+const sql_utils_1 = require("./sql.utils");
+const NAME_AFTER_DOT = /^\s*\.\s*("(?:[^"]|"")*"|[A-Za-z_][\w$]*|\*)/;
+/** `"order"."userId"` for `order."userId"` / `order.userId`, `"order".*` for `order.*`. */
+function toQuotedReference(sql, { word, index }) {
+    var _a, _b;
+    const name = (_b = (_a = NAME_AFTER_DOT.exec(sql.slice(index + word.length))) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : 'column';
+    const quotedName = name.startsWith('"') || name === '*' ? name : `"${name}"`;
+    return `"${word}".${quotedName}`;
+}
+/** The SQL of a query names a reserved word as a qualifier without quotes; see `enableReservedQualifierGuard`. */
+class ReservedQualifierError extends Error {
+    constructor(sql, qualifiers) {
+        const [first] = qualifiers;
+        const found = qualifiers.map(({ word, snippet }) => `"${word}" in ${snippet}`).join('; ');
+        super(`Reserved word used as a qualifier without quotes: ${found}. ` +
+            `PostgreSQL reads it as the key word, not as an alias, and rejects the query. ` +
+            (first
+                ? `Quote both halves, ${toQuotedReference(sql, first)}, or build the reference with tableHelper or the typed methods`
+                : ''));
+        this.name = 'ReservedQualifierError';
+        this.sql = sql;
+        this.qualifiers = qualifiers;
+    }
+}
+exports.ReservedQualifierError = ReservedQualifierError;
+let guard;
+let installed = false;
+let lastScan;
+const reportViolation = (violation) => console.warn(violation);
+function checkQuery(queryBuilder, sql, state) {
+    var _a;
+    const driver = (0, sql_utils_1.getDriverType)(queryBuilder);
+    if (typeof sql !== 'string' || !(0, sql_utils_1.isPostgresLikeDriver)(driver)) {
+        return;
+    }
+    const words = (_a = state.words) !== null && _a !== void 0 ? _a : (0, reserved_qualifier_utils_1.toReservedWordSet)(driver === 'cockroachdb' ? reserved_qualifier_utils_1.COCKROACHDB_RESERVED_KEY_WORDS : reserved_qualifier_utils_1.POSTGRES_RESERVED_KEY_WORDS);
+    // the same SQL again, as a query run in a loop: one scan
+    const qualifiers = lastScan && lastScan.sql === sql && lastScan.words === words
+        ? lastScan.qualifiers
+        : (0, reserved_qualifier_utils_1.scanReservedQualifiers)(sql, words);
+    lastScan = { sql, words, qualifiers };
+    if (qualifiers.length === 0) {
+        return;
+    }
+    const violation = new ReservedQualifierError(sql, qualifiers);
+    if (state.mode === 'throw') {
+        throw violation;
+    }
+    state.onViolation(violation);
+}
+// every query of every builder gets its SQL here before it runs: getMany, getRawMany, getOne, getCount, stream,
+// execute; getSql() too. getQuery() isn't checked: a subquery's SQL is checked as part of the query it is in
+function installGuard() {
+    if (installed) {
+        return;
+    }
+    installed = true;
+    const getQueryAndParameters = typeorm_1.QueryBuilder.prototype.getQueryAndParameters;
+    typeorm_1.QueryBuilder.prototype.getQueryAndParameters = function () {
+        const queryAndParameters = getQueryAndParameters.call(this);
+        if (guard) {
+            checkQuery(this, queryAndParameters[0], guard);
+        }
+        return queryAndParameters;
+    };
+}
+/**
+ * Checks the SQL of every query builder on PostgreSQL and CockroachDB for a reserved word used as a qualifier
+ * without quotes, such as `order."userId"` or `user.id` (`findBareReservedQualifiers`), before the query runs.
+ * TypeORM quotes the aliases it writes, so such a word comes from SQL written by hand, which PostgreSQL rejects.
+ *
+ * Off by default. A second call replaces the options. Other databases aren't checked.
+ */
+function enableReservedQualifierGuard(options = {}) {
+    var _a;
+    const mode = (_a = options.mode) !== null && _a !== void 0 ? _a : 'throw';
+    if (mode !== 'throw' && mode !== 'warn') {
+        throw new TypeError(`Invalid mode ${JSON.stringify(mode)} of the reserved qualifier guard: 'throw' or 'warn'`);
+    }
+    guard = {
+        mode,
+        words: options.words === undefined ? undefined : (0, reserved_qualifier_utils_1.toReservedWordSet)(options.words),
+        onViolation: (options.mode === 'warn' && options.onViolation) || reportViolation,
+    };
+    installGuard();
+}
+exports.enableReservedQualifierGuard = enableReservedQualifierGuard;
+/** Turns the check of `enableReservedQualifierGuard` off. */
+function disableReservedQualifierGuard() {
+    guard = undefined;
+    lastScan = undefined;
+}
+exports.disableReservedQualifierGuard = disableReservedQualifierGuard;

package/dist/utils/reserved-qualifier.utils.d.ts

@@ -0,0 +1,33 @@
+/** A reserved word that qualifies a name without quotes, as in `order."userId"`. */
+export interface ReservedQualifier {
+    /** The word as the SQL has it: `order`, `ORDER`. */
+    word: string;
+    /** Offset of the word in the SQL. */
+    index: number;
+    /** The SQL around the word, on one line. */
+    snippet: string;
+}
+/**
+ * The reserved key words of PostgreSQL, "reserved" in Appendix C of its documentation (`SYSTEM_USER` since
+ * PostgreSQL 16). None can be a table, an alias or a schema without quotes, so none is followed by a `.` in valid
+ * SQL. The words "reserved (can be function or type)" (`LEFT`, `JOIN`, `BINARY`, …) aren't on the list: one may
+ * name the schema of a type, as in `CAST(x AS binary.my_type)`.
+ */
+export declare const POSTGRES_RESERVED_KEY_WORDS: readonly string[];
+/** The reserved key words of CockroachDB: PostgreSQL's without `SYSTEM_USER`, with `CONCURRENTLY` and `CURRENT_SCHEMA`. */
+export declare const COCKROACHDB_RESERVED_KEY_WORDS: readonly string[];
+/** The words in lower case; cached for a frozen list, such as the defaults, which can't change afterwards. */
+export declare function toReservedWordSet(words: readonly string[]): ReadonlySet<string>;
+/** `findBareReservedQualifiers` with the words as a set of lower-case words (`toReservedWordSet`). */
+export declare function scanReservedQualifiers(sql: string, words: ReadonlySet<string>): ReservedQualifier[];
+/**
+ * Reserved words that qualify a name without quotes, as in `order."userId"` or `user.id`: PostgreSQL reads such a
+ * word as the key word, not as an alias, and rejects the statement (`syntax error at or near "order"`).
+ *
+ * Words in string literals (`E'…'` and dollar-quoted ones too), quoted identifiers, comments and parameters are
+ * skipped, and so are words after a dot (`public.order`) and a number after one (`THEN .5`). Case-insensitive;
+ * whitespace may come before the dot (`group . name`).
+ *
+ * @param words the words to look for, `POSTGRES_RESERVED_KEY_WORDS` by default
+ */
+export declare function findBareReservedQualifiers(sql: string, words?: readonly string[]): ReservedQualifier[];