@koalarx/nest 4.0.5 → 4.0.8

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

@@ -1,6 +1,9 @@
 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 {
+  cronExpressionToBoolean,
+  getCronExecutionKey,
+} 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';
@@ -9,6 +12,7 @@ import { reportErrorToLogging } from '@/core/utils/report-error';
 export interface CronJobSettings {
   isActive: boolean;
   timeInMinutes: number;
+  cronExpression?: string;
 }
 
 export function cronJobSettings(
@@ -18,10 +22,13 @@ export function cronJobSettings(
   return {
     isActive: cronExpressionToBoolean(cronExpression),
     timeInMinutes,
+    cronExpression,
   };
 }
 
 export abstract class CronJobHandlerBase {
+  private lastExecutedCronKey: string | null = null;
+
   constructor(
     private readonly redlockService: IRedLockService,
     private readonly loggingService: ILoggingService,
@@ -39,22 +46,36 @@ export abstract class CronJobHandlerBase {
       const timeout = settings.timeInMinutes * MINUTES_TO_MS;
 
       if (settings.isActive) {
-        const ttlSecondsLock = timeout / MS_TO_SECONDS;
-        const acquiredLock = await this.redlockService.acquiredLock(
-          name,
-          ttlSecondsLock,
-        );
+        const executionKey = settings.cronExpression
+          ? getCronExecutionKey(settings.cronExpression)
+          : null;
+
+        const alreadyExecutedThisTick =
+          executionKey !== null &&
+          executionKey === this.lastExecutedCronKey;
+
+        if (!alreadyExecutedThisTick) {
+          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));
 
-        if (acquiredLock) {
-          try {
-            await this.run();
-          } catch (error) {
-            const reportError =
-              error instanceof Error ? error : new Error(String(error));
+              await reportErrorToLogging(this.loggingService, reportError);
+            } finally {
+              if (executionKey !== null) {
+                this.lastExecutedCronKey = executionKey;
+              }
 
-            await reportErrorToLogging(this.loggingService, reportError);
-          } finally {
-            await this.redlockService.releaseLock(name);
+              await this.redlockService.releaseLock(name);
+            }
           }
         }
       }

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

@@ -1,4 +1,3 @@
-import { IComparableId } from '@/core/utils/icomparable';
 import { EventClass } from './event-class';
 import { EventJob } from './event-job';
 
@@ -62,7 +61,7 @@ export class EventQueue {
     }
   }
 
-  static dispatchEventsForAggregate(id: IComparableId) {
+  static dispatchEventsForAggregate(id: string) {
     const aggregate = this.findMarkedAggregateByID(id);
 
     if (aggregate) {
@@ -96,7 +95,7 @@ export class EventQueue {
   }
 
   static findMarkedAggregateByID(
-    id: IComparableId,
+    id: string,
   ): EventJob<unknown> | undefined {
     return this.markedAggregates.find((aggregate) => aggregate._id === id);
   }

package/koala-nest/src/core/common/list-response.base.ts

@@ -0,0 +1,10 @@
+import { ObjectClass } from '@/core/base/object-class';
+import { AutoMap } from '@/core/tools/mapping';
+
+export class ListResponseBase<T> extends ObjectClass<ListResponseBase<T>> {
+  @AutoMap()
+  items!: T[];
+
+  @AutoMap()
+  count!: number;
+}

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

@@ -8,12 +8,17 @@ import { z } from 'zod';
 
 export const envSchema = z.object({
   PORT: z.coerce.number().default(3000),
+  HOST: z.string().default('0.0.0.0'),
   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),
+  RATE_LIMIT_MAX: z.coerce.number().default(0),
+  RATE_LIMIT_WINDOW_MS: z.coerce.number().default(60_000),
+  CORS_ORIGINS: z.string().optional(),
+  BCRYPT_ROUNDS: z.coerce.number().min(4).max(15).default(10),
   JWT_PRIVATE_KEY: z.string().optional(),
   JWT_PUBLIC_KEY: z.string().optional(),
   JWT_ACCESS_TOKEN_EXPIRES_IN: z.string().default('15m'),

package/koala-nest/src/core/http/rate-limit.middleware.ts

@@ -0,0 +1,36 @@
+import type { NextFunction, Request, Response } from 'express';
+
+export interface RateLimitOptions {
+  windowMs: number;
+  maxRequests: number;
+}
+
+export function createRateLimitMiddleware(options: RateLimitOptions) {
+  const hits = new Map<string, number[]>();
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (options.maxRequests <= 0) {
+      next();
+      return;
+    }
+
+    const key = req.ip ?? req.socket.remoteAddress ?? 'unknown';
+    const now = Date.now();
+    const windowStart = now - options.windowMs;
+    const timestamps = (hits.get(key) ?? []).filter(
+      (timestamp) => timestamp > windowStart,
+    );
+
+    if (timestamps.length >= options.maxRequests) {
+      res.status(429).json({
+        statusCode: 429,
+        message: 'Muitas requisições. Tente novamente em instantes.',
+      });
+      return;
+    }
+
+    timestamps.push(now);
+    hits.set(key, timestamps);
+    next();
+  };
+}

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

@@ -3,12 +3,36 @@ import { MappingStore } from './mapping-store';
 
 interface AutoMapConfig<T> {
   type?: () => Type<T>;
+  isArray?: boolean;
 }
 
 export function AutoMap<T>(config?: AutoMapConfig<T>) {
-  return function (target: any, propertyKey: string) {
-    const compositionType: (() => any) | undefined = config?.type;
+  return function (target: object, propertyKey: string) {
+    const designType = Reflect.getMetadata('design:type', target, propertyKey);
+    const isArray = config?.isArray ?? designType === Array;
 
-    MappingStore.setProp(target.constructor, propertyKey, compositionType);
+    if (config?.type) {
+      if (isArray) {
+        Reflect.defineMetadata(
+          'composition:type',
+          config.type,
+          target,
+          propertyKey,
+        );
+      } else if (!designType) {
+        Reflect.defineMetadata(
+          'design:type',
+          config.type(),
+          target,
+          propertyKey,
+        );
+      }
+    }
+
+    MappingStore.setProp(
+      (target as { constructor: Type<unknown> }).constructor,
+      propertyKey,
+      config?.type,
+    );
   };
 }

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

@@ -1,3 +1,4 @@
+import { initializeUndefinedArrayProps } from '@/core/utils/initialize-undefined-array-props';
 import { Type } from '@nestjs/common';
 import { MappingStore } from './mapping-store';
 
@@ -25,7 +26,6 @@ export class AutoMapper {
 
   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) {
@@ -70,9 +70,14 @@ export class AutoMapper {
         }
 
         const targetClass: Type<any> = this.toClass(targetPropType);
+        const sourceValue = data[sourceProp.name];
+
+        if (sourceValue === undefined) {
+          continue;
+        }
 
         targetInstance[targetPropName] = this.map(
-          data[sourceProp.name],
+          sourceValue,
           sourcePropTypeClass,
           targetClass,
         );
@@ -80,23 +85,36 @@ export class AutoMapper {
       }
 
       if (sourceProp.isArray) {
-        targetInstance[targetPropName] = data[sourceProp.name].map(
-          (item: unknown) => {
-            const targetItemType = targetProps.find(
-              (p) => p.name === targetPropName,
-            )!.type;
+        const sourceArray = data[sourceProp.name];
 
-            const targetClassType = this.toClass(targetItemType);
+        if (sourceArray === undefined) {
+          continue;
+        }
 
-            return this.map(item, sourcePropTypeClass, targetClassType);
-          },
-        );
+        targetInstance[targetPropName] = sourceArray.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];
+      const sourceValue = data[sourceProp.name];
+
+      if (sourceValue !== undefined) {
+        targetInstance[targetPropName] = sourceValue;
+      }
     }
 
+    initializeUndefinedArrayProps(
+      targetInstance as Record<string, unknown>,
+      target,
+    );
+
     return targetInstance;
   }
 }

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

@@ -30,8 +30,15 @@ export class MappingStore {
       entity.prototype,
       propName,
     );
-    const isArray = propType === Array;
-    const type = isArray ? (compositionType ?? propType) : propType;
+    const explicitComposition = Reflect.getMetadata(
+      'composition:type',
+      entity.prototype,
+      propName,
+    );
+    const isArray = propType === Array || explicitComposition != null;
+    const type = isArray
+      ? (compositionType ?? explicitComposition ?? propType)
+      : propType;
 
     const props = this._entities.get(entity) || [];
 
@@ -57,32 +64,44 @@ export class MappingStore {
         }
       }
 
-      current = Object.getPrototypeOf(current) as Type<any> | null;
+      const parentPrototype = Object.getPrototypeOf(current.prototype);
+      current = (parentPrototype?.constructor as Type<any> | undefined) ?? null;
     }
 
     return props;
   }
 
+  static getAllProps(entity: Type<any>) {
+    return this.getProps(entity);
+  }
+
   static getPropType(entity: Type<any>, propName: string) {
-    const prop = this._entities.get(entity)?.find((p) => p.name === propName);
+    let current: Type<any> | null = entity;
 
-    if (!prop) {
-      throw new Error(
-        `Property ${propName} not found in entity ${entity.name}`,
-      );
-    }
+    while (current?.prototype) {
+      const prop = this._entities.get(current)?.find((p) => p.name === propName);
 
-    const { type, isArray } = prop;
+      if (prop) {
+        const { type, isArray } = prop;
 
-    if (!type) {
-      return null;
-    }
+        if (!type) {
+          return null;
+        }
 
-    if (isArray && type instanceof Function) {
-      return (type as () => Type<any>)();
+        if (isArray && type instanceof Function) {
+          return (type as () => Type<any>)();
+        }
+
+        return type;
+      }
+
+      const parentPrototype = Object.getPrototypeOf(current.prototype);
+      current = (parentPrototype?.constructor as Type<any> | undefined) ?? null;
     }
 
-    return type;
+    throw new Error(
+      `Property ${propName} not found in entity ${entity.name}`,
+    );
   }
 
   static add(
@@ -105,17 +124,4 @@ export class MappingStore {
   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/utils/cron-expression-to-boolean.ts

@@ -1,5 +1,36 @@
 import { CronExpressionParser } from 'cron-parser';
 
+/**
+ * Retorna uma chave única do tick cron atual, ou null se o instante não coincide.
+ */
+export function getCronExecutionKey(
+  cronExpression: string,
+  now: Date = new Date(),
+): string | null {
+  try {
+    const interval = CronExpressionParser.parse(cronExpression, {
+      currentDate: now,
+    });
+    const prev = interval.prev();
+
+    const matches =
+      prev.getFullYear() === now.getFullYear() &&
+      prev.getMonth() === now.getMonth() &&
+      prev.getDate() === now.getDate() &&
+      prev.getHours() === now.getHours() &&
+      prev.getMinutes() === now.getMinutes() &&
+      prev.getSeconds() === now.getSeconds();
+
+    if (!matches) {
+      return null;
+    }
+
+    return prev.toISOString();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Verifica se a expressão cron corresponde ao momento atual.
  *
@@ -45,21 +76,5 @@ 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;
-  }
+  return getCronExecutionKey(cronExpression, now) !== null;
 }

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

@@ -1,5 +1,10 @@
 import { hash } from 'bcrypt';
 
-export function hashPassword(password: string): Promise<string> {
-  return hash(password, 6);
+const DEFAULT_BCRYPT_ROUNDS = 10;
+
+export function hashPassword(
+  password: string,
+  rounds = Number(process.env.BCRYPT_ROUNDS) || DEFAULT_BCRYPT_ROUNDS,
+): Promise<string> {
+  return hash(password, rounds);
 }

package/koala-nest/src/core/utils/initialize-undefined-array-props.ts

@@ -0,0 +1,20 @@
+import type { Type } from '@nestjs/common';
+import { MappingStore } from '@/core/tools/mapping/mapping-store';
+
+export function initializeUndefinedArrayProps(
+  target: Record<string, unknown>,
+  entity: Type<unknown>,
+  onlyProps?: string[],
+): void {
+  MappingStore.getAllProps(entity).forEach((prop) => {
+    if (onlyProps && !onlyProps.includes(prop.name)) {
+      return;
+    }
+
+    if (target[prop.name] !== undefined || !prop.isArray) {
+      return;
+    }
+
+    target[prop.name] = [];
+  });
+}

package/koala-nest/src/core/utils/resolve-cors-origins.ts

@@ -0,0 +1,24 @@
+/**
+ * CORS aberto por padrão (`true` = reflete a origin da requisição).
+ * Defina `CORS_ORIGINS` apenas quando quiser restringir a origens específicas.
+ */
+export function resolveCorsOrigin(
+  origins: string | undefined,
+): boolean | string | string[] {
+  const normalized = origins?.trim();
+
+  if (!normalized) {
+    return true;
+  }
+
+  const list = normalized
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+  if (list.length === 1) {
+    return list[0];
+  }
+
+  return list;
+}

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

@@ -1,6 +1,61 @@
 import { QUERY_FILTER_PARAMS } from '@/core/constants/query-params';
 import { AutoMap } from '@/core/tools/mapping';
 import type { QueryDirectionType } from '@/core/types';
+import type {
+  FindOptionsOrder,
+  ObjectLiteral,
+  SelectQueryBuilder,
+} from 'typeorm';
+
+type OrderDirection = 'ASC' | 'DESC';
+
+function normalizeDirection(
+  direction?: QueryDirectionType | string,
+): OrderDirection {
+  return String(direction ?? 'asc').toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+}
+
+function flattenOrderBy(
+  order: Record<string, unknown>,
+  prefix = '',
+): Array<{ path: string; direction: OrderDirection }> {
+  const entries: Array<{ path: string; direction: OrderDirection }> = [];
+
+  for (const [key, value] of Object.entries(order)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === 'string') {
+      entries.push({ path, direction: normalizeDirection(value) });
+      continue;
+    }
+
+    if (value && typeof value === 'object') {
+      entries.push(...flattenOrderBy(value as Record<string, unknown>, path));
+    }
+  }
+
+  return entries;
+}
+
+function normalizeFindOptionsOrder(
+  order: Record<string, unknown>,
+): FindOptionsOrder<ObjectLiteral> {
+  const normalized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(order)) {
+    if (typeof value === 'string') {
+      normalized[key] = normalizeDirection(value);
+    } else if (value && typeof value === 'object') {
+      normalized[key] = normalizeFindOptionsOrder(
+        value as Record<string, unknown>,
+      );
+    } else {
+      normalized[key] = value;
+    }
+  }
+
+  return normalized as FindOptionsOrder<ObjectLiteral>;
+}
 
 export class PaginationDto {
   @AutoMap()
@@ -19,17 +74,47 @@ export class PaginationDto {
     return (this.limit ?? 0) * (this.page ?? QUERY_FILTER_PARAMS.page);
   }
 
-  generateOrderBy() {
+  generateOrderBy(): Record<string, unknown> | undefined {
     if (this.orderBy) {
       const orderByField = this.orderBy.split('.');
       return orderByField.reduceRight(
         (acc, item, index) => ({
           [item]: index === orderByField.length - 1 ? this.direction : acc,
         }),
-        {},
+        {} as Record<string, unknown>,
       );
     }
 
     return undefined;
   }
+
+  toFindOptionsOrder(): FindOptionsOrder<ObjectLiteral> | undefined {
+    const order = this.generateOrderBy();
+
+    if (!order) {
+      return undefined;
+    }
+
+    return normalizeFindOptionsOrder(order);
+  }
+
+  applyQueryBuilderPagination<T extends ObjectLiteral>(
+    qb: SelectQueryBuilder<T>,
+    alias: string,
+  ): SelectQueryBuilder<T> {
+    const order = this.generateOrderBy();
+
+    if (order) {
+      for (const { path, direction } of flattenOrderBy(order)) {
+        const sortPath = path.includes('.') ? path : `${alias}.${path}`;
+        qb.addOrderBy(sortPath, direction);
+      }
+    }
+
+    return qb.skip(this.skip()).take(this.limit);
+  }
+
+  static from<T extends PaginationDto>(this: new () => T, props: Partial<T>): T {
+    return Object.assign(new this(), props);
+  }
 }

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

@@ -7,4 +7,12 @@ export class PersonQueryDto extends PaginationDto {
 
   @AutoMap()
   active?: boolean;
+
+  override generateOrderBy() {
+    if (this.orderBy) {
+      return super.generateOrderBy();
+    }
+
+    return { id: 'asc' };
+  }
 }

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

@@ -27,7 +27,6 @@ export class Person extends EntityBase<Person> {
 
   @OneToOne(() => PersonAddress, {
     cascade: true,
-    eager: true,
     onDelete: 'CASCADE',
   })
   @JoinColumn()
@@ -36,7 +35,6 @@ export class Person extends EntityBase<Person> {
 
   @OneToMany(() => PersonContact, (contact) => contact.person, {
     cascade: true,
-    eager: true,
     onDelete: 'CASCADE',
   })
   @AutoMap({ type: () => PersonContact })

package/koala-nest/src/host/bootstrap/apply-http-middleware.ts

@@ -0,0 +1,22 @@
+import { createRateLimitMiddleware } from '@/core/http/rate-limit.middleware';
+import { resolveCorsOrigin } from '@/core/utils/resolve-cors-origins';
+import { EnvService } from '@/infra/common/env.service';
+import type { INestApplication } from '@nestjs/common';
+import cookieParser from 'cookie-parser';
+
+export function applyHttpMiddleware(app: INestApplication) {
+  const env = app.get(EnvService);
+
+  app.use(cookieParser());
+  app.use(
+    createRateLimitMiddleware({
+      windowMs: env.get('RATE_LIMIT_WINDOW_MS'),
+      maxRequests: env.get('RATE_LIMIT_MAX'),
+    }),
+  );
+  app.enableCors({
+    credentials: true,
+    origin: resolveCorsOrigin(env.get('CORS_ORIGINS')),
+    optionsSuccessStatus: 200,
+  });
+}