@pcg/core 1.0.0-alpha.0

package/src/pagination/cursor/cursor-pagination.input.ts

@@ -0,0 +1,96 @@
+import {
+  ArgsType,
+  Field, Int,
+} from '@nestjs/graphql';
+import { IsOptional, Min } from 'class-validator';
+
+@ArgsType()
+export class CursorPaginationInput {
+  /**
+   * The amount of items to be requested per page from the start
+   * @example
+   * ```graphql
+   * query {
+   *  messages(first: 3) {
+   *   edges {
+   *    cursor
+   *    node {
+   *     id
+   *    }
+   *   }
+   *  }
+   * }
+   * ```
+   */
+  @Field(() => Int, {
+    nullable: true,
+  })
+  @Min(1)
+  @IsOptional()
+  first?: number;
+
+  /**
+   * The cursor to start the pagination
+   * @example
+   * ```graphql
+   * query {
+   *  messages(first: 3, after: "xxx") {
+   *   edges {
+   *    cursor
+   *    node {
+   *     id
+   *    }
+   *   }
+   *  }
+   * }
+   * ```
+   */
+  @Field(() => String, {
+    nullable: true,
+  })
+  after?: string;
+
+  /**
+   * The amount of items to be requested per page from the end
+   * @example
+   * ```graphql
+   * query {
+   *  messages(last: 2) {
+   *   edges {
+   *    cursor
+   *    node {
+   *     id
+   *    }
+   *   }
+   *  }
+   * }
+   * ```
+   */
+  @Field(() => Int, {
+    nullable: true,
+  })
+  @Min(1)
+  @IsOptional()
+  last?: number;
+
+  /**
+   * The cursor to end the pagination
+   * @example
+   * ```graphql
+   * query {
+   *  messages(last: 2, before: "xxx") {
+   *   edges {
+   *    cursor
+   *    node {
+   *     id
+   *    }
+   *   }
+   *  }
+   * }
+   * ```
+   */
+  @Field(() => String, {
+    nullable: true,
+  })
+  before?: string;
+}

package/src/pagination/cursor/cursor-pagination.types.ts

@@ -0,0 +1,127 @@
+import { Type } from '@nestjs/common';
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import type { MaybeNull } from '#/types/maybe';
+
+@ObjectType()
+export class CursorPaginationPageInfo {
+  /**
+   * The cursor to the first item in the list
+   */
+  @Field(() => String, {
+    nullable: true,
+  })
+  startCursor!: MaybeNull<string>;
+
+  /**
+   * The cursor to the last item in the list
+   */
+  @Field(() => String, {
+    nullable: true,
+  })
+  endCursor!: MaybeNull<string>;
+
+  /**
+   * Whether there are more items in the list before the start cursor
+   */
+  @Field(() => Boolean, {
+    nullable: true,
+  })
+  hasPreviousPage?: boolean;
+
+  /**
+   * Whether there are more items in the list after the end cursor
+   */
+  @Field(() => Boolean, {
+    nullable: true,
+  })
+  hasNextPage?: boolean;
+}
+
+/**
+ * The edge type for cursor pagination
+ */
+export interface IEdge<T> {
+  /**
+   * The cursor for the item
+   */
+  cursor: string;
+
+  /**
+   * The item
+   */
+  node: T;
+}
+
+export interface ICursorPaginated<T> {
+  /**
+   * The list of edges
+   */
+  edges: IEdge<T>[];
+
+  /**
+   * The pagination info
+   */
+  pageInfo: CursorPaginationPageInfo;
+}
+
+/**
+ * Creates a new GraphQL object type with the name `Paginated${classRef.name}`
+ * that implements the `ICursorPaginated` interface
+ * @param classRef The class reference of the items
+ *
+ * @example Create PaginatedMessages type
+ * ```ts
+ * @ObjectType()
+ * class PaginatedMessages extends CursorPaginated(Message) {}
+ * ```
+ */
+// eslint-disable-next-line func-style
+export function CursorPaginated<T>(classRef: Type<T>): Type<ICursorPaginated<T>> {
+  @ObjectType(`${classRef.name}Edge`)
+  abstract class EdgeType implements IEdge<T> {
+    /**
+     * The cursor for the item
+     */
+    @Field(() => String, {
+      description: 'The cursor for the item',
+    })
+    cursor!: string;
+
+    /**
+     * The item
+     */
+    @Field(() => classRef, {
+      description: 'The item',
+    })
+    node!: T;
+  }
+
+  @ObjectType({
+    isAbstract: true,
+  })
+  abstract class CursorPaginatedType implements ICursorPaginated<T> {
+    /**
+     * The list of edges
+     */
+    @Field(() => [EdgeType], {
+      description: 'The list of edges',
+    })
+    edges!: EdgeType[];
+
+    /**
+     * The pagination info
+     */
+    @Field(() => CursorPaginationPageInfo, {
+      description: 'The pagination info',
+    })
+    pageInfo!: CursorPaginationPageInfo;
+  }
+
+  return CursorPaginatedType as Type<ICursorPaginated<T>>;
+}
+
+export enum CursorOrderBy {
+  createdAt_ASC = 'createdAt_ASC',
+  createdAt_DESC = 'createdAt_DESC',
+}

package/src/pagination/index.ts

@@ -0,0 +1,9 @@
+export * from './cursor/cursor-pagination.helpers.js';
+export * from './cursor/cursor-pagination.input.js';
+export * from './cursor/cursor-pagination.types.js';
+
+export * from './offset/offset-pagination.helpers.js';
+export * from './offset/offset-pagination.input.js';
+export * from './offset/offset-pagination.types.js';
+
+export * from './tools.js';

package/src/pagination/offset/offset-pagination.exception.ts

@@ -0,0 +1,15 @@
+import { NestError } from '#/errors';
+
+export enum OffsetErrorMessage {
+  OUTPUT_LIMIT = `Can't build page meta. Invalid limit`,
+}
+
+export class OffsetPaginationError extends NestError {
+  constructor(public readonly message: OffsetErrorMessage) {
+    super({
+      message,
+      key: 'NST_INVALID_OFFSET_PAGINATION',
+    });
+    this.name = 'OffsetPaginationError';
+  }
+}

package/src/pagination/offset/offset-pagination.helpers.ts

@@ -0,0 +1,122 @@
+import { snakeCase } from '@pcg/text-kit';
+import { GraphQLResolveInfo } from 'graphql';
+
+import { ListMeta } from '#/types/list-meta';
+
+import { PAGINATION_DEFAULT_LIMIT } from '../constants.js';
+import { requiresTotalCount, truncPaginationLimit } from '../tools.js';
+import { OffsetErrorMessage, OffsetPaginationError } from './offset-pagination.exception.js';
+import { OffsetPaginationInput } from './offset-pagination.input.js';
+import { IOffsetPaginated } from './offset-pagination.types.js';
+
+export type SortOrder = 'ASC' | 'DESC';
+
+export interface SortParams<T> {
+  /**
+   * Original sort field name.
+   * @example
+   * const orderBy = 'createdAt_ASC';
+   * const sort = extractSortParams(orderBy); // sort.fieldName = 'uploaderName';
+   * if (sort.fieldName === uploaderName) {
+   *  ...
+   * }
+   */
+  fieldName: T;
+
+  /**
+   * Database column name. Camel cased fieldName.
+   * @example
+   * const orderBy = 'createdAt_ASC';
+   * const sort = extractSortParams(orderBy); // sort.columnName = 'created_at';
+   * query.orderBy(`v.${sort.columnName}`, sort.direction);
+   */
+  columnName: string;
+
+  /**
+   * Sort direction (or order) (ASC | DESC)
+   * @example
+   * const orderBy = 'createdAt_ASC';
+   * const sort = extractSortParams(orderBy); // sort.direction = 'ASC';
+   * query.orderBy(`v.${sort.columnName}`, sort.direction);
+   */
+  direction: SortOrder;
+}
+
+/**
+ * Extract sort field name and sort direction from orderBy string.
+ * @example
+ * const orderBy = 'createdAt_ASC';
+ *
+ * // sort.fieldName = 'createdAt', sort.direction = 'ASC'; sort.columnName = 'created_at';
+ * const sort = extractSortParams(orderBy);
+ */
+export const extractSortParams = <T>(orderBy: string): SortParams<T> => {
+  const slices = orderBy.split('_');
+
+  if (slices.length !== 2) {
+    throw new Error('Invalid orderBy argument');
+  }
+
+  return {
+    fieldName: slices[0] as unknown as T,
+    direction: slices[1] as unknown as SortOrder,
+    columnName: snakeCase(slices[0]),
+  };
+};
+
+export interface OffsetPaginationOptions {
+  limit?: number;
+  offset?: number;
+
+  /**
+   * If true, total count will be calculated by additional SELECT COUNT.
+   * @default true
+   */
+  needCountTotal: boolean;
+}
+
+export interface CreateOffsetPaginationOptionsParams {
+  maxLimit?: number;
+  defaultLimit?: number;
+}
+
+export const createOffsetPaginationOptions = (
+  input: OffsetPaginationInput,
+  info: GraphQLResolveInfo,
+  params?: CreateOffsetPaginationOptionsParams,
+): OffsetPaginationOptions => {
+  const options: OffsetPaginationOptions = {
+    needCountTotal: requiresTotalCount(info),
+    limit: params?.defaultLimit ?? PAGINATION_DEFAULT_LIMIT,
+  };
+
+  if (input.limit) {
+    options.limit = truncPaginationLimit(Number(input.limit), params?.maxLimit);
+
+    if (input.page) {
+      options.offset = (Number(input.page) - 1) * options.limit;
+    }
+  }
+
+  return options;
+};
+
+export const offsetPaginatedOutput = <T>(items: T[], {
+  limit,
+  offset = 0,
+  total = 0,
+}: ListMeta): IOffsetPaginated<T> => {
+  if (!limit) {
+    throw new OffsetPaginationError(OffsetErrorMessage.OUTPUT_LIMIT);
+  }
+
+  return {
+    items,
+    pageInfo: {
+      totalPages: Math.ceil(total / limit),
+      totalItems: total,
+      page: (offset / limit) + 1,
+      limit,
+    },
+  };
+};

package/src/pagination/offset/offset-pagination.input.ts

@@ -0,0 +1,30 @@
+import {
+  ArgsType,
+  Field, Int,
+} from '@nestjs/graphql';
+
+import { PAGINATION_DEFAULT_LIMIT } from '../constants.js';
+
+@ArgsType()
+export class OffsetPaginationInput {
+  /**
+   * the amount of items to be requested per page
+   */
+  @Field(() => Int, {
+    description: 'the amount of items to be requested per page',
+    defaultValue: PAGINATION_DEFAULT_LIMIT,
+    nullable: true,
+  })
+  limit?: number;
+
+  /**
+   * @default 1
+   * the page that is requested
+   */
+  @Field(() => Int, {
+    defaultValue: 1,
+    description: 'the page that is requested',
+  })
+  page?: number = 1;
+}
+

package/src/pagination/offset/offset-pagination.types.ts

@@ -0,0 +1,82 @@
+import { Type } from '@nestjs/common';
+import {
+  Field, Int,
+  ObjectType,
+} from '@nestjs/graphql';
+
+@ObjectType()
+export class OffsetPaginationPageInfo {
+  /**
+   * The total amount of pages
+   * (total items / limit)
+   */
+  @Field(() => Int, {
+    description: 'The total amount of pages (total items / limit)',
+  })
+  totalPages!: number;
+
+  /**
+   * The total amount of items
+   */
+  @Field(() => Int, {
+    description: 'The total amount of items',
+  })
+  totalItems!: number;
+
+  /**
+   * The current page
+   */
+  @Field(() => Int, {
+    description: 'The current page',
+  })
+  page!: number;
+
+  /**
+   * The amount of items to be requested per page
+   */
+  @Field(() => Int, {
+    description: 'The amount of items to be requested per page',
+  })
+  limit!: number;
+}
+
+export interface IOffsetPaginated<T> {
+  items: T[];
+  pageInfo: OffsetPaginationPageInfo;
+}
+
+/**
+ * Creates a new GraphQL object type with the name `Paginated${classRef.name}`
+ * that implements the `IOffsetPaginated` interface
+ * @param classRef The class reference of the items
+ *
+ * @example Create PaginatedUsers type
+ * ```ts
+ * @ObjectType()
+ * class PaginatedUsers extends OffsetPaginated(User) {}
+ * ```
+ */
+// eslint-disable-next-line func-style
+export function OffsetPaginated<T>(classRef: Type<T>): Type<IOffsetPaginated<T>> {
+  @ObjectType({
+    isAbstract: true,
+  })
+  abstract class OffsetPaginatedType implements IOffsetPaginated<T> {
+    /**
+     * The items of the current page
+     */
+    @Field(() => [classRef], {
+      description: 'The items of the current page',
+    })
+    items!: T[];
+
+    /**
+     * The pagination information
+     * (total pages, total items, current page, limit)
+     */
+    @Field(() => OffsetPaginationPageInfo)
+    pageInfo!: OffsetPaginationPageInfo;
+  }
+
+  return OffsetPaginatedType as Type<IOffsetPaginated<T>>;
+}

package/src/pagination/tools.ts

@@ -0,0 +1,53 @@
+import { GraphQLResolveInfo } from 'graphql';
+
+import { PAGINATION_MAX_LIMIT } from './constants.js';
+
+export const truncPaginationLimit = (limit: number, maxLimit = PAGINATION_MAX_LIMIT) =>
+  Math.min(limit, maxLimit);
+
+/**
+ * Determines whether the GraphQL query requires a total count of items.
+ * @param info - The GraphQLResolveInfo object containing information about the query.
+ * @returns A boolean indicating whether the query requires a total count of items.
+ */
+export const requiresTotalCount = (info: GraphQLResolveInfo): boolean => {
+  const fieldNode = info.fieldNodes[0];
+
+  if (!fieldNode.selectionSet) {
+    return false;
+  }
+
+  for (const selection of fieldNode.selectionSet.selections) {
+    if (selection.kind === 'Field' && selection.name.value === 'pageInfo') {
+      if (selection.selectionSet) {
+        for (const pageInfoSelection of selection.selectionSet.selections) {
+          if (
+            pageInfoSelection.kind === 'Field' &&
+                        (pageInfoSelection.name.value === 'totalPages' || pageInfoSelection.name.value === 'totalItems')
+          ) {
+            return true;
+          }
+        }
+      }
+    }
+  }
+
+  if (info.fragments) {
+    const fragments = Object.values(info.fragments);
+    for (const fragment of fragments) {
+      // const regex = new RegExp('/OffsetPagination|PageInfo/i');
+      if (fragment.selectionSet) {
+        for (const pageInfoSelection of fragment.selectionSet.selections) {
+          if (
+            pageInfoSelection.kind === 'Field' &&
+            (pageInfoSelection.name.value === 'totalPages' || pageInfoSelection.name.value === 'totalItems')
+          ) {
+            return true;
+          }
+        }
+      }
+    }
+  }
+
+  return false;
+};

package/src/tools/compose.ts

@@ -0,0 +1,92 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type Constructor = new (...args: any[]) => any
+
+type MixinFunction<TInput, TOutput> = (source: TInput) => TOutput
+
+/**
+ * Compose a class by applying mixins to it.
+ * The code is inspired by https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/, its
+ * just that I have added the support for static types too.
+ *
+ * @param baseClass - The base class to extend
+ * @param mixins - One or more mixin functions to apply sequentially
+ * @returns The composed class with all mixins applied
+ */
+export function compose<TBase extends Constructor, TResult1>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>
+): TResult1
+export function compose<TBase extends Constructor, TResult1, TResult2>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>
+): TResult2
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>
+): TResult3
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>
+): TResult4
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4, TResult5>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>,
+  mixin5: MixinFunction<TResult4, TResult5>
+): TResult5
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4, TResult5, TResult6>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>,
+  mixin5: MixinFunction<TResult4, TResult5>,
+  mixin6: MixinFunction<TResult5, TResult6>
+): TResult6
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4, TResult5, TResult6, TResult7>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>,
+  mixin5: MixinFunction<TResult4, TResult5>,
+  mixin6: MixinFunction<TResult5, TResult6>,
+  mixin7: MixinFunction<TResult6, TResult7>
+): TResult7
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4, TResult5, TResult6, TResult7, TResult8>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>,
+  mixin5: MixinFunction<TResult4, TResult5>,
+  mixin6: MixinFunction<TResult5, TResult6>,
+  mixin7: MixinFunction<TResult6, TResult7>,
+  mixin8: MixinFunction<TResult7, TResult8>
+): TResult8
+export function compose<TBase extends Constructor, TResult1, TResult2, TResult3, TResult4, TResult5, TResult6, TResult7, TResult8, TResult9>(
+  baseClass: TBase,
+  mixin1: MixinFunction<TBase, TResult1>,
+  mixin2: MixinFunction<TResult1, TResult2>,
+  mixin3: MixinFunction<TResult2, TResult3>,
+  mixin4: MixinFunction<TResult3, TResult4>,
+  mixin5: MixinFunction<TResult4, TResult5>,
+  mixin6: MixinFunction<TResult5, TResult6>,
+  mixin7: MixinFunction<TResult6, TResult7>,
+  mixin8: MixinFunction<TResult7, TResult8>,
+  mixin9: MixinFunction<TResult8, TResult9>
+): TResult9
+export function compose<TBase extends Constructor, TMixin extends MixinFunction<TBase, TBase>>(
+  baseClass: TBase,
+  ...mixins: TMixin[]
+) {
+  return mixins.reduce((currentClass, mixin) => mixin(currentClass), baseClass);
+}

package/src/tools/convert-to-bigint.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a number or string value to a BigInt, preserving null and undefined values.
+ *
+ * @param value - The value to convert. Can be a number, string, undefined, or null.
+ * @returns The converted BigInt value, or the original value if it was null or undefined.
+ *
+ * @example
+ * ```typescript
+ * convertToBigInt(123) // returns 123n
+ * convertToBigInt("456") // returns 456n
+ * convertToBigInt(null) // returns null
+ * convertToBigInt(undefined) // returns undefined
+ * ```
+ *
+ * @throws {RangeError} Throws when the input cannot be converted to a valid BigInt.
+ */
+export const convertToBigInt = (value: number | string | undefined | null): bigint | undefined | null => {
+  if (value === null) {
+    return value;
+  }
+
+  if (typeof value === 'undefined') {
+    return value;
+  }
+
+  return BigInt(value);
+};