typeorm-extensions 2.2.0-rc.6 → 2.2.0-rc.7

package/dist/extensions/where-relation-exists.extension.d.ts

@@ -19,17 +19,17 @@ type RelatedCondition<Related extends ObjectLiteral> = (subQuery: SelectQueryBui
  */
 export interface WhereRelationExistsMethods<Entity extends ObjectLiteral> {
     /** Sets `WHERE EXISTS (…)` over the relation, replacing the WHERE conditions set before. */
-    whereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    whereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
     /** Adds `AND EXISTS (…)` over the relation. */
-    andWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    andWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
     /** Adds `OR EXISTS (…)` over the relation. */
-    orWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    orWhereRelationExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
     /** Sets `WHERE NOT EXISTS (…)` over the relation, replacing the WHERE conditions set before. */
-    whereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    whereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
     /** Adds `AND NOT EXISTS (…)` over the relation. */
-    andWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    andWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
     /** Adds `OR NOT EXISTS (…)` over the relation. */
-    orWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
+    orWhereRelationNotExists<Related extends ObjectLiteral, Type extends ObjectLiteral = TypedRoot<Entity, this>>(relation: RelationSelection<Type, Related>, alias: string, where?: RelatedCondition<Related>): this;
 }
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> extends WhereRelationExistsMethods<Entity> {

package/dist/helpers.d.ts

@@ -1,2 +1,6 @@
 export * from './utils/table.utils';
 export { escapeLikePattern } from './utils/search.utils';
+export { COCKROACHDB_RESERVED_KEY_WORDS, findBareReservedQualifiers, POSTGRES_RESERVED_KEY_WORDS, } from './utils/reserved-qualifier.utils';
+export type { ReservedQualifier } from './utils/reserved-qualifier.utils';
+export { disableReservedQualifierGuard, enableReservedQualifierGuard, ReservedQualifierError, } from './utils/reserved-qualifier-guard.utils';
+export type { ReservedQualifierGuardOptions } from './utils/reserved-qualifier-guard.utils';

package/dist/helpers.js

@@ -14,10 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.escapeLikePattern = void 0;
+exports.ReservedQualifierError = exports.enableReservedQualifierGuard = exports.disableReservedQualifierGuard = exports.POSTGRES_RESERVED_KEY_WORDS = exports.findBareReservedQualifiers = exports.COCKROACHDB_RESERVED_KEY_WORDS = exports.escapeLikePattern = void 0;
 // Side-effect-free entry point: `typeorm-extensions/helpers`.
-// Exports helpers (tableHelper, escapeLikePattern) only and patches nothing; importing the package root
-// (`typeorm-extensions`) installs every QueryBuilder extension.
+// Exports helpers (tableHelper, escapeLikePattern, the reserved qualifier guard) only and patches nothing on import;
+// importing the package root (`typeorm-extensions`) installs every QueryBuilder extension.
 __exportStar(require("./utils/table.utils"), exports);
 var search_utils_1 = require("./utils/search.utils");
 Object.defineProperty(exports, "escapeLikePattern", { enumerable: true, get: function () { return search_utils_1.escapeLikePattern; } });
+var reserved_qualifier_utils_1 = require("./utils/reserved-qualifier.utils");
+Object.defineProperty(exports, "COCKROACHDB_RESERVED_KEY_WORDS", { enumerable: true, get: function () { return reserved_qualifier_utils_1.COCKROACHDB_RESERVED_KEY_WORDS; } });
+Object.defineProperty(exports, "findBareReservedQualifiers", { enumerable: true, get: function () { return reserved_qualifier_utils_1.findBareReservedQualifiers; } });
+Object.defineProperty(exports, "POSTGRES_RESERVED_KEY_WORDS", { enumerable: true, get: function () { return reserved_qualifier_utils_1.POSTGRES_RESERVED_KEY_WORDS; } });
+var reserved_qualifier_guard_utils_1 = require("./utils/reserved-qualifier-guard.utils");
+Object.defineProperty(exports, "disableReservedQualifierGuard", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.disableReservedQualifierGuard; } });
+Object.defineProperty(exports, "enableReservedQualifierGuard", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.enableReservedQualifierGuard; } });
+Object.defineProperty(exports, "ReservedQualifierError", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.ReservedQualifierError; } });

package/dist/index.d.ts

@@ -6,3 +6,7 @@ export type { Json } from './types/modules/proxy-callback.types';
 export type { TypedRoot, WithTypedRoot } from './types/modules/typed-root.types';
 export * from './utils/table.utils';
 export { escapeLikePattern } from './utils/search.utils';
+export { COCKROACHDB_RESERVED_KEY_WORDS, findBareReservedQualifiers, POSTGRES_RESERVED_KEY_WORDS, } from './utils/reserved-qualifier.utils';
+export type { ReservedQualifier } from './utils/reserved-qualifier.utils';
+export { disableReservedQualifierGuard, enableReservedQualifierGuard, ReservedQualifierError, } from './utils/reserved-qualifier-guard.utils';
+export type { ReservedQualifierGuardOptions } from './utils/reserved-qualifier-guard.utils';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.escapeLikePattern = void 0;
+exports.ReservedQualifierError = exports.enableReservedQualifierGuard = exports.disableReservedQualifierGuard = exports.POSTGRES_RESERVED_KEY_WORDS = exports.findBareReservedQualifiers = exports.COCKROACHDB_RESERVED_KEY_WORDS = exports.escapeLikePattern = void 0;
 __exportStar(require("./extensions"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./types/interfaces"), exports);
@@ -22,3 +22,11 @@ __exportStar(require("./types/extensions"), exports);
 __exportStar(require("./utils/table.utils"), exports);
 var search_utils_1 = require("./utils/search.utils");
 Object.defineProperty(exports, "escapeLikePattern", { enumerable: true, get: function () { return search_utils_1.escapeLikePattern; } });
+var reserved_qualifier_utils_1 = require("./utils/reserved-qualifier.utils");
+Object.defineProperty(exports, "COCKROACHDB_RESERVED_KEY_WORDS", { enumerable: true, get: function () { return reserved_qualifier_utils_1.COCKROACHDB_RESERVED_KEY_WORDS; } });
+Object.defineProperty(exports, "findBareReservedQualifiers", { enumerable: true, get: function () { return reserved_qualifier_utils_1.findBareReservedQualifiers; } });
+Object.defineProperty(exports, "POSTGRES_RESERVED_KEY_WORDS", { enumerable: true, get: function () { return reserved_qualifier_utils_1.POSTGRES_RESERVED_KEY_WORDS; } });
+var reserved_qualifier_guard_utils_1 = require("./utils/reserved-qualifier-guard.utils");
+Object.defineProperty(exports, "disableReservedQualifierGuard", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.disableReservedQualifierGuard; } });
+Object.defineProperty(exports, "enableReservedQualifierGuard", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.enableReservedQualifierGuard; } });
+Object.defineProperty(exports, "ReservedQualifierError", { enumerable: true, get: function () { return reserved_qualifier_guard_utils_1.ReservedQualifierError; } });

package/dist/types/extensions/index.d.ts

@@ -10,4 +10,5 @@ export * from './search.types';
 export * from './typed-having.types';
 export * from './union.types';
 export * from './join-lateral.types';
+export * from './typed-join-and-map.types';
 export * from './query-returning.types';

package/dist/types/extensions/index.js

@@ -26,4 +26,5 @@ __exportStar(require("./search.types"), exports);
 __exportStar(require("./typed-having.types"), exports);
 __exportStar(require("./union.types"), exports);
 __exportStar(require("./join-lateral.types"), exports);
+__exportStar(require("./typed-join-and-map.types"), exports);
 __exportStar(require("./query-returning.types"), exports);

package/dist/types/extensions/typed-join-and-map.types.d.ts

@@ -0,0 +1,6 @@
+import type { SelectQueryBuilder } from 'typeorm';
+/**
+ * What a map join joins, as TypeORM's `leftJoinAndMapOne` and the others take it: an entity class or name, a
+ * relation (`'user.photos'`), a table name, or a factory that builds a subquery on the query builder it is given.
+ */
+export type JoinAndMapTarget = Function | string | ((qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>);

package/dist/types/extensions/typed-join-and-map.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/modules/typed-root.types.d.ts

@@ -1,17 +1,19 @@
 import type { ObjectLiteral } from 'typeorm';
-declare const typedRoot: unique symbol;
 declare class TypedRootMark<Root> {
-    [typedRoot]?(): Root;
+    __typedRoot?(): Root;
 }
 /**
- * The entity type of a builder whose typed callbacks take another root, set with `typed<Root>()`: the entity
- * with an optional symbol method that only types carry. Entities loaded with it are plain entities.
+ * A query builder whose typed callbacks take another root, as `typed<Root>()` returns it:
+ * `WithTypedRoot<SelectQueryBuilder<Entity>, Root>`, the builder with an optional `__typedRoot` method that only
+ * types carry. A builder of a marked entity, `SelectQueryBuilder<WithTypedRoot<Entity, Root>>`, takes the root too.
  */
-export type WithTypedRoot<Entity, Root extends ObjectLiteral> = Entity & TypedRootMark<Root>;
+export type WithTypedRoot<Marked, Root extends ObjectLiteral> = Marked & TypedRootMark<Root>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type BuilderRoot<Builder> = '__typedRoot' extends keyof Builder ? Builder extends TypedRootMark<infer Root> ? Root extends ObjectLiteral ? Root : never : never : never;
+type EntityRoot<Entity> = '__typedRoot' extends keyof Entity ? IsAny<Entity['__typedRoot' & keyof Entity]> extends true ? Entity : Entity extends TypedRootMark<infer Root> ? Root extends ObjectLiteral ? Root : Entity : Entity : Entity;
 /**
- * The root of a builder's typed callbacks: the one set with `typed<Root>()`, or else its entity. The key check
- * comes first: without `strictNullChecks` an entity with an index signature (`ObjectLiteral`) matches the
- * optional mark too, and its root would be inferred as `unknown`.
+ * The root of a builder's typed callbacks: the one set with `typed<Root>()` on the builder (`Builder`, which the
+ * typed methods pass as `this`) or on its entity, or else the entity.
  */
-export type TypedRoot<Entity> = typeof typedRoot extends keyof Entity ? Entity extends TypedRootMark<infer Root> ? Root extends ObjectLiteral ? Root : Entity : Entity : Entity;
+export type TypedRoot<Entity, Builder = unknown> = [BuilderRoot<Builder>] extends [never] ? EntityRoot<Entity> : BuilderRoot<Builder>;
 export {};

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

@@ -54,8 +54,9 @@ export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(buil
  * 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. An alias of the query without
- * metadata (a subquery or a CTE in FROM or a join) is quoted unless `useQuotes` is `false`:
- * TypeORM leaves its keys as written, and PostgreSQL folds an unquoted `cte.firstName` to `firstname`.
+ * 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.
  */
 export declare function getTypedSelectionKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, selection: KeyProxyCallback<Type> | string, useQuotes?: boolean, columnsFor?: string): string | string[];

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

@@ -70,12 +70,13 @@ function deferColumnKey(aliasName, separator, 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; as written on an unknown alias.
+ *   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 = (alias === null || alias === void 0 ? void 0 : alias.hasMetadata) ? alias.metadata : undefined;
     if (separator === DEFERRED_UNQUOTED) {
-        return metadata || !alias ? `${aliasName}.${name}` : `${escape(aliasName)}.${escape(name)}`;
+        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;
@@ -403,8 +404,9 @@ function isAliasWithoutMetadata(queryBuilder, aliasName) {
  * 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. An alias of the query without
- * metadata (a subquery or a CTE in FROM or a join) is quoted unless `useQuotes` is `false`:
- * TypeORM leaves its keys as written, and PostgreSQL folds an unquoted `cte.firstName` to `firstname`.
+ * 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, columnsFor) {

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[];

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

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBareReservedQualifiers = exports.scanReservedQualifiers = exports.toReservedWordSet = exports.COCKROACHDB_RESERVED_KEY_WORDS = exports.POSTGRES_RESERVED_KEY_WORDS = void 0;
+/**
+ * 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)`.
+ */
+exports.POSTGRES_RESERVED_KEY_WORDS = Object.freeze([
+    'ALL', 'ANALYSE', 'ANALYZE', 'AND', 'ANY', 'ARRAY', 'AS', 'ASC', 'ASYMMETRIC', 'BOTH', 'CASE', 'CAST', 'CHECK',
+    'COLLATE', 'COLUMN', 'CONSTRAINT', 'CREATE', 'CURRENT_CATALOG', 'CURRENT_DATE', 'CURRENT_ROLE', 'CURRENT_TIME',
+    'CURRENT_TIMESTAMP', 'CURRENT_USER', 'DEFAULT', 'DEFERRABLE', 'DESC', 'DISTINCT', 'DO', 'ELSE', 'END', 'EXCEPT',
+    'FALSE', 'FETCH', 'FOR', 'FOREIGN', 'FROM', 'GRANT', 'GROUP', 'HAVING', 'IN', 'INITIALLY', 'INTERSECT', 'INTO',
+    'LATERAL', 'LEADING', 'LIMIT', 'LOCALTIME', 'LOCALTIMESTAMP', 'NOT', 'NULL', 'OFFSET', 'ON', 'ONLY', 'OR', 'ORDER',
+    'PLACING', 'PRIMARY', 'REFERENCES', 'RETURNING', 'SELECT', 'SESSION_USER', 'SOME', 'SYMMETRIC', 'SYSTEM_USER',
+    'TABLE', 'THEN', 'TO', 'TRAILING', 'TRUE', 'UNION', 'UNIQUE', 'USER', 'USING', 'VARIADIC', 'WHEN', 'WHERE',
+    'WINDOW', 'WITH',
+]);
+/** The reserved key words of CockroachDB: PostgreSQL's without `SYSTEM_USER`, with `CONCURRENTLY` and `CURRENT_SCHEMA`. */
+exports.COCKROACHDB_RESERVED_KEY_WORDS = Object.freeze([
+    ...exports.POSTGRES_RESERVED_KEY_WORDS.filter((word) => word !== 'SYSTEM_USER'),
+    'CONCURRENTLY',
+    'CURRENT_SCHEMA',
+]);
+const KEY_WORD = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+const wordSets = new WeakMap();
+/** The words in lower case; cached for a frozen list, such as the defaults, which can't change afterwards. */
+function toReservedWordSet(words) {
+    const cached = wordSets.get(words);
+    if (cached) {
+        return cached;
+    }
+    if (!Array.isArray(words)) {
+        throw new TypeError(`Reserved words must be an array of key words, got ${typeof words}`);
+    }
+    for (const word of words) {
+        if (typeof word !== 'string' || !KEY_WORD.test(word)) {
+            throw new TypeError(`Invalid reserved word ${JSON.stringify(word)}: expected a key word, such as "order"`);
+        }
+    }
+    const set = new Set(words.map((word) => word.toLowerCase()));
+    if (Object.isFrozen(words)) {
+        wordSets.set(words, set);
+    }
+    return set;
+}
+exports.toReservedWordSet = toReservedWordSet;
+const TAB = 9;
+const CARRIAGE_RETURN = 13;
+const LINE_FEED = 10;
+const SPACE = 32;
+const DOUBLE_QUOTE = 34;
+const DOLLAR = 36;
+const QUOTE = 39;
+const STAR = 42;
+const DASH = 45;
+const DOT = 46;
+const SLASH = 47;
+const COLON = 58;
+const BACKSLASH = 92;
+const isSpace = (code) => code === SPACE || (code >= TAB && code <= CARRIAGE_RETURN);
+const isDigit = (code) => code >= 48 && code <= 57;
+// as PostgreSQL reads identifiers: letters, `_` and every non-ASCII character; then digits and `$` too
+const isIdentifierStart = (code) => (code >= 97 && code <= 122) || (code >= 65 && code <= 90) || code === 95 || code >= 128;
+const isIdentifierPart = (code) => isIdentifierStart(code) || isDigit(code) || code === DOLLAR;
+/** Index after the string literal whose opening quote is at `start`; `E'…'` strings take backslash escapes. */
+function skipString(sql, start, backslashEscapes) {
+    for (let i = start + 1; i < sql.length; i++) {
+        const code = sql.charCodeAt(i);
+        if (backslashEscapes && code === BACKSLASH) {
+            i++;
+        }
+        else if (code === QUOTE) {
+            if (sql.charCodeAt(i + 1) !== QUOTE) {
+                return i + 1;
+            }
+            i++;
+        }
+    }
+    return sql.length;
+}
+function skipQuotedIdentifier(sql, start) {
+    for (let i = start + 1; i < sql.length; i++) {
+        if (sql.charCodeAt(i) === DOUBLE_QUOTE) {
+            if (sql.charCodeAt(i + 1) !== DOUBLE_QUOTE) {
+                return i + 1;
+            }
+            i++;
+        }
+    }
+    return sql.length;
+}
+function skipLineComment(sql, start) {
+    for (let i = start + 2; i < sql.length; i++) {
+        const code = sql.charCodeAt(i);
+        if (code === LINE_FEED || code === CARRIAGE_RETURN) {
+            return i;
+        }
+    }
+    return sql.length;
+}
+// PostgreSQL nests block comments: `/* a /* b */ c */` is one comment
+function skipBlockComment(sql, start) {
+    let depth = 0;
+    let i = start;
+    while (i < sql.length) {
+        const code = sql.charCodeAt(i);
+        const next = sql.charCodeAt(i + 1);
+        if (code === SLASH && next === STAR) {
+            depth++;
+            i += 2;
+        }
+        else if (code === STAR && next === SLASH) {
+            depth--;
+            i += 2;
+            if (depth === 0) {
+                return i;
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return sql.length;
+}
+/** Index after the opening tag of a dollar-quoted string at `start` (`$$`, `$tag$`); -1 for a parameter (`$1`). */
+function dollarTagEnd(sql, start) {
+    let i = start + 1;
+    if (isIdentifierStart(sql.charCodeAt(i))) {
+        do {
+            i++;
+        } while (isIdentifierStart(sql.charCodeAt(i)) || isDigit(sql.charCodeAt(i)));
+    }
+    return sql.charCodeAt(i) === DOLLAR ? i + 1 : -1;
+}
+/**
+ * Whether the word from `start` to `end` qualifies a name: a dot follows it, after optional whitespace, and not a
+ * number (`THEN .5`); and it isn't itself a name after a dot (`public.order.id`), next to a quoted name or an
+ * identifier character, or a named parameter (`:order`, but `::` is a cast).
+ */
+function isQualifier(sql, start, end, previous) {
+    let next = end;
+    while (isSpace(sql.charCodeAt(next))) {
+        next++;
+    }
+    if (sql.charCodeAt(next) !== DOT || isDigit(sql.charCodeAt(next + 1)) || previous === DOT) {
+        return false;
+    }
+    const before = sql.charCodeAt(start - 1);
+    return (before !== DOUBLE_QUOTE &&
+        !isIdentifierPart(before) &&
+        !(before === COLON && sql.charCodeAt(start - 2) !== COLON));
+}
+const SNIPPET_CONTEXT = 30;
+// cut at whitespace, not inside a word, when the context has some
+function snippetAt(sql, start, end) {
+    let from = Math.max(0, start - SNIPPET_CONTEXT);
+    let to = Math.min(sql.length, end + SNIPPET_CONTEXT);
+    if (from > 0) {
+        const space = sql.slice(from, start).search(/\s/);
+        if (space !== -1) {
+            from += space + 1;
+        }
+    }
+    if (to < sql.length) {
+        const space = sql.slice(end, to).search(/\s\S*$/);
+        if (space !== -1) {
+            to = end + space;
+        }
+    }
+    return `${from > 0 ? '…' : ''}${sql.slice(from, to).replace(/\s+/g, ' ')}${to < sql.length ? '…' : ''}`;
+}
+/** `findBareReservedQualifiers` with the words as a set of lower-case words (`toReservedWordSet`). */
+function scanReservedQualifiers(sql, words) {
+    const found = [];
+    const length = sql.length;
+    // the last character outside whitespace and comments
+    let previous = -1;
+    let i = 0;
+    while (i < length) {
+        const code = sql.charCodeAt(i);
+        if (isSpace(code)) {
+            i++;
+        }
+        else if (code === DASH && sql.charCodeAt(i + 1) === DASH) {
+            i = skipLineComment(sql, i);
+        }
+        else if (code === SLASH && sql.charCodeAt(i + 1) === STAR) {
+            i = skipBlockComment(sql, i);
+        }
+        else if (code === QUOTE) {
+            i = skipString(sql, i, false);
+            previous = code;
+        }
+        else if (code === DOUBLE_QUOTE) {
+            i = skipQuotedIdentifier(sql, i);
+            previous = code;
+        }
+        else if (code === DOLLAR) {
+            const tagEnd = dollarTagEnd(sql, i);
+            if (tagEnd === -1) {
+                do {
+                    i++;
+                } while (isDigit(sql.charCodeAt(i)));
+            }
+            else {
+                const close = sql.indexOf(sql.slice(i, tagEnd), tagEnd);
+                i = close === -1 ? length : close + (tagEnd - i);
+            }
+            previous = code;
+        }
+        else if (isIdentifierPart(code)) {
+            const start = i;
+            do {
+                i++;
+            } while (isIdentifierPart(sql.charCodeAt(i)));
+            // E'…', the string literal with backslash escapes
+            if (i - start === 1 && (code === 69 || code === 101) && sql.charCodeAt(i) === QUOTE) {
+                i = skipString(sql, i, true);
+                previous = QUOTE;
+                continue;
+            }
+            if (isIdentifierStart(code) &&
+                isQualifier(sql, start, i, previous) &&
+                words.has(sql.slice(start, i).toLowerCase())) {
+                found.push({ word: sql.slice(start, i), index: start, snippet: snippetAt(sql, start, i) });
+            }
+            previous = code;
+        }
+        else {
+            previous = code;
+            i++;
+        }
+    }
+    return found;
+}
+exports.scanReservedQualifiers = scanReservedQualifiers;
+/**
+ * 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
+ */
+function findBareReservedQualifiers(sql, words = exports.POSTGRES_RESERVED_KEY_WORDS) {
+    return scanReservedQualifiers(sql, toReservedWordSet(words));
+}
+exports.findBareReservedQualifiers = findBareReservedQualifiers;