@koalarx/nest 3.1.50 → 4.0.2

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'bun:test';
+import { booleanSchema, envBooleanSchema } from '@/core/schemas/boolean.schema';
+import { documentNumberSchema } from '@/core/schemas/document-number.schema';
+import { setMaskDocumentNumber } from '@/core/schemas/document-number-mask';
+import { emailSchema } from '@/core/schemas/email.schema';
+import { LIST_QUERY_SCHEMA } from '@/core/schemas/list-query.schema';
+import { nativeEnumSchema } from '@/core/schemas/native-enum.schema';
+import {
+  personAddressSchema,
+  personBodySchema,
+  personContactSchema,
+} from '@/application/person/person.schemas';
+
+enum Status {
+  ACTIVE = 1,
+  INACTIVE = 2,
+}
+
+describe('core/schemas', () => {
+  it('booleanSchema converte query string para boolean', () => {
+    const schema = booleanSchema();
+
+    expect(schema.parse('true')).toBe(true);
+    expect(schema.parse('false')).toBe(false);
+    expect(schema.parse(undefined)).toBeUndefined();
+  });
+
+  it('envBooleanSchema interpreta "false" como false', () => {
+    const schema = envBooleanSchema(false);
+
+    expect(schema.parse('false')).toBe(false);
+    expect(schema.parse('true')).toBe(true);
+    expect(schema.parse(undefined)).toBe(false);
+  });
+
+  it('emailSchema valida e-mails opcionais e obrigatórios', () => {
+    expect(emailSchema('user@example.com')).toBe(true);
+    expect(emailSchema(undefined)).toBe(true);
+    expect(emailSchema(undefined, true)).toBe(false);
+    expect(emailSchema('invalid', true)).toBe(false);
+  });
+
+  it('nativeEnumSchema resolve enums numéricos', () => {
+    const schema = nativeEnumSchema(Status);
+
+    expect(schema.isRequired('1')).toBe(Status.ACTIVE);
+    expect(schema.isOptional('')).toBeUndefined();
+  });
+
+  it('documentNumberSchema valida CPF e CNPJ', () => {
+    expect(documentNumberSchema('529.982.247-25')).toBe(true);
+    expect(documentNumberSchema('11.222.333/0001-81')).toBe(true);
+    expect(documentNumberSchema('SK.CB2.G25/0001-32')).toBe(true);
+    expect(documentNumberSchema('123')).toBe(false);
+  });
+
+  it('setMaskDocumentNumber aplica máscara de CPF e CNPJ', () => {
+    expect(setMaskDocumentNumber('52998224725')).toBe('529.982.247-25');
+    expect(setMaskDocumentNumber('11222333000181')).toBe('11.222.333/0001-81');
+    expect(setMaskDocumentNumber('SKCB2G25000132')).toBe('SK.CB2.G25/0001-32');
+  });
+
+  it('LIST_QUERY_SCHEMA converte page 1-based para índice zero-based', () => {
+    expect(LIST_QUERY_SCHEMA.parse({ page: '2' }).page).toBe(1);
+    expect(LIST_QUERY_SCHEMA.parse({ page: '1' }).page).toBe(0);
+    expect(LIST_QUERY_SCHEMA.parse({}).page).toBeUndefined();
+  });
+
+  it('personBodySchema valida create e update de pessoa', () => {
+    expect(
+      personBodySchema().parse({
+        name: 'Jane',
+        address: { address: 'Street' },
+        contacts: [{ contact: 'jane@example.com' }],
+      }).name,
+    ).toBe('Jane');
+
+    expect(
+      personBodySchema(true).parse({
+        id: 1,
+        name: 'Jane',
+        address: { id: 2, address: 'Street' },
+        contacts: [{ id: 3, contact: 'jane@example.com' }],
+      }).id,
+    ).toBe(1);
+
+    expect(
+      personAddressSchema(true).parse({ id: 1, address: 'Street' }).id,
+    ).toBe(1);
+
+    expect(
+      personContactSchema(true).parse({ id: 1, contact: 'a@b.com' }).contact,
+    ).toBe('a@b.com');
+  });
+});

package/koala-nest/src/test/create-auth-e2e-test-app.ts

@@ -0,0 +1,22 @@
+import { AuthGuard } from '@/host/security/guards/auth.guard';
+import { ProfilesGuard } from '@/host/security/guards/profiles.guard';
+import { AppAuthTestModule } from '@/test/app-auth-test.module';
+import { initTestApp, setupTestApp } from '@/test/utils/configure-test-app';
+import { INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+
+export async function createAuthE2ETestApp(): Promise<INestApplication> {
+  const moduleRef = await Test.createTestingModule({
+    imports: [AppAuthTestModule],
+  }).compile();
+
+  const app = moduleRef.createNestApplication();
+  setupTestApp(app);
+
+  app.useGlobalGuards(
+    await app.resolve(AuthGuard),
+    await app.resolve(ProfilesGuard),
+  );
+
+  return initTestApp(app);
+}

package/koala-nest/src/test/create-e2e-test-app.ts

@@ -0,0 +1,14 @@
+import { AppTestModule } from '@/test/app-test.module';
+import { initTestApp, setupTestApp } from '@/test/utils/configure-test-app';
+import { INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+
+export async function createE2ETestApp(): Promise<INestApplication> {
+  const moduleRef = await Test.createTestingModule({
+    imports: [AppTestModule],
+  }).compile();
+
+  const app = moduleRef.createNestApplication();
+  setupTestApp(app);
+  return initTestApp(app);
+}

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

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

package/koala-nest/src/test/host/controllers/auth/auth.controller.e2e.spec.ts

@@ -0,0 +1,87 @@
+/// <reference types="bun-types/test-globals" />
+
+import { createAuthE2ETestApp } from '@/test/create-auth-e2e-test-app';
+import { AUTH_ROUTER_CONFIG } from '@/host/controllers/auth/router.config';
+import { PERSON_ROUTER_CONFIG } from '@/host/controllers/person/router.config';
+import type { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+
+describe('Auth (E2E)', () => {
+  let app: INestApplication;
+  let accessToken: string;
+  let refreshToken: string;
+
+  beforeAll(async () => {
+    app = await createAuthE2ETestApp();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('autentica com email e senha demo', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`${AUTH_ROUTER_CONFIG.group}/login`)
+      .send({ username: 'admin@example.com', password: 'admin123' });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.accessToken).toEqual(expect.any(String));
+    expect(response.body.refreshToken).toEqual(expect.any(String));
+
+    accessToken = response.body.accessToken;
+    refreshToken = response.body.refreshToken;
+  });
+
+  it('retorna dados do usuário autenticado', async () => {
+    const response = await request(app.getHttpServer())
+      .get(`${AUTH_ROUTER_CONFIG.group}/user-info`)
+      .set('Authorization', `Bearer ${accessToken}`);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.email).toBe('admin@example.com');
+    expect(response.body.profile).toBe('admin');
+  });
+
+  it('renova tokens via refresh token no header Authorization', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`${AUTH_ROUTER_CONFIG.group}/refresh`)
+      .set('Authorization', `Bearer ${refreshToken}`);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.accessToken).toEqual(expect.any(String));
+    expect(response.body.refreshToken).toEqual(expect.any(String));
+    expect(response.body.accessToken).not.toBe(accessToken);
+
+    accessToken = response.body.accessToken;
+  });
+
+  it('renova tokens via cookie refreshToken em /auth/refresh', async () => {
+    const response = await request(app.getHttpServer())
+      .post(`${AUTH_ROUTER_CONFIG.group}/refresh`)
+      .set('Cookie', [`refreshToken=${refreshToken}`]);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.accessToken).toEqual(expect.any(String));
+    expect(response.body.refreshToken).toEqual(expect.any(String));
+  });
+
+  it('bloqueia rota protegida sem token', async () => {
+    const response = await request(app.getHttpServer()).get(
+      PERSON_ROUTER_CONFIG.group,
+    );
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  it('permite rota protegida com token válido', async () => {
+    const response = await request(app.getHttpServer())
+      .get(PERSON_ROUTER_CONFIG.group)
+      .set('Authorization', `Bearer ${accessToken}`);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toEqual({
+      items: expect.any(Array),
+      count: expect.any(Number),
+    });
+  });
+});

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

@@ -0,0 +1,181 @@
+/// <reference types="bun-types/test-globals" />
+
+import { CreatePersonHandler } from '@/application/person/create/create-person.handler';
+import { ReadManyPersonHandler } from '@/application/person/read-many/read-many-person.handler';
+import { ReadManyPersonRequest } from '@/application/person/read-many/read-many-person.request';
+import { ReadPersonHandler } from '@/application/person/read/read-person.handler';
+import { AppTestModule } from '@/test/app-test.module';
+import { PersonQueryDto } from '@/domain/dtos/person-query.dto';
+import { IPersonRepository } from '@/domain/repositories/iperson.repository';
+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
+ */
+describe('RepositoryBase - Lazy Loading (E2E)', () => {
+  let moduleRef: TestingModule;
+
+  beforeAll(async () => {
+    moduleRef = await Test.createTestingModule({
+      imports: [AppTestModule],
+    }).compile();
+  });
+
+  describe('findById - Carregamento de Relacionamentos', () => {
+    it('should load person with all relationships using findById', async () => {
+      const createHandler = moduleRef.get(CreatePersonHandler);
+      const created = await createHandler.handle({
+        name: 'João Silva',
+        contacts: [
+          { contact: 'joao@example.com' },
+          { contact: 'joao.silva@example.com' },
+        ],
+        address: {
+          address: 'Rua Principal, 123 - São Paulo',
+        },
+      });
+
+      const readHandler = moduleRef.get(ReadPersonHandler);
+      const person = await readHandler.handle(created.id);
+
+      expect(person.id).toBe(created.id);
+      expect(person.name).toBe('João Silva');
+      expect(person.address).toBeDefined();
+      expect(person.address.address).toBe('Rua Principal, 123 - São Paulo');
+      expect(person.contacts).toBeDefined();
+      expect(person.contacts.length).toBe(2);
+      expect(person.contacts.map((c) => c.contact).sort()).toEqual([
+        'joao.silva@example.com',
+        'joao@example.com',
+      ]);
+    });
+
+    it('should have all relationships loaded and accessible', async () => {
+      const createHandler = moduleRef.get(CreatePersonHandler);
+      const created = await createHandler.handle({
+        name: 'Test Person',
+        contacts: [{ contact: 'test@example.com' }],
+        address: {
+          address: 'Test Address',
+        },
+      });
+
+      const readHandler = moduleRef.get(ReadPersonHandler);
+      const person = await readHandler.handle(created.id);
+
+      expect(person.id).toBe(created.id);
+      expect(person.address).toBeDefined();
+      expect(person.address.address).toBeDefined();
+      expect(person.contacts).toBeDefined();
+      expect(person.contacts.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('findMany - Carregamento Otimizado para Listas', () => {
+    it('should load persons with relationships in findMany', async () => {
+      const createHandler = moduleRef.get(CreatePersonHandler);
+
+      for (let i = 0; i < 2; i++) {
+        await createHandler.handle({
+          name: `Pessoa ${i + 1}`,
+          contacts: [{ contact: `contact${i}@example.com` }],
+          address: {
+            address: `Rua ${i + 1}, 100`,
+          },
+        });
+      }
+
+      const repository = moduleRef.get(IPersonRepository);
+      const query = Object.assign(new PersonQueryDto(), {
+        limit: 100,
+        page: 0,
+      });
+      const { items } = await repository.findMany(query);
+
+      expect(items.length).toBeGreaterThan(0);
+
+      const person = items[0];
+      expect(person.id).toBeDefined();
+      expect(person.name).toBeDefined();
+      expect(person.address).toBeDefined();
+      expect(person.contacts).toBeDefined();
+    });
+
+    it('should load multiple persons efficiently', async () => {
+      const createHandler = moduleRef.get(CreatePersonHandler);
+
+      const createdIds: number[] = [];
+      for (let i = 0; i < 3; i++) {
+        const result = await createHandler.handle({
+          name: `ListPerson ${i + 1}`,
+          contacts: [{ contact: `list${i}@example.com` }],
+          address: {
+            address: `Rua Lista ${i + 1}`,
+          },
+        });
+        createdIds.push(result.id);
+      }
+
+      expect(createdIds.length).toBe(3);
+
+      const readManyHandler = moduleRef.get(ReadManyPersonHandler);
+      const result = await readManyHandler.handle(new ReadManyPersonRequest());
+
+      expect(result.items.length).toBeGreaterThan(0);
+      expect(result.count).toBeGreaterThan(0);
+
+      const returnedIds = result.items.map((p) => p.id);
+      createdIds.forEach((id) => {
+        expect(returnedIds).toContain(id);
+      });
+
+      result.items.forEach((person) => {
+        expect(person.id).toBeDefined();
+        expect(person.name).toBeDefined();
+      });
+    });
+  });
+
+  describe('Comparação entre findById e findMany', () => {
+    it('should load relationships in both methods', async () => {
+      const createHandler = moduleRef.get(CreatePersonHandler);
+      const created = await createHandler.handle({
+        name: 'Comparação Test',
+        contacts: [
+          { contact: 'first@example.com' },
+          { contact: 'second@example.com' },
+        ],
+        address: {
+          address: 'Rua Comparação, 789',
+        },
+      });
+
+      const readHandler = moduleRef.get(ReadPersonHandler);
+      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 personFromFindMany = items.find((p) => p.id === created.id);
+
+      expect(personFromFindMany).toBeDefined();
+      expect(personFromFindById.id).toBe(personFromFindMany!.id);
+      expect(personFromFindById.name).toBe(personFromFindMany!.name);
+
+      expect(personFromFindById.address).toBeDefined();
+      expect(personFromFindById.contacts).toBeDefined();
+      expect(personFromFindById.contacts.length).toBeGreaterThan(0);
+
+      expect(personFromFindMany?.address).toBeDefined();
+      expect(personFromFindMany?.contacts).toBeDefined();
+      expect(personFromFindMany?.contacts.length).toBeGreaterThan(0);
+    });
+  });
+});

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

@@ -0,0 +1,148 @@
+/// <reference types="bun-types/test-globals" />
+
+import { createE2ETestApp } from '@/test/create-e2e-test-app';
+import type { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { PERSON_ROUTER_CONFIG } from '@/host/controllers/person/router.config';
+
+describe('CRUD OF PERSON', () => {
+  let app: INestApplication;
+  let personId: number;
+  let addressId: number;
+
+  beforeAll(async () => {
+    app = await createE2ETestApp();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('should create a person', async () => {
+    const response = await request(app.getHttpServer())
+      .post(PERSON_ROUTER_CONFIG.group)
+      .send({
+        name: 'John Doe',
+        contacts: [],
+        address: {
+          address: 'Street 1',
+        },
+      });
+
+    personId = response.body.id;
+
+    expect(response.statusCode).toBe(201);
+    expect(response.body).toStrictEqual({
+      id: expect.any(Number),
+    });
+  });
+
+  it('should get the created person', async () => {
+    const response = await request(app.getHttpServer()).get(
+      `${PERSON_ROUTER_CONFIG.group}/${personId}`,
+    );
+
+    addressId = response.body.address.id;
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toStrictEqual({
+      id: personId,
+      name: 'John Doe',
+      contacts: [],
+      address: {
+        id: expect.any(Number),
+        address: 'Street 1',
+      },
+      active: true,
+    });
+  });
+
+  it('should get all persons', async () => {
+    const response = await request(app.getHttpServer()).get(
+      PERSON_ROUTER_CONFIG.group,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.count).toBeGreaterThanOrEqual(1);
+    expect(response.body.items).toContainEqual({
+      id: personId,
+      name: 'John Doe',
+      active: true,
+    });
+  });
+
+  it('should get all inactive persons', async () => {
+    const response = await request(app.getHttpServer()).get(
+      `${PERSON_ROUTER_CONFIG.group}?active=false`,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toStrictEqual({
+      items: [],
+      count: 0,
+    });
+  });
+
+  it('should get persons by name', async () => {
+    const response = await request(app.getHttpServer()).get(
+      `${PERSON_ROUTER_CONFIG.group}?name=John`,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toStrictEqual({
+      items: [
+        {
+          id: personId,
+          name: 'John Doe',
+          active: true,
+        },
+      ],
+      count: 1,
+    });
+  });
+
+  it('should update the created person', async () => {
+    const updateResponse = await request(app.getHttpServer())
+      .put(PERSON_ROUTER_CONFIG.group)
+      .send({
+        id: personId,
+        name: 'John Doe Updated',
+        contacts: [],
+        address: {
+          id: addressId,
+          address: 'Street 2',
+        },
+      });
+
+    expect(updateResponse.statusCode).toBe(200);
+
+    const response = await request(app.getHttpServer()).get(
+      `${PERSON_ROUTER_CONFIG.group}/${personId}`,
+    );
+
+    expect(response.body).toStrictEqual({
+      id: personId,
+      name: 'John Doe Updated',
+      contacts: [],
+      address: {
+        id: addressId,
+        address: 'Street 2',
+      },
+      active: true,
+    });
+  });
+
+  it('should delete the created person', async () => {
+    const deleteResponse = await request(app.getHttpServer()).delete(
+      `${PERSON_ROUTER_CONFIG.group}/${personId}`,
+    );
+
+    expect(deleteResponse.statusCode).toBe(204);
+
+    const response = await request(app.getHttpServer()).get(
+      `${PERSON_ROUTER_CONFIG.group}/${personId}`,
+    );
+
+    expect(response.statusCode).toBe(404);
+  });
+});

package/koala-nest/src/test/host/errors.filter.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { ArgumentsHost, HttpStatus } from '@nestjs/common';
+import { ErrorsFilter } from '@/host/filters/errors.filter';
+import { ILoggingService } from '@/domain/common/ilogging.service';
+import { z } from 'zod';
+
+function createHost() {
+  const json = mock(() => undefined);
+  const status = mock(() => ({ json }));
+
+  return {
+    host: {
+      switchToHttp: () => ({
+        getResponse: () => ({ status }),
+        getRequest: () => ({
+          method: 'POST',
+          url: '/person',
+          body: {},
+          headers: {},
+          ip: '127.0.0.1',
+        }),
+      }),
+    } as unknown as ArgumentsHost,
+    status,
+    json,
+  };
+}
+
+describe('ErrorsFilter', () => {
+  it('formata ZodError como HTTP 400', async () => {
+    const loggingService = {
+      report: mock(async () => undefined),
+    } as unknown as ILoggingService;
+    const filter = new ErrorsFilter(undefined, loggingService);
+    const { host, status, json } = createHost();
+
+    await filter.catch(
+      z.object({ name: z.string() }).safeParse({}).error!,
+      host,
+    );
+
+    expect(status).toHaveBeenCalledWith(HttpStatus.BAD_REQUEST);
+    expect(json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        statusCode: HttpStatus.BAD_REQUEST,
+        errors: expect.arrayContaining([
+          expect.objectContaining({ field: 'name' }),
+        ]),
+      }),
+    );
+  });
+
+  it('reporta erros internos via ILoggingService', async () => {
+    const report = mock(async () => undefined);
+    const loggingService = { report } as unknown as ILoggingService;
+    const filter = new ErrorsFilter(undefined, loggingService);
+    const { host, status, json } = createHost();
+    const error = new Error('falha inesperada');
+
+    await filter.catch(error, host);
+
+    expect(report).toHaveBeenCalledWith(
+      expect.objectContaining({
+        error,
+        packageName: expect.any(String),
+        loggedUsername: expect.any(String),
+      }),
+    );
+    expect(status).toHaveBeenCalledWith(HttpStatus.INTERNAL_SERVER_ERROR);
+    expect(json).toHaveBeenCalledWith({
+      statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+      message: 'Erro interno do servidor.',
+    });
+  });
+});

package/koala-nest/src/test/host/is-public-open-api.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  applyAuthSecurityToProtectedRoutes,
+  IsPublic,
+  syncIsPublicRoutesInOpenApi,
+} from '@/host/decorators/is-public.decorator';
+import { Controller, Get, Module } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { Test } from '@nestjs/testing';
+
+@Controller('auth')
+class AuthController {
+  @Get('login')
+  @IsPublic()
+  login() {
+    return {};
+  }
+
+  @Get('profile')
+  profile() {
+    return {};
+  }
+}
+
+@Module({ controllers: [AuthController] })
+class AuthModule {}
+
+describe('IsPublic OpenAPI', () => {
+  it('protege todas as rotas e libera só as marcadas com @IsPublic', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AuthModule],
+    }).compile();
+    const app = moduleRef.createNestApplication();
+    await app.init();
+
+    const schemeNames = ['JWT', 'Google'];
+
+    const document = SwaggerModule.createDocument(
+      app,
+      new DocumentBuilder()
+        .addBearerAuth({ type: 'oauth2' } as never, 'JWT')
+        .addSecurityRequirements('JWT')
+        .addBearerAuth({ type: 'oauth2' } as never, 'Google')
+        .addSecurityRequirements('Google')
+        .build(),
+    );
+
+    syncIsPublicRoutesInOpenApi(document);
+    applyAuthSecurityToProtectedRoutes(document, schemeNames);
+
+    expect(document.paths?.['/auth/login']?.get?.security).toEqual([]);
+    expect(document.paths?.['/auth/profile']?.get?.security).toEqual([
+      { JWT: [] },
+      { Google: [] },
+    ]);
+    expect(document.security).toEqual([{ JWT: [] }, { Google: [] }]);
+
+    await app.close();
+  });
+});