@koalarx/nest 4.0.6 → 4.0.8

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) || [];
 
@@ -64,6 +71,10 @@ export class MappingStore {
     return props;
   }
 
+  static getAllProps(entity: Type<any>) {
+    return this.getProps(entity);
+  }
+
   static getPropType(entity: Type<any>, propName: string) {
     let current: Type<any> | null = entity;
 
@@ -113,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,
+  });
+}

package/koala-nest/src/host/main.ts

@@ -1,7 +1,8 @@
 import 'dotenv/config';
 
+import { applyHttpMiddleware } from '@/host/bootstrap/apply-http-middleware';
+import { resolveApiHost } from '@/core/utils/resolve-api-host';
 import { NestFactory } from '@nestjs/core';
-import cookieParser from 'cookie-parser';
 import { AppModule } from './app.module';
 import { defineDocumentation } from './open-api/define-documentation';
 import { ErrorsFilter } from './filters/errors.filter';
@@ -13,13 +14,7 @@ import { ILoggingService } from '@/domain/common/ilogging.service';
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
-  app.use(cookieParser());
-
-  app.enableCors({
-    credentials: true,
-    origin: true,
-    optionsSuccessStatus: 200,
-  });
+  applyHttpMiddleware(app);
 
   await defineDocumentation(app);
 
@@ -32,12 +27,17 @@ async function bootstrap() {
     await app.resolve(ProfilesGuard),
   );
 
-  await app.listen(process.env.PORT || 3000);
+  const port = Number(process.env.PORT) || 3000;
+  const bindHost = process.env.HOST ?? '0.0.0.0';
+  const publicHost = resolveApiHost(process.env.API_HOST, port);
 
-  console.log(`Server is running on port ${process.env.PORT || 3000}`);
-  console.log(
-    `Documentation is available at http://localhost:${process.env.PORT || 3000}/doc`,
-  );
+  await app.listen(port, bindHost);
+
+  console.log(`Server is running on ${publicHost}`);
+  console.log(`Documentation is available at ${publicHost}/doc`);
 }
 
-bootstrap();
+bootstrap().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/koala-nest/src/infra/common/redis-cache.service.ts

@@ -59,11 +59,22 @@ export class RedisCacheService implements ICacheService {
 
   async invalidateByPrefix(prefix: string): Promise<void> {
     const pattern = `${this.buildKey(prefix)}*`;
-    const keys = await this.client.keys(pattern);
+    let cursor = '0';
 
-    if (keys.length > 0) {
-      await this.client.del(...keys);
-    }
+    do {
+      const [nextCursor, keys] = await this.client.scan(
+        cursor,
+        'MATCH',
+        pattern,
+        'COUNT',
+        100,
+      );
+      cursor = nextCursor;
+
+      if (keys.length > 0) {
+        await this.client.del(...keys);
+      }
+    } while (cursor !== '0');
   }
 
   onModuleDestroy() {

package/koala-nest/src/infra/repositories/person.repository.ts

@@ -30,18 +30,18 @@ export class PersonRepository
     return this.repository
       .findAndCount({
         where,
-        order: query.generateOrderBy(),
+        order: query.toFindOptionsOrder(),
         skip: query.skip(),
         take: query.limit,
       })
       .then(([items, count]) => ({
-        items,
+        items: this.normalizeEntities(items),
         count,
       }));
   }
 
   findById(id: number): Promise<Person | null> {
-    return this.repository.findOne({
+    return this.findOneNormalized({
       where: { id },
       relations: { address: true, contacts: true },
     });

package/koala-nest/src/infra/repositories/repository.base.ts

@@ -1,4 +1,27 @@
-import { DataSource, EntityTarget, ObjectLiteral, Repository } from 'typeorm';
+import { initializeUndefinedArrayProps } from '@/core/utils/initialize-undefined-array-props';
+import type { Type } from '@nestjs/common';
+import {
+  DataSource,
+  EntityTarget,
+  FindManyOptions,
+  FindOneOptions,
+  ObjectLiteral,
+  Repository,
+} from 'typeorm';
+
+function getLoadedRelationKeys(
+  relations?: FindOneOptions<ObjectLiteral>['relations'],
+): string[] {
+  if (!relations) {
+    return [];
+  }
+
+  if (Array.isArray(relations)) {
+    return relations.map(String);
+  }
+
+  return Object.keys(relations);
+}
 
 export class RepositoryBase<T extends ObjectLiteral> {
   protected readonly repository: Repository<T>;
@@ -10,6 +33,52 @@ export class RepositoryBase<T extends ObjectLiteral> {
     this.repository = this.dataSource.getRepository<T>(entity);
   }
 
+  protected normalizeEntity<E extends ObjectLiteral>(
+    entity: E,
+    loadedRelationKeys: string[] = [],
+  ): E {
+    if (loadedRelationKeys.length > 0) {
+      initializeUndefinedArrayProps(
+        entity as Record<string, unknown>,
+        this.getEntityType(),
+        loadedRelationKeys,
+      );
+    }
+
+    return entity;
+  }
+
+  protected normalizeEntities<E extends ObjectLiteral>(
+    entities: E[],
+    loadedRelationKeys: string[] = [],
+  ): E[] {
+    return entities.map((entity) =>
+      this.normalizeEntity(entity, loadedRelationKeys),
+    );
+  }
+
+  protected getEntityType(): Type<unknown> {
+    return this.entity as Type<unknown>;
+  }
+
+  protected findOneNormalized(options: FindOneOptions<T>) {
+    const loadedRelationKeys = getLoadedRelationKeys(options.relations);
+
+    return this.repository
+      .findOne(options)
+      .then((entity) =>
+        entity ? this.normalizeEntity(entity, loadedRelationKeys) : null,
+      );
+  }
+
+  protected findNormalized(options: FindManyOptions<T>) {
+    const loadedRelationKeys = getLoadedRelationKeys(options.relations);
+
+    return this.repository
+      .find(options)
+      .then((entities) => this.normalizeEntities(entities, loadedRelationKeys));
+  }
+
   save(entity: T) {
     return this.repository.save(entity);
   }

package/koala-nest/src/test/application/delete-inactive.job.spec.ts

@@ -1,19 +1,32 @@
+import { describe, expect, it } from 'bun:test';
 import { DeleteInactiveJob } from '@/application/person/jobs/cron/delete-inactive.job';
 import { DeletePersonHandler } from '@/application/person/delete/delete-person.handler';
-import { ReadManyPersonHandler } from '@/application/person/read-many/read-many-person.handler';
+import { Person } from '@/domain/entities/person/person';
+import type { IPersonRepository } from '@/domain/repositories/iperson.repository';
 import { FakeLoggingService } from '@/test/services/fake-logging.service';
 import { FakeRedLockService } from '@/test/services/fake-red-lock.service';
 
 describe('DeleteInactiveJob', () => {
-  it('remove pessoas inativas retornadas pela listagem', async () => {
+  it('remove todas as páginas de pessoas inativas', async () => {
     const deletedIds: number[] = [];
+    const inactivePeople = Array.from({ length: 35 }, (_, index) => {
+      const person = new Person();
+      person.id = index + 1;
+      person.name = `Inactive ${index + 1}`;
+      person.active = false;
+      return person;
+    });
 
-    const readManyPerson = {
-      handle: async () => ({
-        items: [{ id: 1, name: 'Inactive', active: false }],
-        count: 1,
-      }),
-    } as unknown as ReadManyPersonHandler;
+    const repository = {
+      findMany: async (query: { page?: number; limit?: number }) => {
+        const currentPage = query.page ?? 0;
+        const limit = query.limit ?? 30;
+        const start = currentPage * limit;
+        const items = inactivePeople.slice(start, start + limit);
+
+        return { items, count: inactivePeople.length };
+      },
+    } as unknown as IPersonRepository;
 
     const deletePerson = {
       handle: async (id: number) => {
@@ -24,12 +37,12 @@ describe('DeleteInactiveJob', () => {
     const job = new DeleteInactiveJob(
       new FakeRedLockService(),
       new FakeLoggingService(),
-      readManyPerson,
+      repository,
       deletePerson,
     );
 
     await job['run']();
 
-    expect(deletedIds).toEqual([1]);
+    expect(deletedIds).toHaveLength(35);
   });
 });

package/koala-nest/src/test/application/update-person.handler.spec.ts

@@ -58,6 +58,48 @@ describe('UpdatePersonHandler', () => {
     expect(cache.invalidateByPrefixCalls).toEqual([PERSON_LIST_CACHE_PREFIX]);
   });
 
+  it('remove contatos ausentes do payload (órfãos via TypeORM)', async () => {
+    const cache = new CacheStub();
+    const keptContact = PersonContact.from({
+      id: 10,
+      contact: 'keep@example.com',
+      person: undefined as unknown as Person,
+    });
+    const removedContact = PersonContact.from({
+      id: 11,
+      contact: 'remove@example.com',
+      person: undefined as unknown as Person,
+    });
+
+    const person = Person.from({
+      id: 1,
+      name: 'Jane',
+      active: true,
+      address: PersonAddress.from({ id: 5, address: 'Street' }),
+      contacts: [keptContact, removedContact],
+    });
+    keptContact.person = person;
+    removedContact.person = person;
+
+    const repository = {
+      findById: async () => person,
+      save: async (entity: Person) => entity,
+    } as unknown as IPersonRepository;
+
+    const handler = new UpdatePersonHandler(repository, cache);
+
+    await handler.handle({
+      id: 1,
+      name: 'Jane',
+      address: { id: 5, address: 'Street' },
+      contacts: [{ id: 10, contact: 'keep@example.com' }],
+    });
+
+    expect(person.contacts).toHaveLength(1);
+    expect(person.contacts[0].id).toBe(10);
+    expect(person.contacts[0].contact).toBe('keep@example.com');
+  });
+
   it('lança NotFoundException quando a pessoa não existe', async () => {
     const repository = {
       findById: async () => null,

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

@@ -1,8 +1,27 @@
 /// <reference types="bun-types/test-globals" />
 
-import { cronExpressionToBoolean } from '@/core/utils/cron-expression-to-boolean';
+import {
+  cronExpressionToBoolean,
+  getCronExecutionKey,
+} from '@/core/utils/cron-expression-to-boolean';
 import { describe, expect, it } from 'bun:test';
 
+describe('getCronExecutionKey', () => {
+  it('retorna ISO do tick quando o instante coincide com a expressão', () => {
+    const at = new Date(2024, 5, 12, 12, 0, 0, 1);
+
+    expect(getCronExecutionKey('0 0 12 * * *', at)).toBe(
+      new Date(2024, 5, 12, 12, 0, 0).toISOString(),
+    );
+  });
+
+  it('retorna null quando o instante não coincide', () => {
+    const at = new Date(2024, 5, 12, 12, 0, 1);
+
+    expect(getCronExecutionKey('0 0 12 * * *', at)).toBeNull();
+  });
+});
+
 describe('cronExpressionToBoolean', () => {
   it('retorna true quando o instante atual coincide com o tick da expressão', () => {
     const at = new Date(2024, 5, 12, 12, 0, 0, 1);

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

@@ -3,6 +3,15 @@ import { parseOAuth2ProviderEnv } from '@/core/auth/parse-oauth2-provider-env';
 import { envSchema, validateEnvConfig } from '@/core/env';
 
 describe('envSchema', () => {
+  it('define HOST com default 0.0.0.0 para bind em container', () => {
+    const env = envSchema.parse({
+      NODE_ENV: 'test',
+      DATABASE_URL: 'postgres://localhost/test',
+    });
+
+    expect(env.HOST).toBe('0.0.0.0');
+  });
+
   it('interpreta CRON_JOBS_ENABLED=false como desabilitado', () => {
     const env = envSchema.parse({
       NODE_ENV: 'test',
@@ -12,6 +21,16 @@ describe('envSchema', () => {
 
     expect(env.CRON_JOBS_ENABLED).toBe(false);
   });
+
+  it('define rate limit desabilitado por padrão', () => {
+    const env = envSchema.parse({
+      NODE_ENV: 'test',
+      DATABASE_URL: 'postgres://localhost/test',
+    });
+
+    expect(env.RATE_LIMIT_MAX).toBe(0);
+    expect(env.RATE_LIMIT_WINDOW_MS).toBe(60_000);
+  });
 });
 
 describe('parseOAuth2ProviderEnv', () => {