typeorm-extensions 2.2.0-rc.6 → 2.2.0-rc.8

package/README.md

@@ -5,62 +5,101 @@
 [![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
 ```
 
+`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`: keyset pagination with an opaque cursor
+- `applyPaginationFilter` 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`
+- case-insensitive search with escaped wildcards, `applyPeriodFilter` in a time zone
+- `applyOrder` from a client's order filter, `orderByArrayPosition`
+
+**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
 
-For more information, please refer to the [documentation](https://koenigstag.github.io/typeorm-extensions).
+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.
 
 ## ToDo list
 
 - [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
+- [x] Generated columns: the `@GeneratedColumn` decorator, a `@Column` that TypeORM reads and never writes
+- [x] `tableHelper(Entity, alias)` writes the database names of renamed columns
 
 ## License
 

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/cursor-pagination.extension.d.ts

@@ -1,3 +1,4 @@
+import { ObjectLiteral } from 'typeorm';
 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';
@@ -14,6 +15,6 @@ 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>>;
     }
 }

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

@@ -7,6 +7,7 @@ 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 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; } });
@@ -68,6 +69,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) => {
@@ -90,7 +92,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, 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 +107,5 @@ 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 };
 }

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

@@ -58,10 +58,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;
@@ -110,21 +109,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(([key, value]) => {
-        const selector = (0, query_builder_utils_1.resolveDeferredKeys)(builder, key);
-        return 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),
     };
 }
 /**

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

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

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

@@ -3,6 +3,6 @@ import { ObjectLiteral } from 'typeorm';
 import { ApplyPaginationOptions } from '../types/extensions/pagination.types';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
-        applyPaginationFilter(paginationFilter: PaginationFilter, options?: ApplyPaginationOptions): SelectQueryBuilder<Entity>;
+        applyPaginationFilter(paginationFilter: PaginationFilter, options?: ApplyPaginationOptions): this;
     }
 }

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

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

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const typeorm_1 = require("typeorm");
+const SoftDeleteQueryBuilder_1 = require("typeorm/query-builder/SoftDeleteQueryBuilder");
 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");
@@ -17,6 +18,7 @@ const queryBuilders = [
     typeorm_1.SelectQueryBuilder,
     typeorm_1.UpdateQueryBuilder,
     typeorm_1.DeleteQueryBuilder,
+    SoftDeleteQueryBuilder_1.SoftDeleteQueryBuilder,
 ];
 queryBuilders.forEach((builder) => {
     (0, prototype_utils_1.patchPrototype)(builder, extension);

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

@@ -2,6 +2,7 @@ export * from './typed-distinct/typed-distinct.extension';
 export * from './typed-group-by/typed-group-by.extension';
 export * from './typed-having/typed-having.extension';
 export * from './typed-joins/typed-joins.extension';
+export * from './typed-joins/typed-join-and-map.extension';
 export * from './typed-order-by/typed-order-by.extension';
 export * from './typed-select/typed-select.extension';
 export * from './typed-where/typed-where.extension';

package/dist/extensions/typed/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./typed-distinct/typed-distinct.extension"), exports);
 __exportStar(require("./typed-group-by/typed-group-by.extension"), exports);
 __exportStar(require("./typed-having/typed-having.extension"), exports);
 __exportStar(require("./typed-joins/typed-joins.extension"), exports);
+__exportStar(require("./typed-joins/typed-join-and-map.extension"), exports);
 __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);

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

@@ -6,10 +6,10 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
         /**
          * Sets the distinct on clause for Postgres.
          */
-        distinctOnTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, ...distinctOn: Array<KeyProxyCallback<Type>>): SelectQueryBuilder<Entity>;
+        distinctOnTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, ...distinctOn: Array<KeyProxyCallback<Type>>): this;
         /**
          * Sets the distinct on clause for Postgres.
          */
-        distinctOnTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, distinctOn: KeyProxyCallback<Type>): SelectQueryBuilder<Entity>;
+        distinctOnTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, distinctOn: KeyProxyCallback<Type>): this;
     }
 }

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

@@ -12,11 +12,11 @@ export interface TypedGroupByMethods<Entity extends ObjectLiteral> {
      * Sets GROUP BY to the columns the callback selects: `user => user.id`, or several at once,
      * `user => [user.id, user.email]`. Replaces previously set GROUP BY.
      */
-    groupByTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(selection: GroupBySelection<Type>, options?: TypedGroupByOptions): this;
+    groupByTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(selection: GroupBySelection<Type>, options?: TypedGroupByOptions): this;
     /**
      * Adds the columns the callback selects to GROUP BY.
      */
-    addGroupByTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(selection: GroupBySelection<Type>, options?: TypedGroupByOptions): this;
+    addGroupByTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(selection: GroupBySelection<Type>, options?: TypedGroupByOptions): this;
 }
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> extends TypedGroupByMethods<Entity> {

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

@@ -3,7 +3,7 @@ import { DeepUnwrapArray, ProxyColumnValueType } from '../../../types/modules/pr
 import { TypedWhereArgs, TypeOrDefault, UnsetType } from '../../../types/modules/typed-params.types';
 import type { TypedAggregate } from '../../../types/extensions/typed-having.types';
 import type { TypedRoot } from '../../../types/modules/typed-root.types';
-type Selection<Entity extends ObjectLiteral, Type, Value> = (proxy: DeepUnwrapArray<TypeOrDefault<Type, TypedRoot<Entity>>>) => Value;
+type Selection<Root extends ObjectLiteral, Type, Value> = (proxy: DeepUnwrapArray<TypeOrDefault<Type, Root>>) => Value;
 /**
  * A value a column holds. A relation (`u => u.images`), the end of a key path or a JSON object is no column:
  * `COUNT("user"."images")` would fail in the database.
@@ -23,11 +23,11 @@ type AggregateValue<Aggregate, Value> = Aggregate extends 'MIN' | 'MAX' ? Value
  */
 export interface TypedHavingMethods<Entity extends ObjectLiteral> {
     /** Sets HAVING `aggregate(column) condition`, replacing the previous HAVING. */
-    havingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<Entity, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
+    havingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<TypedRoot<Entity, this>, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
     /** Adds AND HAVING `aggregate(column) condition`. */
-    andHavingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<Entity, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
+    andHavingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<TypedRoot<Entity, this>, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
     /** Adds OR HAVING `aggregate(column) condition`. */
-    orHavingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<Entity, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
+    orHavingTyped<Type extends ObjectLiteral = UnsetType, Aggregate extends TypedAggregate = TypedAggregate, Value extends ProxyColumnValueType = ProxyColumnValueType, Operator extends string = string>(aggregate: Aggregate, selection: Selection<TypedRoot<Entity, this>, Type, Value & AggregatedColumn> | CountAll<Aggregate>, conditions: Operator, ...args: TypedWhereArgs<Type, Operator, AggregateValue<Aggregate, Value>>): this;
 }
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> extends TypedHavingMethods<Entity> {

package/dist/extensions/typed/typed-joins/typed-join-and-map.extension.d.ts

@@ -0,0 +1,19 @@
+import { ObjectLiteral } from 'typeorm';
+import { KeyProxyCallback } from '../../../types/modules/proxy-callback.types';
+import type { JoinAndMapTarget } from '../../../types/extensions/typed-join-and-map.types';
+import type { TypedRoot } from '../../../types/modules/typed-root.types';
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+    interface SelectQueryBuilder<Entity extends ObjectLiteral> {
+        /**
+         * TypeORM's `leftJoinAndMapOne` with the property to map to picked by a typed callback: `(u) => u.profile` is
+         * `'user.profile'` on the main alias, `(q) => q.photo.owner` is `'photo.owner'` with an alias-keyed root.
+         */
+        leftJoinAndMapOneTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, mapToProperty: KeyProxyCallback<Type>, entity: JoinAndMapTarget, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        /** TypeORM's `innerJoinAndMapOne` with the property to map to picked by a typed callback. */
+        innerJoinAndMapOneTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, mapToProperty: KeyProxyCallback<Type>, entity: JoinAndMapTarget, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        /** TypeORM's `leftJoinAndMapMany` with the property to map to picked by a typed callback. */
+        leftJoinAndMapManyTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, mapToProperty: KeyProxyCallback<Type>, entity: JoinAndMapTarget, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        /** TypeORM's `innerJoinAndMapMany` with the property to map to picked by a typed callback. */
+        innerJoinAndMapManyTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, mapToProperty: KeyProxyCallback<Type>, entity: JoinAndMapTarget, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+    }
+}

package/dist/extensions/typed/typed-joins/typed-join-and-map.extension.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typeorm_1 = require("typeorm");
+const proxy_key_utils_1 = require("../../../utils/proxy-key.utils");
+// patching
+typeorm_1.SelectQueryBuilder.prototype.leftJoinAndMapOneTyped = function (mapToProperty, entity, alias, condition, parameters) {
+    return addJoinAndMap(this, 'leftJoinAndMapOne', mapToProperty, entity, alias, condition, parameters);
+};
+typeorm_1.SelectQueryBuilder.prototype.innerJoinAndMapOneTyped = function (mapToProperty, entity, alias, condition, parameters) {
+    return addJoinAndMap(this, 'innerJoinAndMapOne', mapToProperty, entity, alias, condition, parameters);
+};
+typeorm_1.SelectQueryBuilder.prototype.leftJoinAndMapManyTyped = function (mapToProperty, entity, alias, condition, parameters) {
+    return addJoinAndMap(this, 'leftJoinAndMapMany', mapToProperty, entity, alias, condition, parameters);
+};
+typeorm_1.SelectQueryBuilder.prototype.innerJoinAndMapManyTyped = function (mapToProperty, entity, alias, condition, parameters) {
+    return addJoinAndMap(this, 'innerJoinAndMapMany', mapToProperty, entity, alias, condition, parameters);
+};
+function addJoinAndMap(query, method, mapToProperty, entity, alias, condition, parameters) {
+    // `() => query.alias`: `(q) => q.photo.owner` needs no main alias, only `(u) => u.profile` does
+    const key = (0, proxy_key_utils_1.getSqlKeyFromProxyCallback)(mapToProperty, () => query.alias, false);
+    return query[method](key, entity, alias, condition, parameters);
+}

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

@@ -3,9 +3,9 @@ import { RelationalKeyProxyCallback } from '../../../types/modules/proxy-callbac
 import type { TypedRoot } from '../../../types/modules/typed-root.types';
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
-        leftJoinTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
-        innerJoinTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
-        leftJoinAndSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
-        innerJoinAndSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
+        leftJoinTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        innerJoinTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        leftJoinAndSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        innerJoinAndSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: RelationalKeyProxyCallback<Type>, alias: string, condition?: string, parameters?: ObjectLiteral): this;
     }
 }

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

@@ -9,11 +9,11 @@ export interface TypedOrderByArrayPositionMethods<Entity extends ObjectLiteral>
      * `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 = TypedRoot<Entity>>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, values: ArgsType, arrayType?: string): this;
+    orderByArrayPositionTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(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 = TypedRoot<Entity>>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, values: ArgsType, arrayType?: string): this;
+    addOrderByArrayPositionTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(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.extension.d.ts

@@ -10,10 +10,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 = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): SelectQueryBuilder<Entity>;
+        orderByTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): this;
         /**
          * Adds ORDER BY condition in the query builder.
          */
-        addOrderByTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): SelectQueryBuilder<Entity>;
+        addOrderByTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType | KeyHolder, order?: 'ASC' | 'DESC', nulls?: 'NULLS FIRST' | 'NULLS LAST', options?: TypedOrderByOptions): this;
     }
 }

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

@@ -1,13 +1,14 @@
 import { ObjectLiteral } from 'typeorm';
+import type { EntityTarget } from 'typeorm';
 import type { WithTypedRoot } from '../../types/modules/typed-root.types';
-type KnownEntity<Entity> = 0 extends 1 & Entity ? ObjectLiteral : Entity;
 declare module 'typeorm/query-builder/SelectQueryBuilder' {
     interface SelectQueryBuilder<Entity extends ObjectLiteral> {
         /**
          * Sets the root of the typed callbacks of the calls that follow, instead of passing it to each of them:
          * the aliases of the query and their entities.
          *
-         * Type-only: returns the builder itself. Call it once; a second call merges the roots.
+         * Type-only: returns the builder itself, marked with the root; its entity type stays. `from()` and `addFrom()`
+         * keep the root, so it may go before them; a second call replaces it.
          *
          * @example
          * type Joins = { checkin: CheckIn; event: Event };
@@ -19,7 +20,28 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          *   .selectTyped((q) => q.checkin.customerId, 'customerId')
          *   .whereTyped((q) => q.event.eventType, '=', type) // instead of whereTyped<Joins>(…)
          */
-        typed<Root extends ObjectLiteral>(): SelectQueryBuilder<WithTypedRoot<KnownEntity<Entity>, Root>>;
+        typed<Root extends ObjectLiteral>(): WithTypedRoot<SelectQueryBuilder<Entity>, Root>;
+        /**
+         * Specifies FROM which entity's table select/update/delete will be executed.
+         * Also sets a main string alias of the selection data.
+         * Removes all previously set from-s. Keeps the root set with `typed()`.
+         */
+        from<T extends ObjectLiteral, Root extends ObjectLiteral>(this: WithTypedRoot<unknown, Root>, entityTarget: (qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>, aliasName: string): WithTypedRoot<SelectQueryBuilder<T>, Root>;
+        /**
+         * Specifies FROM which entity's table select/update/delete will be executed.
+         * Also sets a main string alias of the selection data.
+         * Removes all previously set from-s. Keeps the root set with `typed()`.
+         */
+        from<T extends ObjectLiteral, Root extends ObjectLiteral>(this: WithTypedRoot<unknown, Root>, entityTarget: EntityTarget<T>, aliasName: string): WithTypedRoot<SelectQueryBuilder<T>, Root>;
+        /**
+         * Specifies FROM which entity's table select/update/delete will be executed.
+         * Also sets a main string alias of the selection data. Keeps the root set with `typed()`.
+         */
+        addFrom<T extends ObjectLiteral, Root extends ObjectLiteral>(this: WithTypedRoot<unknown, Root>, entityTarget: (qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>, aliasName: string): WithTypedRoot<SelectQueryBuilder<T>, Root>;
+        /**
+         * Specifies FROM which entity's table select/update/delete will be executed.
+         * Also sets a main string alias of the selection data. Keeps the root set with `typed()`.
+         */
+        addFrom<T extends ObjectLiteral, Root extends ObjectLiteral>(this: WithTypedRoot<unknown, Root>, entityTarget: EntityTarget<T>, aliasName: string): WithTypedRoot<SelectQueryBuilder<T>, Root>;
     }
 }
-export {};

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

@@ -8,28 +8,28 @@ declare module 'typeorm/query-builder/SelectQueryBuilder' {
          * Creates SELECT query.
          * Replaces all previous selections if they exist.
          */
-        selectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: KeyProxyCallback<Type>, selectionAliasName?: string, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        selectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: KeyProxyCallback<Type>, selectionAliasName?: string, useQuotes?: boolean): this;
         /**
          * Creates SELECT query and selects given data.
          * Replaces all previous selections if they exist.
          */
-        selectTyped(this: SelectQueryBuilder<Entity>, selection: string | KeyHolder, selectionAliasName?: string, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        selectTyped(this: SelectQueryBuilder<Entity>, selection: string | KeyHolder, selectionAliasName?: string, useQuotes?: boolean): this;
         /**
          * Creates SELECT query and selects given data.
          * Replaces all previous selections if they exist.
          */
-        selectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: string[] | KeyHolder[] | Array<KeyProxyCallback<Type>>, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        selectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: string[] | KeyHolder[] | Array<KeyProxyCallback<Type>>, useQuotes?: boolean): this;
         /**
          * Adds new selection to the SELECT query.
          */
-        addSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: KeyProxyCallback<Type>, selectionAliasName?: string, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        addSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: KeyProxyCallback<Type>, selectionAliasName?: string, useQuotes?: boolean): this;
         /**
          * Adds new selection to the SELECT query.
          */
-        addSelectTyped(this: SelectQueryBuilder<Entity>, selection: string | KeyHolder, selectionAliasName?: string, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        addSelectTyped(this: SelectQueryBuilder<Entity>, selection: string | KeyHolder, selectionAliasName?: string, useQuotes?: boolean): this;
         /**
          * Adds new selection to the SELECT query.
          */
-        addSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(this: SelectQueryBuilder<Entity>, selection: string[] | KeyHolder[] | Array<KeyProxyCallback<Type>>, useQuotes?: boolean): SelectQueryBuilder<Entity>;
+        addSelectTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(this: SelectQueryBuilder<Entity>, selection: string[] | KeyHolder[] | Array<KeyProxyCallback<Type>>, useQuotes?: boolean): this;
     }
 }

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

@@ -12,7 +12,7 @@ export interface TypedPeriodFilterMethods<Entity extends ObjectLiteral> {
      * 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'` → `column < '2024-02-01'`.
      */
-    applyPeriodFilterTyped<Type extends ObjectLiteral = TypedRoot<Entity>>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, periodFilter: PeriodFilter | null | undefined, options?: ApplyPeriodOptions): this;
+    applyPeriodFilterTyped<Type extends ObjectLiteral = TypedRoot<Entity, this>>(selection: (proxy: DeepUnwrapArray<Type>) => ProxyColumnValueType, periodFilter: PeriodFilter | null | undefined, options?: ApplyPeriodOptions): this;
 }
 declare module 'typeorm/query-builder/WhereExpressionBuilder' {
     interface WhereExpressionBuilder extends TypedPeriodFilterMethods<ObjectLiteral> {
@@ -30,3 +30,7 @@ declare module 'typeorm/query-builder/DeleteQueryBuilder' {
     interface DeleteQueryBuilder<Entity extends ObjectLiteral> extends TypedPeriodFilterMethods<Entity> {
     }
 }
+declare module 'typeorm/query-builder/SoftDeleteQueryBuilder' {
+    interface SoftDeleteQueryBuilder<Entity extends ObjectLiteral> extends TypedPeriodFilterMethods<Entity> {
+    }
+}

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 require("../../period-filter.extension");
 const typeorm_1 = require("typeorm");
+const SoftDeleteQueryBuilder_1 = require("typeorm/query-builder/SoftDeleteQueryBuilder");
 const query_builder_utils_1 = require("../../../utils/query-builder.utils");
 const prototype_utils_1 = require("../../../utils/prototype.utils");
 const period_utils_1 = require("../../../utils/period.utils");
@@ -19,6 +20,7 @@ const queryBuilders = [
     typeorm_1.SelectQueryBuilder,
     typeorm_1.UpdateQueryBuilder,
     typeorm_1.DeleteQueryBuilder,
+    SoftDeleteQueryBuilder_1.SoftDeleteQueryBuilder,
 ];
 queryBuilders.forEach((builder) => {
     (0, prototype_utils_1.patchPrototype)(builder, extension);