typeorm-extensions 2.2.0-rc.7 → 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.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/helpers.d.ts

@@ -1,4 +1,5 @@
 export * from './utils/table.utils';
+export * from './decorators/generated-column.decorator';
 export { escapeLikePattern } from './utils/search.utils';
 export { COCKROACHDB_RESERVED_KEY_WORDS, findBareReservedQualifiers, POSTGRES_RESERVED_KEY_WORDS, } from './utils/reserved-qualifier.utils';
 export type { ReservedQualifier } from './utils/reserved-qualifier.utils';

package/dist/helpers.js

@@ -16,9 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReservedQualifierError = exports.enableReservedQualifierGuard = exports.disableReservedQualifierGuard = exports.POSTGRES_RESERVED_KEY_WORDS = exports.findBareReservedQualifiers = exports.COCKROACHDB_RESERVED_KEY_WORDS = exports.escapeLikePattern = void 0;
 // Side-effect-free entry point: `typeorm-extensions/helpers`.
-// Exports helpers (tableHelper, escapeLikePattern, the reserved qualifier guard) only and patches nothing on import;
+// Exports helpers (tableHelper, escapeLikePattern, the reserved qualifier guard, @GeneratedColumn) only and patches nothing on import;
 // importing the package root (`typeorm-extensions`) installs every QueryBuilder extension.
 __exportStar(require("./utils/table.utils"), exports);
+__exportStar(require("./decorators/generated-column.decorator"), exports);
 var search_utils_1 = require("./utils/search.utils");
 Object.defineProperty(exports, "escapeLikePattern", { enumerable: true, get: function () { return search_utils_1.escapeLikePattern; } });
 var reserved_qualifier_utils_1 = require("./utils/reserved-qualifier.utils");

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

@@ -1,4 +1,5 @@
 import type { CursorOrderParam } from '../interfaces/cursor-pagination.interface';
+import type { OrderType } from '../interfaces/ordering.interface';
 export type GetManyWithCursorOptions<Entity> = {
     /**
      * Columns that order the rows, e.g. `[{ field: 'createdAt', direction: 'DESC' }]`.
@@ -18,4 +19,8 @@ export interface ListWithCursor<Entity> {
      * keyset query loads `pageSize + 1` rows, so it needs no total. Equivalent to `nextCursor !== null`.
      */
     hasMore: boolean;
+    /** The page size used: the `pageSize` given, rounded down, or `10` when it was missing or below 1. */
+    pageSize: number;
+    /** The ORDER BY the page was read in: the `orderBy` columns, then the primary key columns not among them. */
+    orderBy: OrderType[];
 }

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

@@ -18,6 +18,10 @@ export type GetRawManyWithTotalsOptions = Omit<GetManyWithTotalsOptions, 'useTak
 export interface ListWithTotals<Entity> {
     list: Entity[];
     total: number | null;
+    /** The page read, 1-based: the `page` given, or `1` when it was missing or below 1. `null` with `loadAll`. */
+    page: number | null;
+    /** The page size used: the `pageSize` given, or `10` when it was missing or below 1. `null` with `loadAll`. */
+    pageSize: number | null;
     limit: number | null;
     offset: number | null;
     /**

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

@@ -2,4 +2,6 @@ import { PaginationFilter } from "../types/interfaces/pagination.interface";
 export declare const getLimitAndOffset: ({ page, pageSize }: PaginationFilter) => {
     limit: number;
     offset: number;
+    page: number;
+    pageSize: number;
 };

package/dist/utils/pagination.utils.js

@@ -11,6 +11,6 @@ const getLimitAndOffset = ({ page, pageSize }) => {
     }
     const offset = (page >= 1 ? page - 1 : 0) * pageSize;
     const limit = pageSize;
-    return { limit, offset };
+    return { limit, offset, page, pageSize };
 };
 exports.getLimitAndOffset = getLimitAndOffset;

package/dist/utils/query-builder.utils.d.ts

@@ -1,6 +1,8 @@
+import { QueryBuilder } from 'typeorm';
 import type { ObjectLiteral, WhereExpressionBuilder } from 'typeorm';
 import type { ColumnMetadata } from 'typeorm/metadata/ColumnMetadata';
 import type { KeyProxyCallback } from '../types/modules/proxy-callback.types';
+import type { OrderType } from '../types/interfaces/ordering.interface';
 import { JsonPathSqlOptions } from './json-path.utils';
 /** Replaces placeholders of `deferColumnKey` in SQL built by `builder`, through the aliases it has by then. */
 export declare function resolveDeferredKeys(builder: WhereExpressionBuilder, statement: string): string;
@@ -60,3 +62,9 @@ export declare function getTypedSingleColumnKey<Type extends ObjectLiteral>(buil
  * Strings are kept as is.
  */
 export declare function getTypedSelectionKey<Type extends ObjectLiteral>(builder: WhereExpressionBuilder, selection: KeyProxyCallback<Type> | string, useQuotes?: boolean, columnsFor?: string): string | string[];
+/**
+ * The ORDER BY a query is built with, in the order it was applied. `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.
+ */
+export declare function getAppliedOrderBy<Entity extends ObjectLiteral>(builder: QueryBuilder<Entity>): OrderType[];

package/dist/utils/query-builder.utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = exports.resolveDeferredKeys = void 0;
+exports.getAppliedOrderBy = exports.getTypedSelectionKey = exports.getTypedSingleColumnKey = exports.isTypedJsonPath = exports.getTypedColumnKey = exports.toFieldSql = exports.findFieldColumn = exports.getColumnDatabaseName = exports.resolveDeferredKeys = void 0;
 const typeorm_1 = require("typeorm");
 const QueryExpressionMap_1 = require("typeorm/query-builder/QueryExpressionMap");
 const proxy_key_utils_1 = require("./proxy-key.utils");
@@ -442,3 +442,18 @@ function getTypedSelectionKey(builder, selection, useQuotes, columnsFor) {
     return Array.isArray(keyHolder) ? keyHolder.map(toKey) : toKey(keyHolder);
 }
 exports.getTypedSelectionKey = getTypedSelectionKey;
+/**
+ * The ORDER BY a query is built with, in the order it was applied. `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.
+ */
+function getAppliedOrderBy(builder) {
+    var _a;
+    return Object.entries((_a = builder.expressionMap.allOrderBys) !== null && _a !== void 0 ? _a : {}).map(([key, value]) => {
+        const selector = resolveDeferredKeys(builder, key);
+        return typeof value === 'string'
+            ? { selector, order: value }
+            : { selector, order: value.order, nulls: value.nulls };
+    });
+}
+exports.getAppliedOrderBy = getAppliedOrderBy;

package/package.json

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