@koalarx/nest 3.1.49 → 4.0.1

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

@@ -0,0 +1,201 @@
+import { ZodError } from 'zod';
+
+type ZodValidationIssue = ZodError['issues'][number];
+
+export interface ZodFieldError {
+  field: string;
+  message: string;
+}
+
+export interface FormattedZodError {
+  message: string;
+  errors: ZodFieldError[];
+}
+
+const TYPE_LABELS: Record<string, string> = {
+  string: 'texto',
+  number: 'número',
+  int: 'número inteiro',
+  boolean: 'booleano',
+  array: 'lista',
+  object: 'objeto',
+  undefined: 'indefinido',
+  null: 'nulo',
+};
+
+function formatFieldPath(path: PropertyKey[]): string {
+  return path.reduce<string>((acc, segment) => {
+    if (typeof segment === 'number') {
+      return `${acc}[${segment}]`;
+    }
+
+    const segmentLabel = String(segment);
+
+    return acc ? `${acc}.${segmentLabel}` : segmentLabel;
+  }, '');
+}
+
+function formatFieldLabel(field: string): string {
+  return field || 'valor';
+}
+
+function getExpectedTypeLabel(expected: string): string {
+  return TYPE_LABELS[expected] ?? expected;
+}
+
+function getReceivedTypeLabel(message: string): string | undefined {
+  const match = message.match(/received (\w+)/i);
+  if (!match) {
+    return undefined;
+  }
+
+  return getExpectedTypeLabel(match[1].toLowerCase());
+}
+
+function formatLimitValue(value: number | bigint | undefined): number {
+  if (typeof value === 'bigint') {
+    return Number(value);
+  }
+
+  return value ?? 0;
+}
+
+function formatTooSmallMessage(
+  fieldLabel: string,
+  issue: ZodValidationIssue,
+): string {
+  if (issue.code !== 'too_small') {
+    return `O campo ${fieldLabel} possui um valor muito pequeno.`;
+  }
+
+  const minimum = formatLimitValue(issue.minimum);
+
+  if (issue.origin === 'string') {
+    if (minimum <= 1) {
+      return `O campo ${fieldLabel} é obrigatório.`;
+    }
+
+    return `O campo ${fieldLabel} deve ter no mínimo ${minimum} caracteres.`;
+  }
+
+  if (issue.origin === 'number') {
+    if (issue.inclusive === false) {
+      return `O campo ${fieldLabel} deve ser maior que ${minimum}.`;
+    }
+
+    return `O campo ${fieldLabel} deve ser no mínimo ${minimum}.`;
+  }
+
+  if (issue.origin === 'array') {
+    if (minimum <= 1) {
+      return `O campo ${fieldLabel} deve conter ao menos um item.`;
+    }
+
+    return `O campo ${fieldLabel} deve conter no mínimo ${minimum} itens.`;
+  }
+
+  return `O campo ${fieldLabel} possui um valor muito pequeno.`;
+}
+
+function formatTooBigMessage(
+  fieldLabel: string,
+  issue: ZodValidationIssue,
+): string {
+  if (issue.code !== 'too_big') {
+    return `O campo ${fieldLabel} possui um valor muito grande.`;
+  }
+
+  const maximum = formatLimitValue(issue.maximum);
+
+  if (issue.origin === 'string') {
+    return `O campo ${fieldLabel} deve ter no máximo ${maximum} caracteres.`;
+  }
+
+  if (issue.origin === 'number') {
+    return `O campo ${fieldLabel} deve ser no máximo ${maximum}.`;
+  }
+
+  if (issue.origin === 'array') {
+    return `O campo ${fieldLabel} deve conter no máximo ${maximum} itens.`;
+  }
+
+  return `O campo ${fieldLabel} possui um valor muito grande.`;
+}
+
+function formatInvalidTypeMessage(
+  fieldLabel: string,
+  issue: ZodValidationIssue,
+): string {
+  if (issue.code !== 'invalid_type') {
+    return `O campo ${fieldLabel} possui um valor inválido.`;
+  }
+
+  const expected = issue.expected
+    ? getExpectedTypeLabel(issue.expected)
+    : 'válido';
+  const received = getReceivedTypeLabel(issue.message);
+
+  if (issue.expected === 'undefined' || received === 'indefinido') {
+    return `O campo ${fieldLabel} é obrigatório.`;
+  }
+
+  if (received) {
+    return `O campo ${fieldLabel} deve ser ${expected}, mas foi recebido ${received}.`;
+  }
+
+  return `O campo ${fieldLabel} deve ser ${expected}.`;
+}
+
+function formatInvalidFormatMessage(
+  fieldLabel: string,
+  issue: ZodValidationIssue,
+): string {
+  if (issue.code !== 'invalid_format') {
+    return `O campo ${fieldLabel} está em um formato inválido.`;
+  }
+
+  switch (issue.format) {
+    case 'email':
+      return `O campo ${fieldLabel} deve ser um e-mail válido.`;
+    case 'uuid':
+      return `O campo ${fieldLabel} deve ser um UUID válido.`;
+    case 'url':
+      return `O campo ${fieldLabel} deve ser uma URL válida.`;
+    default:
+      return `O campo ${fieldLabel} está em um formato inválido.`;
+  }
+}
+
+function formatIssueMessage(issue: ZodValidationIssue): string {
+  const field = formatFieldPath(issue.path);
+  const fieldLabel = formatFieldLabel(field);
+
+  switch (issue.code) {
+    case 'too_small':
+      return formatTooSmallMessage(fieldLabel, issue);
+    case 'too_big':
+      return formatTooBigMessage(fieldLabel, issue);
+    case 'invalid_type':
+      return formatInvalidTypeMessage(fieldLabel, issue);
+    case 'invalid_format':
+      return formatInvalidFormatMessage(fieldLabel, issue);
+    case 'invalid_value':
+      return `O campo ${fieldLabel} possui um valor inválido.`;
+    default:
+      return `O campo ${fieldLabel} possui um valor inválido.`;
+  }
+}
+
+export function formatZodError(error: ZodError): FormattedZodError {
+  const errors = error.issues.map((issue) => ({
+    field: formatFieldPath(issue.path),
+    message: formatIssueMessage(issue),
+  }));
+
+  const message =
+    errors.length === 1
+      ? errors[0].message
+      : `Foram encontrados ${errors.length} erros de validação.`;
+
+  return { message, errors };
+}

package/koala-nest/src/core/utils/hash-password.ts

@@ -0,0 +1,5 @@
+import { hash } from 'bcrypt';
+
+export function hashPassword(password: string): Promise<string> {
+  return hash(password, 6);
+}

package/koala-nest/src/core/utils/icomparable.ts

@@ -0,0 +1 @@
+export type IComparableId = string | number;

package/koala-nest/src/core/utils/is-provider-registered.ts

@@ -0,0 +1,40 @@
+import { INestApplication, type InjectionToken } from '@nestjs/common';
+import { ModulesContainer } from '@nestjs/core';
+
+export function isProviderRegistered(
+  app: INestApplication,
+  token: InjectionToken,
+): boolean {
+  const modulesContainer = app.get(ModulesContainer);
+
+  return [...modulesContainer.values()].some(
+    (module) => module?.providers?.has(token) ?? false,
+  );
+}
+
+export function resolveAppProvider<T>(
+  app: INestApplication,
+  token: InjectionToken,
+): T | undefined {
+  try {
+    const resolved = app.get<T>(token, { strict: false });
+
+    if (resolved) {
+      return resolved;
+    }
+  } catch {
+    // provider ausente neste contexto
+  }
+
+  const modulesContainer = app.get(ModulesContainer);
+
+  for (const moduleRef of modulesContainer.values()) {
+    const provider = moduleRef.providers.get(token);
+
+    if (provider?.instance) {
+      return provider.instance as T;
+    }
+  }
+
+  return undefined;
+}

package/koala-nest/src/core/utils/name-to-login.ts

@@ -0,0 +1,25 @@
+import { IUserRepository } from '@/domain/repositories/iuser.repository';
+import { randomString } from '@koalarx/utils';
+
+export async function nameToLogin(
+  value: string,
+  userRepository: IUserRepository,
+) {
+  const firstNameAndLast = value.split(/(\s).+\s/).join('');
+  const username = firstNameAndLast.toLowerCase().replace(/ /g, '.');
+
+  let usernameExists = false;
+  let result = username;
+
+  do {
+    usernameExists = await userRepository
+      .getByLogin(result)
+      .then((user) => !!user);
+
+    if (usernameExists) {
+      result = username.concat('#').concat(randomString(4, { numbers: true }));
+    }
+  } while (usernameExists);
+
+  return result;
+}

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

@@ -0,0 +1,7 @@
+import { ICacheService } from '@/domain/common/icache.service';
+
+export const PERSON_LIST_CACHE_PREFIX = 'person:list';
+
+export function invalidatePersonListCache(cache: ICacheService) {
+  return cache.invalidateByPrefix(PERSON_LIST_CACHE_PREFIX);
+}

package/koala-nest/src/core/utils/report-error.ts

@@ -0,0 +1,18 @@
+import packageJson from '../../../package.json';
+import { ILoggingService } from '@/domain/common/ilogging.service';
+
+export async function reportErrorToLogging(
+  loggingService: ILoggingService,
+  error: Error,
+  loggedUsername?: string,
+): Promise<void> {
+  try {
+    await loggingService.report({
+      error,
+      packageName: packageJson.name,
+      loggedUsername: loggedUsername ?? 'system',
+    });
+  } catch {
+    console.error(error);
+  }
+}

package/koala-nest/src/core/utils/resolve-api-host.ts

@@ -0,0 +1,8 @@
+export function resolveApiHost(host: string | undefined, port: number): string {
+  const rawHost = host ?? `http://localhost:${port}`;
+  const normalized = rawHost.replace(/\/$/, '');
+  const hasProtocol =
+    normalized.startsWith('http://') || normalized.startsWith('https://');
+
+  return hasProtocol ? normalized : `http://${normalized}`;
+}

package/koala-nest/src/core/utils/time.constants.ts

@@ -0,0 +1,5 @@
+/** Conversão de minutos para milissegundos. */
+export const MINUTES_TO_MS = 60 * 1000;
+
+/** Conversão de milissegundos para segundos. */
+export const MS_TO_SECONDS = 1000;

package/koala-nest/src/domain/auth/dtos/auth-provider-config.dto.ts

@@ -0,0 +1,12 @@
+import { ObjectClass } from '@/core/base/object-class';
+
+export class AuthProviderConfigDto extends ObjectClass<AuthProviderConfigDto> {
+  authorizationUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+  clientId: string;
+  clientSecret: string;
+  state: string;
+  redirectUri: string;
+  scope: string;
+}

package/koala-nest/src/domain/auth/dtos/oauth-user-info.dto.ts

@@ -0,0 +1,9 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { ObjectClass } from '@/core/base/object-class';
+
+export class OAuthUserInfoDto extends ObjectClass<OAuthUserInfoDto> {
+  login: string;
+  email: string;
+  name?: string;
+  profile?: AuthProfile;
+}

package/koala-nest/src/domain/auth/services/iauth.service.ts

@@ -0,0 +1,37 @@
+import { JwtClaims } from '@/core/auth/jwt-claims';
+import { AuthProviderConfigDto } from '../dtos/auth-provider-config.dto';
+import { OAuthUserInfoDto } from '../dtos/oauth-user-info.dto';
+
+export abstract class IOAuth2Service {
+  abstract providerConfig(provider: string): Promise<AuthProviderConfigDto>;
+  abstract authLink(provider: string, redirectUri?: string): Promise<string>;
+  abstract resolveScalarOAuthFlow(provider: string): Promise<{
+    authorizationUrl: string;
+    redirectUri: string;
+    clientId: string;
+    clientSecret: string;
+  }>;
+  abstract exchangeCode(
+    provider: string,
+    code: string,
+    state: string,
+    redirectUri?: string,
+  ): Promise<OAuthUserInfoDto>;
+  /** Troca authorization code do Scalar (sem validar state — o IdP já validou). */
+  abstract exchangeScalarCode(
+    provider: string,
+    code: string,
+    redirectUri?: string,
+  ): Promise<OAuthUserInfoDto>;
+}
+
+export abstract class IJwtTokenService {
+  abstract signAccessToken(claims: JwtClaims): string;
+  abstract signRefreshToken(claims: JwtClaims): string;
+  abstract signTokenPair(claims: JwtClaims): {
+    accessToken: string;
+    access_token: string;
+    refreshToken: string;
+    refresh_token: string;
+  };
+}

package/koala-nest/src/domain/common/icache.service.ts

@@ -0,0 +1,11 @@
+export abstract class ICacheService {
+  abstract get(key: string): Promise<string | null>;
+  abstract set(key: string, value: string, ttl?: number): Promise<void>;
+  abstract setIfNotExists(
+    key: string,
+    value: string,
+    ttl: number,
+  ): Promise<boolean>;
+  abstract invalidate(key: string): Promise<void>;
+  abstract invalidateByPrefix(prefix: string): Promise<void>;
+}

package/koala-nest/src/domain/common/ilogging.service.ts

@@ -0,0 +1,9 @@
+export interface LoggingReportProps {
+  loggedUsername: string;
+  packageName: string;
+  error: Error;
+}
+
+export abstract class ILoggingService {
+  abstract report(data: LoggingReportProps): Promise<void>;
+}

package/koala-nest/src/domain/common/ired-lock.service.ts

@@ -0,0 +1,4 @@
+export abstract class IRedLockService {
+  abstract acquiredLock(key: string, ttlSecondsLock: number): Promise<boolean>;
+  abstract releaseLock(key: string): Promise<void>;
+}

package/koala-nest/src/domain/dtos/logged-user-info.dto.ts

@@ -0,0 +1,30 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { AuthenticatedUser } from '@/core/auth/jwt-claims';
+import { AutoMap } from '@/core/tools/mapping';
+
+export class LoggedUserInfoDto {
+  @AutoMap()
+  sub: string;
+
+  @AutoMap()
+  name?: string;
+
+  @AutoMap()
+  profile?: AuthProfile;
+
+  @AutoMap()
+  login?: string;
+
+  @AutoMap()
+  email?: string;
+
+  static fromAuthenticatedUser(user: AuthenticatedUser): LoggedUserInfoDto {
+    return Object.assign(new LoggedUserInfoDto(), {
+      sub: user.sub,
+      name: user.name,
+      profile: user.profile,
+      login: user.login,
+      email: user.email,
+    });
+  }
+}

package/koala-nest/src/domain/dtos/pagination.dto.ts

@@ -0,0 +1,35 @@
+import { QUERY_FILTER_PARAMS } from '@/core/constants/query-params';
+import { AutoMap } from '@/core/tools/mapping';
+import type { QueryDirectionType } from '@/core/types';
+
+export class PaginationDto {
+  @AutoMap()
+  page?: number = 0;
+
+  @AutoMap()
+  limit?: number = QUERY_FILTER_PARAMS.limit;
+
+  @AutoMap()
+  orderBy?: string = '';
+
+  @AutoMap()
+  direction?: QueryDirectionType = 'asc';
+
+  skip() {
+    return (this.limit ?? 0) * (this.page ?? QUERY_FILTER_PARAMS.page);
+  }
+
+  generateOrderBy() {
+    if (this.orderBy) {
+      const orderByField = this.orderBy.split('.');
+      return orderByField.reduceRight(
+        (acc, item, index) => ({
+          [item]: index === orderByField.length - 1 ? this.direction : acc,
+        }),
+        {},
+      );
+    }
+
+    return undefined;
+  }
+}

package/koala-nest/src/domain/dtos/person-query.dto.ts

@@ -0,0 +1,10 @@
+import { AutoMap } from '@/core/tools/mapping';
+import { PaginationDto } from './pagination.dto';
+
+export class PersonQueryDto extends PaginationDto {
+  @AutoMap()
+  name?: string;
+
+  @AutoMap()
+  active?: boolean;
+}

package/koala-nest/src/domain/entities/person/person-address.ts

@@ -0,0 +1,14 @@
+import { EntityBase } from '@/core/base/entity.base';
+import { AutoMap } from '@/core/tools/mapping';
+import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity('person_address')
+export class PersonAddress extends EntityBase<PersonAddress> {
+  @PrimaryGeneratedColumn()
+  @AutoMap()
+  id: number;
+
+  @Column()
+  @AutoMap()
+  address: string;
+}

package/koala-nest/src/domain/entities/person/person-contact.ts

@@ -0,0 +1,28 @@
+import { AutoMap } from '@/core/tools/mapping';
+import {
+  Column,
+  Entity,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  type Relation,
+} from 'typeorm';
+import type { Person } from './person';
+import { EntityBase } from '@/core/base/entity.base';
+
+@Entity('person_contact')
+export class PersonContact extends EntityBase<PersonContact> {
+  @PrimaryGeneratedColumn()
+  @AutoMap()
+  id: number;
+
+  @Column()
+  @AutoMap()
+  contact: string;
+
+  @ManyToOne('Person', 'contacts', {
+    onDelete: 'CASCADE',
+    orphanedRowAction: 'delete',
+  })
+  @AutoMap()
+  person: Relation<Person>;
+}

package/koala-nest/src/domain/entities/person/person.ts

@@ -0,0 +1,44 @@
+import { AutoMap } from '@/core/tools/mapping';
+import {
+  Column,
+  Entity,
+  JoinColumn,
+  OneToMany,
+  OneToOne,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+import { PersonAddress } from './person-address';
+import { PersonContact } from './person-contact';
+import { EntityBase } from '@/core/base/entity.base';
+
+@Entity('person')
+export class Person extends EntityBase<Person> {
+  @PrimaryGeneratedColumn()
+  @AutoMap()
+  id: number;
+
+  @Column()
+  @AutoMap()
+  name: string;
+
+  @Column({ default: true })
+  @AutoMap()
+  active: boolean;
+
+  @OneToOne(() => PersonAddress, {
+    cascade: true,
+    eager: true,
+    onDelete: 'CASCADE',
+  })
+  @JoinColumn()
+  @AutoMap()
+  address: PersonAddress;
+
+  @OneToMany(() => PersonContact, (contact) => contact.person, {
+    cascade: true,
+    eager: true,
+    onDelete: 'CASCADE',
+  })
+  @AutoMap({ type: () => PersonContact })
+  contacts: PersonContact[];
+}

package/koala-nest/src/domain/entities/user/enums/user-status.enum.ts

@@ -0,0 +1,6 @@
+export enum UserStatus {
+  inactive = 'inactive',
+  active = 'active',
+  blocked = 'blocked',
+  pending = 'pending',
+}

package/koala-nest/src/domain/entities/user/user.ts

@@ -0,0 +1,49 @@
+import { AuthProfile } from '@/core/auth/auth-profile.enum';
+import { EntityBase } from '@/core/base/entity.base';
+import { AutoMap } from '@/core/tools/mapping';
+import { UserStatus } from '@/domain/entities/user/enums/user-status.enum';
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  PrimaryGeneratedColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+
+@Entity('users')
+export class User extends EntityBase<User> {
+  @PrimaryGeneratedColumn('uuid')
+  @AutoMap()
+  id: string;
+
+  @Column()
+  @AutoMap()
+  name: string;
+
+  @Column({ unique: true })
+  @AutoMap()
+  email: string;
+
+  @Column({ unique: true })
+  @AutoMap()
+  login: string;
+
+  @Column()
+  password: string;
+
+  @Column({ type: 'varchar' })
+  @AutoMap()
+  profile: AuthProfile;
+
+  @Column({ type: 'varchar', default: UserStatus.active })
+  @AutoMap()
+  status: UserStatus;
+
+  @CreateDateColumn()
+  @AutoMap()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  @AutoMap()
+  updatedAt: Date;
+}

package/koala-nest/src/domain/repositories/iperson.repository.ts

@@ -0,0 +1,10 @@
+import { ListResponse } from '@/core/types';
+import { PersonQueryDto } from '../dtos/person-query.dto';
+import { Person } from '../entities/person/person';
+
+export abstract class IPersonRepository {
+  abstract findMany(query: PersonQueryDto): Promise<ListResponse<Person>>;
+  abstract findById(id: number): Promise<Person | null>;
+  abstract save(person: Person): Promise<Person>;
+  abstract delete(person: Person): Promise<void>;
+}

package/koala-nest/src/domain/repositories/iuser.repository.ts

@@ -0,0 +1,8 @@
+import { User } from '@/domain/entities/user/user';
+
+export abstract class IUserRepository {
+  abstract getById(id: string): Promise<User | null>;
+  abstract getByEmail(email: string): Promise<User | null>;
+  abstract getByLogin(login: string): Promise<User | null>;
+  abstract save(user: User): Promise<User>;
+}

package/koala-nest/src/domain/services/ilogged-user-info.service.ts

@@ -0,0 +1,5 @@
+import { LoggedUserInfoDto } from '@/domain/dtos/logged-user-info.dto';
+
+export abstract class ILoggedUserInfoService {
+  abstract getUser(): LoggedUserInfoDto;
+}