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

package/dist/extensions/where-is-in.extension.js

@@ -1,39 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const typeorm_1 = require("typeorm");
 const prototype_utils_1 = require("../utils/prototype.utils");
 const where_utils_1 = require("../utils/where.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
 // patching
+const createWhereIsInMethod = (method, operator) => function (field, array) {
+    return attachWhereIsIn(this, method, field, operator, array);
+};
 const extension = {
     prototype: {
-        whereIsIn: function (field, array) {
-            return attachWhereIsIn(this, 'where', field, 'IN', array);
-        },
-        andWhereIsIn: function (field, array) {
-            return attachWhereIsIn(this, 'andWhere', field, 'IN', array);
-        },
-        orWhereIsIn: function (field, array) {
-            return attachWhereIsIn(this, 'orWhere', field, 'IN', array);
-        },
-        whereIsNotIn: function (field, array) {
-            return attachWhereIsIn(this, 'where', field, 'NOT IN', array);
-        },
-        andWhereIsNotIn: function (field, array) {
-            return attachWhereIsIn(this, 'andWhere', field, 'NOT IN', array);
-        },
-        orWhereIsNotIn: function (field, array) {
-            return attachWhereIsIn(this, 'orWhere', field, 'NOT IN', array);
-        },
+        whereIsIn: createWhereIsInMethod('where', 'IN'),
+        andWhereIsIn: createWhereIsInMethod('andWhere', 'IN'),
+        orWhereIsIn: createWhereIsInMethod('orWhere', 'IN'),
+        whereIsNotIn: createWhereIsInMethod('where', 'NOT IN'),
+        andWhereIsNotIn: createWhereIsInMethod('andWhere', 'NOT IN'),
+        orWhereIsNotIn: createWhereIsInMethod('orWhere', 'NOT IN'),
     },
 };
-const queryBuilders = [
-    typeorm_1.SelectQueryBuilder,
-    typeorm_1.UpdateQueryBuilder,
-    typeorm_1.DeleteQueryBuilder,
-];
-queryBuilders.forEach((builder) => {
-    (0, prototype_utils_1.patchPrototype)(builder, extension);
-});
+(0, prototype_utils_1.patchPrototypes)(prototype_utils_1.WHERE_QUERY_BUILDERS, extension);
 // implementation
 function attachWhereIsIn(builder, method, field, operator, array) {
     if (method && typeof field === 'string' && typeof operator === 'string') {

package/dist/extensions/where-json.extension.d.ts

@@ -53,3 +53,7 @@ declare module 'typeorm/query-builder/DeleteQueryBuilder' {
     interface DeleteQueryBuilder<Entity extends ObjectLiteral> extends WhereJsonMethods {
     }
 }
+declare module 'typeorm/query-builder/SoftDeleteQueryBuilder' {
+    interface SoftDeleteQueryBuilder<Entity extends ObjectLiteral> extends WhereJsonMethods {
+    }
+}

package/dist/extensions/where-json.extension.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const typeorm_1 = require("typeorm");
 const prototype_utils_1 = require("../utils/prototype.utils");
 const query_builder_utils_1 = require("../utils/query-builder.utils");
 const sql_utils_1 = require("../utils/sql.utils");
@@ -22,14 +21,7 @@ const extension = {
         orWhereJsonHasKey: createWhereJsonHasKeyMethod('orWhere'),
     },
 };
-const queryBuilders = [
-    typeorm_1.SelectQueryBuilder,
-    typeorm_1.UpdateQueryBuilder,
-    typeorm_1.DeleteQueryBuilder,
-];
-queryBuilders.forEach((builder) => {
-    (0, prototype_utils_1.patchPrototype)(builder, extension);
-});
+(0, prototype_utils_1.patchPrototypes)(prototype_utils_1.WHERE_QUERY_BUILDERS, extension);
 // implementation
 /**
  * `CAST("table"."column" AS jsonb)`: makes `json` and `simple-json` (text) columns work, and is dropped by PostgreSQL

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

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

package/dist/extensions/where-relation-exists.extension.js

@@ -22,18 +22,12 @@ const extension = {
 // implementation
 function attachRelationExists(builder, method, negate, relationSelection, alias, where) {
     const methodName = `${method}Relation${negate ? 'Not' : ''}Exists`;
-    const key = (0, query_builder_utils_1.getTypedSelectionKey)(builder, relationSelection);
-    if (Array.isArray(key)) {
-        throw new TypeError(`${methodName} expects the callback to select one relation, got ${key.length}: ${key.join(', ')}`);
-    }
-    const dot = key.indexOf('.');
-    const ownerAlias = key.slice(0, dot);
-    const propertyPath = key.slice(dot + 1);
-    const aliases = queryAliases(builder);
+    const { aliasName: ownerAlias, propertyPath } = (0, query_builder_utils_1.resolveTypedProperty)(builder, relationSelection, methodName);
+    const aliases = (0, query_builder_utils_1.listQueryAliases)(builder);
     const owner = aliases.find((candidate) => candidate.name === ownerAlias);
     const relation = (owner === null || owner === void 0 ? void 0 : owner.hasMetadata) ? owner.metadata.findRelationWithPropertyPath(propertyPath) : undefined;
-    if (!relation) {
-        throw new TypeError(`${methodName}: ${key} is not a relation of an entity of the query`);
+    if (!owner || !relation) {
+        throw new TypeError(`${methodName}: ${ownerAlias}.${propertyPath} is not a relation of an entity of the query`);
     }
     // in the subquery the alias would hide the outer one the join condition refers to; SQLite matches
     // names without case, so 'USER' would hide 'user' there
@@ -45,26 +39,12 @@ function attachRelationExists(builder, method, negate, relationSelection, alias,
         .createQueryBuilder()
         .select('1')
         .from(relation.inverseEntityMetadata.target, alias);
-    const correlation = joinCondition(relation, ownerAlias, alias, column, subQuery);
+    const correlation = joinCondition(relation, owner.name, alias, column, subQuery);
     where === null || where === void 0 ? void 0 : where(subQuery);
     // after the caller's conditions, so a `where` or an `orWhere` of theirs can't drop or bypass it
     (0, where_utils_1.andWhereNarrowing)(subQuery, correlation);
     return (0, where_exists_extension_1.attachExists)(builder, method, subQuery, negate);
 }
-/**
- * The aliases of the query and of the queries it is part of. Inside `Brackets` the builder has the outer
- * query's main alias but none of its joins: those are on its parent.
- */
-function queryAliases(builder) {
-    const aliases = [];
-    // parentQueryBuilder is protected in TypeORM's types
-    let query = builder;
-    for (; query; query = query.parentQueryBuilder) {
-        const { aliases: own, mainAlias } = query.expressionMap;
-        aliases.push(...own, ...(mainAlias ? [mainAlias] : []));
-    }
-    return aliases;
-}
 const equal = (left, right) => `${left} = ${right}`;
 /** The condition between the related rows (`alias`) and the outer row (`ownerAlias`); joins the junction table of a many-to-many. */
 function joinCondition(relation, ownerAlias, alias, column, subQuery) {

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 { CursorOrderParam, RawCursorOrderParam } 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' }]`.
@@ -9,7 +10,17 @@ export type GetManyWithCursorOptions<Entity> = {
     /** Use `take` instead of `limit`, as needed for queries with joined collections. Defaults to `false`. */
     useTakeAndSkip?: boolean;
 };
+export type GetRawManyWithCursorOptions = {
+    /**
+     * SQL expressions that order the rows. On a query of an entity without GROUP BY or DISTINCT the
+     * primary key of the main alias is appended when it isn't listed; otherwise the last key has to be
+     * unique per row, or rows with equal keys may be skipped or repeated between pages.
+     * It replaces any ORDER BY of the query.
+     */
+    orderBy: RawCursorOrderParam[];
+};
 export interface ListWithCursor<Entity> {
+    /** The entities of the page, or with `getRawManyWithCursor` its raw rows. */
     list: Entity[];
     /** Cursor of the next page, `null` on the last page. */
     nextCursor: string | null;
@@ -18,4 +29,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` keys, 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/interfaces/cursor-pagination.interface.d.ts

@@ -14,3 +14,14 @@ export type CursorOrderParam<Entity> = {
     /** `'ASC'` by default. */
     direction?: OrderDirection;
 };
+/** An SQL expression that orders the rows of `getRawManyWithCursor`. */
+export type RawCursorOrderParam = {
+    /**
+     * A column (`user.createdAt`, `"user"."created_at"`) or a computed value
+     * (`CASE "member"."role" WHEN 'owner' THEN 0 ELSE 1 END`). It must be valid in WHERE, so not an
+     * aggregate, and must not be `NULL`.
+     */
+    selector: string;
+    /** `'ASC'` by default. */
+    direction?: OrderDirection;
+};

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.d.ts

@@ -5,6 +5,11 @@ export declare class InvalidCursorError extends TypeError {
 }
 /** A key value in a cursor: as read from the database, or a JS Date tagged as `{ $date }`. */
 export type CursorValue = string | number | boolean;
+/**
+ * Short stable name of an SQL expression key, for the cursor to recognise its order by: a cursor
+ * carries no SQL. 32-bit FNV-1a; telling orders apart doesn't need more.
+ */
+export declare function getExpressionKeyName(selector: string): string;
 /** base64url-encoded JSON of the key fields and the key values of the last row. */
 export declare function encodeCursor(fields: string[], values: unknown[]): string;
 /** Key values of a cursor made for `fields`; throws `InvalidCursorError` otherwise. */

package/dist/utils/cursor.utils.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildKeysetCondition = exports.getTextCastType = exports.supportsRowValueComparison = exports.decodeCursor = exports.encodeCursor = exports.InvalidCursorError = void 0;
+exports.buildKeysetCondition = exports.getTextCastType = exports.supportsRowValueComparison = exports.decodeCursor = exports.encodeCursor = exports.getExpressionKeyName = 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') {
@@ -34,6 +34,19 @@ const fromBase64Url = (value) => {
     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)));
 };
+/**
+ * Short stable name of an SQL expression key, for the cursor to recognise its order by: a cursor
+ * carries no SQL. 32-bit FNV-1a; telling orders apart doesn't need more.
+ */
+function getExpressionKeyName(selector) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < selector.length; i++) {
+        hash ^= selector.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `sql:${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+exports.getExpressionKeyName = getExpressionKeyName;
 /** 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) };
@@ -77,9 +90,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 +99,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,15 @@
+import type { ObjectLiteral, SelectQueryBuilder } from "typeorm";
+import type { ApplyPaginationOptions } from "../types/extensions/pagination.types";
 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;
 };
+/** What `applyPagination` does, for code that must not depend on what is patched under that name. */
+export declare const paginateQuery: <Entity extends ObjectLiteral>(builder: SelectQueryBuilder<Entity>, paginationFilter: PaginationFilter, options?: ApplyPaginationOptions) => SelectQueryBuilder<Entity>;