typeorm-extensions 1.3.5 → 2.1.0

package/dist/utils/cursor.utils.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKeysetCondition = exports.getTextCastType = exports.supportsRowValueComparison = exports.decodeCursor = exports.encodeCursor = exports.InvalidCursorError = void 0;
+const sql_utils_1 = require("./sql.utils");
+/** A cursor that can't be decoded or doesn't belong to the query's order (e.g. tampered with). */
+class InvalidCursorError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCursorError';
+    }
+}
+exports.InvalidCursorError = InvalidCursorError;
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+const toCursorValue = (value) => {
+    if (isDate(value)) {
+        return { $date: value.toISOString() };
+    }
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    return value;
+};
+// base64url of UTF-8 text, with the globals of Node 16+ and browsers (no Buffer, no @types/node)
+const toBase64Url = (text) => {
+    let binary = '';
+    new TextEncoder().encode(text).forEach((byte) => (binary += String.fromCharCode(byte)));
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+const fromBase64Url = (value) => {
+    if (!/^[A-Za-z0-9_-]*$/.test(value)) {
+        throw new InvalidCursorError('Invalid cursor: not base64url');
+    }
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+    return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+};
+/** base64url-encoded JSON of the key fields and the key values of the last row. */
+function encodeCursor(fields, values) {
+    const payload = { k: fields, v: values.map(toCursorValue) };
+    return toBase64Url(JSON.stringify(payload));
+}
+exports.encodeCursor = encodeCursor;
+const isCursorValue = (value) => typeof value === 'string' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    typeof value === 'boolean' ||
+    (typeof value === 'object' &&
+        value !== null &&
+        typeof value.$date === 'string');
+/** Key values of a cursor made for `fields`; throws `InvalidCursorError` otherwise. */
+function decodeCursor(cursor, fields) {
+    let payload;
+    try {
+        payload = JSON.parse(fromBase64Url(cursor));
+    }
+    catch {
+        throw new InvalidCursorError('Invalid cursor: it could not be decoded');
+    }
+    if (!payload ||
+        !Array.isArray(payload.k) ||
+        !Array.isArray(payload.v) ||
+        payload.k.length !== fields.length ||
+        payload.v.length !== fields.length ||
+        payload.k.some((field, i) => field !== fields[i]) ||
+        !payload.v.every(isCursorValue)) {
+        throw new InvalidCursorError(`Invalid cursor: it was not made for the order (${fields.join(', ')})`);
+    }
+    return payload.v.map((value) => {
+        if (typeof value !== 'object') {
+            return value;
+        }
+        const date = new Date(value.$date);
+        if (isNaN(date.getTime())) {
+            throw new InvalidCursorError('Invalid cursor: invalid date');
+        }
+        return date;
+    });
+}
+exports.decodeCursor = decodeCursor;
+/** Databases that compare row values: `(a, b) < (1, 2)`. */
+const supportsRowValueComparison = (driver) => driver === 'postgres' ||
+    driver === 'aurora-postgres' ||
+    driver === 'cockroachdb' ||
+    (0, sql_utils_1.isMysqlLikeDriver)(driver) ||
+    (0, sql_utils_1.isSqliteLikeDriver)(driver);
+exports.supportsRowValueComparison = supportsRowValueComparison;
+/**
+ * Type to read a date / time column as text with, so the cursor keeps the database's own precision
+ * (PostgreSQL timestamps have microseconds, a JS Date only milliseconds). `undefined` when unknown.
+ */
+const getTextCastType = (driver) => {
+    if (driver === 'postgres' || driver === 'aurora-postgres' || driver === 'cockroachdb' || (0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        return 'text';
+    }
+    if ((0, sql_utils_1.isMysqlLikeDriver)(driver)) {
+        return 'char';
+    }
+    if (driver === 'mssql') {
+        return 'nvarchar(max)';
+    }
+    return undefined;
+};
+exports.getTextCastType = getTextCastType;
+/**
+ * WHERE condition for the rows after the cursor:
+ * - same direction everywhere, on databases with row values: `(a, b) > (:a, :b)`
+ * - otherwise: `a >= :a AND (a > :a OR (a = :a AND b < :b))`, where the leading bound lets an index on `a` be used
+ */
+function buildKeysetCondition(keys, useRowValues) {
+    const operator = (key) => (key.direction === 'ASC' ? '>' : '<');
+    if (keys.length === 1) {
+        const [key] = keys;
+        return `${key.column} ${operator(key)} :${key.paramName}`;
+    }
+    if (useRowValues && keys.every((key) => key.direction === keys[0].direction)) {
+        const columns = keys.map((key) => key.column).join(', ');
+        const params = keys.map((key) => `:${key.paramName}`).join(', ');
+        return `(${columns}) ${operator(keys[0])} (${params})`;
+    }
+    const expand = (index) => {
+        const key = keys[index];
+        const after = `${key.column} ${operator(key)} :${key.paramName}`;
+        if (index === keys.length - 1) {
+            return after;
+        }
+        return `(${after} OR (${key.column} = :${key.paramName} AND ${expand(index + 1)}))`;
+    };
+    const [first] = keys;
+    return `(${first.column} ${operator(first)}= :${first.paramName} AND ${expand(0)})`;
+}
+exports.buildKeysetCondition = buildKeysetCondition;

package/dist/utils/json-path.utils.d.ts

@@ -0,0 +1,22 @@
+import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
+import type { DatabaseType } from 'typeorm';
+/** `->>` gives the value as text (as an SQL value on SQLite), `->` as JSON. */
+export type JsonAccessor = 'text' | 'json';
+export declare const isJsonColumn: (column: ColumnMetadata) => boolean;
+/** `-> 'settings' ->> 'theme'`: every key but the last one with `->`, the last one with `jsonOperator`. */
+export declare function buildJsonPath(fieldNames: readonly string[], jsonOperator: '->>' | '->'): string;
+export interface JsonPathSqlOptions {
+    /** Defaults to `'text'`. */
+    accessor?: JsonAccessor;
+    /** The value the path is compared with: on PostgreSQL a `'text'` path is cast to its type. */
+    value?: unknown;
+    /** Compares a `'text'` path as a timestamp whatever `value` is, since a period also takes date strings. */
+    asTimestamp?: boolean;
+}
+/**
+ * SQL for a path inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'`, cast on PostgreSQL to the
+ * type of the compared value (`CAST(… AS numeric)`). A `simple-json` column is text there, so it is cast to
+ * `jsonb` first. SQLite (3.38+) has the same operators, and `->>` gives SQL values, so it needs no cast, except
+ * for a timestamp: there it is rewritten in the format TypeORM stores dates and binds `Date` parameters in.
+ */
+export declare function toJsonPathSql(driver: DatabaseType | undefined, columnSql: string, column: ColumnMetadata, jsonPath: readonly string[], { accessor, value, asTimestamp }?: JsonPathSqlOptions): string;

package/dist/utils/json-path.utils.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonPathSql = exports.buildJsonPath = exports.isJsonColumn = void 0;
+const sql_utils_1 = require("./sql.utils");
+const JSON_COLUMN_TYPES = ['json', 'jsonb', 'simple-json'];
+const isJsonColumn = (column) => JSON_COLUMN_TYPES.includes(String(column.type));
+exports.isJsonColumn = isJsonColumn;
+/** Wraps a JSON key in single quotes, doubling any quote inside it (standard SQL string literal). */
+const toJsonKeyLiteral = (fieldName) => `'${String(fieldName).replace(/'/g, "''")}'`;
+/** `-> 'settings' ->> 'theme'`: every key but the last one with `->`, the last one with `jsonOperator`. */
+function buildJsonPath(fieldNames, jsonOperator) {
+    return fieldNames
+        .map((fieldName, index) => `${index === fieldNames.length - 1 ? jsonOperator : '->'} ${toJsonKeyLiteral(fieldName)}`)
+        .join(' ');
+}
+exports.buildJsonPath = buildJsonPath;
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+/**
+ * PostgreSQL type to compare a `->>` value (text) with `value` as: text compares `'9' >= '10'` as true.
+ * An array (IN, ANY) is typed by its first value; strings and unknown values stay text.
+ */
+function getJsonTextCast(value) {
+    const sample = Array.isArray(value) ? value.find((item) => item !== null && item !== undefined) : value;
+    if (typeof sample === 'number' || typeof sample === 'bigint') {
+        return 'numeric';
+    }
+    if (typeof sample === 'boolean') {
+        return 'boolean';
+    }
+    if (isDate(sample)) {
+        return 'timestamptz';
+    }
+    return undefined;
+}
+/**
+ * SQL for a path inside a JSON column: `"exec"."details" -> 'meta' ->> 'endTs'`, cast on PostgreSQL to the
+ * type of the compared value (`CAST(… AS numeric)`). A `simple-json` column is text there, so it is cast to
+ * `jsonb` first. SQLite (3.38+) has the same operators, and `->>` gives SQL values, so it needs no cast, except
+ * for a timestamp: there it is rewritten in the format TypeORM stores dates and binds `Date` parameters in.
+ */
+function toJsonPathSql(driver, columnSql, column, jsonPath, { accessor = 'text', value, asTimestamp = false } = {}) {
+    const path = buildJsonPath(jsonPath, accessor === 'json' ? '->' : '->>');
+    const isTimestamp = asTimestamp && accessor === 'text';
+    if ((0, sql_utils_1.isSqliteLikeDriver)(driver)) {
+        const sql = `${columnSql} ${path}`;
+        return isTimestamp ? `strftime('%Y-%m-%d %H:%M:%f', ${sql})` : sql;
+    }
+    if (!(0, sql_utils_1.isPostgresLikeDriver)(driver)) {
+        throw new TypeError(`Typed keys into a JSON column (${column.propertyPath}.${jsonPath.join('.')}) are supported on PostgreSQL and SQLite, ` +
+            `not on ${driver !== null && driver !== void 0 ? driver : 'a query without a connection'}`);
+    }
+    const source = String(column.type) === 'simple-json' ? `CAST(${columnSql} AS jsonb)` : columnSql;
+    const sql = `${source} ${path}`;
+    const cast = isTimestamp ? 'timestamptz' : accessor === 'text' ? getJsonTextCast(value) : undefined;
+    return cast ? `CAST(${sql} AS ${cast})` : sql;
+}
+exports.toJsonPathSql = toJsonPathSql;

package/dist/utils/order.utils.d.ts

@@ -0,0 +1,15 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { OrderDirection } from '../types/interfaces/ordering.interface';
+import type { ArgsType } from '../types/util-types';
+/**
+ * `'ASC'` / `'DESC'` for any `OrderDirection`: `'asc'` / `'desc'` in any case, `1` / `-1`,
+ * `true` (ASC) / `false` (DESC). Anything else is the default direction (ASC).
+ */
+export declare function toSqlOrderDirection(direction: OrderDirection | undefined | null): 'ASC' | 'DESC';
+/**
+ * Selects `array_position(:values, column)` under a generated alias and orders by that alias.
+ * TypeORM can't order by a function expression together with `take` and joins
+ * (`"array_position(…" alias was not found`), but it can order by a selection alias.
+ * `column` is already quoted.
+ */
+export declare function attachOrderByArrayPosition<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, column: string, values: ArgsType, arrayType: string | undefined, replace: boolean): SelectQueryBuilder<Entity>;

package/dist/utils/order.utils.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachOrderByArrayPosition = exports.toSqlOrderDirection = void 0;
+const constants_1 = require("../constants");
+const sql_utils_1 = require("./sql.utils");
+/**
+ * `'ASC'` / `'DESC'` for any `OrderDirection`: `'asc'` / `'desc'` in any case, `1` / `-1`,
+ * `true` (ASC) / `false` (DESC). Anything else is the default direction (ASC).
+ */
+function toSqlOrderDirection(direction) {
+    if (typeof direction === 'boolean') {
+        return direction ? 'ASC' : 'DESC';
+    }
+    if (typeof direction === 'number') {
+        return direction === -1 ? 'DESC' : 'ASC';
+    }
+    if (typeof direction === 'string' && /asc|desc/i.test(direction)) {
+        return direction.toUpperCase();
+    }
+    return constants_1.defaultOrderDirection;
+}
+exports.toSqlOrderDirection = toSqlOrderDirection;
+/**
+ * Selects `array_position(:values, column)` under a generated alias and orders by that alias.
+ * TypeORM can't order by a function expression together with `take` and joins
+ * (`"array_position(…" alias was not found`), but it can order by a selection alias.
+ * `column` is already quoted.
+ */
+function attachOrderByArrayPosition(builder, column, values, arrayType, replace) {
+    if (!Array.isArray(values)) {
+        throw new TypeError(`orderByArrayPosition on "${column}" expects an array of values, got ${values}`);
+    }
+    const castTo = arrayType === undefined ? undefined : (0, sql_utils_1.assertArrayType)(arrayType);
+    const paramName = (0, sql_utils_1.createUniqueParameterName)('position');
+    // lower case: PostgreSQL folds the unquoted alias in ORDER BY
+    const selectionAlias = `array_${paramName}`.toLowerCase();
+    const parameter = castTo ? `CAST(:${paramName} AS ${castTo})` : `:${paramName}`;
+    builder
+        .addSelect(`array_position(${parameter}, ${column})`, selectionAlias)
+        .setParameter(paramName, values);
+    return replace
+        ? builder.orderBy(selectionAlias, 'ASC', 'NULLS LAST')
+        : builder.addOrderBy(selectionAlias, 'ASC', 'NULLS LAST');
+}
+exports.attachOrderByArrayPosition = attachOrderByArrayPosition;

package/dist/utils/period.utils.d.ts

@@ -0,0 +1,9 @@
+import type { WhereExpressionBuilder } from 'typeorm';
+import type { PeriodFilter } from '../types/interfaces/period.interface';
+import type { ApplyPeriodOptions } from '../types/extensions/period.types';
+/**
+ * Adds `column >= :periodFrom` and `column <= :periodTo` conditions (or their exclusive versions) with
+ * AND, so the filter narrows whatever WHERE conditions the query already has, OR ones included:
+ * `(a OR b) AND column >= …`. `column` is already quoted.
+ */
+export declare function attachPeriodFilter<QB extends WhereExpressionBuilder>(builder: QB, column: string, periodFilter: PeriodFilter | null | undefined, options?: ApplyPeriodOptions): QB;

package/dist/utils/period.utils.js

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

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

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

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

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

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

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