@koalarx/nest 3.1.50 → 4.0.1

package/koala-nest/src/core/auth/parse-jwt-expires-in.ts

@@ -0,0 +1,30 @@
+/** Converte `expiresIn` do @nestjs/jwt (ex.: `15m`, `7d`) para segundos. */
+export function parseJwtExpiresInToSeconds(expiresIn: string): number {
+  if (/^\d+$/.test(expiresIn)) {
+    return parseInt(expiresIn, 10);
+  }
+
+  const match = expiresIn.match(/^(\d+)(ms|s|m|h|d)$/);
+
+  if (!match) {
+    throw new Error(`JWT expiresIn inválido: ${expiresIn}`);
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case 'ms':
+      return value / 1000;
+    case 's':
+      return value;
+    case 'm':
+      return value * 60;
+    case 'h':
+      return value * 3600;
+    case 'd':
+      return value * 86400;
+    default:
+      return value;
+  }
+}

package/koala-nest/src/core/auth/parse-oauth2-provider-env.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+const OAUTH2_ENV_FIELD = {
+  DOMAIN: 'domain',
+  CLIENT_ID: 'clientId',
+  CLIENT_SECRET: 'clientSecret',
+  SCOPE: 'scope',
+  REDIRECT_PATH: 'redirectPath',
+  AUTHORIZATION_URL: 'authorizationUrl',
+  TOKEN_URL: 'tokenUrl',
+  USERINFO_URL: 'userInfoUrl',
+} as const;
+
+const OAUTH2_ENV_PATTERN =
+  /^OAUTH2_([A-Z0-9_]+)_(DOMAIN|CLIENT_ID|CLIENT_SECRET|SCOPE|REDIRECT_PATH|AUTHORIZATION_URL|TOKEN_URL|USERINFO_URL)$/;
+
+export const oauth2ProviderEnvEntrySchema = z.object({
+  domain: z.string().optional(),
+  clientId: z.string().optional(),
+  clientSecret: z.string().optional(),
+  scope: z.string().optional(),
+  redirectPath: z.string().optional(),
+  authorizationUrl: z.string().optional(),
+  tokenUrl: z.string().optional(),
+  userInfoUrl: z.string().optional(),
+});
+
+export type OAuth2ProviderEnvEntry = z.infer<
+  typeof oauth2ProviderEnvEntrySchema
+>;
+
+export function parseOAuth2ProviderEnv(
+  config: Record<string, unknown>,
+): Record<string, OAuth2ProviderEnvEntry> {
+  const providers: Record<string, OAuth2ProviderEnvEntry> = {};
+
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value !== 'string' || !value) {
+      continue;
+    }
+
+    const match = key.match(OAUTH2_ENV_PATTERN);
+
+    if (!match) {
+      continue;
+    }
+
+    const providerKey = match[1].toLowerCase();
+    const field = OAUTH2_ENV_FIELD[match[2] as keyof typeof OAUTH2_ENV_FIELD];
+
+    providers[providerKey] ??= {};
+    providers[providerKey][field] = value;
+  }
+
+  return providers;
+}

package/koala-nest/src/core/auth/resolve-refresh-token.ts

@@ -0,0 +1,40 @@
+import { AuthHttp } from '@/core/auth/auth.constants';
+import { isAuthRefreshRoute } from '@/core/auth/auth-routes';
+
+type RefreshTokenRequest = {
+  cookies?: Record<string, string>;
+  body?: Record<string, string>;
+  headers: Record<string, string | string[] | undefined>;
+};
+
+export function resolveRefreshTokenFromRequest(
+  request: RefreshTokenRequest,
+): string | undefined {
+  const authorization = request.headers.authorization;
+
+  if (typeof authorization === 'string') {
+    if (authorization.startsWith(AuthHttp.BEARER_PREFIX)) {
+      return authorization.slice(AuthHttp.BEARER_PREFIX.length).trim();
+    }
+  }
+
+  return (
+    request.cookies?.[AuthHttp.REFRESH_TOKEN_COOKIE] ??
+    request.body?.refresh_token ??
+    request.body?.refreshToken
+  );
+}
+
+export function applyRefreshTokenForRefreshRoute(
+  request: RefreshTokenRequest & { url?: string },
+): void {
+  if (!isAuthRefreshRoute(request.url)) {
+    return;
+  }
+
+  const refreshToken = resolveRefreshTokenFromRequest(request);
+
+  if (refreshToken) {
+    request.headers.authorization = `${AuthHttp.BEARER_PREFIX}${refreshToken}`;
+  }
+}

package/koala-nest/src/core/background-services/cron-service/cron-job.handler.base.ts

@@ -0,0 +1,65 @@
+import { ILoggingService } from '@/domain/common/ilogging.service';
+import { IRedLockService } from '@/domain/common/ired-lock.service';
+import { cronExpressionToBoolean } from '@/core/utils/cron-expression-to-boolean';
+import { DEFAULT_CRON_POLL_MINUTES } from '@/core/constants/cron.constants';
+import { MINUTES_TO_MS, MS_TO_SECONDS } from '@/core/utils/time.constants';
+import { delay } from '@koalarx/utils/KlDelay';
+import { reportErrorToLogging } from '@/core/utils/report-error';
+
+export interface CronJobSettings {
+  isActive: boolean;
+  timeInMinutes: number;
+}
+
+export function cronJobSettings(
+  cronExpression: string,
+  timeInMinutes = DEFAULT_CRON_POLL_MINUTES,
+): CronJobSettings {
+  return {
+    isActive: cronExpressionToBoolean(cronExpression),
+    timeInMinutes,
+  };
+}
+
+export abstract class CronJobHandlerBase {
+  constructor(
+    private readonly redlockService: IRedLockService,
+    private readonly loggingService: ILoggingService,
+  ) {}
+
+  protected abstract run(): Promise<void>;
+
+  protected abstract settings(): Promise<CronJobSettings>;
+
+  async start(): Promise<void> {
+    const name = this.constructor.name;
+
+    while (true) {
+      const settings = await this.settings();
+      const timeout = settings.timeInMinutes * MINUTES_TO_MS;
+
+      if (settings.isActive) {
+        const ttlSecondsLock = timeout / MS_TO_SECONDS;
+        const acquiredLock = await this.redlockService.acquiredLock(
+          name,
+          ttlSecondsLock,
+        );
+
+        if (acquiredLock) {
+          try {
+            await this.run();
+          } catch (error) {
+            const reportError =
+              error instanceof Error ? error : new Error(String(error));
+
+            await reportErrorToLogging(this.loggingService, reportError);
+          } finally {
+            await this.redlockService.releaseLock(name);
+          }
+        }
+      }
+
+      await delay(timeout);
+    }
+  }
+}

package/koala-nest/src/core/background-services/event-service/event-class.ts

@@ -0,0 +1,5 @@
+export abstract class EventClass<TEntity = unknown> {
+  ocurredAt: Date = new Date();
+
+  constructor(public data?: TEntity) {}
+}

package/koala-nest/src/core/background-services/event-service/event-handler.base.ts

@@ -0,0 +1,17 @@
+import { Type } from '@nestjs/common';
+import { EventClass } from './event-class';
+import { EventQueue } from './event-queue';
+
+export abstract class EventHandlerBase<TEvent extends EventClass = EventClass> {
+  constructor(public readonly event: Type<TEvent>) {}
+
+  abstract handleEvent(event: TEvent): Promise<void>;
+
+  setupSubscriptions() {
+    EventQueue.register(
+      this.handleEvent.bind(this),
+      this.constructor.name,
+      this.event.name,
+    );
+  }
+}

package/koala-nest/src/core/background-services/event-service/event-job.ts

@@ -0,0 +1,31 @@
+import { Type } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+import { EventClass } from './event-class';
+import { EventHandlerBase } from './event-handler.base';
+import { EventQueue } from './event-queue';
+
+export abstract class EventJob<TEntity> {
+  private _eventQueue: EventClass<TEntity>[] = [];
+
+  _id = randomUUID();
+
+  /**
+   * Lista os handlers que processam eventos deste agregado.
+   * Usado pelo `EventQueue.dispatch` para rotear eventos enfileirados.
+   * Registre as mesmas classes em `JobsModule.register({ eventHandlers })`.
+   */
+  abstract defineHandlers(): Array<Type<EventHandlerBase>>;
+
+  get eventQueue(): EventClass<TEntity>[] {
+    return this._eventQueue;
+  }
+
+  clearQueue() {
+    this._eventQueue = [];
+  }
+
+  addEvent(event: EventClass<TEntity>): void {
+    this._eventQueue.push(event);
+    EventQueue.markAggregateForDispatch(this);
+  }
+}

package/koala-nest/src/core/background-services/event-service/event-queue.ts

@@ -0,0 +1,107 @@
+import { IComparableId } from '@/core/utils/icomparable';
+import { EventClass } from './event-class';
+import { EventJob } from './event-job';
+
+type EventJobCallback = (event: EventClass) => void;
+
+interface EventQueueJobItem {
+  eventClassName: string;
+  callback: EventJobCallback;
+}
+
+export class EventQueue {
+  private static handlersMap: Record<string, EventQueueJobItem[]> = {};
+
+  private static markedAggregates: EventJob<unknown>[] = [];
+
+  private static dispatch(event: EventClass) {
+    const eventJobHandlers = this.markedAggregates.find((aggregate) =>
+      aggregate.eventQueue.find((queuedEvent) => queuedEvent === event),
+    );
+
+    const eventHandler = Object.keys(this.handlersMap).find((handlerName) =>
+      eventJobHandlers
+        ?.defineHandlers()
+        .find(
+          (handler) =>
+            handler.name === handlerName &&
+            this.handlersMap[handler.name].some(
+              (job) => job.eventClassName === event.constructor.name,
+            ),
+        ),
+    );
+
+    if (eventHandler) {
+      const jobs = this.handlersMap[eventHandler];
+
+      for (const job of jobs) {
+        job.callback(event);
+      }
+    }
+  }
+
+  private static dispatchAggregateEvents(aggregate: EventJob<unknown>) {
+    aggregate.eventQueue.forEach((event) => this.dispatch(event));
+  }
+
+  private static removeAggregateFromMarkedDispatchList(
+    aggregate: EventJob<unknown>,
+  ) {
+    const index = this.markedAggregates.findIndex(
+      (item) => item._id === aggregate._id,
+    );
+
+    this.markedAggregates.splice(index, 1);
+  }
+
+  static markAggregateForDispatch(aggregate: EventJob<unknown>) {
+    const aggregateFound = !!this.findMarkedAggregateByID(aggregate._id);
+
+    if (!aggregateFound) {
+      this.markedAggregates.push(aggregate);
+    }
+  }
+
+  static dispatchEventsForAggregate(id: IComparableId) {
+    const aggregate = this.findMarkedAggregateByID(id);
+
+    if (aggregate) {
+      this.dispatchAggregateEvents(aggregate);
+      aggregate.clearQueue();
+      this.removeAggregateFromMarkedDispatchList(aggregate);
+    }
+  }
+
+  static register(
+    callback: EventJobCallback,
+    handlerClassName: string,
+    eventClassName: string,
+  ) {
+    if (!(handlerClassName in this.handlersMap)) {
+      this.handlersMap[handlerClassName] = [];
+    }
+
+    this.handlersMap[handlerClassName].push({
+      eventClassName,
+      callback,
+    });
+  }
+
+  static clearHandlers() {
+    this.handlersMap = {};
+  }
+
+  static clearMarkedAggregates() {
+    this.markedAggregates = [];
+  }
+
+  static findMarkedAggregateByID(
+    id: IComparableId,
+  ): EventJob<unknown> | undefined {
+    return this.markedAggregates.find((aggregate) => aggregate._id === id);
+  }
+
+  static getMarkedAggregates() {
+    return this.markedAggregates;
+  }
+}

package/koala-nest/src/core/base/entity.base.ts

@@ -0,0 +1,3 @@
+import { ObjectClass } from './object-class';
+
+export abstract class EntityBase<T> extends ObjectClass<T> {}

package/koala-nest/src/core/base/object-class.ts

@@ -0,0 +1,14 @@
+export type ObjectClassProps<T> = {
+  [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+
+export abstract class ObjectClass<T = object> {
+  declare protected readonly _propsType?: ObjectClassProps<T>;
+
+  static from<This extends new () => object>(
+    this: This,
+    props: ObjectClassProps<InstanceType<This>>,
+  ): InstanceType<This> {
+    return Object.assign(new this(), props) as InstanceType<This>;
+  }
+}

package/koala-nest/src/core/constants/cache.constants.ts

@@ -0,0 +1,16 @@
+/** Prefixos e chaves do cache distribuído / em memória. */
+export const CacheKeyPrefix = {
+  OAUTH2_STATE: 'oauth2:state:',
+  RED_LOCK: 'redLock:',
+} as const;
+
+/** TTLs em segundos para entradas de cache. */
+export const CacheTtlSeconds = {
+  /** Estado OAuth2 durante o fluxo de autorização (10 minutos). */
+  OAUTH2_STATE: 10 * 60,
+  /** Listagem paginada de Person (2 minutos). */
+  PERSON_LIST: 120,
+} as const;
+
+/** TTL padrão do RedLock quando não derivado do cron (segundos). */
+export const DEFAULT_RED_LOCK_TTL_SECONDS = 30;

package/koala-nest/src/core/constants/cron.constants.ts

@@ -0,0 +1,14 @@
+/** Expressões cron prontas (segundo = 6 campos). */
+export const CronExpression = {
+  /** A cada 15 segundos — intervalo didático para o template de exemplo. */
+  EVERY_15_SECONDS: '*/15 * * * * *',
+  /** A cada minuto. */
+  EVERY_MINUTE: '0 */1 * * * *',
+  /** A cada 5 minutos. */
+  EVERY_FIVE_MINUTES: '0 */5 * * * *',
+  /** A cada hora (minuto 0). */
+  HOURLY: '0 0 * * * *',
+} as const;
+
+/** Intervalo padrão de poll dos cron jobs (minutos). */
+export const DEFAULT_CRON_POLL_MINUTES = 0.01;

package/koala-nest/src/core/constants/query-params.ts

@@ -0,0 +1,7 @@
+import { QueryDirectionType } from '../types';
+
+export const QUERY_FILTER_PARAMS = {
+  direction: 'asc' as QueryDirectionType,
+  page: 0,
+  limit: 30,
+};

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

@@ -0,0 +1,42 @@
+import {
+  oauth2ProviderEnvEntrySchema,
+  parseOAuth2ProviderEnv,
+  type OAuth2ProviderEnvEntry,
+} from '@/core/auth/parse-oauth2-provider-env';
+import { envBooleanSchema } from '@/core/schemas';
+import { z } from 'zod';
+
+export const envSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['test', 'develop', 'staging', 'production']),
+  DATABASE_URL: z.string(),
+  REDIS_CONNECTION_STRING: z.string().optional(),
+  CACHE_KEY_PREFIX: z.string().optional(),
+  CRON_JOBS_ENABLED: envBooleanSchema(false),
+  BOOTSTRAP_DELAY_MS: z.coerce.number().default(0),
+  JWT_PRIVATE_KEY: z.string().optional(),
+  JWT_PUBLIC_KEY: z.string().optional(),
+  JWT_ACCESS_TOKEN_EXPIRES_IN: z.string().default('15m'),
+  JWT_REFRESH_TOKEN_EXPIRES_IN: z.string().default('7d'),
+  API_HOST: z.string().optional(),
+  OAUTH2_PROVIDERS: z.string().optional(),
+});
+
+export type Env = z.infer<typeof envSchema> & {
+  OAUTH2_PROVIDER_ENV: Record<string, OAuth2ProviderEnvEntry>;
+};
+
+export function validateEnvConfig(config: Record<string, unknown>): Env {
+  const parsed = envSchema.parse(config);
+  const rawProviders = parseOAuth2ProviderEnv(config);
+  const OAUTH2_PROVIDER_ENV: Record<string, OAuth2ProviderEnvEntry> = {};
+
+  for (const [key, entry] of Object.entries(rawProviders)) {
+    OAUTH2_PROVIDER_ENV[key] = oauth2ProviderEnvEntrySchema.parse(entry);
+  }
+
+  return {
+    ...parsed,
+    OAUTH2_PROVIDER_ENV,
+  };
+}

package/koala-nest/src/core/schemas/boolean.schema.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+function parseBoolean(value: unknown) {
+  if (value === 'true' || value === true) {
+    return true;
+  }
+
+  if (value === 'false' || value === false) {
+    return false;
+  }
+
+  return undefined;
+}
+
+export function booleanSchema() {
+  return z.preprocess(parseBoolean, z.boolean().optional());
+}
+
+export function envBooleanSchema(defaultValue = false) {
+  return z.preprocess(
+    (value) => parseBoolean(value) ?? defaultValue,
+    z.boolean(),
+  );
+}

package/koala-nest/src/core/schemas/document-number-mask.ts

@@ -0,0 +1,22 @@
+import { maskCpf, maskCnpj } from '@koalarx/utils/KlString';
+import {
+  isCnpjDocument,
+  isCpfDocument,
+  unmaskDocumentNumber,
+} from '@/core/schemas/document-number.utils';
+
+export function setMaskDocumentNumber(document?: string) {
+  if (!document) {
+    return '';
+  }
+
+  if (isCpfDocument(document)) {
+    return maskCpf(unmaskDocumentNumber(document));
+  }
+
+  if (isCnpjDocument(document)) {
+    return maskCnpj(unmaskDocumentNumber(document));
+  }
+
+  return document;
+}

package/koala-nest/src/core/schemas/document-number.schema.ts

@@ -0,0 +1,21 @@
+import { validateCpf, validateCnpj } from '@koalarx/utils/KlString';
+import {
+  isCnpjDocument,
+  isCpfDocument,
+} from '@/core/schemas/document-number.utils';
+
+export function documentNumberSchema(value: string) {
+  if (value === '' || value === 'undefined' || value === 'null') {
+    return true;
+  }
+
+  if (isCpfDocument(value)) {
+    return validateCpf(value);
+  }
+
+  if (isCnpjDocument(value)) {
+    return validateCnpj(value);
+  }
+
+  return false;
+}

package/koala-nest/src/core/schemas/document-number.utils.ts

@@ -0,0 +1,15 @@
+const DOCUMENT_MASK_PATTERN = /[/.-\s]/gi;
+
+export function unmaskDocumentNumber(value: string): string {
+  return value.replace(DOCUMENT_MASK_PATTERN, '').toUpperCase();
+}
+
+export function isCpfDocument(value: string): boolean {
+  const unmasked = unmaskDocumentNumber(value);
+
+  return unmasked.length === 11 && /^\d{11}$/.test(unmasked);
+}
+
+export function isCnpjDocument(value: string): boolean {
+  return unmaskDocumentNumber(value).length === 14;
+}

package/koala-nest/src/core/schemas/email.schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+export function emailSchema(email?: string, isRequired = false) {
+  if (isRequired && !email) {
+    return false;
+  }
+
+  if (!email) {
+    return true;
+  }
+
+  return z.coerce.string().max(50).pipe(z.email()).safeParse(email).success;
+}

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

@@ -0,0 +1,6 @@
+export { booleanSchema, envBooleanSchema } from './boolean.schema';
+export { documentNumberSchema } from './document-number.schema';
+export { setMaskDocumentNumber } from './document-number-mask';
+export { emailSchema } from './email.schema';
+export { LIST_QUERY_SCHEMA } from './list-query.schema';
+export { nativeEnumSchema } from './native-enum.schema';

package/koala-nest/src/core/schemas/list-query.schema.ts

@@ -0,0 +1,18 @@
+import { QUERY_FILTER_PARAMS } from '@/core/constants/query-params';
+import { z } from 'zod';
+
+export const LIST_QUERY_SCHEMA = z.object({
+  page: z.coerce
+    .number()
+    .transform((value) => {
+      if (value) {
+        return value - 1;
+      }
+
+      return QUERY_FILTER_PARAMS.page;
+    })
+    .optional(),
+  limit: z.coerce.number().default(QUERY_FILTER_PARAMS.limit).optional(),
+  orderBy: z.string().optional(),
+  direction: z.enum(['asc', 'desc']).default('asc').optional(),
+});

package/koala-nest/src/core/schemas/native-enum.schema.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+type NativeEnumLike = Record<string, string | number>;
+
+interface NativeEnumInterface<TEnum extends NativeEnumLike> {
+  isOptional: (value: string) => TEnum[keyof TEnum] | undefined;
+  isRequired: (value: string) => TEnum[keyof TEnum];
+}
+
+export function nativeEnumSchema<TEnum extends NativeEnumLike>(
+  nativeEnum: TEnum,
+): NativeEnumInterface<TEnum> {
+  return {
+    isOptional: (value: string) => {
+      if (value === 'null' || value === '') {
+        return undefined;
+      }
+
+      return z.coerce
+        .number()
+        .transform((parsed) => {
+          if (parsed !== undefined) {
+            return z.nativeEnum(nativeEnum).parse(parsed);
+          }
+
+          return undefined;
+        })
+        .parse(value);
+    },
+    isRequired: (value: string) =>
+      z.coerce
+        .number()
+        .transform((parsed) => z.nativeEnum(nativeEnum).parse(parsed))
+        .parse(value),
+  };
+}

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

@@ -0,0 +1,14 @@
+import { Type } from '@nestjs/common';
+import { MappingStore } from './mapping-store';
+
+interface AutoMapConfig<T> {
+  type?: () => Type<T>;
+}
+
+export function AutoMap<T>(config?: AutoMapConfig<T>) {
+  return function (target: any, propertyKey: string) {
+    const compositionType: (() => any) | undefined = config?.type;
+
+    MappingStore.setProp(target.constructor, propertyKey, compositionType);
+  };
+}