@pcg/core 1.0.0-alpha.0 → 1.0.0-alpha.2

package/src/tools/create-list-meta.ts

@@ -1,64 +0,0 @@
-import { ListMeta } from '#/types/list-meta';
-import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-import { fetchTotalWithQuery } from './fetch-total-with-query.js';
-
-export interface CreateListMetaOptions<T extends ObjectLiteral> {
-  /**
-   * Typeorm query builder
-   */
-  query: SelectQueryBuilder<T>;
-
-  /**
-   * If true, total count will be calculated by additional SELECT COUNT.
-   */
-  needCountTotal?: boolean;
-
-  /**
-   * Limit of items
-   */
-  limit?: number;
-
-  /**
-   * Offset of items
-   */
-  offset?: number;
-}
-
-/**
- * Create list meta object
- * @returns list meta object
- * @example
- * class UsersService {
- *  async getMany(opts: GetManyUsersOptions): Promise<[User[], ListMeta]> {
- *    ...
- *   return Promise.all([
- *     query.getMany(),
- *     createListMeta<User>({
- *       query,
- *       needCountTotal,
- *       limit,
- *       offset,
- *     }),
- *   ]);
- * }
- */
-export const createListMeta = async <T extends ObjectLiteral>(
-  {
-    query,
-    needCountTotal = false,
-    limit,
-    offset,
-  }: CreateListMetaOptions<T>,
-): Promise<ListMeta> => {
-  const meta: ListMeta = {
-    limit,
-    offset,
-  };
-
-  if (needCountTotal) {
-    meta.total = await fetchTotalWithQuery(query);
-  }
-
-  return meta;
-};
-

package/src/tools/define-statuses.ts

@@ -1,15 +0,0 @@
-/**
- * Define statuses. Returns array of statuses from filter or default statuses
- * @param statuses - array of statuses from filter. Can be undefined
- * @param defaultStatuses - array of default statuses
- * @returns final array of statuses
- * @example
- * const statuses = defineStatuses(['active', 'pending'], ['active']);
- * // statuses = ['active', 'pending']
- *
- * const statuses = defineStatuses(undefined, ['active']);
- * // statuses = ['active']
- */
-export const defineStatuses = <T>(statuses: T[] | undefined, defaultStatuses: T[]) => {
-  return Array.isArray(statuses) ? statuses : defaultStatuses;
-};

package/src/tools/env.ts

@@ -1,139 +0,0 @@
-import { Type as ClassConstructor } from '@nestjs/common';
-import { plainToInstance } from 'class-transformer';
-import { validateSync } from 'class-validator';
-
-import { AppEnv } from '#/enums/app-env.enum';
-
-/**
- * Validate environment variables using class-validator
- *
- * @param cls - class with environment variables
- * @throws Error if validation fails
- * @returns validated config as typed object
- * @example
- * ```ts
- * export class AppConfigEnvironmentVariables {
- *  @Type(() => Number)
- *  @IsNumber()
- *  PORT = 3000;
- * }
- *
- * const env = validateEnv(AppConfigEnvironmentVariables); // typed object
- * // env.PORT is now a number
- * ```
- */
-export const validateEnv = <T>(cls: ClassConstructor<T>): T => {
-  const validatedConfig = plainToInstance(
-    cls,
-    process.env,
-    {
-      enableImplicitConversion: true,
-    },
-  );
-
-  const errors = validateSync(validatedConfig as unknown as object, {
-    skipMissingProperties: false,
-  });
-
-  if (errors.length > 0) {
-    throw new Error(errors.toString());
-  }
-
-  return validatedConfig;
-};
-
-/**
- * Returns a string with a dash prefix based on the current environment.
- * If the environment is development or local, returns '-dev'.
- * If the environment is stage, returns '-stage'.
- * Otherwise, returns an empty string.
- *
- * @returns a string with a dash prefix based on the current environment
- * @example
- * ```typescript
- * const name = `my-app${withDashEnv()}`;
- * ```
- */
-export const withDashEnv = () => {
-  if (process.env.APP_ENV === AppEnv.DEVELOPMENT || process.env.APP_ENV === AppEnv.LOCAL || process.env.APP_ENV === AppEnv.TEST) {
-    return '-dev';
-  }
-
-  if (process.env.APP_ENV === AppEnv.STAGE) {
-    return '-stage';
-  }
-
-  return '';
-};
-
-/**
- * Returns a string with a dash prefix based on the current environment.
- * If the environment is development or local, returns '.dev'.
- * If the environment is stage, returns '.stage'.
- * Otherwise, returns an empty string.
- *
- * @returns a string with a dot prefix based on the current environment
- * @example
- * ```typescript
- * const name = `config${withDotEnv()}`;
- * ```
- */
-export const withDotEnv = () => {
-  if (process.env.APP_ENV === AppEnv.DEVELOPMENT || process.env.APP_ENV === AppEnv.LOCAL || process.env.APP_ENV === AppEnv.TEST) {
-    return '.dev';
-  }
-
-  if (process.env.APP_ENV === AppEnv.STAGE) {
-    return '.stage';
-  }
-
-  return '';
-};
-
-/**
- * Returns a string with a colon prefix based on the current environment.
- * If the environment is development or local, returns ':dev'.
- * If the environment is stage, returns ':stage'.
- * Otherwise, returns an empty string.
- *
- * @returns a string with a colon prefix based on the current environment
- * @example
- * ```typescript
- * const name = `my:app${withColonEnv()}`;
- * ```
- */
-export const withColonEnv = () => {
-  if (process.env.APP_ENV === AppEnv.DEVELOPMENT || process.env.APP_ENV === AppEnv.LOCAL || process.env.APP_ENV === AppEnv.TEST) {
-    return ':dev';
-  }
-
-  if (process.env.APP_ENV === AppEnv.STAGE) {
-    return ':stage';
-  }
-
-  return '';
-};
-
-/**
- * Returns a string with an underscore prefix based on the current environment.
- * If the environment is development or local, returns '_dev'.
- * If the environment is stage, returns '_stage'.
- * Otherwise, returns an empty string.
- *
- * @returns a string with an underscore prefix based on the current environment
- * @example
- * ```typescript
- * const name = `my_app${withUnderscoreEnv()}`;
- * ```
- */
-export const withUnderscoreEnv = () => {
-  if (process.env.APP_ENV === AppEnv.DEVELOPMENT || process.env.APP_ENV === AppEnv.LOCAL || process.env.APP_ENV === AppEnv.TEST) {
-    return '_dev';
-  }
-
-  if (process.env.APP_ENV === AppEnv.STAGE) {
-    return '_stage';
-  }
-
-  return '';
-};

package/src/tools/fetch-total-with-query.ts

@@ -1,48 +0,0 @@
-import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-
-/**
- * Returns total count of items with typeorm query
- * @param query - typeorm query builder
- * @returns total count of items
- */
-/**
- * Returns total count of items with typeorm query
- * @param query - typeorm query builder
- * @returns total count of items
- */
-export const fetchTotalWithQuery = async <T extends ObjectLiteral>(
-  query: SelectQueryBuilder<T>,
-): Promise<number> => {
-  const totalQueryBuilder = query.clone();
-
-  // Clear any pagination settings
-  totalQueryBuilder
-    .offset(undefined)
-    .limit(undefined)
-    .skip(undefined)
-    .take(undefined)
-    .orderBy();
-
-  const hasDistinctOn = totalQueryBuilder.expressionMap.selectDistinctOn && totalQueryBuilder.expressionMap.selectDistinctOn.length > 0;
-  const isGrouped = totalQueryBuilder.expressionMap.groupBys && totalQueryBuilder.expressionMap.groupBys.length > 0;
-
-  // Check if the original query has DISTINCT ON or GROUP BY
-  if (hasDistinctOn || isGrouped) {
-    // Wrap the query (either with DISTINCT ON or GROUP BY) in a subquery and count the results
-    const subQuery = totalQueryBuilder.getQuery();
-
-    const result = await query.connection
-      .createQueryBuilder()
-      .select('COUNT(*)', 'rowsCount')
-      .from(`(${subQuery})`, 'subQuery')
-      .setParameters(totalQueryBuilder.getParameters())
-      .getRawOne<{
-      rowsCount: number;
-    }>();
-
-    return result?.rowsCount ?? 0;
-  }
-
-  // If no DISTINCT ON or GROUP BY, just get the count directly
-  return await totalQueryBuilder.getCount();
-};

package/src/tools/generate-entity-id.ts

@@ -1,23 +0,0 @@
-import { createRandomString } from '@pcg/text-kit';
-
-/**
- * Generates a unique entity identifier by combining product name, entity prefix, delimiter, and random string.
- *
- * @param product - The product short name to include in the entity ID (e.g., 'fwd' for Forward)
- * @param prefix - The entity type prefix to include in the entity ID (e.g., 'u' for user, 'org' for organization)
- * @param delimiter - The delimiter to separate components (default: ':')
- * @param size - The length of the random string component (default: 11)
- * @returns A formatted entity ID string in the format: `${product}${prefix}${delimiter}${randomString}`
- *
- * @example
- * ```typescript
- * generateEntityId('fwd', 'org')
- * // Returns: 'fwdorg:A1b2C3d4E5f'
- *
- * generateEntityId('myapp', 'u', '_', 8)
- * // Returns: 'myappuser_A1b2C3d4'
- * ```
- */
-export const generateEntityId = (product: string, prefix: string, delimiter = ':', size = 11): string => {
-  return `${product}${prefix}${delimiter}${createRandomString(size)}`;
-};

package/src/tools/get-request-language.ts

@@ -1,13 +0,0 @@
-import { parse } from 'accept-language-parser';
-
-import { NestExpressRequest } from '#/types/express-request';
-
-export const getRequestLanguage = (req: NestExpressRequest, fallbackLanguage: string): string => {
-  const headers = req?.headers as ({
-    ['accept-language']?: string;
-  });
-
-  return parse(headers['accept-language'])
-    ?.[0]
-    ?.code ?? fallbackLanguage;
-};

package/src/tools/is-object.ts

@@ -1,10 +0,0 @@
-/**
- * Checks if the given value is an object (not an array).
- * @param {unknown} obj - The value to check.
- * @returns {boolean} Returns true if `obj` is an object, false otherwise.
- * @example
- * isObject({ a: 1 });  // Returns true
- * isObject([1, 2, 3]);  // Returns false
- */
-export const isObject = (obj: unknown): obj is Record<string, unknown> =>
-  obj !== null && !!obj && typeof obj === 'object' && !Array.isArray(obj);

package/src/tools/postgres/locale-to-pg-collate.ts

@@ -1,21 +0,0 @@
-/**
- * Converts a locale string to a PostgreSQL collation identifier.
- *
- * @param locale - The locale string to convert (e.g., 'uk', 'en')
- * @returns The PostgreSQL collation identifier (e.g., 'uk_UA', 'en_US')
- *
- * @example
- * ```typescript
- * localeToPgCollate('uk') // returns 'uk_UA'
- * localeToPgCollate('en') // returns 'en_US'
- * ```
- */
-export const localeToPgCollate = (locale: string) => {
-  let collate = 'en_US';
-
-  if (locale === 'uk') {
-    collate = 'uk_UA';
-  }
-
-  return collate;
-};

package/src/tools/remove-undefined-properties.ts

@@ -1,20 +0,0 @@
-type DefinedValuesOnly<T> = {
-  [K in keyof T]: T[K] extends undefined ? never : K;
-}[keyof T];
-
-type UndefinedRemoved<T> = {
-  [K in DefinedValuesOnly<T>]: T[K];
-};
-
-export const removeUndefinedProperties = <T extends object>(obj: T): UndefinedRemoved<T> => {
-  const result: Partial<UndefinedRemoved<T>> = {
-  };
-
-  for (const key in obj) {
-    if (Object.prototype.hasOwnProperty.call(obj, key) && obj[key as keyof T] !== undefined) {
-      (result as Record<string, unknown>)[key] = obj[key as keyof T];
-    }
-  }
-
-  return result as UndefinedRemoved<T>;
-};

package/src/tools/request-id.ts

@@ -1,25 +0,0 @@
-import { createRandomString } from '@pcg/text-kit';
-
-import { NestExpressRequest } from '#/types/express-request';
-
-
-export const generateRequestId = (appShortName: string) => {
-  return `${appShortName}req:${createRandomString()}`;
-};
-
-export const extractRequestId = (req: NestExpressRequest): string => {
-  const headers = req?.headers as ({
-    'x-request-id'?: string;
-    'x-cloud-trace-context'?: string;
-  });
-
-  if (headers?.['x-request-id']) {
-    return headers['x-request-id'];
-  }
-
-  if (headers['x-cloud-trace-context']) {
-    return req.appShortname + `req:${headers['x-cloud-trace-context']}`;
-  }
-
-  return generateRequestId(req.appShortname);
-};

package/src/tools/stringify-opts.ts

@@ -1,20 +0,0 @@
-/**
- * Converts an object into a human-readable string representation.
- *
- * Takes an object and transforms it into a string where each key-value pair
- * is formatted as "key JSON-value" and all pairs are joined with " and ".
- *
- * @param opts - The object to stringify
- * @returns A string representation of the object with entries joined by " and "
- *
- * @example
- * ```ts
- * stringifyOpts({ name: 'John', age: 30 })
- * // Returns: 'name "John" and age 30'
- * ```
- */
-export const stringifyOpts = (opts: object) => {
-  return Object.entries(opts)
-    .map(([key, value]) => `${key} ${JSON.stringify(value)}`)
-    .join(' and ');
-};

package/src/tools/typeorm/add-filter.ts

@@ -1,164 +0,0 @@
-import {
-    Brackets, In, IsNull, ObjectLiteral, SelectQueryBuilder, WhereExpressionBuilder,
-} from 'typeorm';
-
-import { MaybeNull } from '#/types/maybe';
-
-/**
- * Adds a filter condition to a TypeORM SelectQueryBuilder based on the provided field and value(s).
- *
- * Handles three types of filtering:
- * - Single value filtering: when a single non-null value is provided
- * - Multiple value filtering: when an array of values is provided
- * - Null value filtering: when null is explicitly provided as the filter value
- *
- * @template T - The entity type that extends ObjectLiteral
- * @template K - The field name key type that must be a string key of T
- *
- * @param query - The TypeORM SelectQueryBuilder instance to add the filter to
- * @param fieldName - The name of the field to filter by, must be a valid key of entity T
- * @param valueOrValues - The filter value(s). Can be:
- *   - A single value of type T[K]
- *   - An array of values of type T[K]
- *   - null to filter for null values
- *   - An array containing null values
- * @example
- * ```typescript
- * // Single value filter
- * addFilterByField(queryBuilder, 'status', 'active');
- * // Multiple values filter
- * addFilterByField(queryBuilder, 'id', [1, 2, 3]);
- * // Null value filter
- * addFilterByField(queryBuilder, 'deletedAt', null);
- * ```
- *
- * @returns void - Modifies the query builder in place
- */
-export const addFilterByField = <
-  T extends ObjectLiteral,
-  K extends (keyof T & string)
->(query: SelectQueryBuilder<T>, fieldName: K, valueOrValues: MaybeNull<T[K]> | MaybeNull<T[K]>[]): void => {
-  const isFilterValueMultiple = Array.isArray(valueOrValues);
-
-  if (isFilterValueMultiple) {
-    addMultipleFilter(query, fieldName, valueOrValues);
-  } else if (valueOrValues === null) {
-    addNullableFilter(query, fieldName);
-  } else {
-    addSingleFilter(query, fieldName, valueOrValues);
-  }
-};
-
-/**
- * Adds a filter to a TypeORM query that matches multiple values for a given column,
- * including support for null values.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @template K - The key type that must be both a key of T and a string
- * @param query - The TypeORM SelectQueryBuilder instance to add the filter to
- * @param columnName - The name of the column to filter on
- * @param values - An array of values to match, which may include null
- *
- * @remarks
- * This function creates an OR condition that matches any of the provided values.
- * If the values array includes null, a separate null check is added to the filter.
- * Non-null values are handled using TypeORM's `In` operator.
- *
- * @example
- * ```typescript
- * const query = repository.createQueryBuilder('user');
- * addMultipleFilter(query, 'status', ['active', 'pending', null]);
- * // Generates: WHERE (status IS NULL OR status IN ('active', 'pending'))
- * ```
- */
-const addMultipleFilter = <
-  T extends ObjectLiteral,
-  K extends (keyof T & string)
->(query: SelectQueryBuilder<T>, columnName: K, values: MaybeNull<T[K]>[]): void => {
-  query.andWhere(new Brackets((subQuery) => {
-    if (values.includes(null)) {
-      addNullValueToMultipleFilter(subQuery, columnName);
-    }
-
-    const notNullValues = values.filter((v) => v !== null);
-    subQuery.orWhere({
-      [columnName]: In(notNullValues),
-    });
-  }));
-};
-
-/**
- * Adds a single filter condition to a TypeORM SelectQueryBuilder.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @template K - The column name type, constrained to string keys of T
- *
- * @param query - The SelectQueryBuilder instance to add the filter to
- * @param columnName - The name of the column to filter on
- * @param value - The value to filter by, must match the type of the column
- *
- * @returns void
- *
- * @example
- * ```typescript
- * const query = repository.createQueryBuilder('user');
- * addSingleFilter(query, 'email', 'user@example.com');
- * // Results in: WHERE user.email = 'user@example.com'
- * ```
- */
-const addSingleFilter = <
-  T extends ObjectLiteral,
-  K extends (keyof T & string)
->(query: SelectQueryBuilder<T>, columnName: K, value: T[K]): void => {
-  query.andWhere({
-    [columnName]: value,
-  });
-};
-
-/**
- * Adds a nullable filter to a TypeORM query builder.
- *
- * This function applies a WHERE clause that filters for NULL values in the specified column.
- * The filter is combined with existing conditions using AND logic.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @param query - The TypeORM SelectQueryBuilder instance to add the filter to
- * @param columnName - The name of the column to check for NULL values
- * @returns void
- *
- * @example
- * ```typescript
- * const query = repository.createQueryBuilder('user');
- * addNullableFilter(query, 'deletedAt');
- * // Results in: WHERE deletedAt IS NULL
- * ```
- */
-const addNullableFilter = <T extends ObjectLiteral>(query: SelectQueryBuilder<T>, columnName: string): void => {
-  query.andWhere({
-    [columnName]: IsNull(),
-  });
-};
-
-/**
- * Adds an OR condition to the query to check if the specified column is NULL.
- *
- * This function is used to extend filtering logic by adding a null value check
- * as an alternative condition in a WHERE clause.
- *
- * @param query - The TypeORM WhereExpressionBuilder instance to which the null condition will be added
- * @param columnName - The name of the database column to check for NULL values
- *
- * @returns void
- *
- * @example
- * ```typescript
- * const queryBuilder = repository.createQueryBuilder('user');
- * addNullValueToMultipleFilter(queryBuilder, 'deletedAt');
- * // Results in: WHERE ... OR deletedAt IS NULL
- * ```
- */
-const addNullValueToMultipleFilter = (query: WhereExpressionBuilder, columnName: string): void => {
-  query.orWhere({
-    [columnName]: IsNull(),
-  });
-};

package/src/tools/typeorm/ensure-inner-join.ts

@@ -1,36 +0,0 @@
-import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-import { isAliasAlreadyBusy } from './is-alias-already-busy.js';
-
-/**
- * Ensures an inner join is added to the TypeORM query builder only if the alias is not already in use.
- *
- * This function checks if the specified alias is already being used in the query builder.
- * If the alias is available, it adds an inner join with the provided entity, alias, and optional condition.
- * If the alias is already busy, the function returns without making any changes to the query.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @param query - The TypeORM SelectQueryBuilder instance to add the inner join to
- * @param entity - The entity class (Function) or entity name (string) to join
- * @param alias - The alias to use for the joined entity
- * @param condition - Optional join condition as a string
- * @returns void
- *
- * @example
- * ```typescript
- * const query = repository.createQueryBuilder('user');
- * ensureInnerJoin(query, Profile, 'profile', 'profile.userId = user.id');
- * ```
- */
-export const ensureInnerJoin = <T extends ObjectLiteral>(
-  query: SelectQueryBuilder<T>,
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  entity: Function | string,
-  alias: string,
-  condition?: string,
-): void => {
-  if (isAliasAlreadyBusy(query, alias)) {
-    return;
-  }
-
-  query.innerJoin(entity, alias, condition);
-};

package/src/tools/typeorm/ensure-left-join.ts

@@ -1,36 +0,0 @@
-import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-import { isAliasAlreadyBusy } from './is-alias-already-busy.js';
-
-/**
- * Ensures a left join is added to a TypeORM query builder if the alias is not already in use.
- *
- * This function checks if the specified alias is already being used in the query.
- * If the alias is available, it performs a left join with the provided entity, alias, and optional condition.
- * If the alias is already busy, the function returns early without modifying the query.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @param query - The TypeORM SelectQueryBuilder instance to add the left join to
- * @param entity - The entity class (Function) or table name (string) to join
- * @param alias - The alias name to use for the joined entity
- * @param condition - Optional join condition as a string (e.g., "alias.id = entity.foreignId")
- * @returns void
- *
- * @example
- * ```typescript
- * ensureLeftJoin(queryBuilder, User, 'user', 'user.id = post.userId');
- * ```
- */
-export const ensureLeftJoin = <T extends ObjectLiteral>(
-  query: SelectQueryBuilder<T>,
-
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  entity: Function | string,
-  alias: string,
-  condition?: string,
-): void => {
-  if (isAliasAlreadyBusy(query, alias)) {
-    return;
-  }
-
-  query.leftJoin(entity, alias, condition);
-};

package/src/tools/typeorm/is-alias-already-busy.ts

@@ -1,25 +0,0 @@
-import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
-
-/**
- * Checks if a given alias is already used in the query builder's join attributes.
- *
- * This utility function inspects the query builder's expression map to determine
- * whether a specific alias name has already been assigned to any join attribute.
- * This is useful to avoid alias conflicts when building complex TypeORM queries.
- *
- * @template T - The entity type that extends ObjectLiteral
- * @param {SelectQueryBuilder<T>} query - The TypeORM SelectQueryBuilder instance to check
- * @param {string} alias - The alias name to search for in the join attributes
- * @returns {boolean} True if the alias is already used in any join attribute, false otherwise
- *
- * @example
- * ```typescript
- * const query = repository.createQueryBuilder('user');
- * const isBusy = isAliasAlreadyBusy(query, 'profile');
- * if (!isBusy) {
- *   query.leftJoinAndSelect('user.profile', 'profile');
- * }
- * ```
- */
-export const isAliasAlreadyBusy = <T extends ObjectLiteral>(query: SelectQueryBuilder<T>, alias: string) =>
-  query.expressionMap.joinAttributes.some((a) => a.alias.name === alias);