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

package/dist/helpers.d.ts

@@ -1,2 +1,7 @@
 export * from './utils/table.utils';
+export * from './decorators/generated-column.decorator';
 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,19 @@ 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, @GeneratedColumn) only and patches nothing on import;
+// importing the package root (`typeorm-extensions`) installs every QueryBuilder extension.
 __exportStar(require("./utils/table.utils"), exports);
+__exportStar(require("./decorators/generated-column.decorator"), 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

@@ -4,5 +4,4 @@ export * from './types/interfaces';
 export * from './types/extensions';
 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 * from './helpers';

package/dist/index.js

@@ -14,11 +14,8 @@ 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;
 __exportStar(require("./extensions"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./types/interfaces"), exports);
 __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; } });
+__exportStar(require("./helpers"), exports);

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/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-group-by.types.d.ts

@@ -1,8 +1,8 @@
 export type TypedGroupByOptions = {
     /**
      * Group by the quoted database column (`"ticket"."ticket_status"`) instead of `ticket.status`,
-     * which TypeORM maps to the column itself. TypeORM maps only aliases with metadata, so a subquery
-     * in FROM needs it on PostgreSQL, where an unquoted `sub.firstName` is folded to `firstname`.
+     * which TypeORM maps to the column itself. Keys of an alias without metadata (a subquery in FROM)
+     * are quoted unless this is `false`: PostgreSQL folds an unquoted `sub.firstName` to `firstname`.
      */
     useQuotes?: boolean;
 };

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/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. */
@@ -16,6 +20,13 @@ export declare function resolveCalculatedColumn<Entity extends ObjectLiteral>(bu
  * The alias the entity is built from can't be ordered by: PostgreSQL folds it unquoted
  * (`user_imagesCount` → `user_imagescount`), and quoted it breaks the DISTINCT query TypeORM pages
  * through with `take` / `skip` and joins, which takes only select aliases it knows unquoted.
+ *
+ * A value already selected for order keeps its alias, so ORDER BY and DISTINCT ON name the same
+ * column: PostgreSQL requires DISTINCT ON to match the leading ORDER BY.
  */
 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,8 +1,10 @@
 "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");
+const ORDER_ALIAS_PREFIX = 'calculated';
+const ORDER_ALIAS_PATTERN = new RegExp(`^${ORDER_ALIAS_PREFIX}_\\w+$`);
 function findCalculatedColumn(builder, property, aliasName) {
     const { expressionMap } = builder;
     const alias = aliasName === undefined
@@ -19,10 +21,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 +36,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
@@ -48,6 +51,9 @@ exports.resolveCalculatedColumn = resolveCalculatedColumn;
  * The alias the entity is built from can't be ordered by: PostgreSQL folds it unquoted
  * (`user_imagesCount` → `user_imagescount`), and quoted it breaks the DISTINCT query TypeORM pages
  * through with `take` / `skip` and joins, which takes only select aliases it knows unquoted.
+ *
+ * A value already selected for order keeps its alias, so ORDER BY and DISTINCT ON name the same
+ * column: PostgreSQL requires DISTINCT ON to match the leading ORDER BY.
  */
 function selectCalculatedForOrder(builder, property, aliasName, methodName) {
     const { key, label } = resolveCalculatedColumn(builder, property, aliasName, methodName);
@@ -55,9 +61,32 @@ function selectCalculatedForOrder(builder, property, aliasName, methodName) {
     if (!select) {
         throw new TypeError(`${methodName}: ${label} isn't selected: select it with addSelectCalculated first`);
     }
-    const orderAlias = (0, sql_utils_1.createUniqueParameterName)('calculated').toLowerCase();
+    // found by its SQL rather than kept aside, so a clone of the builder finds it too
+    const selectedForOrder = builder.expressionMap.selects.find((candidate) => candidate.aliasName !== undefined &&
+        ORDER_ALIAS_PATTERN.test(candidate.aliasName) &&
+        candidate.selection === select.selection);
+    if (selectedForOrder === null || selectedForOrder === void 0 ? void 0 : selectedForOrder.aliasName) {
+        return selectedForOrder.aliasName;
+    }
+    const orderAlias = (0, sql_utils_1.createUniqueParameterName)(ORDER_ALIAS_PREFIX).toLowerCase();
     // TypeORM keeps a subquery selection as its SQL, with its parameters already on the builder
     builder.addSelect(select.selection, orderAlias);
     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,19 @@
-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;
 /**
  * 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
@@ -29,6 +41,11 @@ export declare function findFieldColumn(builder: WhereExpressionBuilder, field:
  *   `stringToSQLIdentifier` does, in the driver's quotes.
  */
 export declare function toFieldSql(builder: WhereExpressionBuilder, field: string): string;
+/** The alias and property of the `@CalculatedColumn` a typed key picks; undefined for any other key. */
+export declare function findTypedCalculatedProperty(builder: WhereExpressionBuilder, keyHolder: KeyHolder): {
+    aliasName: string | undefined;
+    propertyPath: string;
+} | undefined;
 /**
  * SQL key for a typed callback on `builder`: `"alias"."column"`, or `"column"` on UPDATE / DELETE.
  *
@@ -47,10 +64,32 @@ export declare function isTypedJsonPath<Type extends ObjectLiteral>(builder: Whe
  */
 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.
+ * 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.
  *
  * Without quotes it is `alias.propertyPath` (`user.name`, `images.url`, `p.address.city`),
  * which TypeORM maps to the column itself. With `useQuotes` it is the quoted database column
- * (`"t"."ticket_status"`), since TypeORM doesn't map quoted keys. Strings are kept as is.
+ * (`"t"."ticket_status"`), since TypeORM doesn't map quoted keys. An alias of the query without
+ * metadata (a subquery or a CTE in FROM or a join), or one the query still doesn't have when the SQL
+ * is built, is quoted unless `useQuotes` is `false`: TypeORM leaves its keys as written, and
+ * PostgreSQL folds an unquoted `cte.firstName` to `firstname`.
+ * Strings are kept as is.
+ */
+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 getTypedSelectionKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, selection: KeyProxyCallback<Type> | string, useQuotes?: boolean): string | string[];
+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;