@koalarx/nest 4.0.5 → 4.0.8

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/read-many-person.handler.spec.ts

@@ -21,18 +21,58 @@ describe('ReadManyPersonHandler', () => {
       contacts: [],
     });
 
+    let capturedPage: number | undefined;
     const repository = {
-      findMany: async () => ({ items: [person], count: 1 }),
+      findMany: async (query: { page?: number; skip: () => number }) => {
+        capturedPage = query.page;
+        return { items: [person], count: 1 };
+      },
     } as unknown as IPersonRepository;
 
     const handler = new ReadManyPersonHandler(repository, new CacheStub());
-    const result = await handler.handle(new ReadManyPersonRequest());
+    const result = await handler.handle({ page: '2', limit: '5' } as never);
 
+    expect(capturedPage).toBe(1);
     expect(result.count).toBe(1);
     expect(result.items).toHaveLength(1);
     expect(result.items[0].name).toBe('Jane');
   });
 
+  it('preserva paginação ao receber instância de ReadManyPersonRequest', async () => {
+    let capturedPage: number | undefined;
+    const repository = {
+      findMany: async (query: { page?: number }) => {
+        capturedPage = query.page;
+        return { items: [], count: 0 };
+      },
+    } as unknown as IPersonRepository;
+
+    const handler = new ReadManyPersonHandler(repository, new CacheStub());
+    const request = Object.assign(new ReadManyPersonRequest(), {
+      page: '2',
+      limit: '5',
+    });
+
+    await handler.handle(request);
+
+    expect(capturedPage).toBe(1);
+  });
+
+  it('aplica defaults de paginação quando a request não informa page', async () => {
+    let capturedPage: number | undefined;
+    const repository = {
+      findMany: async (query: { page?: number }) => {
+        capturedPage = query.page;
+        return { items: [], count: 0 };
+      },
+    } as unknown as IPersonRepository;
+
+    const handler = new ReadManyPersonHandler(repository, new CacheStub());
+    await handler.handle(new ReadManyPersonRequest());
+
+    expect(capturedPage).toBe(0);
+  });
+
   it('reutiliza cache para a mesma consulta de listagem', async () => {
     const person = Person.from({
       id: 1,

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', () => {

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

@@ -0,0 +1,62 @@
+/// <reference types="bun-types/test-globals" />
+
+import { createRateLimitMiddleware } from '@/core/http/rate-limit.middleware';
+import { describe, expect, it } from 'bun:test';
+
+function createMockResponse() {
+  const response = {
+    statusCode: 200,
+    body: undefined as unknown,
+    status(code: number) {
+      this.statusCode = code;
+      return this;
+    },
+    json(payload: unknown) {
+      this.body = payload;
+      return this;
+    },
+  };
+
+  return response;
+}
+
+describe('createRateLimitMiddleware', () => {
+  it('permite requisições quando rate limit está desabilitado', () => {
+    const middleware = createRateLimitMiddleware({
+      windowMs: 60_000,
+      maxRequests: 0,
+    });
+    let called = false;
+    const next = () => {
+      called = true;
+    };
+
+    middleware(
+      { ip: '127.0.0.1' } as never,
+      createMockResponse() as never,
+      next,
+    );
+
+    expect(called).toBe(true);
+  });
+
+  it('bloqueia requisições após atingir maxRequests', () => {
+    const middleware = createRateLimitMiddleware({
+      windowMs: 60_000,
+      maxRequests: 2,
+    });
+    const req = { ip: '127.0.0.1' } as never;
+    const next = () => {};
+
+    middleware(req, createMockResponse() as never, next);
+    middleware(req, createMockResponse() as never, next);
+    const blockedResponse = createMockResponse();
+
+    middleware(req, blockedResponse as never, next);
+
+    expect(blockedResponse.statusCode).toBe(429);
+    expect(blockedResponse.body).toMatchObject({
+      statusCode: 429,
+    });
+  });
+});

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

@@ -0,0 +1,63 @@
+/// <reference types="bun-types/test-globals" />
+
+import { initializeUndefinedArrayProps } from '@/core/utils/initialize-undefined-array-props';
+import { AutoMap } from '@/core/tools/mapping';
+import { MappingStore } from '@/core/tools/mapping/mapping-store';
+import { describe, expect, it } from 'bun:test';
+
+class ChildItem {
+  @AutoMap()
+  name!: string;
+}
+
+class EntityWithArrays {
+  @AutoMap()
+  title!: string;
+
+  @AutoMap({ type: () => ChildItem })
+  children!: ChildItem[];
+}
+
+describe('initializeUndefinedArrayProps', () => {
+  it('inicializa props de array mapeadas como [] quando undefined', () => {
+    const target = { title: 'Test' } as Record<string, unknown>;
+
+    initializeUndefinedArrayProps(target, EntityWithArrays);
+
+    expect(target.children).toEqual([]);
+  });
+
+  it('respeita onlyProps quando informado', () => {
+    const target = { title: 'Test' } as Record<string, unknown>;
+
+    initializeUndefinedArrayProps(target, EntityWithArrays, ['title']);
+
+    expect(target.children).toBeUndefined();
+  });
+
+  it('não sobrescreve array já definido', () => {
+    const existing: ChildItem[] = [];
+    const target = { title: 'Test', children: existing } as Record<
+      string,
+      unknown
+    >;
+
+    initializeUndefinedArrayProps(target, EntityWithArrays);
+
+    expect(target.children).toBe(existing);
+  });
+
+  it('detecta arrays via metadata composition:type', () => {
+    class DtoWithExplicitArray {
+      @AutoMap({ type: () => ChildItem, isArray: true })
+      items!: ChildItem[];
+    }
+
+    MappingStore.getAllProps(DtoWithExplicitArray);
+
+    const target = {} as Record<string, unknown>;
+    initializeUndefinedArrayProps(target, DtoWithExplicitArray);
+
+    expect(target.items).toEqual([]);
+  });
+});

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

@@ -104,6 +104,21 @@ describe('AutoMapper', () => {
     expect(person.contacts[0].contact).toBe(personRequest.contacts[0].contact);
   });
 
+  it('inicializa arrays undefined no destino após o map', () => {
+    createMap(PersonRequest, Person);
+
+    const personRequest = PersonRequest.from({
+      name: 'John Doe',
+      address: {
+        address: '123 Main St',
+      },
+    });
+
+    const person = AutoMapper.map(personRequest, PersonRequest, Person);
+
+    expect(person.contacts).toEqual([]);
+  });
+
   it('should apply forMember custom mappings', () => {
     class SourceRequest {
       @AutoMap()
@@ -137,6 +152,67 @@ describe('AutoMapper', () => {
     expect(target.fullName).toBe('John Doe');
   });
 
+  it('should map inherited properties from parent classes', () => {
+    class BaseRequest {
+      @AutoMap()
+      page?: number;
+
+      @AutoMap()
+      limit?: number;
+    }
+
+    class ChildRequest extends BaseRequest {
+      @AutoMap()
+      name?: string;
+    }
+
+    class BaseDto {
+      @AutoMap()
+      page?: number = 0;
+
+      @AutoMap()
+      limit?: number = 10;
+    }
+
+    class ChildDto extends BaseDto {
+      @AutoMap()
+      name?: string;
+    }
+
+    createMap(ChildRequest, ChildDto);
+
+    const source = Object.assign(new ChildRequest(), {
+      page: 2,
+      limit: 25,
+      name: 'John',
+    });
+
+    const target = AutoMapper.map(source, ChildRequest, ChildDto);
+
+    expect(target.page).toBe(2);
+    expect(target.limit).toBe(25);
+    expect(target.name).toBe('John');
+  });
+
+  it('should resolve inherited property types via getProps and getPropType', () => {
+    class BaseRequest {
+      @AutoMap()
+      page?: number;
+    }
+
+    class ChildRequest extends BaseRequest {
+      @AutoMap()
+      name?: string;
+    }
+
+    const props = MappingStore.getProps(ChildRequest).map((p) => p.name);
+
+    expect(props).toContain('page');
+    expect(props).toContain('name');
+    expect(MappingStore.getPropType(ChildRequest, 'page')).toBe(Number);
+    expect(MappingStore.getPropType(ChildRequest, 'name')).toBe(String);
+  });
+
   it('should map nested objects using the target property name', () => {
     class SourceChild {
       @AutoMap()