typeorm-extensions 1.3.5 → 2.0.0

package/README.md

@@ -27,23 +27,27 @@ npm install typeorm-extensions
 ## Usage
 
 ```typescript
-import 'typeorm-extensions'; // Import the library root to extend the QueryBuilder with all extensions
+import { tableHelper } from 'typeorm-extensions'; // Importing the library root extends the QueryBuilder with all extensions
 
 // Or init specific extension: import 'typeorm-extensions/dist/extensions/pagination.extension';
 
+// Type-safe SQL fragments for an entity alias
+const t = tableHelper<UserEntity>('users');
+
 const query = myDataSource
-  .createQueryBuilder()
-  .from(UserEntity, 'users')
+  .getRepository(UserEntity)
+  .createQueryBuilder('users')
   // Join relation defined in entity model
   .leftJoinTyped(user => user.images, 'images')
   // Select type-safe properties
-  .selectTyped(user => ([
-    id: user.id,
-    name: user.name,
-    email: user.email,
-  ]))
+  .selectTyped(user => [
+    user.id,
+    user.name,
+    user.email,
+    user.images.url,
+  ])
   .whereTyped(user => user.name, 'ILIKE', 'John')
-  .andWhereTyped(user => user.metadata, ` ->> 'jsonField' =`, 'some-value')
+  .andWhereTyped(user => user.metadata, `${t.jsonPath('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
@@ -56,7 +60,7 @@ For more information, please refer to the [documentation](https://koenigstag.git
 
 ## ToDo list
 
-- [ ] Add tests for pagination and order extensions
+- [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

package/dist/constants/index.d.ts

@@ -1,5 +1,5 @@
 export declare const defaultPageSize = 10;
 export declare const defaultUseTakeAndSkip = false;
-export declare const defaultUseDoubleQuotes = true;
+export declare const defaultUseQuotes = true;
 export declare const defaultOrderDirection = "ASC";
 export declare const defaultNullsOrder: undefined;

package/dist/constants/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultNullsOrder = exports.defaultOrderDirection = exports.defaultUseDoubleQuotes = exports.defaultUseTakeAndSkip = exports.defaultPageSize = void 0;
+exports.defaultNullsOrder = exports.defaultOrderDirection = exports.defaultUseQuotes = exports.defaultUseTakeAndSkip = exports.defaultPageSize = void 0;
 exports.defaultPageSize = 10;
 exports.defaultUseTakeAndSkip = false;
-exports.defaultUseDoubleQuotes = true;
+exports.defaultUseQuotes = true;
 exports.defaultOrderDirection = 'ASC';
 exports.defaultNullsOrder = undefined;

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

@@ -0,0 +1,18 @@
+import type { CursorPaginationFilter } from '../types/interfaces/cursor-pagination.interface';
+import type { GetManyWithCursorOptions, ListWithCursor } from '../types/extensions/cursor-pagination.types';
+export { InvalidCursorError } from '../utils/cursor.utils';
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity> {
+        /**
+         * Loads a page with keyset (cursor) pagination: instead of OFFSET, the rows after the last row of
+         * the previous page, `WHERE (createdAt, id) < (:lastCreatedAt, :lastId)`. Pages stay fast however
+         * 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`.
+         * 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>>;
+    }
+}

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

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidCursorError = void 0;
+const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder");
+const constants_1 = require("../constants");
+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 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; } });
+// patching
+const extension = {
+    prototype: {
+        getManyWithCursor(cursorFilter, options) {
+            return getManyWithCursor(this, cursorFilter, options);
+        },
+    },
+};
+(0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);
+const isDateColumn = (column) => column.type === Date || (typeof column.type === 'string' && /date|time/i.test(column.type));
+/** The columns of `orderBy`, followed by the primary key columns that aren't among them. */
+function getCursorKeys(builder, orderBy) {
+    const mainAlias = builder.expressionMap.mainAlias;
+    if (!(mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.hasMetadata)) {
+        throw new TypeError('getManyWithCursor needs a query on an entity (createQueryBuilder of a repository or an entity)');
+    }
+    const metadata = mainAlias.metadata;
+    const keys = (orderBy !== null && orderBy !== void 0 ? orderBy : []).map(({ field, direction }) => {
+        const column = metadata.findColumnWithPropertyPath(String(field));
+        if (!column) {
+            throw new TypeError(`getManyWithCursor: "${String(field)}" is not a column of ${metadata.name}`);
+        }
+        return { column, direction: (0, order_utils_1.toSqlOrderDirection)(direction) };
+    });
+    // the primary key makes the order total: rows with equal keys can't be skipped or repeated
+    const lastDirection = keys.length ? keys[keys.length - 1].direction : 'ASC';
+    for (const column of metadata.primaryColumns) {
+        if (!keys.some((key) => key.column === column)) {
+            keys.push({ column, direction: lastDirection });
+        }
+    }
+    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 query = builder.clone();
+    const alias = query.alias;
+    const driver = query.connection.driver.options.type;
+    const textCastType = (0, cursor_utils_1.getTextCastType)(driver);
+    const quotedColumn = (column) => `${query.escape(alias)}.${query.escape(column.databaseName)}`;
+    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]);
+            return { column: quotedColumn(key.column), 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(`${alias}.${key.column.propertyPath}`, key.direction));
+    // 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) => {
+        const keyAlias = `cursor_key_${i}`;
+        const column = quotedColumn(key.column);
+        const selection = isDateColumn(key.column) && textCastType ? `CAST(${column} AS ${textCastType})` : column;
+        query.addSelect(selection, keyAlias);
+        return keyAlias;
+    });
+    const primaryAliases = keys
+        .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);
+    }
+    const { entities, raw } = await query.getRawAndEntities();
+    const list = entities.slice(0, pageSize);
+    if (entities.length <= pageSize) {
+        return { list, nextCursor: null };
+    }
+    // with joined collections there are several raw rows per entity: find one of the last entity's
+    const last = list[list.length - 1];
+    const lastRaw = raw.find((row) => primaryAliases.every(({ column, keyAlias }) => String(row[keyAlias]) === String(column.getEntityValue(last))));
+    if (!lastRaw) {
+        throw new Error('getManyWithCursor: could not find the key values of the last row');
+    }
+    const values = keyAliases.map((keyAlias, i) => {
+        const value = lastRaw[keyAlias];
+        if (value === null || value === undefined) {
+            throw new TypeError(`getManyWithCursor: "${fields[i]}" is NULL in the last row; cursor keys must be non-null columns`);
+        }
+        return value;
+    });
+    return { list, nextCursor: (0, cursor_utils_1.encodeCursor)(fields, values) };
+}

package/dist/extensions/index.d.ts

@@ -2,4 +2,11 @@ export * from './get-many-with-totals.extension';
 export * from './order.extension';
 export * from './pagination.extension';
 export * from './where-is-in.extension';
+export * from './where-is-any.extension';
+export * from './where-array.extension';
+export * from './where-json.extension';
+export * from './where-is-distinct-from.extension';
+export * from './period-filter.extension';
+export * from './cursor-pagination.extension';
+export * from './order-by-array-position.extension';
 export * from './typed';

package/dist/extensions/index.js

@@ -18,4 +18,11 @@ __exportStar(require("./get-many-with-totals.extension"), exports);
 __exportStar(require("./order.extension"), exports);
 __exportStar(require("./pagination.extension"), exports);
 __exportStar(require("./where-is-in.extension"), exports);
+__exportStar(require("./where-is-any.extension"), exports);
+__exportStar(require("./where-array.extension"), exports);
+__exportStar(require("./where-json.extension"), exports);
+__exportStar(require("./where-is-distinct-from.extension"), exports);
+__exportStar(require("./period-filter.extension"), exports);
+__exportStar(require("./cursor-pagination.extension"), exports);
+__exportStar(require("./order-by-array-position.extension"), exports);
 __exportStar(require("./typed"), exports);

package/dist/extensions/order-by-array-position.extension.d.ts

@@ -0,0 +1,24 @@
+import { ObjectLiteral } from 'typeorm';
+import type { ArgsType } from '../types/util-types';
+export interface OrderByArrayPositionMethods {
+    /**
+     * Sets ORDER BY the position of the column's value in `values` (PostgreSQL):
+     * `array_position(:values, column)`. Keeps the order of ids that come from elsewhere
+     * (search results, recommendations), e.g. after `whereIsAny(column, ids)`.
+     * Rows whose value isn't in `values` come last. `arrayType` (e.g. `'uuid[]'`) casts the array.
+     * Like `orderBy`, it replaces the previous ORDER BY.
+     *
+     * The position is selected under a generated alias (`array_position_…`) and ordered by it,
+     * which also works with `take` / `skip` and joins; it shows up in `getRawMany()` results.
+     */
+    orderByArrayPosition(field: string, values: ArgsType, arrayType?: string): this;
+    /**
+     * Adds ORDER BY the position of the column's value in `values` (PostgreSQL), like `addOrderBy`.
+     * See `orderByArrayPosition`.
+     */
+    addOrderByArrayPosition(field: string, values: ArgsType, arrayType?: string): this;
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends OrderByArrayPositionMethods {
+    }
+}

package/dist/extensions/order-by-array-position.extension.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder");
+const prototype_utils_1 = require("../utils/prototype.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
+const order_utils_1 = require("../utils/order.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
+// patching
+const createOrderByArrayPositionMethod = (replace) => function (field, values, arrayType) {
+    return (0, order_utils_1.attachOrderByArrayPosition)(this, (0, query_builder_utils_1.toFieldSql)(this, field), values, arrayType, replace);
+};
+const extension = {
+    prototype: {
+        orderByArrayPosition: createOrderByArrayPositionMethod(true),
+        addOrderByArrayPosition: createOrderByArrayPositionMethod(false),
+    },
+};
+(0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);

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

@@ -1,8 +1,9 @@
 import type { OrderParam, OrderFilter } from '../types/interfaces/ordering.interface';
+import { ObjectLiteral } from 'typeorm';
 import type { ApplyOrderOptions } from '../types/extensions/order.types';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity> {
-        applyOrder<OrderEntity>(orderBy: OrderParam<OrderEntity>, options?: ApplyOrderOptions): SelectQueryBuilder<Entity>;
-        applyOrderFilter<OrderEntity>(orderFilter: OrderFilter<OrderEntity>, options?: ApplyOrderOptions): SelectQueryBuilder<Entity>;
+        applyOrder<OrderEntity extends ObjectLiteral>(orderBy: OrderParam<OrderEntity>, options?: ApplyOrderOptions): SelectQueryBuilder<Entity>;
+        applyOrderFilter<OrderEntity extends ObjectLiteral>(orderFilter: OrderFilter<OrderEntity>, options?: ApplyOrderOptions): SelectQueryBuilder<Entity>;
     }
 }

package/dist/extensions/order.extension.js

@@ -4,8 +4,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder");
 const constants_1 = require("../constants");
 const common_utils_1 = require("../utils/common.utils");
-const identifier_utils_1 = require("../utils/identifier.utils");
 const prototype_utils_1 = require("../utils/prototype.utils");
+const table_utils_1 = require("../utils/table.utils");
+const order_utils_1 = require("../utils/order.utils");
+const query_builder_utils_1 = require("../utils/query-builder.utils");
 // patching
 const extension = {
     prototype: {
@@ -28,22 +30,23 @@ const alwaysAliasWhiteList = [
     'deletedAt',
     'deleted_at',
 ];
-function getOrderOption(orderBy, defaultAlias, options) {
-    const { useDoubleQuotes = constants_1.defaultUseDoubleQuotes, alias: customAlias, alwaysAliasFields = alwaysAliasWhiteList, } = options !== null && options !== void 0 ? options : {};
+function getOrderOption(builder, orderBy, options) {
+    var _a;
+    const defaultAlias = builder.alias;
+    const { useQuotes = constants_1.defaultUseQuotes, alias: customAlias, alwaysAliasFields = alwaysAliasWhiteList, } = options !== null && options !== void 0 ? options : {};
     const { field, direction, isReversed, nulls: nullsOrder, tableAlias: otherTableAlias, } = orderBy;
     const alias = otherTableAlias || customAlias ||
         (alwaysAliasFields.includes(field) ? defaultAlias : undefined);
-    const identifier = new identifier_utils_1.Identifier(field, alias, useDoubleQuotes);
-    const selector = identifier.fieldIdentifier();
+    const table = (0, table_utils_1.tableHelper)(alias, { useQuotes });
+    // TypeORM maps an unquoted `alias.property` to the column itself; anything else must name the
+    // column: `@Column({ name: 'created_at' }) createdAt` is ordered by "created_at", not "createdAt"
+    const column = alias && !useQuotes
+        ? field
+        : (_a = (0, query_builder_utils_1.getColumnDatabaseName)(builder, alias, field)) !== null && _a !== void 0 ? _a : field;
+    const selector = table.column(column);
     const order = typeof isReversed === 'boolean' && (0, common_utils_1.isNil)(direction)
         ? (isReversed ? 'DESC' : 'ASC')
-        : typeof direction === 'boolean'
-            ? (direction ? 'ASC' : 'DESC')
-            : typeof direction === 'number'
-                ? (direction === -1 ? 'DESC' : 'ASC')
-                : typeof direction === 'string' && /asc|desc/i.test(direction)
-                    ? direction.toUpperCase()
-                    : constants_1.defaultOrderDirection;
+        : (0, order_utils_1.toSqlOrderDirection)(direction);
     const nulls = typeof nullsOrder === 'string' && /first|last/i.test(nullsOrder)
         ? `NULLS ${nullsOrder.toUpperCase()}`
         : constants_1.defaultNullsOrder;
@@ -55,7 +58,7 @@ function getOrderOption(orderBy, defaultAlias, options) {
 }
 function applyOrder(builder, orderBy, options) {
     const { resetPreviousOrder = false } = options !== null && options !== void 0 ? options : {};
-    const orderOption = getOrderOption(orderBy, builder.alias, options);
+    const orderOption = getOrderOption(builder, orderBy, options);
     const query = resetPreviousOrder ? builder.orderBy() : builder;
     return query.addOrderBy(orderOption.selector, orderOption.order, orderOption.nulls);
 }

package/dist/extensions/period-filter.extension.d.ts

@@ -0,0 +1,29 @@
+import { ObjectLiteral } from 'typeorm';
+import type { PeriodFilter } from '../types/interfaces/period.interface';
+import type { ApplyPeriodOptions } from '../types/extensions/period.types';
+export interface PeriodFilterMethods {
+    /**
+     * Adds AND WHERE conditions for a period: `field >= :periodFrom AND field <= :periodTo`.
+     * Missing, `null` or empty ends are skipped, so an empty filter adds nothing.
+     * Both ends are inclusive unless `options.includeFrom` / `options.includeTo` is `false`.
+     * A date-only string (`'2024-01-31'`) stands for the whole day: `periodTo: '2024-01-31'` → `field < '2024-02-01'`.
+     * Invalid dates (`new Date('x')`, `'2024-02-30'`) throw a `TypeError`.
+     */
+    applyPeriodFilter(field: string, periodFilter: PeriodFilter | null | undefined, options?: ApplyPeriodOptions): this;
+}
+declare module 'typeorm/query-builder/WhereExpressionBuilder' {
+    interface WhereExpressionBuilder extends PeriodFilterMethods {
+    }
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends PeriodFilterMethods {
+    }
+}
+declare module 'typeorm/query-builder/UpdateQueryBuilder' {
+    interface UpdateQueryBuilder<Entity extends ObjectLiteral> extends PeriodFilterMethods {
+    }
+}
+declare module 'typeorm/query-builder/DeleteQueryBuilder' {
+    interface DeleteQueryBuilder<Entity extends ObjectLiteral> extends PeriodFilterMethods {
+    }
+}

package/dist/extensions/period-filter.extension.js

@@ -0,0 +1,23 @@
+"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 period_utils_1 = require("../utils/period.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface, @typescript-eslint/no-unused-vars */
+// patching
+const extension = {
+    prototype: {
+        applyPeriodFilter(field, periodFilter, options) {
+            return (0, period_utils_1.attachPeriodFilter)(this, (0, query_builder_utils_1.toFieldSql)(this, field), periodFilter, options);
+        },
+    },
+};
+const queryBuilders = [
+    typeorm_1.SelectQueryBuilder,
+    typeorm_1.UpdateQueryBuilder,
+    typeorm_1.DeleteQueryBuilder,
+];
+queryBuilders.forEach((builder) => {
+    (0, prototype_utils_1.patchPrototype)(builder, extension);
+});

package/dist/extensions/typed/index.d.ts

@@ -4,3 +4,13 @@ export * from './typed-order-by/typed-order-by.extension';
 export * from './typed-select/typed-select.extension';
 export * from './typed-where/typed-where.extension';
 export * from './typed-where/typed-where-is-in.extension';
+export * from './typed-where/typed-where-is-any.extension';
+export * from './typed-where/typed-where-array.extension';
+export * from './typed-where/typed-where-json.extension';
+export * from './typed-where/typed-where-is-distinct-from.extension';
+export * from './typed-where/typed-period-filter.extension';
+export * from './typed-where/typed-where-ilike.extension';
+export * from './typed-where/typed-where-lower.extension';
+export * from './typed-where/typed-where-similar.extension';
+export * from './typed-returning/typed-returning.extension';
+export * from './typed-order-by/typed-order-by-array-position.extension';

package/dist/extensions/typed/index.js

@@ -23,3 +23,13 @@ __exportStar(require("./typed-order-by/typed-order-by.extension"), exports);
 __exportStar(require("./typed-select/typed-select.extension"), exports);
 __exportStar(require("./typed-where/typed-where.extension"), exports);
 __exportStar(require("./typed-where/typed-where-is-in.extension"), exports);
+__exportStar(require("./typed-where/typed-where-is-any.extension"), exports);
+__exportStar(require("./typed-where/typed-where-array.extension"), exports);
+__exportStar(require("./typed-where/typed-where-json.extension"), exports);
+__exportStar(require("./typed-where/typed-where-is-distinct-from.extension"), exports);
+__exportStar(require("./typed-where/typed-period-filter.extension"), exports);
+__exportStar(require("./typed-where/typed-where-ilike.extension"), exports);
+__exportStar(require("./typed-where/typed-where-lower.extension"), exports);
+__exportStar(require("./typed-where/typed-where-similar.extension"), exports);
+__exportStar(require("./typed-returning/typed-returning.extension"), exports);
+__exportStar(require("./typed-order-by/typed-order-by-array-position.extension"), exports);

package/dist/extensions/typed/typed-distinct/typed-distinct.extension.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const typeorm_1 = require("typeorm");
-const proxy_key_utils_1 = require("../../../utils/proxy-key.utils");
+const query_builder_utils_1 = require("../../../utils/query-builder.utils");
 // patching and implementation
 typeorm_1.SelectQueryBuilder.prototype.distinctOnTyped = function (...distinctOn) {
     if (Array.isArray(distinctOn) && distinctOn.length) {
-        const keys = distinctOn.map((callback) => (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(callback, this.alias)).flat();
+        const keys = distinctOn.map((callback) => (0, query_builder_utils_1.getTypedSelectionKey)(this, callback)).flat();
         return this.distinctOn(keys);
     }
     return this;

package/dist/extensions/typed/typed-joins/typed-joins.extension.js

@@ -28,6 +28,7 @@ typeorm_1.SelectQueryBuilder.prototype.innerJoinAndSelectTyped = function (selec
     return this;
 };
 function addJoin(query, method, selection, alias, condition, parameters) {
-    const key = (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(selection, query.alias, false);
+    // `() => query.alias`: `(q) => q.base.images` needs no main alias, only `(u) => u.images` does
+    const key = (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(selection, () => query.alias, false);
     return query[method](key, alias, condition, parameters);
 }

package/dist/extensions/typed/typed-order-by/typed-order-by-array-position.extension.d.ts

@@ -0,0 +1,20 @@
+import '../../order-by-array-position.extension';
+import { ObjectLiteral } from 'typeorm';
+import { DeepUnwrapArray, ProxyColumnValueType } from '../../../types/modules/proxy-callback.types';
+import type { ArgsType } from '../../../types/util-types';
+export interface TypedOrderByArrayPositionMethods<Entity extends ObjectLiteral> {
+    /**
+     * Sets ORDER BY the position of the property's column value in `values` (PostgreSQL):
+     * `array_position(:values, column)`. Rows whose value isn't in `values` come last.
+     * Like `orderBy`, it replaces the previous ORDER BY. See `orderByArrayPosition`.
+     */
+    orderByArrayPositionTyped<Type extends ObjectLiteral = Entity>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, values: ArgsType, arrayType?: string): this;
+    /**
+     * Adds ORDER BY the position of the property's column value in `values` (PostgreSQL), like `addOrderBy`.
+     */
+    addOrderByArrayPositionTyped<Type extends ObjectLiteral = Entity>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, values: ArgsType, arrayType?: string): this;
+}
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> extends TypedOrderByArrayPositionMethods<Entity> {
+    }
+}

package/dist/extensions/typed/typed-order-by/typed-order-by-array-position.extension.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../../order-by-array-position.extension");
+const SelectQueryBuilder_1 = require("typeorm/query-builder/SelectQueryBuilder");
+const query_builder_utils_1 = require("../../../utils/query-builder.utils");
+const prototype_utils_1 = require("../../../utils/prototype.utils");
+const order_utils_1 = require("../../../utils/order.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface */
+// patching
+const createOrderByArrayPositionTypedMethod = (replace) => function (selection, values, arrayType) {
+    const methodName = replace ? 'orderByArrayPositionTyped' : 'addOrderByArrayPositionTyped';
+    const column = (0, query_builder_utils_1.getTypedSingleColumnKey)(this, selection, methodName);
+    return (0, order_utils_1.attachOrderByArrayPosition)(this, column, values, arrayType, replace);
+};
+const extension = {
+    prototype: {
+        orderByArrayPositionTyped: createOrderByArrayPositionTypedMethod(true),
+        addOrderByArrayPositionTyped: createOrderByArrayPositionTypedMethod(false),
+    },
+};
+(0, prototype_utils_1.patchPrototype)(SelectQueryBuilder_1.SelectQueryBuilder, extension);

package/dist/extensions/typed/typed-order-by/typed-order-by.extension.d.ts

@@ -1,6 +1,7 @@
 import { ObjectLiteral } from 'typeorm';
-import { ProxyColumnValueType } from '../../../types/modules/proxy-callback.types';
+import { DeepUnwrapArray, ProxyColumnValueType } from '../../../types/modules/proxy-callback.types';
 import { KeyHolder } from '../../../utils/proxy-key.utils';
+import type { TypedOrderByOptions } from '../../../types/extensions/typed-order-by.types';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
         /**
@@ -8,10 +9,10 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          * If you had previously ORDER BY expression defined,
          * calling this function will override previously set ORDER BY conditions.
          */
-        orderByTyped<Type extends ObjectLiteral = Entity>(this: SelectQueryBuilder<Entity>, selection: (proxy: Type) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST'): SelectQueryBuilder<Entity>;
+        orderByTyped<Type extends ObjectLiteral = Entity>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): SelectQueryBuilder<Entity>;
         /**
          * Adds ORDER BY condition in the query builder.
          */
-        addOrderByTyped<Type extends ObjectLiteral = Entity>(this: SelectQueryBuilder<Entity>, selection: (proxy: Type) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST'): SelectQueryBuilder<Entity>;
+        addOrderByTyped<Type extends ObjectLiteral = Entity>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): SelectQueryBuilder<Entity>;
     }
 }

package/dist/extensions/typed/typed-order-by/typed-order-by.extension.js

@@ -2,23 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const typeorm_1 = require("typeorm");
 const proxy_key_utils_1 = require("../../../utils/proxy-key.utils");
+const query_builder_utils_1 = require("../../../utils/query-builder.utils");
 // patching and implementation
-typeorm_1.SelectQueryBuilder.prototype.orderByTyped = function (selection, order, nulls) {
+typeorm_1.SelectQueryBuilder.prototype.orderByTyped = function (selection, order, nulls, options) {
     if (selection instanceof proxy_key_utils_1.KeyHolder) {
-        return this.orderBy(selection.toSql(), order, nulls);
+        return this.orderBy(selection.toSql(undefined, options === null || options === void 0 ? void 0 : options.useQuotes), order, nulls);
     }
     if (typeof selection === 'function') {
-        const key = (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(selection, this.alias);
+        const key = (0, query_builder_utils_1.getTypedSelectionKey)(this, selection, options === null || options === void 0 ? void 0 : options.useQuotes);
         return this.orderBy(key, order, nulls);
     }
     return this;
 };
-typeorm_1.SelectQueryBuilder.prototype.addOrderByTyped = function (selection, order, nulls, useDoubleQuotes) {
+typeorm_1.SelectQueryBuilder.prototype.addOrderByTyped = function (selection, order, nulls, options) {
     if (selection instanceof proxy_key_utils_1.KeyHolder) {
-        return this.addOrderBy(selection.toSql(), order, nulls);
+        return this.addOrderBy(selection.toSql(undefined, options === null || options === void 0 ? void 0 : options.useQuotes), order, nulls);
     }
     if (typeof selection === 'function') {
-        const key = (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(selection, this.alias, useDoubleQuotes);
+        const key = (0, query_builder_utils_1.getTypedSelectionKey)(this, selection, options === null || options === void 0 ? void 0 : options.useQuotes);
         return this.addOrderBy(key, order, nulls);
     }
     return this;

package/dist/extensions/typed/typed-returning/typed-returning.extension.d.ts

@@ -0,0 +1,27 @@
+import { ObjectLiteral } from 'typeorm';
+import type { KeyProxyCallback } from '../../../types/modules/proxy-callback.types';
+export interface TypedReturningMethods<Entity extends ObjectLiteral> {
+    /**
+     * Sets the columns to return from entity properties: `RETURNING` on PostgreSQL and MariaDB, `OUTPUT` on SQL Server.
+     * `returningTyped(u => [u.id, u.status])` returns the columns of `id` and `status`, whatever their
+     * database names; the rows come in `execute()`'s `raw`. A property that isn't a column of the
+     * entity throws a `TypeError` (TypeORM's `returning([...])` silently skips it).
+     */
+    returningTyped(selection: KeyProxyCallback<Entity>): this;
+}
+declare module 'typeorm/query-builder/InsertQueryBuilder' {
+    interface InsertQueryBuilder<Entity extends ObjectLiteral> extends TypedReturningMethods<Entity> {
+    }
+}
+declare module 'typeorm/query-builder/UpdateQueryBuilder' {
+    interface UpdateQueryBuilder<Entity extends ObjectLiteral> extends TypedReturningMethods<Entity> {
+    }
+}
+declare module 'typeorm/query-builder/DeleteQueryBuilder' {
+    interface DeleteQueryBuilder<Entity extends ObjectLiteral> extends TypedReturningMethods<Entity> {
+    }
+}
+declare module 'typeorm/query-builder/SoftDeleteQueryBuilder' {
+    interface SoftDeleteQueryBuilder<Entity extends ObjectLiteral> extends TypedReturningMethods<Entity> {
+    }
+}

package/dist/extensions/typed/typed-returning/typed-returning.extension.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const SoftDeleteQueryBuilder_1 = require("typeorm/query-builder/SoftDeleteQueryBuilder");
+const proxy_key_utils_1 = require("../../../utils/proxy-key.utils");
+const prototype_utils_1 = require("../../../utils/prototype.utils");
+/* eslint-enable @typescript-eslint/no-empty-interface */
+// patching
+const extension = {
+    prototype: {
+        // the same implementation for the Insert, Update, Delete and SoftDelete builders
+        returningTyped(selection) {
+            const keyHolders = (0, proxy_key_utils_1.getKeyHolder)(selection);
+            const paths = (Array.isArray(keyHolders) ? keyHolders : [keyHolders]).map((keyHolder) => keyHolder.getKeys().join('.'));
+            const mainAlias = this.expressionMap.mainAlias;
+            if (!(mainAlias === null || mainAlias === void 0 ? void 0 : mainAlias.hasMetadata)) {
+                // no entity to map properties with: return the columns by name
+                return this.returning(paths.map((path) => this.escape(path)).join(', '));
+            }
+            for (const path of paths) {
+                // a column, an embedded column (`address.city`) or a relation with join columns (`owner`)
+                if (mainAlias.metadata.findColumnsWithPropertyPath(path).length === 0) {
+                    throw new TypeError(`returningTyped: "${path}" is not a column of ${mainAlias.metadata.name}`);
+                }
+            }
+            return this.returning(paths);
+        },
+    },
+};
+const queryBuilders = [
+    typeorm_1.InsertQueryBuilder,
+    typeorm_1.UpdateQueryBuilder,
+    typeorm_1.DeleteQueryBuilder,
+    SoftDeleteQueryBuilder_1.SoftDeleteQueryBuilder,
+];
+queryBuilders.forEach((builder) => {
+    (0, prototype_utils_1.patchPrototype)(builder, extension);
+});