@koalarx/nest 4.0.6 → 4.1.0

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/app-auth-test.module.ts

@@ -3,7 +3,7 @@ import { AuthModule } from '@/host/controllers/auth/auth.module';
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { PersonModule } from '@/host/controllers/person/person.module';
-import { e2eDatabaseUrl } from '@/test/e2e-context';
+import { e2eDatabaseUrl, e2eSchemaName } from '@/test/e2e-context';
 import { getJwtTestKeys } from '@/test/utils/jwt-test-keys';
 
 const jwtKeys = getJwtTestKeys();
@@ -18,6 +18,7 @@ const jwtKeys = getJwtTestKeys();
           PORT: 3000,
           NODE_ENV: 'test',
           DATABASE_URL: e2eDatabaseUrl,
+          DATABASE_SCHEMA: e2eSchemaName,
           JWT_PRIVATE_KEY: jwtKeys.privateKey,
           JWT_PUBLIC_KEY: jwtKeys.publicKey,
           JWT_ACCESS_TOKEN_EXPIRES_IN: '15m',

package/koala-nest/src/test/app-test.module.ts

@@ -2,7 +2,7 @@ import { envSchema } from '@/core/env';
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { PersonModule } from '@/host/controllers/person/person.module';
-import { e2eDatabaseUrl } from '@/test/e2e-context';
+import { e2eDatabaseUrl, e2eSchemaName } from '@/test/e2e-context';
 
 @Module({
   imports: [
@@ -14,6 +14,7 @@ import { e2eDatabaseUrl } from '@/test/e2e-context';
           PORT: 3000,
           NODE_ENV: 'test',
           DATABASE_URL: e2eDatabaseUrl,
+          DATABASE_SCHEMA: e2eSchemaName,
         }),
     }),
     PersonModule,

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

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()

package/koala-nest/src/test/core/pagination-typeorm.spec.ts

@@ -0,0 +1,74 @@
+/// <reference types="bun-types/test-globals" />
+
+import { PaginationDto } from '@/domain/dtos/pagination.dto';
+import { PersonQueryDto } from '@/domain/dtos/person-query.dto';
+import { describe, expect, it } from 'bun:test';
+
+describe('PaginationDto TypeORM', () => {
+  it('toFindOptionsOrder normaliza direction para ASC/DESC', () => {
+    const query = PaginationDto.from({ orderBy: 'name', direction: 'desc' });
+
+    expect(query.toFindOptionsOrder()).toEqual({ name: 'DESC' });
+  });
+
+  it('toFindOptionsOrder suporta ordenação aninhada', () => {
+    const query = PaginationDto.from({
+      orderBy: 'address.city',
+      direction: 'asc',
+    });
+
+    expect(query.toFindOptionsOrder()).toEqual({
+      address: { city: 'ASC' },
+    });
+  });
+
+  it('applyQueryBuilderPagination aplica order, skip e take', () => {
+    const qb = {
+      expressionMap: {
+        orderBys: {} as Record<string, string>,
+        skip: 0,
+        take: 0,
+      },
+      addOrderBy(path: string, direction: string) {
+        this.expressionMap.orderBys[path] = direction;
+        return this;
+      },
+      skip(value: number) {
+        this.expressionMap.skip = value;
+        return this;
+      },
+      take(value: number) {
+        this.expressionMap.take = value;
+        return this;
+      },
+    };
+    const query = PaginationDto.from({
+      page: 1,
+      limit: 10,
+      orderBy: 'name',
+      direction: 'desc',
+    });
+
+    const result = query.applyQueryBuilderPagination(qb as never, 'entity');
+
+    expect(result.expressionMap.orderBys).toEqual({ 'entity.name': 'DESC' });
+    expect(result.expressionMap.skip).toBe(10);
+    expect(result.expressionMap.take).toBe(10);
+  });
+});
+
+describe('PersonQueryDto default sort', () => {
+  it('usa id asc quando orderBy não é informado', () => {
+    const query = PersonQueryDto.from({ name: 'Jane' });
+
+    expect(query.generateOrderBy()).toEqual({ id: 'asc' });
+    expect(query.toFindOptionsOrder()).toEqual({ id: 'ASC' });
+  });
+
+  it('delega para PaginationDto quando orderBy é informado', () => {
+    const query = PersonQueryDto.from({ orderBy: 'name', direction: 'desc' });
+
+    expect(query.generateOrderBy()).toEqual({ name: 'desc' });
+    expect(query.toFindOptionsOrder()).toEqual({ name: 'DESC' });
+  });
+});

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test';
+import { resolveCorsOrigin } from '@/core/utils/resolve-cors-origins';
+
+describe('resolveCorsOrigin', () => {
+  it('permite qualquer origin quando CORS_ORIGINS não está definido', () => {
+    expect(resolveCorsOrigin(undefined)).toBe(true);
+    expect(resolveCorsOrigin('')).toBe(true);
+    expect(resolveCorsOrigin('   ')).toBe(true);
+  });
+
+  it('aceita lista de origens separadas por vírgula', () => {
+    expect(
+      resolveCorsOrigin('http://localhost:4200, https://app.example.com'),
+    ).toEqual(['http://localhost:4200', 'https://app.example.com']);
+  });
+
+  it('retorna string única quando há uma origem', () => {
+    expect(resolveCorsOrigin('https://app.example.com')).toBe(
+      'https://app.example.com',
+    );
+  });
+});

package/koala-nest/src/test/core/sync-improvements.spec.ts

@@ -0,0 +1,39 @@
+/// <reference types="bun-types/test-globals" />
+
+import { ListResponseBase } from '@/core/common/list-response.base';
+import { PaginationDto } from '@/domain/dtos/pagination.dto';
+import { describe, expect, it } from 'bun:test';
+
+class QueryPersonDto extends PaginationDto {
+  name?: string;
+}
+
+class PersonListItem {
+  id!: number;
+  name!: string;
+}
+
+class PersonListResponse extends ListResponseBase<PersonListItem> {}
+
+describe('PaginationDto.from', () => {
+  it('cria instância com props parciais herdando defaults', () => {
+    const query = QueryPersonDto.from({ name: 'Jane', limit: 50 });
+
+    expect(query).toBeInstanceOf(QueryPersonDto);
+    expect(query.name).toBe('Jane');
+    expect(query.limit).toBe(50);
+    expect(query.page).toBe(0);
+  });
+});
+
+describe('ListResponseBase.from', () => {
+  it('cria resposta paginada via ObjectClass.from', () => {
+    const response = PersonListResponse.from({
+      items: [{ id: 1, name: 'Jane' }],
+      count: 1,
+    });
+
+    expect(response.items).toHaveLength(1);
+    expect(response.count).toBe(1);
+  });
+});

package/koala-nest/src/test/e2e-context.ts

@@ -1,7 +1,10 @@
 export let e2eDatabaseUrl: string | undefined;
+export let e2eSchemaName: string | undefined;
 
-export function setE2EDatabaseUrl(url: string) {
+export function setE2EDatabaseContext(url: string, schemaName: string) {
   e2eDatabaseUrl = url;
+  e2eSchemaName = schemaName;
   process.env.DATABASE_URL = url;
+  process.env.DATABASE_SCHEMA = schemaName;
   process.env.NODE_ENV = 'test';
 }

package/koala-nest/src/test/host/controllers/person/lazy-loading.e2e.spec.ts

@@ -12,9 +12,9 @@ import { Test, TestingModule } from '@nestjs/testing';
 /**
  * Testes E2E do RepositoryBase - Lazy Loading
  *
- * Valida o carregamento efetivo de relacionamentos em diferentes cenários:
- * - findById: carrega recursivamente todos os relacionamentos
- * - findMany: carrega com otimização para listas
+ * Valida o carregamento de relacionamentos por cenário:
+ * - findById: carrega address e contacts (detalhe da entidade)
+ * - findMany: retorna apenas dados escalares (performance em listagens)
  */
 describe('RepositoryBase - Lazy Loading (E2E)', () => {
   let moduleRef: TestingModule;
@@ -75,8 +75,8 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
     });
   });
 
-  describe('findMany - Carregamento Otimizado para Listas', () => {
-    it('should load persons with relationships in findMany', async () => {
+  describe('findMany - Listagem sem Relacionamentos', () => {
+    it('should return persons without loading relationships in findMany', async () => {
       const createHandler = moduleRef.get(CreatePersonHandler);
 
       for (let i = 0; i < 2; i++) {
@@ -90,10 +90,7 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
       }
 
       const repository = moduleRef.get(IPersonRepository);
-      const query = Object.assign(new PersonQueryDto(), {
-        limit: 100,
-        page: 0,
-      });
+      const query = PersonQueryDto.from({ limit: 100, page: 0 });
       const { items } = await repository.findMany(query);
 
       expect(items.length).toBeGreaterThan(0);
@@ -101,8 +98,9 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
       const person = items[0];
       expect(person.id).toBeDefined();
       expect(person.name).toBeDefined();
-      expect(person.address).toBeDefined();
-      expect(person.contacts).toBeDefined();
+      expect(person.active).toBeDefined();
+      expect(person.address).toBeUndefined();
+      expect(person.contacts).toBeUndefined();
     });
 
     it('should load multiple persons efficiently', async () => {
@@ -136,12 +134,13 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
       result.items.forEach((person) => {
         expect(person.id).toBeDefined();
         expect(person.name).toBeDefined();
+        expect(person.active).toBeDefined();
       });
     });
   });
 
   describe('Comparação entre findById e findMany', () => {
-    it('should load relationships in both methods', async () => {
+    it('should load relationships only in findById', async () => {
       const createHandler = moduleRef.get(CreatePersonHandler);
       const created = await createHandler.handle({
         name: 'Comparação Test',
@@ -158,11 +157,9 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
       const personFromFindById = await readHandler.handle(created.id);
 
       const repository = moduleRef.get(IPersonRepository);
-      const query = Object.assign(new PersonQueryDto(), {
-        limit: 100,
-        page: 0,
-      });
-      const { items } = await repository.findMany(query);
+      const { items } = await repository.findMany(
+        PersonQueryDto.from({ limit: 100, page: 0 }),
+      );
       const personFromFindMany = items.find((p) => p.id === created.id);
 
       expect(personFromFindMany).toBeDefined();
@@ -173,9 +170,8 @@ describe('RepositoryBase - Lazy Loading (E2E)', () => {
       expect(personFromFindById.contacts).toBeDefined();
       expect(personFromFindById.contacts.length).toBeGreaterThan(0);
 
-      expect(personFromFindMany?.address).toBeDefined();
-      expect(personFromFindMany?.contacts).toBeDefined();
-      expect(personFromFindMany?.contacts.length).toBeGreaterThan(0);
+      expect(personFromFindMany?.address).toBeUndefined();
+      expect(personFromFindMany?.contacts).toBeUndefined();
     });
   });
 });