typeorm-extensions 2.1.0 → 2.2.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 koenigstag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -59,6 +59,9 @@ For more information, please refer to the [documentation](https://koenigstag.git
 ## ToDo list
 
 - [x] Add tests for pagination and order extensions
-- [ ] Virtual column decorator and its query-builder methods (`addSelectVirtual`, `orderByVirtual`, `getManyWithVirtual`, `getOneWithVirtual`)
-- [ ] Add `withVirtualColumns` option to `findManyWithTotals` method to use `getManyWithVirtual` instead of `getMany`
-- [ ] Add `isVirtual` option to `OrderParam` to indicate usage of `orderByVirtual` method
+- [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
+
+## License
+
+[MIT](./LICENSE)

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

@@ -0,0 +1,30 @@
+import { ColumnType, ValueTransformer } from 'typeorm';
+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.
+     */
+    type?: ColumnType;
+    /** Converts the selected value, e.g. JSON text from SQLite. Only `from` is used. */
+    transformer?: ValueTransformer | ValueTransformer[];
+};
+/**
+ * A property that a query fills with an SQL expression of its own, through `addSelectCalculated`:
+ * a count, a latest date, a flag. It is no column of the table: schema sync leaves it out, `save`,
+ * `insert` and `update` never write it, and an entity loaded without `addSelectCalculated` doesn't have it.
+ *
+ * Unlike TypeORM's `@VirtualColumn`, whose one SQL query runs whenever the entity is loaded, each
+ * query chooses whether to compute it, and how.
+ *
+ * @example
+ * \@CalculatedColumn()
+ * imagesCount?: number;
+ *
+ * userRepository
+ *   .createQueryBuilder('user')
+ *   .addSelectCalculated('(SELECT COUNT(*) FROM "images" "i" WHERE "i"."userId" = "user"."id")', 'imagesCount')
+ *   .getMany(); // [{ id: 1, …, imagesCount: 2 }]
+ */
+export declare function CalculatedColumn(typeOrOptions?: ColumnType | CalculatedColumnOptions): PropertyDecorator;

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalculatedColumn = void 0;
+const typeorm_1 = require("typeorm");
+/**
+ * A property that a query fills with an SQL expression of its own, through `addSelectCalculated`:
+ * a count, a latest date, a flag. It is no column of the table: schema sync leaves it out, `save`,
+ * `insert` and `update` never write it, and an entity loaded without `addSelectCalculated` doesn't have it.
+ *
+ * Unlike TypeORM's `@VirtualColumn`, whose one SQL query runs whenever the entity is loaded, each
+ * query chooses whether to compute it, and how.
+ *
+ * @example
+ * \@CalculatedColumn()
+ * imagesCount?: number;
+ *
+ * userRepository
+ *   .createQueryBuilder('user')
+ *   .addSelectCalculated('(SELECT COUNT(*) FROM "images" "i" WHERE "i"."userId" = "user"."id")', 'imagesCount')
+ *   .getMany(); // [{ id: 1, …, imagesCount: 2 }]
+ */
+function CalculatedColumn(typeOrOptions) {
+    return (object, propertyName) => {
+        var _a, _b;
+        const options = typeof typeOrOptions === 'object' ? typeOrOptions : { type: typeOrOptions };
+        const reflectedType = typeof Reflect === 'object' && typeof Reflect.getMetadata === 'function'
+            ? Reflect.getMetadata('design:type', object, propertyName)
+            : undefined;
+        // a union type (`string | null`) is reflected as Object, which no driver converts from
+        const type = (_a = options.type) !== null && _a !== void 0 ? _a : (reflectedType !== Object ? reflectedType : undefined);
+        if (!type) {
+            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();
+        // 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({
+            target: object.constructor,
+            propertyName: String(propertyName),
+            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,
+                select: false,
+                insert: false,
+                update: false,
+                transformer: conversion ? [...transformers, conversion] : options.transformer,
+            },
+        });
+    };
+}
+exports.CalculatedColumn = CalculatedColumn;
+function toNumber(value) {
+    if (typeof value === 'bigint') {
+        return Number(value);
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        return value;
+    }
+    const number = Number(value);
+    return Number.isNaN(number) ? value : number;
+}
+function toBoolean(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return !['', '0', 'f', 'false'].includes(value.trim().toLowerCase());
+    }
+    return Boolean(value);
+}
+const numberConversion = { from: toNumber, to: (value) => value };
+const booleanConversion = { from: toBoolean, to: (value) => value };
+const ownConversions = new Map([
+    [Number, numberConversion],
+    [Boolean, booleanConversion],
+    ['boolean', booleanConversion],
+    ['bool', booleanConversion],
+]);

package/dist/decorators/index.d.ts

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

package/dist/decorators/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./calculated-column.decorator"), exports);

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

@@ -0,0 +1,33 @@
+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>);
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> {
+        /**
+         * Selects an SQL expression into a `@CalculatedColumn` property of the main alias's entity:
+         * `getMany()` / `getOne()` put the value into the entities, converted by the column's type.
+         * The selection is `addSelect`'s: an expression or a subquery factory.
+         *
+         * The value is read when the entity is selected as a whole (the alias, not some of its columns).
+         * Throws a `TypeError` if the property isn't a `@CalculatedColumn`.
+         */
+        addSelectCalculated<K extends keyof Entity & string, SubEntity extends ObjectLiteral = ObjectLiteral>(selection: CalculatedSelection<SubEntity>, property: K): this;
+        /** Selects into a `@CalculatedColumn` property of the entity of another alias, e.g. a joined one. */
+        addSelectCalculated<SubEntity extends ObjectLiteral = ObjectLiteral>(selection: CalculatedSelection<SubEntity>, property: string, alias: string): this;
+        /**
+         * Sets ORDER BY the value of a `@CalculatedColumn` property of the main alias's entity, selected
+         * with `addSelectCalculated` first. Replaces the previous ORDER BY, like `orderBy`.
+         *
+         * The value is selected a second time under a generated alias (`calculated_…`) and ordered by it,
+         * which also works with `take` / `skip` and joins; it shows up in `getRawMany()` results.
+         * Throws a `TypeError` if the property isn't a selected `@CalculatedColumn`.
+         */
+        orderByCalculated<K extends keyof Entity & string>(property: K, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST'): this;
+        /** Sets ORDER BY a `@CalculatedColumn` property of the entity of another alias, e.g. a joined one. */
+        orderByCalculated(property: string, order: 'ASC' | 'DESC' | undefined, nulls: 'NULLS FIRST' | 'NULLS LAST' | undefined, alias: string): this;
+        /** Adds ORDER BY the value of a `@CalculatedColumn` property, like `addOrderBy` (see `orderByCalculated`). */
+        addOrderByCalculated<K extends keyof Entity & string>(property: K, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST'): this;
+        /** Adds ORDER BY a `@CalculatedColumn` property of the entity of another alias. */
+        addOrderByCalculated(property: string, order: 'ASC' | 'DESC' | undefined, nulls: 'NULLS FIRST' | 'NULLS LAST' | undefined, alias: string): this;
+    }
+}

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const prototype_utils_1 = require("../utils/prototype.utils");
+const calculated_column_utils_1 = require("../utils/calculated-column.utils");
+// patching
+const extension = {
+    prototype: {
+        addSelectCalculated(selection, property, alias) {
+            return addSelectCalculated(this, selection, property, alias);
+        },
+        orderByCalculated(property, order, nulls, alias) {
+            return attachOrderByCalculated(this, 'orderBy', property, order, nulls, alias);
+        },
+        addOrderByCalculated(property, order, nulls, alias) {
+            return attachOrderByCalculated(this, 'addOrderBy', property, order, nulls, alias);
+        },
+    },
+};
+(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

@@ -9,7 +9,8 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          * deep they are, and rows inserted meanwhile don't shift them.
          *
          * Orders the query by `options.orderBy` (the primary key is appended), replacing its ORDER BY,
-         * loads `pageSize + 1` rows to know whether there is a next page, and returns `nextCursor`.
+         * loads `pageSize + 1` rows to know whether there is a next page, and returns `nextCursor`
+         * together with `hasMore`.
          * The query builder itself is not changed. Throws `InvalidCursorError` for a cursor that can't
          * be decoded or was made for another order.
          */

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

@@ -29,7 +29,8 @@ function getCursorKeys(builder, orderBy) {
     const metadata = mainAlias.metadata;
     const keys = (orderBy !== null && orderBy !== void 0 ? orderBy : []).map(({ field, direction }) => {
         const column = metadata.findColumnWithPropertyPath(String(field));
-        if (!column) {
+        // a @CalculatedColumn is in the metadata, but not in the table
+        if (!column || column.isVirtualProperty) {
             throw new TypeError(`getManyWithCursor: "${String(field)}" is not a column of ${metadata.name}`);
         }
         return { column, direction: (0, order_utils_1.toSqlOrderDirection)(direction) };
@@ -89,7 +90,7 @@ async function getManyWithCursor(builder, cursorFilter, options) {
     const { entities, raw } = await query.getRawAndEntities();
     const list = entities.slice(0, pageSize);
     if (entities.length <= pageSize) {
-        return { list, nextCursor: null };
+        return { list, nextCursor: null, hasMore: false };
     }
     // with joined collections there are several raw rows per entity: find one of the last entity's
     const last = list[list.length - 1];
@@ -104,5 +105,5 @@ async function getManyWithCursor(builder, cursorFilter, options) {
         }
         return value;
     });
-    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values) };
+    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values), hasMore: true };
 }

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

@@ -1,8 +1,16 @@
 import './pagination.extension';
+import { ObjectLiteral } from 'typeorm';
 import { PaginationFilter } from '../types/interfaces/pagination.interface';
-import type { GetManyWithTotalsOptions, ListWithTotals } from '../types/extensions';
+import type { GetManyWithTotalsOptions, GetRawManyWithTotalsOptions, ListWithTotals } from '../types/extensions';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity> {
         getManyWithTotals(paginationFilter: PaginationFilter, options?: GetManyWithTotalsOptions): Promise<ListWithTotals<Entity>>;
+        /**
+         * `getManyWithTotals` for raw rows: the page comes from `getRawMany()`, paged with LIMIT / OFFSET.
+         * `total` is the number of rows the query returns without pagination, counted as a subquery,
+         * `SELECT COUNT(*) FROM (query)`, so GROUP BY, HAVING and DISTINCT count the way they page.
+         * `options.countExpression` counts with an expression of the query instead.
+         */
+        getRawManyWithTotals<Row = ObjectLiteral>(paginationFilter: PaginationFilter, options?: GetRawManyWithTotalsOptions): Promise<ListWithTotals<Row>>;
     }
 }

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("./pagination.extension");
 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");
 // patching
 const extension = {
@@ -10,32 +11,179 @@ const extension = {
         getManyWithTotals(paginationFilter, options) {
             return getManyWithTotals(this, paginationFilter, options);
         },
+        getRawManyWithTotals(paginationFilter, options) {
+            return getRawManyWithTotals(this, paginationFilter, options);
+        },
     },
 };
 (0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);
 // implementation
-async function getManyWithTotals(builder, paginationFilter, options) {
+/**
+ * Whether the count and the page query may run at the same time. A builder bound to a query
+ * runner — inside a transaction, or from a transactional manager — runs them one after another:
+ * there is one connection, on which the driver would serialise them anyway, and on `pg` that queue
+ * is deprecated. Without one, each query obtains a runner: its own pooled connection, or on SQLite
+ * the driver's single shared runner.
+ *
+ * `useTransaction` is not consulted. With a pool each query opens a transaction on its own
+ * connection, whether the two run together or one after another. On SQLite the two share the
+ * 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;
+}
+function getManyWithTotals(builder, paginationFilter, options) {
+    return readWithTotals(builder, paginationFilter, options, {
+        rows: (query) => query.getMany(),
+        // on a clone: getCount writes to the expression map the page query reads
+        count: (query) => cloneForCount(query).getCount(),
+    });
+}
+/** A clone with a cache id of its own: under the page query's id each would read the other's cached rows. */
+function cloneForCount(query) {
+    const clone = query.clone();
+    if (clone.expressionMap.cacheId) {
+        clone.expressionMap.cacheId = `${clone.expressionMap.cacheId}-count`;
+    }
+    return clone;
+}
+function getRawManyWithTotals(builder, paginationFilter, options) {
+    const { countExpression, ...totalsOptions } = options !== null && options !== void 0 ? options : {};
+    // take / skip page entities; raw rows are paged with LIMIT / OFFSET
+    return readWithTotals(builder, paginationFilter, { ...totalsOptions, useTakeAndSkip: false }, {
+        rows: (query) => query.getRawMany(),
+        count: (query) => countRawRows(query, countExpression),
+    });
+}
+async function readWithTotals(builder, paginationFilter, options, read) {
+    var _a;
     const { disableTotalsCalculation = false, loadAll = false, ...paginationOptions } = options || {};
     const { limit, offset } = loadAll
         ? { limit: null, offset: null }
         : (0, pagination_utils_1.getLimitAndOffset)(paginationFilter);
-    const requests = [null, []];
-    if (!disableTotalsCalculation) {
-        requests[0] = await builder.getCount();
+    // without a total, one row past the page is what tells whether more rows follow
+    const probeForMore = disableTotalsCalculation && !loadAll && limit !== null;
+    const readPage = () => {
+        if (loadAll) {
+            return read.rows(builder);
+        }
+        const paged = builder.applyPaginationFilter(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);
+            }
+        }
+        return read.rows(paged);
+    };
+    let total = null;
+    let rows;
+    if (disableTotalsCalculation) {
+        rows = await readPage();
+    }
+    else if (canCountConcurrently(builder)) {
+        // the count clones the builder before readPage mutates it, so it has to start first: the two
+        // queries would otherwise share one expression map, which each of them writes to
+        const counting = read.count(builder);
+        // a page that throws before its query starts (a limit TypeORM rejects) waits for the count too
+        const reading = new Promise((resolve) => resolve(readPage()));
+        [total, rows] = await bothOrFirstError(counting, reading);
+    }
+    else {
+        total = await read.count(builder);
+        rows = await readPage();
     }
-    if (loadAll) {
-        requests[1] = await builder.getMany();
+    let list = rows;
+    let hasMore;
+    if (probeForMore) {
+        hasMore = rows.length > limit;
+        list = hasMore ? rows.slice(0, limit) : rows;
     }
     else {
-        requests[1] = await builder
-            .applyPaginationFilter(paginationFilter, paginationOptions)
-            .getMany();
+        hasMore =
+            total !== null && offset !== null ? offset + rows.length < total : null;
     }
-    const [total, list] = requests;
+    // 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,
         limit,
         offset,
+        hasMore,
+        orderBy,
     };
 }
+/**
+ * Both results, or the first error once both queries have settled. `Promise.all` alone would reject as soon as
+ * one fails, while the other still runs on its own connection: the call would return with a query in flight,
+ * whose outcome nobody reads. When both fail, the count's error is thrown, being the first query started.
+ */
+async function bothOrFirstError(first, second) {
+    const [a, b] = await Promise.all([settle(first), settle(second)]);
+    if (!a.fulfilled) {
+        throw a.reason;
+    }
+    if (!b.fulfilled) {
+        throw b.reason;
+    }
+    return [a.value, b.value];
+}
+// Promise.allSettled is ES2020, past the ES2019 target of the build
+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
+ * `countExpression` replaces the select list instead, without GROUP BY, HAVING and DISTINCT.
+ * Builds the count query before its first `await`, so the builder may change afterwards.
+ */
+async function countRawRows(builder, countExpression) {
+    var _a;
+    const unpaged = cloneForCount(builder)
+        .orderBy()
+        .offset(undefined)
+        .limit(undefined)
+        .skip(undefined)
+        .take(undefined)
+        .setOption('disable-global-order');
+    let counting;
+    if (countExpression) {
+        // the expression counts on its own: DISTINCT ON next to an aggregate is an error
+        const counter = unpaged.select(countExpression, 'count').groupBy().distinct(false).distinctOn([]);
+        counter.expressionMap.havings = [];
+        counting = counter.getRawOne();
+    }
+    else {
+        // on the builder's query runner, if it has one: inside its transaction
+        const counter = builder.connection
+            .createQueryBuilder(getQueryRunner(builder))
+            .select('COUNT(*)', 'count')
+            .from(`(${unpaged.getQuery()})`, 'counted')
+            .setParameters(unpaged.getParameters());
+        // TypeORM 0.3's `$1` / `?` parameters; 1.x has none
+        const { nativeParameters } = unpaged.expressionMap;
+        if (nativeParameters) {
+            counter.setNativeParameters(nativeParameters);
+        }
+        const { cache, cacheId, cacheDuration } = unpaged.expressionMap;
+        Object.assign(counter.expressionMap, { cache, cacheId, cacheDuration });
+        counting = counter.getRawOne();
+    }
+    // COUNT is a bigint on PostgreSQL, which the driver hands over as a string
+    const row = await counting;
+    return Number((_a = row === null || row === void 0 ? void 0 : row.count) !== null && _a !== void 0 ? _a : 0);
+}

package/dist/extensions/index.d.ts

@@ -10,3 +10,10 @@ export * from './period-filter.extension';
 export * from './cursor-pagination.extension';
 export * from './order-by-array-position.extension';
 export * from './typed';
+export * from './union.extension';
+export * from './calculated-column.extension';
+export * from './join-unnest.extension';
+export * from './join-lateral.extension';
+export * from './where-exists.extension';
+export * from './where-relation-exists.extension';
+export * from './query-returning.extension';

package/dist/extensions/index.js

@@ -26,3 +26,10 @@ __exportStar(require("./period-filter.extension"), exports);
 __exportStar(require("./cursor-pagination.extension"), exports);
 __exportStar(require("./order-by-array-position.extension"), exports);
 __exportStar(require("./typed"), exports);
+__exportStar(require("./union.extension"), exports);
+__exportStar(require("./calculated-column.extension"), exports);
+__exportStar(require("./join-unnest.extension"), exports);
+__exportStar(require("./join-lateral.extension"), exports);
+__exportStar(require("./where-exists.extension"), exports);
+__exportStar(require("./where-relation-exists.extension"), exports);
+__exportStar(require("./query-returning.extension"), exports);

package/dist/extensions/join-lateral.extension.d.ts

@@ -0,0 +1,19 @@
+import { ObjectLiteral } from 'typeorm';
+import type { LateralSubQuery } from '../types/extensions/join-lateral.types';
+export interface JoinLateralMethods {
+    /**
+     * `LEFT JOIN LATERAL (subQuery) "alias" ON condition`: the subquery runs for each row and can use
+     * the columns of the tables joined before it, e.g. the latest ticket of each user. Rows without a
+     * match stay, with `NULL` columns. The condition defaults to `TRUE`.
+     *
+     * PostgreSQL, CockroachDB, MySQL 8.0.14+ and Oracle have LATERAL; SQLite, SQL Server and MariaDB don't.
+     * The subquery's columns are raw: select them with `addSelect('"alias"."column"', 'name')`.
+     */
+    leftJoinLateral<SubEntity extends ObjectLiteral = ObjectLiteral>(subQuery: LateralSubQuery<SubEntity>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+    /** `INNER JOIN LATERAL`: as `leftJoinLateral`, but rows without a match are dropped. */
+    innerJoinLateral<SubEntity extends ObjectLiteral = ObjectLiteral>(subQuery: LateralSubQuery<SubEntity>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends JoinLateralMethods {
+    }
+}

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const parameter_utils_1 = require("../utils/parameter.utils");
+const prototype_utils_1 = require("../utils/prototype.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
+// patching
+const extension = {
+    prototype: {
+        leftJoinLateral(subQuery, alias, condition, parameters) {
+            return joinLateral(this, 'leftJoin', subQuery, alias, condition, parameters);
+        },
+        innerJoinLateral(subQuery, alias, condition, parameters) {
+            return joinLateral(this, 'innerJoin', subQuery, alias, condition, parameters);
+        },
+    },
+};
+(0, prototype_utils_1.patchPrototype)(typeorm_1.SelectQueryBuilder, extension);
+function joinLateral(builder, method, subQuery, alias, condition = 'TRUE', parameters) {
+    const lateral = toLateralSql(builder, subQuery);
+    // TypeORM puts the getQuery() of a join's subquery factory into the SQL as it is, and adds its
+    // getParameters(): handing it the LATERAL keyword with the subquery is its own subquery-join path
+    const factory = () => ({
+        getQuery: () => `LATERAL ${lateral.sql}`,
+        getParameters: () => lateral.parameters,
+    });
+    return builder[method](factory, alias, condition, parameters);
+}
+function toLateralSql(builder, subQuery) {
+    if (typeof subQuery === 'string') {
+        // raw SQL: its placeholders are the query's own parameters, set with `parameters` or setParameter
+        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 };
+}
+/**
+ * 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 subQuery = builder.connection.createQueryBuilder(queryRunner);
+    subQuery.expressionMap.subQuery = true;
+    return subQuery;
+}

package/dist/extensions/join-unnest.extension.d.ts

@@ -0,0 +1,19 @@
+import { ObjectLiteral } from 'typeorm';
+import { ArgsType } from '../types/util-types';
+export interface JoinUnnestMethods {
+    /**
+     * Keeps the rows whose `field` is one of `array`, joining the array as a set of rows:
+     * `INNER JOIN (SELECT DISTINCT unnest(CAST(:array AS uuid[])) AS "value") "unnest_x7k2q"
+     * ON "user"."id" = "unnest_x7k2q"."value"`. The same rows as `whereIsAny(field, array)`; for a
+     * large array the planner can join from it instead of testing every row against it.
+     *
+     * `arrayType` (`'uuid[]'`) defaults to the array of the column type, when `field` names an entity
+     * column; otherwise, and for enum columns, it is required. An empty array matches no row.
+     * PostgreSQL and CockroachDB.
+     */
+    innerJoinUnnest(field: string, array: ArgsType | null | undefined, arrayType?: string): this;
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends JoinUnnestMethods {
+    }
+}