@koalarx/nest 3.1.50 → 4.0.1

package/koala-nest/src/core/tools/mapping/auto-mapper.ts

@@ -0,0 +1,102 @@
+import { Type } from '@nestjs/common';
+import { MappingStore } from './mapping-store';
+
+export class AutoMapper {
+  private static isEntity(value: any) {
+    const nonEntityTypes = [String, Number, Boolean, Date, Object, Function];
+
+    return (
+      value instanceof Object &&
+      value !== null &&
+      !Array.isArray(value) &&
+      !nonEntityTypes.includes(value)
+    );
+  }
+
+  private static isClass(value: any) {
+    return value instanceof Function && !value.prototype;
+  }
+
+  private static toClass(type: Type<any> | (() => Type<any>)) {
+    return this.isClass(type)
+      ? (type as () => Type<any>)()
+      : (type as Type<any>);
+  }
+
+  static map<S, R>(data: any, source: Type<S>, target: Type<R>): R {
+    const mapping = MappingStore.getMapping(source, target);
+
+    const targetInstance = new target();
+
+    if (!mapping) {
+      throw new Error(`Mapping not found for ${target.name}`);
+    }
+
+    const sourceProps = MappingStore.getProps(source);
+    const targetProps = MappingStore.getProps(target);
+
+    if (!targetProps) {
+      throw new Error(`Target properties not found for ${target.name}`);
+    }
+
+    const customTargetProps = new Set<string>();
+
+    for (const member of mapping.formMember) {
+      for (const [targetProp, mapFn] of Object.entries(member)) {
+        if (typeof mapFn === 'function') {
+          targetInstance[targetProp] = mapFn(data);
+          customTargetProps.add(targetProp);
+        }
+      }
+    }
+
+    for (const sourceProp of sourceProps) {
+      const targetProp = targetProps.find((p) => p.name === sourceProp.name);
+
+      if (!targetProp || customTargetProps.has(targetProp.name)) {
+        continue;
+      }
+
+      const targetPropName = targetProp.name;
+      const sourcePropTypeClass = this.toClass(sourceProp.type);
+
+      if (!sourceProp.isArray && this.isEntity(sourcePropTypeClass)) {
+        const targetPropType = targetProps.find(
+          (p) => p.name === targetPropName,
+        )?.type;
+
+        if (!targetPropType) {
+          continue;
+        }
+
+        const targetClass: Type<any> = this.toClass(targetPropType);
+
+        targetInstance[targetPropName] = this.map(
+          data[sourceProp.name],
+          sourcePropTypeClass,
+          targetClass,
+        );
+        continue;
+      }
+
+      if (sourceProp.isArray) {
+        targetInstance[targetPropName] = data[sourceProp.name].map(
+          (item: unknown) => {
+            const targetItemType = targetProps.find(
+              (p) => p.name === targetPropName,
+            )!.type;
+
+            const targetClassType = this.toClass(targetItemType);
+
+            return this.map(item, sourcePropTypeClass, targetClassType);
+          },
+        );
+        continue;
+      }
+
+      targetInstance[targetPropName] = data[sourceProp.name];
+    }
+
+    return targetInstance;
+  }
+}

package/koala-nest/src/core/tools/mapping/create-map.ts

@@ -0,0 +1,11 @@
+import { Type } from '@nestjs/common';
+import { ForMemberDefinition } from './for-member';
+import { MappingStore } from './mapping-store';
+
+export function createMap<TSource, TTarget>(
+  source: Type<TSource>,
+  target: Type<TTarget>,
+  ...formMember: ForMemberDefinition<TTarget, TSource>
+) {
+  MappingStore.add(source, target, ...formMember);
+}

package/koala-nest/src/core/tools/mapping/for-member.ts

@@ -0,0 +1,16 @@
+export type ForMemberResult<TTarget, TSource> = {
+  [Key in keyof TTarget]: (source: TSource) => TTarget[Key];
+};
+
+export type ForMemberDefinition<TTarget, TSource> = Array<
+  Partial<ForMemberResult<TTarget, TSource>>
+>;
+
+export function forMember<TTarget, TSource>(
+  targetProp: keyof TTarget,
+  map: (source: TSource) => TTarget[keyof TTarget],
+): Partial<ForMemberResult<TTarget, TSource>> {
+  return {
+    [targetProp]: map,
+  } as Partial<ForMemberResult<TTarget, TSource>>;
+}

package/koala-nest/src/core/tools/mapping/index.ts

@@ -0,0 +1,4 @@
+export * from './auto-map';
+export * from './for-member';
+export * from './create-map';
+export * from './auto-mapper';

package/koala-nest/src/core/tools/mapping/mapping-store.ts

@@ -0,0 +1,121 @@
+import { Type } from '@nestjs/common';
+import { ForMemberDefinition } from './for-member';
+
+interface EntityPropDefs {
+  name: string;
+  type: Type<any> | (() => Type<any>);
+  isArray: boolean;
+}
+
+interface MappingDefinition {
+  source: Type<any>;
+  target: Type<any>;
+  formMember: ForMemberDefinition<any, any>;
+}
+
+export class MappingStore {
+  private static readonly _entities = new Map<Type<any>, EntityPropDefs[]>();
+  private static readonly _mappings = new Map<
+    Type<any>,
+    Map<Type<any>, MappingDefinition>
+  >();
+
+  static setProp(
+    entity: Type<any>,
+    propName: string,
+    compositionType?: () => Type<any>,
+  ) {
+    const propType = Reflect.getMetadata(
+      'design:type',
+      entity.prototype,
+      propName,
+    );
+    const isArray = propType === Array;
+    const type = isArray ? (compositionType ?? propType) : propType;
+
+    const props = this._entities.get(entity) || [];
+
+    props.push({
+      name: propName,
+      type,
+      isArray,
+    });
+
+    this._entities.set(entity, props);
+  }
+
+  static getProps(entity: Type<any>) {
+    const props: EntityPropDefs[] = [];
+    const seen = new Set<string>();
+    let current: Type<any> | null = entity;
+
+    while (current?.prototype) {
+      for (const prop of this._entities.get(current) ?? []) {
+        if (!seen.has(prop.name)) {
+          seen.add(prop.name);
+          props.push(prop);
+        }
+      }
+
+      current = Object.getPrototypeOf(current) as Type<any> | null;
+    }
+
+    return props;
+  }
+
+  static getPropType(entity: Type<any>, propName: string) {
+    const prop = this._entities.get(entity)?.find((p) => p.name === propName);
+
+    if (!prop) {
+      throw new Error(
+        `Property ${propName} not found in entity ${entity.name}`,
+      );
+    }
+
+    const { type, isArray } = prop;
+
+    if (!type) {
+      return null;
+    }
+
+    if (isArray && type instanceof Function) {
+      return (type as () => Type<any>)();
+    }
+
+    return type;
+  }
+
+  static add(
+    source: Type<any>,
+    target: Type<any>,
+    ...formMember: ForMemberDefinition<any, any>
+  ) {
+    const targetMappings =
+      this._mappings.get(source) ?? new Map<Type<any>, MappingDefinition>();
+
+    targetMappings.set(target, {
+      source,
+      target,
+      formMember,
+    });
+
+    this._mappings.set(source, targetMappings);
+  }
+
+  static getMapping(source: Type<any>, target: Type<any>) {
+    return this._mappings.get(source)?.get(target) ?? null;
+  }
+
+  /** Compatibilidade com chave legada usada em testes. */
+  static getMappingByName(mapName: string) {
+    for (const targetMappings of this._mappings.values()) {
+      for (const mapping of targetMappings.values()) {
+        if (`${mapping.source.name}To${mapping.target.name}` === mapName) {
+          return mapping;
+        }
+      }
+    }
+
+    return null;
+  }
+}

package/koala-nest/src/core/types/auth-provider-config-response.type.ts

@@ -0,0 +1,5 @@
+export type AuthProviderConfigResponseType = {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+};

package/koala-nest/src/core/types/index.ts

@@ -0,0 +1,5 @@
+export type QueryDirectionType = 'asc' | 'desc';
+export interface ListResponse<T> {
+  items: T[];
+  count: number;
+}

package/koala-nest/src/core/utils/build-list-cache-key.ts

@@ -0,0 +1,19 @@
+export function buildListCacheKey(prefix: string, query: object) {
+  const normalized = Object.keys(query)
+    .sort()
+    .reduce<Record<string, unknown>>((acc, key) => {
+      const value = (query as Record<string, unknown>)[key];
+
+      if (typeof value === 'function') {
+        return acc;
+      }
+
+      if (value !== undefined && value !== null && value !== '') {
+        acc[key] = value;
+      }
+
+      return acc;
+    }, {});
+
+  return `${prefix}:${JSON.stringify(normalized)}`;
+}

package/koala-nest/src/core/utils/cron-expression-to-boolean.ts

@@ -0,0 +1,65 @@
+import { CronExpressionParser } from 'cron-parser';
+
+/**
+ * Verifica se a expressão cron corresponde ao momento atual.
+ *
+ * @param cronExpression Expressão cron a ser validada
+ * @returns booleano indicando se o cronjob deve ser executado agora
+ *
+ * ---
+ *
+ * Guia de formação da cronExpression:
+ *
+ * Uma expressão cron padrão possui 6 campos separados por espaço:
+ *
+ *   segundo   minuto   hora   dia-mês   mês   dia-semana
+ *   -------   ------   ----   -------   ---   ----------
+ *      0        0      12       1       *        *
+ *
+ * Exemplo:
+ *   '0 0 12 * * *' → executa todo dia ao meio-dia
+ *
+ * Campos:
+ *   - segundo:        (0-59)
+ *   - minuto:         (0-59)
+ *   - hora:           (0-23)
+ *   - dia do mês:     (1-31)
+ *   - mês:            (1-12 ou JAN-DEC)
+ *   - dia da semana:  (0-7 ou SUN-SAT, 0/7=domingo)
+ *
+ * Caracteres especiais:
+ *   - *   qualquer valor
+ *   - ,   lista de valores
+ *   - -   intervalo
+ *   - /   passo
+ *   - L   último dia
+ *   - #   enésimo dia da semana do mês
+ *
+ * Exemplos:
+ *   - '0 0 * * * *'        → todo início de hora
+ *   - '0 0/5 * * * *'      → a cada 5 minutos
+ *   - '0 0 8 * * 1-5'      → 8h de segunda a sexta
+ *   - '0 0 0 1 1 *'        → todo 1º de janeiro à meia-noite
+ */
+export function cronExpressionToBoolean(
+  cronExpression: string,
+  now: Date = new Date(),
+): boolean {
+  try {
+    const interval = CronExpressionParser.parse(cronExpression, {
+      currentDate: now,
+    });
+    const prev = interval.prev();
+
+    return (
+      prev.getFullYear() === now.getFullYear() &&
+      prev.getMonth() === now.getMonth() &&
+      prev.getDate() === now.getDate() &&
+      prev.getHours() === now.getHours() &&
+      prev.getMinutes() === now.getMinutes() &&
+      prev.getSeconds() === now.getSeconds()
+    );
+  } catch {
+    return false;
+  }
+}

package/koala-nest/src/core/utils/env.config.ts

@@ -0,0 +1,17 @@
+export class EnvConfig {
+  static get isEnvTest() {
+    return process.env.NODE_ENV === 'test';
+  }
+
+  static get isEnvDevelop() {
+    return process.env.NODE_ENV === 'develop';
+  }
+
+  static get isEnvStaging() {
+    return process.env.NODE_ENV === 'staging';
+  }
+
+  static get isEnvProduction() {
+    return process.env.NODE_ENV === 'production';
+  }
+}

package/koala-nest/src/core/utils/filter-request-params.ts

@@ -0,0 +1,29 @@
+import { ArgumentsHost } from '@nestjs/common/interfaces';
+import { Request, Response } from 'express';
+
+type RequestUser = { login?: string; sub?: string };
+
+export class FilterRequestParams {
+  static get(host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request & { user?: RequestUser }>();
+    const method = request.method;
+    const isGetMethod = method === 'GET';
+
+    return {
+      response,
+      loggedUserName:
+        request?.user?.login ??
+        request?.user?.sub ??
+        request.headers.origin ??
+        request.ip ??
+        '',
+      filterParams: {
+        method,
+        payload: !isGetMethod ? request.body : undefined,
+        endpoint: request.url,
+      },
+    };
+  }
+}

package/koala-nest/src/core/utils/format-typeorm-error.ts

@@ -0,0 +1,173 @@
+import { HttpStatus } from '@nestjs/common';
+import {
+  EntityNotFoundError,
+  OptimisticLockVersionMismatchError,
+  QueryFailedError,
+  TypeORMError,
+} from 'typeorm';
+
+export interface FieldError {
+  field: string;
+  message: string;
+}
+
+export interface FormattedTypeOrmError {
+  statusCode: HttpStatus;
+  message: string;
+  errors?: FieldError[];
+}
+
+interface PostgresDriverError {
+  code?: string;
+  detail?: string;
+  constraint?: string;
+  table?: string;
+  column?: string;
+  message?: string;
+}
+
+const POSTGRES_ERROR_MESSAGES: Record<
+  string,
+  (field?: string) => { message: string; statusCode: HttpStatus }
+> = {
+  '23505': (field) => ({
+    statusCode: HttpStatus.CONFLICT,
+    message: field
+      ? `Já existe um registro com este valor para o campo ${field}.`
+      : 'Já existe um registro com este valor.',
+  }),
+  '23503': (field) => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: field
+      ? `O valor informado para o campo ${field} não possui um registro relacionado.`
+      : 'O registro referenciado não foi encontrado.',
+  }),
+  '23502': (field) => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: field
+      ? `O campo ${field} é obrigatório.`
+      : 'Um ou mais campos obrigatórios não foram informados.',
+  }),
+  '23514': (field) => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: field
+      ? `O valor informado para o campo ${field} é inválido.`
+      : 'Um ou mais valores informados são inválidos.',
+  }),
+  '22P02': () => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: 'Formato de dado inválido.',
+  }),
+  '22001': (field) => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: field
+      ? `O valor informado para o campo ${field} é muito longo.`
+      : 'Um ou mais valores informados são muito longos.',
+  }),
+  '22003': (field) => ({
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: field
+      ? `O valor informado para o campo ${field} está fora do intervalo permitido.`
+      : 'Um ou mais valores numéricos estão fora do intervalo permitido.',
+  }),
+};
+
+function extractFieldFromDetail(detail?: string): string | undefined {
+  if (!detail) {
+    return undefined;
+  }
+
+  const keyMatch = detail.match(/Key \(([^)]+)\)=/);
+  if (keyMatch) {
+    return keyMatch[1];
+  }
+
+  const nullColumnMatch = detail.match(/null value in column "([^"]+)"/);
+  if (nullColumnMatch) {
+    return nullColumnMatch[1];
+  }
+
+  return undefined;
+}
+
+function getPostgresDriverError(
+  exception: QueryFailedError,
+): PostgresDriverError | undefined {
+  const driverError = exception.driverError;
+
+  if (!driverError || typeof driverError !== 'object') {
+    return undefined;
+  }
+
+  return driverError;
+}
+
+function formatQueryFailedError(
+  exception: QueryFailedError,
+): FormattedTypeOrmError {
+  const driverError = getPostgresDriverError(exception);
+  const field =
+    driverError?.column ?? extractFieldFromDetail(driverError?.detail);
+  const mapped = driverError?.code
+    ? POSTGRES_ERROR_MESSAGES[driverError.code]?.(field)
+    : undefined;
+
+  if (mapped) {
+    return {
+      statusCode: mapped.statusCode,
+      message: mapped.message,
+      errors: field ? [{ field, message: mapped.message }] : undefined,
+    };
+  }
+
+  return {
+    statusCode: HttpStatus.BAD_REQUEST,
+    message: 'Não foi possível processar a operação no banco de dados.',
+  };
+}
+
+function formatEntityNotFoundError(): FormattedTypeOrmError {
+  return {
+    statusCode: HttpStatus.NOT_FOUND,
+    message: 'Registro não encontrado.',
+  };
+}
+
+function formatOptimisticLockError(): FormattedTypeOrmError {
+  return {
+    statusCode: HttpStatus.CONFLICT,
+    message:
+      'O registro foi alterado por outra operação. Atualize os dados e tente novamente.',
+  };
+}
+
+function formatGenericTypeOrmError(
+  exception: TypeORMError,
+): FormattedTypeOrmError {
+  return {
+    statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+    message: exception.message || 'Erro interno ao acessar o banco de dados.',
+  };
+}
+
+export function formatTypeOrmError(
+  exception: TypeORMError,
+): FormattedTypeOrmError {
+  if (exception instanceof QueryFailedError) {
+    return formatQueryFailedError(exception);
+  }
+
+  if (exception instanceof EntityNotFoundError) {
+    return formatEntityNotFoundError();
+  }
+
+  if (exception instanceof OptimisticLockVersionMismatchError) {
+    return formatOptimisticLockError();
+  }
+
+  return formatGenericTypeOrmError(exception);
+}
+
+export function isTypeOrmError(exception: Error): exception is TypeORMError {
+  return exception instanceof TypeORMError;
+}