typeorm-extensions 1.2.0

package/.eslintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/.eslintrc

@@ -0,0 +1,12 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ]
+}

package/README.md

@@ -0,0 +1,46 @@
+# TypeORM Extensions
+
+[![Build Status](https://travis-ci.org/your-username/typeorm-extensions.svg?branch=main)](https://travis-ci.org/your-username/typeorm-extensions)
+[![npm version](https://badge.fury.io/js/typeorm-extensions.svg)](https://badge.fury.io/js/typeorm-extensions)
+
+## Description
+
+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.
+
+## Features
+
+- 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.
+
+## Installation
+
+To install `typeorm-extensions`:
+
+Npm:
+```bash
+npm install typeorm-extensions
+```
+
+## Usage
+
+```typescript
+import { createQueryBuilder } from 'typeorm';
+import 'typeorm-extensions'; // Import the library root to extend the QueryBuilder with all extensions
+
+// Or init specific extension: import from 'typeorm-extensions/dist/extensions/pagination.extension';
+
+const query = createQueryBuilder()
+  .from(User, 'user')
+  .selectTyped(user => ([
+    id: user.id,
+    name: user.name,
+    email: user.email,
+  ]))
+  .orderTyped(user => user.createdAt, 'ASC')
+  .applyPagination({ page: 1, pageSize: 10 });
+```
+
+## Documentation
+
+For more information, please refer to the [documentation](https://koenigstag.github.io/typeorm-extensions).

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "typeorm-extensions",
+  "version": "1.2.0",
+  "description": "typeorm commonly used extensions",
+  "main": "./dist/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koenigstag/typeorm-extensions.git"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "lint": "eslint . --ext .ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "typeorm",
+    "extension",
+    "extensions",
+    "util",
+    "utils"
+  ],
+  "author": "koenigstag",
+  "license": "ISC",
+  "dependencies": {
+    "typeorm": "^0.3.20"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "eslint": "^8.57.0",
+    "typescript": "5.3"
+  }
+}

package/src/constants/index.ts

@@ -0,0 +1,9 @@
+export const defaultPageSize = 10;
+
+export const defaultUseTakeAndSkip = true;
+
+export const defaultUseDoubleQuotes = false;
+
+export const defaultOrderDirection = 'ASC';
+
+export const defaultNullsOrder = undefined;

package/src/extensions/get-many-with-totals.extension.ts

@@ -0,0 +1,62 @@
+import { SelectQueryBuilder } from 'typeorm/query-builder/SelectQueryBuilder';
+import { PaginationFilter } from '../types/interfaces/pagination.interface';
+import { getLimitAndOffset } from '../utils/pagination.utils';
+import { ApplyPaginationOptions } from './pagination.extension';
+
+export type GetManyWithTotalsOptions = {
+  disableTotalsCalculation?: boolean;
+  loadAll?: boolean;
+};
+
+export interface ListWithTotals<Entity> {
+  list: Entity[];
+  totalCount: number | null;
+  limit: number | null;
+  offset: number | null;
+}
+
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+  interface SelectQueryBuilder<Entity> {
+    getManyWithTotals(
+      paginationFilter: PaginationFilter,
+      options?: GetManyWithTotalsOptions
+    ): Promise<ListWithTotals<Entity>>;
+  }
+}
+
+SelectQueryBuilder.prototype.getManyWithTotals = async function <Entity>(
+  paginationFilter: PaginationFilter,
+  options?: GetManyWithTotalsOptions & ApplyPaginationOptions
+): Promise<ListWithTotals<Entity>> {
+  const { disableTotalsCalculation = false, loadAll = false } = options || {};
+
+  const { limit, offset } = loadAll
+    ? { limit: null, offset: null }
+    : getLimitAndOffset(paginationFilter);
+
+  const requests = [];
+
+  if (!disableTotalsCalculation) {
+    requests[0] = this.getCount();
+  } else {
+    requests[0] = Promise.resolve(null);
+  }
+
+  if (loadAll) {
+    requests[1] = this.getMany();
+  } else {
+    requests[1] = this.applyPaginationFilter(paginationFilter).getMany();
+  }
+
+  const [totalCount, list] = (await Promise.all(requests)) as [
+    number | null,
+    Entity[]
+  ];
+
+  return {
+    list,
+    totalCount: totalCount,
+    limit,
+    offset,
+  };
+};

package/src/extensions/index.ts

@@ -0,0 +1,4 @@
+export * from './get-many-with-totals.extension';
+export * from './ordering.extension';
+export * from './pagination.extension';
+export * from './typed';

package/src/extensions/ordering.extension.ts

@@ -0,0 +1,123 @@
+import { SelectQueryBuilder } from 'typeorm/query-builder/SelectQueryBuilder';
+import type {
+  OrderParam,
+  OrderFilter,
+  OrderType,
+} from '../types/interfaces/ordering.interface';
+import {
+  defaultNullsOrder,
+  defaultOrderDirection,
+  defaultUseDoubleQuotes,
+} from '../constants';
+import { ObjectLiteral } from 'typeorm';
+import { isNil } from '../utils/common.utils';
+import { Identifier } from '../utils/identifier.utils';
+
+const alwaysAliasWhiteList = [
+  'id',
+  'createdAt',
+  'created_at',
+  'updatedAt',
+  'updated_at',
+  'deletedAt',
+  'deleted_at',
+];
+
+export type ApplyOrderOptions = {
+  useDoubleQuotes?: boolean;
+  alias?: string;
+  alwaysAliasFields?: string[];
+  resetPreviousOrder?: boolean;
+};
+
+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>;
+  }
+}
+
+SelectQueryBuilder.prototype.applyOrder = function <
+  Entity extends ObjectLiteral,
+  OrderEntity
+>(
+  orderBy: OrderParam<OrderEntity>,
+  options?: ApplyOrderOptions
+): SelectQueryBuilder<Entity> {
+  const { resetPreviousOrder = false } = options ?? {};
+
+  const orderOption = getOrderOption(orderBy, this.alias, options);
+
+  const query = resetPreviousOrder ? this.orderBy() : this;
+
+  return query.addOrderBy(
+    orderOption.selector,
+    orderOption.order,
+    orderOption.nulls
+  );
+};
+
+SelectQueryBuilder.prototype.applyOrderFilter = function <
+  Entity extends ObjectLiteral,
+  OrderEntity
+>(
+  orderFilter: OrderFilter<OrderEntity>,
+  options?: ApplyOrderOptions
+): SelectQueryBuilder<Entity> {
+  if (!isNil(orderFilter?.orderBy)) {
+    return orderFilter.orderBy!.reduce(
+      (acc, order, index) =>
+        acc.applyOrder(order, {
+          ...options,
+          resetPreviousOrder: index === 0 ? options?.resetPreviousOrder : false,
+        }),
+      this as SelectQueryBuilder<Entity>
+    );
+  }
+
+  return this;
+};
+
+export const getOrderOption = <OrderEntity>(
+  orderBy: OrderParam<OrderEntity>,
+  defaultAlias: string,
+  options?: ApplyOrderOptions
+): OrderType => {
+  const {
+    useDoubleQuotes = defaultUseDoubleQuotes,
+    alias: customAlias,
+    alwaysAliasFields = alwaysAliasWhiteList,
+  } = options ?? {};
+  const {
+    field,
+    direction = defaultOrderDirection,
+    nulls: nullsOrder = defaultNullsOrder,
+  } = orderBy;
+
+  const alias =
+    customAlias ??
+    (alwaysAliasFields.includes(field as string) ? defaultAlias : undefined);
+
+  const identifier = new Identifier(field, alias, useDoubleQuotes);
+
+  const selector = identifier.fieldIdentifier();
+  const order = direction.toUpperCase() as 'ASC' | 'DESC';
+
+  const nulls = nullsOrder
+    ? (`NULLS ${nullsOrder.toUpperCase()}` as 'NULLS LAST' | 'NULLS FIRST')
+    : undefined;
+
+  return {
+    selector,
+    order,
+    nulls,
+  };
+};
+
+export {};

package/src/extensions/pagination.extension.ts

@@ -0,0 +1,35 @@
+import { SelectQueryBuilder } from 'typeorm/query-builder/SelectQueryBuilder';
+import type { PaginationFilter } from '../types/interfaces/pagination.interface';
+import { defaultUseTakeAndSkip } from '../constants';
+import { getLimitAndOffset } from '../utils/pagination.utils';
+import { ObjectLiteral } from 'typeorm';
+
+export type ApplyPaginationOptions = {
+  useTakeAndSkip?: boolean;
+};
+
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+  interface SelectQueryBuilder<Entity> {
+    applyPaginationFilter(
+      paginationFilter: PaginationFilter,
+      options?: ApplyPaginationOptions
+    ): SelectQueryBuilder<Entity>;
+  }
+}
+
+SelectQueryBuilder.prototype.applyPaginationFilter = function <Entity extends ObjectLiteral>(
+  paginationFilter: PaginationFilter,
+  options?: ApplyPaginationOptions
+): SelectQueryBuilder<Entity> {
+  const { useTakeAndSkip = defaultUseTakeAndSkip } = options || {};
+
+  const { limit, offset } = getLimitAndOffset(paginationFilter);
+
+  if (useTakeAndSkip) {
+    return this.take(limit).skip(offset);
+  }
+
+  return this.limit(limit).offset(offset);
+};
+
+export {};

package/src/extensions/typed/index.ts

@@ -0,0 +1,12 @@
+//Extensions
+export * from './typed-distinct/typed-distinct.extension';
+// export * from './typed/typed-group-by/typed-group-by.extension';
+// export * from './typed/typed-having/typed-having.extension';
+export * from './typed-joins/typed-joins.extension';
+export * from './typed-order-by/typed-order-by.extension';
+export * from './typed-select/typed-select.extension';
+export * from './typed-where/typed-where.extension';
+
+// Types
+export * from './typeorm-querybuilder.types';
+export * from './typeorm.types';

package/src/extensions/typed/typed-distinct/typed-distinct.extension.ts

@@ -0,0 +1,38 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { ColumnValueType } from '../typeorm.types';
+import { getSqlKey } from '../../../utils/proxy-key.utils';
+
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+	interface SelectQueryBuilder<Entity> {
+		/**
+		 * Sets the distinct on clause for Postgres.
+		 */
+		distinctOnTyped<Type extends ObjectLiteral = Entity>(
+			this: SelectQueryBuilder<Entity>,
+			...distinctOn: Array<(proxy: Type) => ColumnValueType>
+		): SelectQueryBuilder<Entity>;
+		/**
+		 * Sets the distinct on clause for Postgres.
+		 */
+		distinctOnTyped<Type extends ObjectLiteral = Entity>(
+			this: SelectQueryBuilder<Entity>,
+			distinctOn: (proxy: Type) => Array<ColumnValueType>
+		): SelectQueryBuilder<Entity>;
+	}
+}
+
+SelectQueryBuilder.prototype.distinctOnTyped = function <
+	Entity extends ObjectLiteral,
+	Type extends ObjectLiteral = Entity
+>(
+	this: SelectQueryBuilder<Entity>,
+	...distinctOn: Array<(proxy: Type) => ColumnValueType | Array<ColumnValueType>>
+): SelectQueryBuilder<Entity> {
+	if (Array.isArray(distinctOn) && distinctOn.length) {
+		const keys = distinctOn.map((callback) => getSqlKey<Type>(callback, this.alias)).flat(3);
+
+		return this.distinctOn(keys as string[]);
+	}
+
+	return this;
+};

package/src/extensions/typed/typed-joins/typed-joins.extension.ts

@@ -0,0 +1,141 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { RelationalKeyProxyCallback } from '../typeorm-querybuilder.types';
+import { getSqlKey } from '../../../utils/proxy-key.utils';
+
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+  interface SelectQueryBuilder<Entity> {
+    leftJoinTyped<Type extends ObjectLiteral = Entity>(
+      this: SelectQueryBuilder<Entity>,
+      selection: RelationalKeyProxyCallback<Type>,
+      alias: string,
+      condition?: string,
+      parameters?: ObjectLiteral
+    ): SelectQueryBuilder<Entity>;
+    innerJoinTyped<Type extends ObjectLiteral = Entity>(
+      this: SelectQueryBuilder<Entity>,
+      selection: RelationalKeyProxyCallback<Type>,
+      alias: string,
+      condition?: string,
+      parameters?: ObjectLiteral
+    ): SelectQueryBuilder<Entity>;
+
+    leftJoinAndSelectTyped<Type extends ObjectLiteral = Entity>(
+      this: SelectQueryBuilder<Entity>,
+      selection: RelationalKeyProxyCallback<Type>,
+      alias: string,
+      condition?: string,
+      parameters?: ObjectLiteral
+    ): SelectQueryBuilder<Entity>;
+    innerJoinAndSelectTyped<Type extends ObjectLiteral = Entity>(
+      this: SelectQueryBuilder<Entity>,
+      selection: RelationalKeyProxyCallback<Type>,
+      alias: string,
+      condition?: string,
+      parameters?: ObjectLiteral
+    ): SelectQueryBuilder<Entity>;
+  }
+}
+
+SelectQueryBuilder.prototype.leftJoinTyped = function <
+  Entity extends ObjectLiteral,
+  Type extends ObjectLiteral = Entity
+>(
+  this: SelectQueryBuilder<Entity>,
+  selection: RelationalKeyProxyCallback<Type>,
+  alias: string,
+  condition?: string,
+  parameters?: ObjectLiteral
+) {
+  if (typeof selection === 'function') {
+    return addJoin(this, 'leftJoin', selection, alias, condition, parameters);
+  }
+
+  return this;
+};
+
+SelectQueryBuilder.prototype.innerJoinTyped = function <
+  Entity extends ObjectLiteral,
+  Type extends ObjectLiteral = Entity
+>(
+  this: SelectQueryBuilder<Entity>,
+  selection: RelationalKeyProxyCallback<Type>,
+  alias: string,
+  condition?: string,
+  parameters?: ObjectLiteral
+) {
+  if (typeof selection === 'function') {
+    return addJoin(this, 'innerJoin', selection, alias, condition, parameters);
+  }
+
+  return this;
+};
+
+SelectQueryBuilder.prototype.leftJoinAndSelectTyped = function <
+  Entity extends ObjectLiteral,
+  Type extends ObjectLiteral = Entity
+>(
+  this: SelectQueryBuilder<Entity>,
+  selection: RelationalKeyProxyCallback<Type>,
+  alias: string,
+  condition?: string,
+  parameters?: ObjectLiteral
+) {
+  if (typeof selection === 'function') {
+    return addJoin(
+      this,
+      'leftJoinAndSelect',
+      selection,
+      alias,
+      condition,
+      parameters
+    );
+  }
+
+  return this;
+};
+
+SelectQueryBuilder.prototype.innerJoinAndSelectTyped = function <
+  Entity extends ObjectLiteral,
+  Type extends ObjectLiteral = Entity
+>(
+  this: SelectQueryBuilder<Entity>,
+  selection: RelationalKeyProxyCallback<Type>,
+  alias: string,
+  condition?: string,
+  parameters?: ObjectLiteral
+) {
+  if (typeof selection === 'function') {
+    return addJoin(
+      this,
+      'innerJoinAndSelect',
+      selection,
+      alias,
+      condition,
+      parameters
+    );
+  }
+
+  return this;
+};
+
+type JoinMethod =
+  | 'leftJoin'
+  | 'innerJoin'
+  | 'leftJoinAndSelect'
+  | 'innerJoinAndSelect';
+
+function addJoin<
+  Entity extends ObjectLiteral,
+  Type extends ObjectLiteral = Entity
+>(
+  query: SelectQueryBuilder<Entity>,
+  method: JoinMethod,
+  selection: RelationalKeyProxyCallback<Type>,
+  alias: string,
+  condition?: string,
+  parameters?: ObjectLiteral
+) {
+  const key = getSqlKey<Type>(selection, query.alias) as string;
+
+  return query[method](key, alias, condition, parameters);
+}

package/src/extensions/typed/typed-order-by/typed-order-by.extension.ts

@@ -0,0 +1,73 @@
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { ColumnValueType } from '../typeorm.types';
+import { KeyHolder } from '../typeorm-querybuilder.types';
+import { getSqlKey } from '../../../utils/proxy-key.utils';
+
+declare module 'typeorm/query-builder/SelectQueryBuilder' {
+	interface SelectQueryBuilder<Entity> {
+		/**
+		 * Sets ORDER BY condition in the query builder.
+		 * 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) => ColumnValueType | KeyHolder,
+			order?: 'ASC' | 'DESC',
+			nulls?: 'NULLS FIRST' | 'NULLS LAST'
+		): SelectQueryBuilder<Entity>;
+		/**
+		 * Adds ORDER BY condition in the query builder.
+		 */
+		addOrderByTyped<Type extends ObjectLiteral = Entity>(
+			this: SelectQueryBuilder<Entity>,
+			selection: (proxy: Type) => ColumnValueType | KeyHolder,
+			order?: 'ASC' | 'DESC',
+			nulls?: 'NULLS FIRST' | 'NULLS LAST'
+		): SelectQueryBuilder<Entity>;
+	}
+}
+
+SelectQueryBuilder.prototype.orderByTyped = function <
+	Entity extends ObjectLiteral,
+	Type extends ObjectLiteral = Entity
+>(
+	this: SelectQueryBuilder<Entity>,
+	selection?: (proxy: Type) => ColumnValueType | KeyHolder,
+	order?: 'ASC' | 'DESC',
+	nulls?: 'NULLS FIRST' | 'NULLS LAST'
+): SelectQueryBuilder<Entity> {
+	if (selection instanceof KeyHolder) {
+		return this.orderBy(selection.toSql(), order, nulls);
+	}
+
+	if (typeof selection === 'function') {
+		const key = getSqlKey<Type>(selection, this.alias) as string;
+
+		return this.orderBy(key, order, nulls);
+	}
+
+	return this;
+};
+
+SelectQueryBuilder.prototype.addOrderByTyped = function <
+	Entity extends ObjectLiteral,
+	Type extends ObjectLiteral = Entity
+>(
+	this: SelectQueryBuilder<Entity>,
+	selection?: (proxy: Type) => ColumnValueType | KeyHolder,
+	order?: 'ASC' | 'DESC',
+	nulls?: 'NULLS FIRST' | 'NULLS LAST'
+): SelectQueryBuilder<Entity> {
+	if (selection instanceof KeyHolder) {
+		return this.addOrderBy(selection.toSql(), order, nulls);
+	}
+
+	if (typeof selection === 'function') {
+		const key = getSqlKey<Type>(selection, this.alias) as string;
+
+		return this.addOrderBy(key, order, nulls);
+	}
+
+	return this;
+};