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

package/dist/types/extensions/cursor-pagination.types.d.ts

@@ -1,4 +1,5 @@
 import type { CursorOrderParam } from '../interfaces/cursor-pagination.interface';
+import type { OrderType } from '../interfaces/ordering.interface';
 export type GetManyWithCursorOptions<Entity> = {
     /**
      * Columns that order the rows, e.g. `[{ field: 'createdAt', direction: 'DESC' }]`.
@@ -18,4 +19,8 @@ export interface ListWithCursor<Entity> {
      * keyset query loads `pageSize + 1` rows, so it needs no total. Equivalent to `nextCursor !== null`.
      */
     hasMore: boolean;
+    /** The page size used: the `pageSize` given, rounded down, or `10` when it was missing or below 1. */
+    pageSize: number;
+    /** The ORDER BY the page was read in: the `orderBy` columns, then the primary key columns not among them. */
+    orderBy: OrderType[];
 }

package/dist/types/extensions/get-many-with-totals.types.d.ts

@@ -18,6 +18,10 @@ export type GetRawManyWithTotalsOptions = Omit<GetManyWithTotalsOptions, 'useTak
 export interface ListWithTotals<Entity> {
     list: Entity[];
     total: number | null;
+    /** The page read, 1-based: the `page` given, or `1` when it was missing or below 1. `null` with `loadAll`. */
+    page: number | null;
+    /** The page size used: the `pageSize` given, or `10` when it was missing or below 1. `null` with `loadAll`. */
+    pageSize: number | null;
     limit: number | null;
     offset: number | null;
     /**

package/dist/utils/calculated-column.utils.d.ts

@@ -1,10 +1,14 @@
 import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
+/** `addSelect`'s selection: an SQL expression, or a factory that builds a subquery on the builder it is given. */
+export type CalculatedSelection<SubEntity extends ObjectLiteral = ObjectLiteral> = string | ((qb: SelectQueryBuilder<ObjectLiteral>) => SelectQueryBuilder<SubEntity>);
 type ResolvedCalculatedColumn = {
     /** The key TypeORM reads the column's value from when it builds the entity. */
     key: string;
     /** `Entity.property`, for error messages. */
     label: string;
 };
+export declare const isCalculated: (column: ColumnMetadata | undefined) => column is ColumnMetadata;
 /** Whether `property` of the entity of `aliasName` (the main alias by default) is a `@CalculatedColumn`. */
 export declare function isCalculatedColumn<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, property: string, aliasName?: string): boolean;
 /** The `@CalculatedColumn` `property` of the entity of `aliasName`; throws a `TypeError` for anything else. */
@@ -18,4 +22,8 @@ export declare function resolveCalculatedColumn<Entity extends ObjectLiteral>(bu
  * through with `take` / `skip` and joins, which takes only select aliases it knows unquoted.
  */
 export declare function selectCalculatedForOrder<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, property: string, aliasName: string | undefined, methodName: string): string;
+/** Selects `selection` into the `@CalculatedColumn` `property` of the entity of `aliasName` (the main alias by default). */
+export declare function addSelectCalculatedColumn<Entity extends ObjectLiteral, SubEntity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, selection: CalculatedSelection<SubEntity>, property: string, aliasName: string | undefined, methodName: string): SelectQueryBuilder<Entity>;
+/** ORDER BY the value of a `@CalculatedColumn` selected with `addSelectCalculated`, through `orderBy` or `addOrderBy`. */
+export declare function orderByCalculatedColumn<Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, method: 'orderBy' | 'addOrderBy', property: string, order: 'ASC' | 'DESC' | undefined, nulls: 'NULLS FIRST' | 'NULLS LAST' | undefined, aliasName: string | undefined, methodName: string): SelectQueryBuilder<Entity>;
 export {};

package/dist/utils/calculated-column.utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectCalculatedForOrder = exports.resolveCalculatedColumn = exports.isCalculatedColumn = void 0;
+exports.orderByCalculatedColumn = exports.addSelectCalculatedColumn = exports.selectCalculatedForOrder = exports.resolveCalculatedColumn = exports.isCalculatedColumn = exports.isCalculated = void 0;
 const DriverUtils_1 = require("typeorm/driver/DriverUtils");
 const sql_utils_1 = require("./sql.utils");
 function findCalculatedColumn(builder, property, aliasName) {
@@ -19,10 +19,11 @@ function findCalculatedColumn(builder, property, aliasName) {
 }
 // @CalculatedColumn: a virtual property without the query of TypeORM's @VirtualColumn
 const isCalculated = (column) => !!(column === null || column === void 0 ? void 0 : column.isVirtualProperty) && !column.query;
+exports.isCalculated = isCalculated;
 /** Whether `property` of the entity of `aliasName` (the main alias by default) is a `@CalculatedColumn`. */
 function isCalculatedColumn(builder, property, aliasName) {
     var _a;
-    return isCalculated((_a = findCalculatedColumn(builder, property, aliasName)) === null || _a === void 0 ? void 0 : _a.column);
+    return (0, exports.isCalculated)((_a = findCalculatedColumn(builder, property, aliasName)) === null || _a === void 0 ? void 0 : _a.column);
 }
 exports.isCalculatedColumn = isCalculatedColumn;
 /** The `@CalculatedColumn` `property` of the entity of `aliasName`; throws a `TypeError` for anything else. */
@@ -33,7 +34,7 @@ function resolveCalculatedColumn(builder, property, aliasName, methodName) {
         throw new TypeError(`${methodName}: the alias "${aliasName !== null && aliasName !== void 0 ? aliasName : (_a = builder.expressionMap.mainAlias) === null || _a === void 0 ? void 0 : _a.name}" has no entity with "${property}"`);
     }
     const label = `${found.entityName}.${property}`;
-    if (!isCalculated(found.column)) {
+    if (!(0, exports.isCalculated)(found.column)) {
         throw new TypeError(`${methodName}: ${label} is not a @CalculatedColumn`);
     }
     // shortened past the driver's alias length limit, as TypeORM does it
@@ -61,3 +62,19 @@ function selectCalculatedForOrder(builder, property, aliasName, methodName) {
     return orderAlias;
 }
 exports.selectCalculatedForOrder = selectCalculatedForOrder;
+/** Selects `selection` into the `@CalculatedColumn` `property` of the entity of `aliasName` (the main alias by default). */
+function addSelectCalculatedColumn(builder, selection, property, aliasName, methodName) {
+    const { key } = resolveCalculatedColumn(builder, property, aliasName, methodName);
+    // two calls: addSelect's overloads take a string or a factory, not their union
+    if (typeof selection === 'function') {
+        return builder.addSelect(selection, key);
+    }
+    return builder.addSelect(selection, key);
+}
+exports.addSelectCalculatedColumn = addSelectCalculatedColumn;
+/** ORDER BY the value of a `@CalculatedColumn` selected with `addSelectCalculated`, through `orderBy` or `addOrderBy`. */
+function orderByCalculatedColumn(builder, method, property, order, nulls, aliasName, methodName) {
+    const orderAlias = selectCalculatedForOrder(builder, property, aliasName, methodName);
+    return builder[method](orderAlias, order, nulls);
+}
+exports.orderByCalculatedColumn = orderByCalculatedColumn;

package/dist/utils/common.utils.d.ts

@@ -1,2 +1,4 @@
+/** A Date, also one from another realm (a vm context, a test runner's sandbox), where `instanceof Date` is false. */
+export declare const isDate: (value: unknown) => value is Date;
 export declare const isNil: (val: unknown) => boolean;
 export declare function randomString(length?: number): string;

package/dist/utils/common.utils.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.randomString = exports.isNil = void 0;
+exports.randomString = exports.isNil = exports.isDate = void 0;
+/** A Date, also one from another realm (a vm context, a test runner's sandbox), where `instanceof Date` is false. */
+const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
+exports.isDate = isDate;
 const isNil = (val) => typeof val === 'undefined' || val === null;
 exports.isNil = isNil;
 function randomString(length = 21) {

package/dist/utils/cursor.utils.js

@@ -2,6 +2,7 @@
 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");
+const common_utils_1 = require("./common.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) {
@@ -10,9 +11,8 @@ class InvalidCursorError extends TypeError {
     }
 }
 exports.InvalidCursorError = InvalidCursorError;
-const isDate = (value) => Object.prototype.toString.call(value) === '[object Date]';
 const toCursorValue = (value) => {
-    if (isDate(value)) {
+    if ((0, common_utils_1.isDate)(value)) {
         return { $date: value.toISOString() };
     }
     if (typeof value === 'bigint') {
@@ -77,9 +77,7 @@ function decodeCursor(cursor, fields) {
 }
 exports.decodeCursor = decodeCursor;
 /** Databases that compare row values: `(a, b) < (1, 2)`. */
-const supportsRowValueComparison = (driver) => driver === 'postgres' ||
-    driver === 'aurora-postgres' ||
-    driver === 'cockroachdb' ||
+const supportsRowValueComparison = (driver) => (0, sql_utils_1.isPostgresLikeDriver)(driver) ||
     (0, sql_utils_1.isMysqlLikeDriver)(driver) ||
     (0, sql_utils_1.isSqliteLikeDriver)(driver);
 exports.supportsRowValueComparison = supportsRowValueComparison;
@@ -88,7 +86,7 @@ exports.supportsRowValueComparison = supportsRowValueComparison;
  * (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)) {
+    if ((0, sql_utils_1.isPostgresLikeDriver)(driver) || (0, sql_utils_1.isSqliteLikeDriver)(driver)) {
         return 'text';
     }
     if ((0, sql_utils_1.isMysqlLikeDriver)(driver)) {

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toJsonPathSql = exports.buildJsonPath = exports.isJsonColumn = void 0;
 const sql_utils_1 = require("./sql.utils");
+const common_utils_1 = require("./common.utils");
 const JSON_COLUMN_TYPES = ['json', 'jsonb', 'simple-json'];
 const isJsonColumn = (column) => JSON_COLUMN_TYPES.includes(String(column.type));
 exports.isJsonColumn = isJsonColumn;
@@ -14,7 +15,6 @@ function buildJsonPath(fieldNames, jsonOperator) {
         .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.
@@ -27,7 +27,7 @@ function getJsonTextCast(value) {
     if (typeof sample === 'boolean') {
         return 'boolean';
     }
-    if (isDate(sample)) {
+    if ((0, common_utils_1.isDate)(sample)) {
         return 'timestamptz';
     }
     return undefined;

package/dist/utils/pagination.utils.d.ts

@@ -1,5 +1,12 @@
+import type { ObjectLiteral, SelectQueryBuilder } from "typeorm";
 import { PaginationFilter } from "../types/interfaces/pagination.interface";
+/** The page size to read: a number or a numeric string of at least 1, rounded down; `defaultPageSize` otherwise. */
+export declare const normalizePageSize: (pageSize: unknown) => number;
+/** Limits the rows with `take`, which counts entities rather than rows when the query joins a collection, or with `limit`. */
+export declare const setPageLimit: <Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, limit: number, useTakeAndSkip: boolean) => SelectQueryBuilder<Entity>;
 export declare const getLimitAndOffset: ({ page, pageSize }: PaginationFilter) => {
     limit: number;
     offset: number;
+    page: number;
+    pageSize: number;
 };

package/dist/utils/pagination.utils.js

@@ -1,16 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLimitAndOffset = void 0;
+exports.getLimitAndOffset = exports.setPageLimit = exports.normalizePageSize = void 0;
 const constants_1 = require("../constants");
+// an unparsed query parameter is a string: "20" + 1 would be "201"
+const toPositiveInteger = (value, fallback) => {
+    const number = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof number === 'number' && Number.isFinite(number) && number >= 1 ? Math.floor(number) : fallback;
+};
+/** The page size to read: a number or a numeric string of at least 1, rounded down; `defaultPageSize` otherwise. */
+const normalizePageSize = (pageSize) => toPositiveInteger(pageSize, constants_1.defaultPageSize);
+exports.normalizePageSize = normalizePageSize;
+/** Limits the rows with `take`, which counts entities rather than rows when the query joins a collection, or with `limit`. */
+const setPageLimit = (builder, limit, useTakeAndSkip) => (useTakeAndSkip ? builder.take(limit) : builder.limit(limit));
+exports.setPageLimit = setPageLimit;
 const getLimitAndOffset = ({ page, pageSize }) => {
-    if (!page || page < 1) {
-        page = 1;
-    }
-    if (!pageSize || pageSize < 1) {
-        pageSize = constants_1.defaultPageSize;
-    }
-    const offset = (page >= 1 ? page - 1 : 0) * pageSize;
-    const limit = pageSize;
-    return { limit, offset };
+    const normalizedPage = toPositiveInteger(page, 1);
+    const normalizedPageSize = (0, exports.normalizePageSize)(pageSize);
+    return {
+        limit: normalizedPageSize,
+        offset: (normalizedPage - 1) * normalizedPageSize,
+        page: normalizedPage,
+        pageSize: normalizedPageSize,
+    };
 };
 exports.getLimitAndOffset = getLimitAndOffset;

package/dist/utils/parameter.utils.d.ts

@@ -1,7 +1,17 @@
 import type { ObjectLiteral } from 'typeorm';
+/** The parameter names an SQL fragment refers to, as TypeORM reads its placeholders. */
+export declare function getPlaceholderNames(sql: string): string[];
 /**
  * Renames the parameters of a subquery to unique names, in its SQL and in its parameters. A query
  * has one parameter namespace, so two subqueries with a `:status` each would otherwise both read
  * whichever value was set last. Placeholders that aren't keys of `parameters` stay as they are.
  */
 export declare function withUniqueParameterNames(sql: string, parameters: ObjectLiteral): [string, ObjectLiteral];
+/**
+ * The SQL of a query, without the parentheses a `subQuery()` builder writes around itself, and its parameters, both
+ * renamed unique (see `withUniqueParameterNames`).
+ */
+export declare function toSubQuerySql(query: {
+    getQuery(): string;
+    getParameters(): ObjectLiteral;
+}): [string, ObjectLiteral];

package/dist/utils/parameter.utils.js

@@ -1,9 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withUniqueParameterNames = void 0;
+exports.toSubQuerySql = exports.withUniqueParameterNames = exports.getPlaceholderNames = void 0;
 const sql_utils_1 = require("./sql.utils");
 // TypeORM's placeholder syntax, `:name` and `:...name`, as its drivers match it
 const PARAMETER_PLACEHOLDER = /:(\.\.\.)?([A-Za-z0-9_.]+)/g;
+/** The parameter names an SQL fragment refers to, as TypeORM reads its placeholders. */
+function getPlaceholderNames(sql) {
+    // a regex of its own: a global regex keeps its position between exec calls
+    const placeholder = new RegExp(PARAMETER_PLACEHOLDER.source, 'g');
+    const names = [];
+    for (let match = placeholder.exec(sql); match !== null; match = placeholder.exec(sql)) {
+        names.push(match[2]);
+    }
+    return names;
+}
+exports.getPlaceholderNames = getPlaceholderNames;
 /**
  * Renames the parameters of a subquery to unique names, in its SQL and in its parameters. A query
  * has one parameter namespace, so two subqueries with a `:status` each would otherwise both read
@@ -19,3 +30,13 @@ function withUniqueParameterNames(sql, parameters) {
     return [renamedSql, renamedParameters];
 }
 exports.withUniqueParameterNames = withUniqueParameterNames;
+/**
+ * The SQL of a query, without the parentheses a `subQuery()` builder writes around itself, and its parameters, both
+ * renamed unique (see `withUniqueParameterNames`).
+ */
+function toSubQuerySql(query) {
+    const sql = query.getQuery();
+    const wrapped = 'expressionMap' in query && query.expressionMap.subQuery;
+    return withUniqueParameterNames(wrapped ? sql.slice(1, -1) : sql, query.getParameters());
+}
+exports.toSubQuerySql = toSubQuerySql;

package/dist/utils/period.utils.js

@@ -4,6 +4,7 @@ exports.attachPeriodFilter = void 0;
 const sql_utils_1 = require("./sql.utils");
 const where_utils_1 = require("./where.utils");
 const time_zone_utils_1 = require("./time-zone.utils");
+const common_utils_1 = require("./common.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) {
@@ -18,7 +19,7 @@ function normalizeBoundary(value, name) {
     if (value === undefined || value === null || value === '') {
         return undefined;
     }
-    if (Object.prototype.toString.call(value) === '[object Date]') {
+    if ((0, common_utils_1.isDate)(value)) {
         if (isNaN(value.getTime())) {
             throw new TypeError(`Invalid ${name}: invalid Date`);
         }

package/dist/utils/prototype.utils.d.ts

@@ -1,9 +1,18 @@
+import { DeleteQueryBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'typeorm';
+import { SoftDeleteQueryBuilder } from 'typeorm/query-builder/SoftDeleteQueryBuilder';
 export type PatchPrototypeOptions = {
     /** Leave a method the target already has, own or inherited: TypeORM's, or another library's. */
     onlyMissing?: boolean;
 };
+/** The query builders with a WHERE clause, which the where extensions patch. */
+export declare const WHERE_QUERY_BUILDERS: (typeof SelectQueryBuilder | typeof UpdateQueryBuilder | typeof DeleteQueryBuilder | typeof SoftDeleteQueryBuilder)[];
 export declare function patchPrototype<T extends {
     prototype: any;
 }, S extends {
     prototype: any;
 }>(target: T, source: S, options?: PatchPrototypeOptions): void;
+export declare function patchPrototypes<S extends {
+    prototype: any;
+}>(targets: ReadonlyArray<{
+    prototype: any;
+}>, source: S, options?: PatchPrototypeOptions): void;

package/dist/utils/prototype.utils.js

@@ -1,7 +1,11 @@
 "use strict";
-/* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.patchPrototype = void 0;
+exports.patchPrototypes = exports.patchPrototype = exports.WHERE_QUERY_BUILDERS = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const typeorm_1 = require("typeorm");
+const SoftDeleteQueryBuilder_1 = require("typeorm/query-builder/SoftDeleteQueryBuilder");
+/** The query builders with a WHERE clause, which the where extensions patch. */
+exports.WHERE_QUERY_BUILDERS = [typeorm_1.SelectQueryBuilder, typeorm_1.UpdateQueryBuilder, typeorm_1.DeleteQueryBuilder, SoftDeleteQueryBuilder_1.SoftDeleteQueryBuilder];
 function patchPrototype(target, source, options = {}) {
     for (const method of Object.keys(source.prototype)) {
         if (options.onlyMissing && method in target.prototype) {
@@ -11,3 +15,9 @@ function patchPrototype(target, source, options = {}) {
     }
 }
 exports.patchPrototype = patchPrototype;
+function patchPrototypes(targets, source, options) {
+    for (const target of targets) {
+        patchPrototype(target, source, options);
+    }
+}
+exports.patchPrototypes = patchPrototypes;

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

@@ -1,7 +1,17 @@
-import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
+import { QueryBuilder } from 'typeorm';
+import type { ObjectLiteral, QueryRunner, SelectQueryBuilder, WhereExpressionBuilder } from 'typeorm';
 import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
+import type { Alias } from 'typeorm/query-builder/Alias';
 import type { KeyProxyCallback } from '../types/modules/proxy-callback.types';
+import type { OrderType } from '../types/interfaces/ordering.interface';
+import { KeyHolder } from './proxy-key.utils';
 import { JsonPathSqlOptions } from './json-path.utils';
+/**
+ * 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.
+ */
+export declare function listQueryAliases(builder: WhereExpressionBuilder | QueryBuilder<ObjectLiteral>): Alias[];
 /** Replaces placeholders of `deferColumnKey` in SQL built by `builder`, through the aliases it has by then. */
 export declare function resolveDeferredKeys(builder: WhereExpressionBuilder, statement: string): string;
 /**
@@ -48,6 +58,14 @@ export declare function isTypedJsonPath<Type extends ObjectLiteral>(builder: Whe
  * 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;
+/**
+ * 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`.
+ */
+export declare function resolveTypedProperty<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, callback: KeyProxyCallback<Type>, methodName: string): {
+    aliasName: string | undefined;
+    propertyPath: string;
+};
 /**
  * Key for typed select / order / distinct / group by on a SelectQueryBuilder.
  *
@@ -59,4 +77,14 @@ export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(buil
  * 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[];
+export declare function getTypedSelectionKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, selection: KeyProxyCallback<Type> | KeyHolder | string, useQuotes?: boolean, columnsFor?: string): string | string[];
+/**
+ * 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.
+ */
+export declare function getAppliedOrderBy<Entity extends ObjectLiteral>(builder: QueryBuilder<Entity>): OrderType[];
+/** The query without paging: no ORDER BY (nor the entity's default one), LIMIT, OFFSET, take or skip. */
+export declare function withoutPaging<Entity extends ObjectLiteral>(query: SelectQueryBuilder<Entity>): SelectQueryBuilder<Entity>;
+/** The query runner a builder was created with, from a transactional manager; `undefined` for one from the pool. */
+export declare function getQueryRunner<Entity extends ObjectLiteral>(builder: QueryBuilder<Entity>): QueryRunner | undefined;

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

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = exports.resolveDeferredKeys = void 0;
+exports.getQueryRunner = exports.withoutPaging = exports.getAppliedOrderBy = exports.getTypedSelectionKey = exports.resolveTypedProperty = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = 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`).
  *
@@ -33,21 +34,24 @@ function requireMainAliasName(queryBuilder, key) {
     return mainAlias.name;
 }
 /**
- * An alias of the query by name, or of a query it is part of. 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, its own first.
+ * 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 findQueryAlias(queryBuilder, aliasName) {
-    var _a, _b;
+function listQueryAliases(builder) {
+    var _a;
+    const aliases = [];
     // parentQueryBuilder is protected in TypeORM's types
-    for (let query = queryBuilder; query; query = query.parentQueryBuilder) {
-        const { aliases = [], mainAlias } = (_a = query.expressionMap) !== null && _a !== void 0 ? _a : {};
-        const alias = (_b = aliases.find((candidate) => candidate.name === aliasName)) !== null && _b !== void 0 ? _b : ((mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.name) === aliasName ? mainAlias : undefined);
-        if (alias) {
-            return alias;
-        }
+    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 undefined;
+    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';
@@ -74,7 +78,7 @@ function deferColumnKey(aliasName, separator, name) {
  *   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;
+    const metadata = metadataOf(alias);
     if (separator === DEFERRED_UNQUOTED) {
         return metadata ? `${aliasName}.${name}` : `${escape(aliasName)}.${escape(name)}`;
     }
@@ -149,13 +153,11 @@ function installDeferredKeyResolution() {
     }
 }
 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) {
     var _a;
-    const alias = aliasName === undefined
-        ? (_a = queryBuilder.expressionMap) === null || _a === void 0 ? void 0 : _a.mainAlias
-        : findQueryAlias(queryBuilder, aliasName);
-    return (alias === null || alias === void 0 ? void 0 : alias.hasMetadata) ? alias.metadata : undefined;
+    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
@@ -185,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;
@@ -205,27 +208,17 @@ exports.findFieldColumn = findFieldColumn;
  */
 function toFieldSql(builder, field) {
     const queryBuilder = builder;
+    const column = findFieldColumn(builder, field);
     const dot = field.indexOf('.');
-    if (dot > 0) {
-        const aliasName = field.slice(0, dot);
-        const metadata = getAliasMetadata(queryBuilder, aliasName);
-        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;
-        }
-        const parts = TWO_PART_FIELD.exec(field);
-        if (parts && !findQueryAlias(queryBuilder, aliasName)) {
-            return deferColumnKey(parts[1], DEFERRED_FIELD, parts[2]);
-        }
+    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));
 }
@@ -266,15 +259,13 @@ 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;
@@ -283,10 +274,12 @@ 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;
@@ -314,7 +307,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('.'),
@@ -327,11 +320,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;
+    var _a;
     if (aliasName !== undefined && !metadata && !findQueryAlias(queryBuilder, aliasName)) {
         return deferColumnKey(aliasName, DEFERRED_PROPERTY, propertyPath);
     }
-    const columnName = (_b = (_a = (column !== null && column !== void 0 ? column : metadata === null || metadata === void 0 ? void 0 : metadata.findColumnWithPropertyPath(propertyPath))) === null || _a === void 0 ? void 0 : _a.databaseName) !== null && _b !== void 0 ? _b : propertyPath;
+    const 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)}`;
@@ -377,6 +370,19 @@ function getTypedSingleColumnKey(builder, callback, methodName, jsonOptions) {
     return key;
 }
 exports.getTypedSingleColumnKey = getTypedSingleColumnKey;
+/**
+ * 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
@@ -442,3 +448,35 @@ function getTypedSelectionKey(builder, selection, useQuotes, columnsFor) {
     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;