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

package/README.md

@@ -57,8 +57,8 @@ npm install typeorm-extensions
 
 **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`: keyset pagination with an opaque cursor
-- `applyPaginationFilter` for a page of any query
+- `getManyWithCursor` and `getRawManyWithCursor`: keyset pagination with an opaque cursor, by columns or by SQL expressions
+- `applyPagination` for a page of any query
 
 **Filters and ordering** ([docs](https://koenigstag.github.io/typeorm-extensions/docs/api/where/))
 - `whereIsIn` / `whereIsNotIn` that handle empty arrays, `whereIsAny`, null-safe `whereIsDistinctFrom`

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

@@ -1,6 +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> {
@@ -16,5 +16,17 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          * be decoded or was made for another order.
          */
         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

@@ -8,6 +8,7 @@ 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; } });
@@ -17,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);
@@ -101,3 +105,82 @@ async function getManyWithCursor(builder, cursorFilter, options) {
     });
     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

@@ -67,10 +67,10 @@ 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 { useTakeAndSkip = constants_1.defaultUseTakeAndSkip } = paginationOptions;
-            // replaces the limit applyPaginationFilter just set, keeping its offset
+            // replaces the limit paginateQuery just set, keeping its offset
             (0, pagination_utils_1.setPageLimit)(paged, limit + 1, useTakeAndSkip);
         }
         return read.rows(paged);

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

@@ -3,6 +3,12 @@ import { ObjectLiteral } from 'typeorm';
 import { ApplyPaginationOptions } from '../types/extensions/pagination.types';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
+        /**
+         * Pages the query by `page` and `pageSize` (page 1 and 10 rows by default): LIMIT / OFFSET, or
+         * `take` / `skip` with `useTakeAndSkip`, which a query joining a collection needs.
+         */
+        applyPagination(paginationFilter: PaginationFilter, options?: ApplyPaginationOptions): this;
+        /** @deprecated Use `applyPagination`, which takes the same arguments. Will be removed in 3.0. */
         applyPaginationFilter(paginationFilter: PaginationFilter, options?: ApplyPaginationOptions): this;
     }
 }

package/dist/extensions/pagination.extension.js

@@ -1,25 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable @typescript-eslint/no-explicit-any */
 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");
 // patching
 const extension = {
     prototype: {
+        applyPagination(paginationFilter, options) {
+            return (0, pagination_utils_1.paginateQuery)(this, paginationFilter, options);
+        },
+        // calls the implementation, not this.applyPagination: an application may patch a method of that name itself
         applyPaginationFilter(paginationFilter, options) {
-            return applyPaginationFilter(this, paginationFilter, options);
+            return (0, pagination_utils_1.paginateQuery)(this, paginationFilter, options);
         },
     },
 };
 (0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);
-// implementation
-function applyPaginationFilter(builder, paginationFilter, options) {
-    const { useTakeAndSkip = constants_1.defaultUseTakeAndSkip } = options || {};
-    const { limit, offset } = (0, pagination_utils_1.getLimitAndOffset)(paginationFilter);
-    if (useTakeAndSkip) {
-        return builder.take(limit).skip(offset);
-    }
-    return builder.limit(limit).offset(offset);
-}

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

@@ -1,4 +1,4 @@
-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> = {
     /**
@@ -10,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;
@@ -21,6 +31,6 @@ export interface ListWithCursor<Entity> {
     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. */
+    /** The ORDER BY the page was read in: the `orderBy` keys, then the primary key columns not among them. */
     orderBy: OrderType[];
 }

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/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,6 +1,6 @@
 "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). */
@@ -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) };

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

@@ -1,4 +1,5 @@
 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;
@@ -10,3 +11,5 @@ export declare const getLimitAndOffset: ({ page, pageSize }: PaginationFilter) =
     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>;

package/dist/utils/pagination.utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLimitAndOffset = exports.setPageLimit = exports.normalizePageSize = void 0;
+exports.paginateQuery = 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) => {
@@ -24,3 +24,10 @@ const getLimitAndOffset = ({ page, pageSize }) => {
     };
 };
 exports.getLimitAndOffset = getLimitAndOffset;
+/** What `applyPagination` does, for code that must not depend on what is patched under that name. */
+const paginateQuery = (builder, paginationFilter, options) => {
+    const { useTakeAndSkip = constants_1.defaultUseTakeAndSkip } = options || {};
+    const { limit, offset } = (0, exports.getLimitAndOffset)(paginationFilter);
+    return useTakeAndSkip ? builder.take(limit).skip(offset) : builder.limit(limit).offset(offset);
+};
+exports.paginateQuery = paginateQuery;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeorm-extensions",
-  "version": "2.2.0-rc.10",
+  "version": "2.2.0-rc.11",
   "description": "typeorm commonly used extensions",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",