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

package/README.md

@@ -5,62 +5,93 @@
 [![Issues](https://img.shields.io/github/issues-raw/koenigstag/typeorm-extensions.svg?maxAge=25000)](https://github.com/koenigstag/typeorm-extensions/issues)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/koenigstag/typeorm-extensions/pulls)
 
-## Description
+**Type-safe extensions for the TypeORM QueryBuilder.** Write selects, joins, conditions and ordering as property callbacks the compiler checks against your entities, page through results with totals or cursors, and build the raw SQL you still need with helpers that quote it for the database.
 
-TypeORM Extensions is a library that provides additional functionality and extensions for the TypeORM QueryBuilder. It aims to simplify common tasks and enhance the capabilities of TypeORM.
+```typescript
+import 'typeorm-extensions';
 
-## Features
+const { list, total, hasMore } = await dataSource
+  .getRepository(UserEntity)
+  .createQueryBuilder('user')
+  .leftJoinTyped(user => user.images, 'images')
+  .whereTyped(user => user.createdAt, '>', since)
+  // a key inside a JSON column: "user"."metadata" ->> 'role' = :param
+  .andWhereTyped(user => user.metadata.role, '=', 'admin')
+  .orderByTyped(user => user.images.url, 'ASC', 'NULLS LAST')
+  .getManyWithTotals({ page: 1, pageSize: 20 });
+```
 
-- Simplicity: applying pagination and ordering to queries is as simple as calling a method.
-- Type Safety: the library is written in TypeScript and provides type-safe QueryBuilder methods based on Entity  metadata.
-- Flexibility: the library is designed to be flexible and can be used with any TypeORM entity.
+Try it in the [playground](https://koenigstag.github.io/typeorm-extensions/playground/): an editor and a database in the browser.
 
-## Installation
+## Why
 
-To install `typeorm-extensions`:
+The QueryBuilder takes columns as strings. A renamed property, a typo or a half-quoted alias compiles and then fails at runtime:
 
-Install using npm, yarn or pnpm:
-```bash
-npm install typeorm-extensions
+```typescript
+.where('user.createdAt > :since', { since })   // still compiles after createdAt is renamed
+.andWhere('order."userId" = :userId', { userId }) // PostgreSQL: syntax error at or near "order"
 ```
 
-## Usage
+With the extensions a column is a property of the entity type, so the compiler catches the rename, and the SQL is built and quoted for you:
 
 ```typescript
-import 'typeorm-extensions'; // Importing the library root extends the QueryBuilder with all extensions
+.whereTyped(user => user.createdAt, '>', since)
 
-// Or init specific extension: import 'typeorm-extensions/dist/extensions/pagination.extension';
+const orders = tableHelper(OrderEntity, 'order');
+.andWhere(`${orders.userId} = :userId`, { userId }) // "order"."userId" = :userId
+```
 
-const query = myDataSource
-  .getRepository(UserEntity)
-  .createQueryBuilder('users')
-  // Join relation defined in entity model
-  .leftJoinTyped(user => user.images, 'images')
-  // Select type-safe properties
-  .selectTyped(user => [
-    user.id,
-    user.name,
-    user.email,
-    user.images.url,
-  ])
-  .whereTyped(user => user.name, 'ILIKE', 'John')
-  // Paths into JSON columns: "users"."metadata" ->> 'role' = :param
-  .andWhereTyped(user => user.metadata.role, '=', 'admin')
-  // Order by type-safe own and relation properties
-  .orderByTyped(user => user.images.url, 'ASC', 'NULLS LAST')
-  // Use pagination as simple as that
-  .applyPaginationFilter({ page: 1, pageSize: 10 }, { useTakeAndSkip: true });
+## Installation
+
+```bash
+npm install typeorm-extensions
 ```
 
-## Documentation
+`typeorm` 0.3.12 or later, or 1.x, is a peer dependency. Release candidates of the next version are published under the `next` tag: `npm install typeorm-extensions@next`.
+
+## Features
+
+**Typed queries** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/typed/))
+- `selectTyped`, `whereTyped` (keys inside JSON columns too; `strictParams` checks the parameter against the column type), `orderByTyped`, `groupByTyped` / `havingTyped`, `distinctOnTyped`, `returningTyped`
+- typed joins and map joins (`leftJoinTyped`, `innerJoinAndMapOneTyped`, …), `typed<Root>()` for the aliases a query joins, `whereRelationExists` built from the relation metadata
+
+**Pagination** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/pagination/))
+- `getManyWithTotals` and `getRawManyWithTotals`: the rows of a page, the total, `page` / `pageSize`, `hasMore` and the order it was read in
+- `getManyWithCursor` and `getRawManyWithCursor`: keyset pagination with an opaque cursor, by columns or by SQL expressions
+- `applyPagination` for a page of any query
 
-For more information, please refer to the [documentation](https://koenigstag.github.io/typeorm-extensions).
+**Filters and ordering** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/where/))
+- `whereIsIn` / `whereIsNotIn` that handle empty arrays, `whereIsAny`, null-safe `whereIsDistinctFrom`
+- case-insensitive search with escaped wildcards, `applyPeriodFilter` in a time zone
+- `applyOrder` from a client's order filter, `orderByArrayPosition`
 
-## ToDo list
+**Subqueries and joins**
+- `whereExists` / `whereNotExists`, with the subquery's parameters renamed so they never clash with the outer query's
+- `leftJoinLateral` / `innerJoinLateral`, `innerJoinUnnest`, `fromUnion` and CTE unions
+
+**SQL helpers** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/utils/tableHelper/))
+- `tableHelper`: quoted column references, conditions, counts, sums, JSON objects and paths, time zones. Given the entity class it writes the database name of a renamed column
+- the reserved qualifier guard: catches SQL like `order."userId"` before PostgreSQL rejects it
+
+**Columns** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/columns/generatedColumn/))
+- `@CalculatedColumn` with `addSelectCalculated` / `orderByCalculated`: a value each query computes
+- `@GeneratedColumn`: a column the database generates, which TypeORM reads and never writes
+
+## Entry points
+
+| Import | Gives |
+|---|---|
+| `import 'typeorm-extensions'` | every QueryBuilder extension, and all exports |
+| `import 'typeorm-extensions/dist/extensions/pagination.extension'` | one extension |
+| `import { tableHelper, GeneratedColumn } from 'typeorm-extensions/helpers'` | the helpers, with no side effects |
+
+## Compatibility
+
+TypeORM 0.3.12 and later, and 1.x. CI runs the test suite on SQLite with TypeORM 0.3.12, the latest 0.3 and 1.x, and on MySQL 8.4. Features that only work on some databases (array and JSON operators, `DISTINCT ON`, `orderByArrayPosition`, …) say so in their docs.
+
+## Documentation
 
-- [x] Add tests for pagination and order extensions
-- [x] Calculated columns: the `@CalculatedColumn` decorator and `addSelectCalculated`. `getMany`, `getOne` and `getManyWithTotals` fill them as they are, so they need no variants of their own
-- [x] Order by a calculated column: `orderByCalculated`, and `applyOrder` orders a `@CalculatedColumn` field by its value
+The [documentation](https://koenigstag.github.io/typeorm-extensions/) has a page for every method, with its signature, options and examples, and the [playground](https://koenigstag.github.io/typeorm-extensions/playground/) runs them.
 
 ## License
 

package/dist/decorators/calculated-column.decorator.d.ts

@@ -3,11 +3,15 @@ export type CalculatedColumnOptions = {
     /**
      * The type the selected value is converted from, as for `@Column`: `'boolean'`, `'jsonb'`, `'timestamptz'`.
      * Defaults to the property's TypeScript type with `emitDecoratorMetadata`: `Number`, `String`, `Boolean`, `Date`.
-     * `Number` turns numeric strings (a PostgreSQL `COUNT`, an `AVG`) into numbers, decimals kept; `Boolean`
-     * reads `0` / `1`, `'0'` / `'1'` and `t` / `f` as well.
+     * `Number` and the numeric SQL types (`'integer'`, `'bigint'`, `'numeric'`, `'decimal'`, `'float'`, …) turn
+     * numeric strings (a PostgreSQL `COUNT`, an `AVG`) into numbers, decimals kept; `Boolean` reads `0` / `1`,
+     * `'0'` / `'1'` and `t` / `f` as well.
      */
     type?: ColumnType;
-    /** Converts the selected value, e.g. JSON text from SQLite. Only `from` is used. */
+    /**
+     * Converts the selected value, e.g. JSON text from SQLite. Only `from` is used. It replaces the conversion of
+     * the type: it gets the value as the database returned it, a PostgreSQL `COUNT` as a string.
+     */
     transformer?: ValueTransformer | ValueTransformer[];
 };
 /**

package/dist/decorators/calculated-column.decorator.js

@@ -21,7 +21,7 @@ const typeorm_1 = require("typeorm");
  */
 function CalculatedColumn(typeOrOptions) {
     return (object, propertyName) => {
-        var _a, _b;
+        var _a;
         const options = typeof typeOrOptions === 'object' ? typeOrOptions : { type: typeOrOptions };
         const reflectedType = typeof Reflect === 'object' && typeof Reflect.getMetadata === 'function'
             ? Reflect.getMetadata('design:type', object, propertyName)
@@ -32,8 +32,9 @@ function CalculatedColumn(typeOrOptions) {
             throw new TypeError(`@CalculatedColumn() on ${object.constructor.name}.${String(propertyName)} needs a type: ` +
                 `@CalculatedColumn('varchar'), or a property type of number, string, boolean or Date`);
         }
-        const conversion = ownConversions.get(type);
-        const transformers = [(_b = options.transformer) !== null && _b !== void 0 ? _b : []].flat();
+        const ownConversion = ownConversions.get(typeof type === 'string' ? type.toLowerCase() : type);
+        // a transformer of its own replaces the conversion and takes the value as the database returned it
+        const conversion = options.transformer === undefined ? ownConversion : undefined;
         // the mode of TypeORM's @VirtualColumn: not a column of the table, never inserted or updated;
         // with no `query` and `select: false` TypeORM never selects it by itself
         (0, typeorm_1.getMetadataArgsStorage)().columns.push({
@@ -42,12 +43,12 @@ function CalculatedColumn(typeOrOptions) {
             mode: 'virtual-property',
             options: {
                 // the drivers parseInt a Number (AVG 150.5 → 150) and read MySQL's '0' as true, so these
-                // types are converted here; String is a type no driver converts. TypeORM applies `from` last to first
-                type: conversion ? String : type,
+                // types are converted here; String is a type no driver converts
+                type: ownConversion ? String : type,
                 select: false,
                 insert: false,
                 update: false,
-                transformer: conversion ? [...transformers, conversion] : options.transformer,
+                transformer: conversion !== null && conversion !== void 0 ? conversion : options.transformer,
             },
         });
     };
@@ -74,8 +75,36 @@ function toBoolean(value) {
 }
 const numberConversion = { from: toNumber, to: (value) => value };
 const booleanConversion = { from: toBoolean, to: (value) => value };
+// a COUNT is a bigint and an AVG a numeric, which drivers hand over as strings to keep their precision
+const numericTypes = [
+    'int',
+    'int2',
+    'int4',
+    'int8',
+    'int64',
+    'integer',
+    'tinyint',
+    'smallint',
+    'mediumint',
+    'bigint',
+    'unsigned big int',
+    'long',
+    'numeric',
+    'decimal',
+    'dec',
+    'fixed',
+    'smalldecimal',
+    'number',
+    'float',
+    'float4',
+    'float8',
+    'double',
+    'double precision',
+    'real',
+];
 const ownConversions = new Map([
     [Number, numberConversion],
+    ...numericTypes.map((type) => [type, numberConversion]),
     [Boolean, booleanConversion],
     ['boolean', booleanConversion],
     ['bool', booleanConversion],

package/dist/decorators/generated-column.decorator.d.ts

@@ -0,0 +1,17 @@
+import { ColumnOptions, ColumnType } from 'typeorm';
+/** The options of `@Column`, without those that would let TypeORM write the column. */
+export type GeneratedColumnOptions = Omit<ColumnOptions, 'insert' | 'update' | 'readonly'>;
+/**
+ * A column of the table that the database computes: `GENERATED ALWAYS AS (…) STORED`. TypeORM reads it like any
+ * column and never writes it. `asExpression` alone doesn't stop TypeORM (0.3 and 1.x) from sending the column in
+ * `save`, `insert` and `update`, which the database rejects for a generated column.
+ *
+ * Pass `asExpression` and `generatedType: 'STORED'` when TypeORM creates the schema (synchronize, generated
+ * migrations); a column created by a hand-written migration needs neither.
+ *
+ * @example
+ * \@GeneratedColumn({ type: 'integer', asExpression: 'price * quantity', generatedType: 'STORED' })
+ * total: number;
+ */
+export declare function GeneratedColumn(options?: GeneratedColumnOptions): PropertyDecorator;
+export declare function GeneratedColumn(type: ColumnType, options?: GeneratedColumnOptions): PropertyDecorator;

package/dist/decorators/generated-column.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeneratedColumn = void 0;
+const typeorm_1 = require("typeorm");
+function GeneratedColumn(typeOrOptions, options = {}) {
+    const columnOptions = typeof typeOrOptions === 'object'
+        ? { ...typeOrOptions }
+        : typeOrOptions === undefined
+            ? { ...options }
+            : { ...options, type: typeOrOptions };
+    // TypeORM 0.3 applies `readonly` after `update`: `readonly: false` from an untyped caller would turn writes back on
+    delete columnOptions.readonly;
+    return (0, typeorm_1.Column)({ ...columnOptions, insert: false, update: false });
+}
+exports.GeneratedColumn = GeneratedColumn;

package/dist/decorators/index.d.ts

@@ -1 +1,2 @@
 export * from './calculated-column.decorator';
+export * from './generated-column.decorator';

package/dist/decorators/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./calculated-column.decorator"), exports);
+__exportStar(require("./generated-column.decorator"), exports);

package/dist/extensions/calculated-column.extension.d.ts

@@ -1,6 +1,6 @@
-import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-/** `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>);
+import { ObjectLiteral } from 'typeorm';
+import { CalculatedSelection } from '../utils/calculated-column.utils';
+export type { CalculatedSelection };
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
         /**

package/dist/extensions/calculated-column.extension.js

@@ -7,27 +7,14 @@ const calculated_column_utils_1 = require("../utils/calculated-column.utils");
 const extension = {
     prototype: {
         addSelectCalculated(selection, property, alias) {
-            return addSelectCalculated(this, selection, property, alias);
+            return (0, calculated_column_utils_1.addSelectCalculatedColumn)(this, selection, property, alias, 'addSelectCalculated');
         },
         orderByCalculated(property, order, nulls, alias) {
-            return attachOrderByCalculated(this, 'orderBy', property, order, nulls, alias);
+            return (0, calculated_column_utils_1.orderByCalculatedColumn)(this, 'orderBy', property, order, nulls, alias, 'orderByCalculated');
         },
         addOrderByCalculated(property, order, nulls, alias) {
-            return attachOrderByCalculated(this, 'addOrderBy', property, order, nulls, alias);
+            return (0, calculated_column_utils_1.orderByCalculatedColumn)(this, 'addOrderBy', property, order, nulls, alias, 'addOrderByCalculated');
         },
     },
 };
 (0, prototype_utils_1.patchPrototype)(typeorm_1.SelectQueryBuilder, extension);
-// implementation
-function addSelectCalculated(builder, selection, property, aliasName) {
-    const { key } = (0, calculated_column_utils_1.resolveCalculatedColumn)(builder, property, aliasName, 'addSelectCalculated');
-    // 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);
-}
-function attachOrderByCalculated(builder, method, property, order, nulls, aliasName) {
-    const orderAlias = (0, calculated_column_utils_1.selectCalculatedForOrder)(builder, property, aliasName, `${method}Calculated`);
-    return builder[method](orderAlias, order, nulls);
-}

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

@@ -1,5 +1,6 @@
+import { ObjectLiteral } from 'typeorm';
 import type { CursorPaginationFilter } from '../types/interfaces/cursor-pagination.interface';
-import type { GetManyWithCursorOptions, ListWithCursor } from '../types/extensions/cursor-pagination.types';
+import type { GetManyWithCursorOptions, GetRawManyWithCursorOptions, ListWithCursor } from '../types/extensions/cursor-pagination.types';
 export { InvalidCursorError } from '../utils/cursor.utils';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity> {
@@ -14,6 +15,18 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          * The query builder itself is not changed. Throws `InvalidCursorError` for a cursor that can't
          * be decoded or was made for another order.
          */
-        getManyWithCursor(cursorFilter: CursorPaginationFilter | null | undefined, options: GetManyWithCursorOptions<Entity>): Promise<ListWithCursor<Entity>>;
+        getManyWithCursor<CursorEntity extends ObjectLiteral = Entity>(this: SelectQueryBuilder<CursorEntity>, cursorFilter: CursorPaginationFilter | null | undefined, options: GetManyWithCursorOptions<CursorEntity>): Promise<ListWithCursor<CursorEntity>>;
+        /**
+         * `getManyWithCursor` for raw rows (`getRawMany()`), ordered by SQL expressions, so a computed
+         * value can be a key too: `CASE "member"."role" WHEN 'owner' THEN 0 ELSE 1 END`.
+         *
+         * Orders the query by `options.orderBy`, replacing its ORDER BY, and appends the primary key of
+         * the main alias when the query is on an entity and has no GROUP BY or DISTINCT. Loads
+         * `pageSize + 1` rows with LIMIT and returns `nextCursor` together with `hasMore`. The cursor
+         * names the keys by a hash of their SQL, not the SQL itself.
+         * The query builder itself is not changed. Throws `InvalidCursorError` for a cursor that can't
+         * be decoded or was made for another order.
+         */
+        getRawManyWithCursor<Row = ObjectLiteral>(cursorFilter: CursorPaginationFilter | null | undefined, options: GetRawManyWithCursorOptions): Promise<ListWithCursor<Row>>;
     }
 }

package/dist/extensions/cursor-pagination.extension.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InvalidCursorError = void 0;
 const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder");
-const constants_1 = require("../constants");
+const pagination_utils_1 = require("../utils/pagination.utils");
 const prototype_utils_1 = require("../utils/prototype.utils");
 const order_utils_1 = require("../utils/order.utils");
 const where_utils_1 = require("../utils/where.utils");
 const sql_utils_1 = require("../utils/sql.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
+const common_utils_1 = require("../utils/common.utils");
 const cursor_utils_1 = require("../utils/cursor.utils");
 var cursor_utils_2 = require("../utils/cursor.utils");
 Object.defineProperty(exports, "InvalidCursorError", { enumerable: true, get: function () { return cursor_utils_2.InvalidCursorError; } });
@@ -16,6 +18,9 @@ const extension = {
         getManyWithCursor(cursorFilter, options) {
             return getManyWithCursor(this, cursorFilter, options);
         },
+        getRawManyWithCursor(cursorFilter, options) {
+            return getRawManyWithCursor(this, cursorFilter, options);
+        },
     },
 };
 (0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);
@@ -44,14 +49,11 @@ function getCursorKeys(builder, orderBy) {
     }
     return keys;
 }
-const getPageSize = (pageSize) => typeof pageSize === 'number' && Number.isFinite(pageSize) && pageSize >= 1
-    ? Math.floor(pageSize)
-    : constants_1.defaultPageSize;
 async function getManyWithCursor(builder, cursorFilter, options) {
     const { orderBy, useTakeAndSkip = false } = options !== null && options !== void 0 ? options : {};
     const keys = getCursorKeys(builder, orderBy);
     const fields = keys.map((key) => key.column.propertyPath);
-    const pageSize = getPageSize(cursorFilter === null || cursorFilter === void 0 ? void 0 : cursorFilter.pageSize);
+    const pageSize = (0, pagination_utils_1.normalizePageSize)(cursorFilter === null || cursorFilter === void 0 ? void 0 : cursorFilter.pageSize);
     const query = builder.clone();
     const alias = query.alias;
     const driver = query.connection.driver.options.type;
@@ -68,6 +70,7 @@ async function getManyWithCursor(builder, cursorFilter, options) {
     }
     query.orderBy();
     keys.forEach((key) => query.addOrderBy(`${alias}.${key.column.propertyPath}`, key.direction));
+    const appliedOrderBy = (0, query_builder_utils_1.getAppliedOrderBy)(query);
     // the key values of the last row are read from the raw result: dates and times as text, so the
     // cursor keeps the database's precision (PostgreSQL timestamps have microseconds, a JS Date has not)
     const keyAliases = keys.map((key, i) => {
@@ -81,16 +84,11 @@ async function getManyWithCursor(builder, cursorFilter, options) {
         .map((key, i) => ({ key, i }))
         .filter(({ key }) => key.column.isPrimary)
         .map(({ key, i }) => ({ column: key.column, keyAlias: keyAliases[i] }));
-    if (useTakeAndSkip) {
-        query.take(pageSize + 1);
-    }
-    else {
-        query.limit(pageSize + 1);
-    }
+    (0, pagination_utils_1.setPageLimit)(query, pageSize + 1, useTakeAndSkip);
     const { entities, raw } = await query.getRawAndEntities();
     const list = entities.slice(0, pageSize);
     if (entities.length <= pageSize) {
-        return { list, nextCursor: null, hasMore: false };
+        return { list, nextCursor: null, hasMore: false, pageSize, orderBy: appliedOrderBy };
     }
     // with joined collections there are several raw rows per entity: find one of the last entity's
     const last = list[list.length - 1];
@@ -105,5 +103,84 @@ async function getManyWithCursor(builder, cursorFilter, options) {
         }
         return value;
     });
-    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values), hasMore: true };
+    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values), hasMore: true, pageSize, orderBy: appliedOrderBy };
+}
+/** The expressions of `orderBy`, followed by the primary key of the main alias when it identifies a row. */
+function getExpressionKeys(builder, orderBy) {
+    var _a;
+    const keys = (orderBy !== null && orderBy !== void 0 ? orderBy : []).map(({ selector, direction }) => {
+        if (typeof selector !== 'string' || !selector.trim()) {
+            throw new TypeError('getRawManyWithCursor: every orderBy key needs a selector');
+        }
+        return { selector, direction: (0, order_utils_1.toSqlOrderDirection)(direction) };
+    });
+    const { expressionMap } = builder;
+    const mainAlias = expressionMap.mainAlias;
+    // grouped or distinct rows are not one per entity, and their primary key may not even be selectable
+    const isRowPerEntity = expressionMap.groupBys.length === 0 &&
+        !expressionMap.selectDistinct &&
+        !((_a = expressionMap.selectDistinctOn) === null || _a === void 0 ? void 0 : _a.length);
+    if ((mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.hasMetadata) && isRowPerEntity) {
+        const lastDirection = keys.length ? keys[keys.length - 1].direction : 'ASC';
+        for (const column of mainAlias.metadata.primaryColumns) {
+            const quoted = `${builder.escape(mainAlias.name)}.${builder.escape(column.databaseName)}`;
+            const path = `${mainAlias.name}.${column.propertyPath}`;
+            if (!keys.some((key) => key.selector === quoted || key.selector === path)) {
+                keys.push({ selector: quoted, direction: lastDirection });
+            }
+        }
+    }
+    if (!keys.length) {
+        throw new TypeError('getRawManyWithCursor: orderBy is empty and the query has no primary key to order by');
+    }
+    return keys;
+}
+async function getRawManyWithCursor(builder, cursorFilter, options) {
+    const keys = getExpressionKeys(builder, options === null || options === void 0 ? void 0 : options.orderBy);
+    const fields = keys.map((key) => (0, cursor_utils_1.getExpressionKeyName)(key.selector));
+    const pageSize = (0, pagination_utils_1.normalizePageSize)(cursorFilter === null || cursorFilter === void 0 ? void 0 : cursorFilter.pageSize);
+    const query = builder.clone();
+    const driver = query.connection.driver.options.type;
+    const textCastType = (0, cursor_utils_1.getTextCastType)(driver);
+    if (cursorFilter === null || cursorFilter === void 0 ? void 0 : cursorFilter.cursor) {
+        const values = (0, cursor_utils_1.decodeCursor)(cursorFilter.cursor, fields);
+        const keysetColumns = keys.map((key, i) => {
+            const paramName = (0, sql_utils_1.createUniqueParameterName)(`cursor${i}`);
+            query.setParameter(paramName, values[i]);
+            // in parentheses: an expression may bind looser than the comparison
+            return { column: `(${key.selector})`, direction: key.direction, paramName };
+        });
+        (0, where_utils_1.andWhereNarrowing)(query, (0, cursor_utils_1.buildKeysetCondition)(keysetColumns, (0, cursor_utils_1.supportsRowValueComparison)(driver)));
+    }
+    query.orderBy();
+    keys.forEach((key) => query.addOrderBy(key.selector, key.direction));
+    const appliedOrderBy = (0, query_builder_utils_1.getAppliedOrderBy)(query);
+    // the type of an expression is unknown here: each key is also read as text, which the cursor
+    // takes instead when the driver returned a Date, so timestamps keep the database's precision
+    const keyAliases = keys.map((key, i) => {
+        const valueAlias = `cursor_key_${i}`;
+        const textAlias = textCastType ? `cursor_text_${i}` : undefined;
+        query.addSelect(key.selector, valueAlias);
+        if (textAlias) {
+            query.addSelect(`CAST((${key.selector}) AS ${textCastType})`, textAlias);
+        }
+        return { valueAlias, textAlias };
+    });
+    const addedAliases = new Set(keyAliases.flatMap(({ valueAlias, textAlias }) => (textAlias ? [valueAlias, textAlias] : [valueAlias])));
+    query.limit(pageSize + 1);
+    const rows = await query.getRawMany();
+    const page = rows.slice(0, pageSize);
+    const list = page.map((row) => Object.fromEntries(Object.entries(row).filter(([column]) => !addedAliases.has(column))));
+    if (rows.length <= pageSize) {
+        return { list, nextCursor: null, hasMore: false, pageSize, orderBy: appliedOrderBy };
+    }
+    const last = page[page.length - 1];
+    const values = keyAliases.map(({ valueAlias, textAlias }, i) => {
+        const value = last[valueAlias];
+        if (value === null || value === undefined) {
+            throw new TypeError(`getRawManyWithCursor: "${keys[i].selector}" is NULL in the last row; cursor keys must not be NULL`);
+        }
+        return (0, common_utils_1.isDate)(value) && textAlias ? last[textAlias] : value;
+    });
+    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values), hasMore: true, pageSize, orderBy: appliedOrderBy };
 }

package/dist/extensions/get-many-with-totals.extension.js

@@ -5,6 +5,7 @@ const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder")
 const pagination_utils_1 = require("../utils/pagination.utils");
 const constants_1 = require("../constants");
 const prototype_utils_1 = require("../utils/prototype.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
 // patching
 const extension = {
     prototype: {
@@ -30,8 +31,7 @@ const extension = {
  * runner, so the one that starts second finds a transaction active and does not open its own.
  */
 function canCountConcurrently(builder) {
-    const queryBuilder = builder;
-    return !queryBuilder.queryRunner;
+    return !(0, query_builder_utils_1.getQueryRunner)(builder);
 }
 function getManyWithTotals(builder, paginationFilter, options) {
     return readWithTotals(builder, paginationFilter, options, {
@@ -57,10 +57,9 @@ function getRawManyWithTotals(builder, paginationFilter, options) {
     });
 }
 async function readWithTotals(builder, paginationFilter, options, read) {
-    var _a;
     const { disableTotalsCalculation = false, loadAll = false, ...paginationOptions } = options || {};
-    const { limit, offset } = loadAll
-        ? { limit: null, offset: null }
+    const { limit, offset, page, pageSize } = loadAll
+        ? { limit: null, offset: null, page: null, pageSize: null }
         : (0, pagination_utils_1.getLimitAndOffset)(paginationFilter);
     // without a total, one row past the page is what tells whether more rows follow
     const probeForMore = disableTotalsCalculation && !loadAll && limit !== null;
@@ -68,17 +67,11 @@ async function readWithTotals(builder, paginationFilter, options, read) {
         if (loadAll) {
             return read.rows(builder);
         }
-        const paged = builder.applyPaginationFilter(paginationFilter, paginationOptions);
+        const paged = (0, pagination_utils_1.paginateQuery)(builder, paginationFilter, paginationOptions);
         if (probeForMore) {
-            const probeLimit = limit + 1;
             const { useTakeAndSkip = constants_1.defaultUseTakeAndSkip } = paginationOptions;
-            // replaces the limit applyPaginationFilter just set, keeping its offset
-            if (useTakeAndSkip) {
-                paged.take(probeLimit);
-            }
-            else {
-                paged.limit(probeLimit);
-            }
+            // replaces the limit paginateQuery just set, keeping its offset
+            (0, pagination_utils_1.setPageLimit)(paged, limit + 1, useTakeAndSkip);
         }
         return read.rows(paged);
     };
@@ -109,18 +102,15 @@ async function readWithTotals(builder, paginationFilter, options, read) {
         hasMore =
             total !== null && offset !== null ? offset + rows.length < total : null;
     }
-    // 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
-    const orderBy = Object.entries((_a = builder.expressionMap.allOrderBys) !== null && _a !== void 0 ? _a : {}).map(([selector, value]) => typeof value === 'string'
-        ? { selector, order: value }
-        : { selector, order: value.order, nulls: value.nulls });
     return {
         list,
         total,
+        page,
+        pageSize,
         limit,
         offset,
         hasMore,
-        orderBy,
+        orderBy: (0, query_builder_utils_1.getAppliedOrderBy)(builder),
     };
 }
 /**
@@ -143,9 +133,6 @@ async function bothOrFirstError(first, second) {
 function settle(promise) {
     return promise.then((value) => ({ fulfilled: true, value }), (reason) => ({ fulfilled: false, reason }));
 }
-function getQueryRunner(builder) {
-    return builder.queryRunner;
-}
 /**
  * Counts the rows of a raw query without its pagination and ORDER BY. The query goes into a
  * subquery, so the count is that of its result rows whatever it groups or filters. A
@@ -154,13 +141,7 @@ function getQueryRunner(builder) {
  */
 async function countRawRows(builder, countExpression) {
     var _a;
-    const unpaged = cloneForCount(builder)
-        .orderBy()
-        .offset(undefined)
-        .limit(undefined)
-        .skip(undefined)
-        .take(undefined)
-        .setOption('disable-global-order');
+    const unpaged = (0, query_builder_utils_1.withoutPaging)(cloneForCount(builder));
     let counting;
     if (countExpression) {
         // the expression counts on its own: DISTINCT ON next to an aggregate is an error
@@ -171,7 +152,7 @@ async function countRawRows(builder, countExpression) {
     else {
         // on the builder's query runner, if it has one: inside its transaction
         const counter = builder.connection
-            .createQueryBuilder(getQueryRunner(builder))
+            .createQueryBuilder((0, query_builder_utils_1.getQueryRunner)(builder))
             .select('COUNT(*)', 'count')
             .from(`(${unpaged.getQuery()})`, 'counted')
             .setParameters(unpaged.getParameters());

package/dist/extensions/join-lateral.extension.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const typeorm_1 = require("typeorm");
 const parameter_utils_1 = require("../utils/parameter.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
 const prototype_utils_1 = require("../utils/prototype.utils");
 /* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
 // patching
@@ -32,18 +33,15 @@ function toLateralSql(builder, subQuery) {
         return { sql: `(${subQuery})`, parameters: {} };
     }
     const subBuilder = typeof subQuery === 'function' ? subQuery(detachedSubQuery(builder)) : subQuery;
-    const query = subBuilder.getQuery();
-    // a builder from subQuery() wraps itself in parentheses, any other doesn't
-    const wrapped = subBuilder.expressionMap.subQuery ? query : `(${query})`;
-    const [sql, parameters] = (0, parameter_utils_1.withUniqueParameterNames)(wrapped, subBuilder.getParameters());
-    return { sql, parameters };
+    const [sql, parameters] = (0, parameter_utils_1.toSubQuerySql)(subBuilder);
+    return { sql: `(${sql})`, parameters };
 }
 /**
  * A subquery builder for a factory, as TypeORM's `subQuery()` but without a parent: TypeORM's would
  * set the factory's parameters on the outer query under their own names, before they can be renamed.
  */
 function detachedSubQuery(builder) {
-    const queryRunner = builder.queryRunner;
+    const queryRunner = (0, query_builder_utils_1.getQueryRunner)(builder);
     const subQuery = builder.connection.createQueryBuilder(queryRunner);
     subQuery.expressionMap.subQuery = true;
     return subQuery;