@koalarx/nest 1.19.0 → 3.0.1

package/src/test/utils/create-e2e-database.ts

@@ -0,0 +1,55 @@
+import 'dotenv/config'
+import { execSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { Pool } from 'pg'
+
+function generateUniqueDatabaseURL() {
+  const schemaId = randomUUID()
+
+  if (!process.env.DATABASE_URL) {
+    throw new Error('Please provider a DATABASE_URL environment variable')
+  }
+
+  const url = new URL(process.env.DATABASE_URL)
+  url.pathname = `/${schemaId}`
+
+  return {
+    url: url.toString(),
+    schemaId,
+  }
+}
+
+export async function createE2EDatabase(runtime: 'node' | 'bun' = 'node') {
+  const { url, schemaId } = generateUniqueDatabaseURL()
+
+  process.env.DATABASE_URL = url
+  process.env.DIRECT_URL = url
+  process.env.PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK = 'true'
+
+  try {
+    // Conectar ao banco padrão para criar novo banco
+    const baseUrl = new URL(process.env.DATABASE_URL)
+    baseUrl.pathname = '/postgres'
+    const pool = new Pool({ connectionString: baseUrl.toString() })
+
+    try {
+      // Criar banco de dados
+      await pool.query(`CREATE DATABASE "${schemaId}"`)
+    } finally {
+      await pool.end()
+    }
+
+    // Executar migrations no novo banco com a variável de ambiente corrigida
+    const env = { ...process.env, DATABASE_URL: url, DIRECT_URL: url }
+    execSync(`${runtime}x prisma migrate deploy`, {
+      cwd: process.cwd(),
+      env,
+      stdio: 'inherit',
+    })
+  } catch (error) {
+    console.error('Erro ao criar banco de dados e2e:', error)
+    throw error
+  }
+
+  return schemaId
+}

package/src/test/utils/drop-e2e-database.ts

@@ -0,0 +1,36 @@
+import 'dotenv/config'
+import { Pool } from 'pg'
+
+export async function dropE2EDatabase(schemaId: string) {
+  await new Promise((resolve) => setTimeout(resolve, 1000))
+  const baseUrl = new URL(process.env.DATABASE_URL || '')
+  baseUrl.pathname = '/postgres'
+  const pool = new Pool({
+    connectionString: baseUrl.toString(),
+    idleTimeoutMillis: 100,
+  })
+
+  try {
+    // Terminate all connections to the database
+    await pool.query(`
+      SELECT pg_terminate_backend(pg_stat_activity.pid)
+      FROM pg_stat_activity
+      WHERE pg_stat_activity.datname = '${schemaId}'
+      AND pid <> pg_backend_pid()
+    `)
+
+    // Small delay to ensure connections are terminated
+    await new Promise((resolve) => setTimeout(resolve, 500))
+
+    // Drop the database
+    await pool.query(`DROP DATABASE IF EXISTS "${schemaId}"`)
+  } catch {
+    // Silently fail - connection may already be closed
+  } finally {
+    try {
+      await pool.end()
+    } catch {
+      // Ignore pool end errors
+    }
+  }
+}

package/src/test/utils/wait-for.ts

@@ -0,0 +1,31 @@
+/**
+ * This function loops through a function rerunning all assertions
+ * inside of it until it gets a truthy result.
+ *
+ * If the maximum duration is reached, it then rejects.
+ *
+ * @param expectations A function containing all tests assertions
+ * @param maxDuration Maximum wait time before rejecting
+ */
+export async function waitFor(
+  assertions: () => void,
+  maxDuration = 1000,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let elapsedTime = 0
+
+    const interval = setInterval(() => {
+      elapsedTime += 10
+
+      try {
+        assertions()
+        clearInterval(interval)
+        resolve()
+      } catch (err) {
+        if (elapsedTime >= maxDuration) {
+          reject(err)
+        }
+      }
+    }, 10)
+  })
+}

package/tsconfig.lib.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "sourceMap": false,
+  },
+  "exclude": [
+    "**/*.spec.ts",
+    "**/*.e2e-spec.ts"
+  ],
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Igor D. Rangel
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,499 +0,0 @@
-<p align="center">
-  <a href="https://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
-</p>
-
-<h1 align="center">@koalarx/nest</h1>
-
-<p align="center">Uma abstração <a href="https://nestjs.com" target="_blank">NestJS</a> robusta para criar APIs escaláveis seguindo os princípios do Domain-Driven Design (DDD).</p>
-
-<div align="center">
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Bun](https://img.shields.io/badge/Bun-1.3%2B-black)](https://bun.sh)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.1%2B-blue)](https://www.typescriptlang.org/)
-[![CLI](https://img.shields.io/badge/CLI-@koalarx/nest--cli-brightgreen)](https://www.npmjs.com/package/@koalarx/nest-cli)
-[![VS Code Extension](https://img.shields.io/badge/VS%20Code-MCP%20Extension-blue)](https://marketplace.visualstudio.com/items?itemName=koalarx.koala-libs-mcp-docs)
-
-</div>
-
-## 🤖 Extensão VS Code com MCP
-
-Acelere seu desenvolvimento com a **extensão oficial para VS Code**! Toda a documentação do Koala Nest integrada diretamente no GitHub Copilot através do Model Context Protocol.
-
-**[📦 Instalar Extensão](https://marketplace.visualstudio.com/items?itemName=koalarx.koala-libs-mcp-docs)**
-
-Basta instalar e perguntar ao Copilot sobre o Koala Nest - ele terá acesso instantâneo à documentação oficial!
-
-> 💡 **Exemplo:** "Como criar um controller CRUD no Koala Nest?" - O Copilot responderá com base na documentação atualizada.
-
-**[📖 Documentação da Extensão MCP](./docs/09-mcp-vscode-extension.md)**
-
-## 🎯 O que você consegue fazer com @koalarx/nest
-
-- ✅ **Implementar APIs REST completas** com CRUD automático
-- ✅ **AutoMapping** transparente entre Request, Entity e Response
-- ✅ **Validação automática** com Zod integrado
-- ✅ **Testes unitários e E2E** simplificados
-- ✅ **CronJobs** com suporte a múltiplos pods via Redis
-- ✅ **EventJobs** para processamento assíncrono de eventos
-- ✅ **Paginação** automaticamente documentada
-- ✅ **Documentação OpenAPI (Swagger ou Scalar)** automática
-
-## 📚 Documentação Completa
-
-Toda a documentação está organizada em arquivos separados para facilitar a navegação:
-
-| Documento | Descrição |
-|-----------|-----------|
-| [**EXAMPLE.md**](./docs/EXAMPLE.md) | **Exemplo prático completo** - API CRUD com todas as camadas DDD |
-| [**CLI Reference**](./docs/00-cli-reference.md) | Guia da CLI oficial - Forma rápida de criar projetos |
-| [**Guia de Instalação**](./docs/01-guia-instalacao.md) | Como instalar e configurar a biblioteca |
-| [**Configuração Inicial**](./docs/02-configuracao-inicial.md) | Setup do projeto com KoalaNestModule e KoalaApp |
-| [**Tratamento de Erros**](./docs/04-tratamento-erros.md) | Sistema robusto de tratamento e filtros de exceção |
-| [**Features Avançadas**](./docs/05-features-avancadas.md) | Cron Jobs, Event Handlers, Redis, Transações e Padrões de Autenticação |
-| [**Decoradores**](./docs/06-decoradores.md) | @IsPublic, @Upload, @Cookies e mais |
-| [**Guia Bun**](./docs/07-guia-bun.md) | Por que Bun e como usá-lo |
-| [**Prisma Client**](./docs/08-prisma-client.md) | Integração com Prisma |
-| [**🤖 Extensão MCP**](./docs/09-mcp-vscode-extension.md) | **Extensão VS Code com integração ao Copilot** |
-
-## Quick Start
-
-### Usando Bun (Recomendado - Mais Rápido)
-
-O projeto agora usa **Bun** como runtime JavaScript. Para instalar o Bun:
-
-```bash
-# Instalar Bun (Windows, macOS, Linux)
-curl -fsSL https://bun.sh/install | bash
-
-# Ou em Windows com PowerShell:
-powershell -Command "irm https://bun.sh/install.ps1 | iex"
-
-# Instalar dependências
-bun install
-
-# Iniciar em modo desenvolvimento
-bun run start:dev
-
-# Executar testes
-bun run test
-
-# Fazer build
-bun run build
-```
-
-**Vantagens do Bun:**
-- ⚡ Runtime ~3x mais rápido que Node.js
-- 📦 Package manager integrado (mais rápido que npm)
-- 🧪 Test runner nativo (compatível com Vitest)
-- 🔄 Hot reload automático
-- 💾 Menor consumo de memória
-
-### Forma Rápida com CLI (Recomendado)
-
-```bash
-# Instalar a CLI globalmente
-npm install -g @koalarx/nest-cli
-
-# Criar novo projeto estruturado
-koala-nest new meu-projeto
-
-# Entrar na pasta
-cd meu-projeto
-
-# Iniciar em modo desenvolvimento (com Bun)
-bun run start:dev
-```
-
-**Pronto!** Seu projeto está estruturado com:
-- [x] Módulo DDD configurado
-- [x] Documentação da API (Scalar UI)
-- [x] Tratamento de erros robusto
-- [x] Banco de dados Prisma
-- [x] Redis para background services
-
-### Forma Manual
-
-> ⚠️ **Requisito Obrigatório**: A abstração de banco de dados da biblioteca requer **Prisma como ORM**. 
->
-> **💡 Dica**: Para um exemplo completo e funcionando, veja [docs/EXAMPLE.md](./docs/EXAMPLE.md)
-
-```bash
-# Com Bun (Recomendado - Mais rápido)
-bun install @koalarx/nest
-
-# Ou com npm (Alternativa)
-npm install @koalarx/nest
-```
-
-### 2. Criar Módulo Principal
-
-```typescript
-// src/host/app.module.ts
-import { KoalaNestModule } from '@koalarx/nest/core/koala-nest.module'
-import { Module } from '@nestjs/common'
-import { env } from '../core/env'
-// Importar seus módulos de controllers
-// import { PersonModule } from './controllers/person/person.module'
-
-@Module({
-  imports: [
-    KoalaNestModule.register({
-      env,
-      // controllers: [PersonModule], // Adicione seus módulos aqui
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### 3. Inicializar Aplicação
-
-```typescript
-// src/host/main.ts
-import { NestFactory } from '@nestjs/core'
-import { KoalaApp } from '@koalarx/nest/core/koala-app'
-import { AppModule } from './app.module'
-import { DbTransactionContext } from '@/infra/database/db-transaction-context'
-import { setPrismaClientOptions } from '@koalarx/nest/core/database/prisma.service'
-import { PrismaPg } from '@prisma/adapter-pg'
-import { Pool } from 'pg'
-import 'dotenv/config'
-
-async function bootstrap() {
-  // Configurar Prisma com adapter PostgreSQL
-  const pool = new Pool({
-    connectionString: process.env.DATABASE_URL,
-  })
-  const adapter = new PrismaPg(pool)
-  setPrismaClientOptions({ adapter })
-
-  // Criar aplicação NestJS
-  const app = await NestFactory.create(AppModule)
-  
-  // Configurar e iniciar KoalaApp
-  await new KoalaApp(app)
-    .useDoc({
-      ui: 'scalar',
-      endpoint: '/doc',
-      title: 'API de Demonstração',
-      version: '1.0',
-    })
-    .setAppName('example')
-    .setInternalUserName('integration.bot')
-    .setDbTransactionContext(DbTransactionContext)
-    .enableCors()
-    .buildAndServe()
-}
-
-bootstrap()
-```
-
-### 4. Executar
-
-```bash
-npm run start:dev
-```
-
-Acesse `http://localhost:3000/doc` para a documentação interativa!
-
-## Principais Features
-
-### Camadas DDD (Domain-Driven Design)
-
-A biblioteca implementa um padrão com 4 camadas bem definidas:
-
-1. **Domain** - Entidades, DTOs e interfaces de repositório
-2. **Application** - Handlers com lógica de negócio, Validators, AutoMapping
-3. **Host** - Controllers REST que expõem os endpoints
-4. **Infra** - Repositórios concretos e acesso ao banco de dados
-
-Veja [docs/EXAMPLE.md](./docs/EXAMPLE.md) para implementação completa.
-
-### AutoMapping Automático
-
-Converte Request → Entity → Response transparentemente:
-
-```typescript
-// Define os mapeamentos
-createMap(CreatePersonRequest, Person)
-createMap(Person, ReadPersonResponse)
-
-// Usa automaticamente
-const person = mapper.map(request, CreatePersonRequest, Person)
-const response = mapper.map(entity, Person, ReadPersonResponse)
-```
-
-### Validação com Zod
-
-Validação tipada integrada com transformação de dados:
-
-```typescript
-export class CreatePersonValidator extends RequestValidatorBase<CreatePersonRequest> {
-  protected get schema(): ZodType<any, ZodTypeDef, any> {
-    return z.object({
-      name: z.string(),
-      phones: z.array(z.object({ phone: z.string() })),
-      address: z.object({ address: z.string() }),
-    })
-  }
-}
-```
-
-### Handlers e RequestResult
-
-Padrão funcional para tratamento de sucesso/erro:
-
-```typescript
-@Injectable()
-export class CreatePersonHandler extends RequestHandlerBase<...> {
-  async handle(req: CreatePersonRequest): Promise<RequestResult<Error, CreatePersonResponse>> {
-    const person = this.mapper.map(
-      new CreatePersonValidator(req).validate(),
-      CreatePersonRequest,
-      Person,
-    )
-    const result = await this.repository.save(person)
-    return ok({ id: result.id })
-  }
-}
-
-// Controller
-const response = await handler.handle(request)
-if (response.isFailure()) {
-  throw response.value
-}
-return response.value
-```
-
-### Paginação Automática
-
-Queries com paginação documentada automaticamente:
-
-```typescript
-// Requisição
-GET /person?name=John&active=true&page=1&pageSize=10
-
-// Response com count
-{
-  "items": [...],
-  "count": 5
-}
-```
-
-### CronJobs com Redis (Sincronização)
-
-Tarefas agendadas com lock automático via RedLock em ambientes multi-pod:
-
-```typescript
-@Injectable()
-export class DeleteInactiveJob extends CronJobHandlerBase {
-  protected async settings(): Promise<CronJobSettings> {
-    return {
-      isActive: true,
-      timeInMinutes: 1,
-    }
-  }
-
-  protected async run(): Promise<CronJobResponse> {
-    // Executa apenas em um pod por vez
-    const result = await this.readManyPerson.handle(
-      new ReadManyPersonDto({ active: false })
-    )
-    
-    if (result.isOk()) {
-      for (const person of result.value.items) {
-        await this.deletePerson.handle(person.id)
-      }
-    }
-    
-    return ok(null)
-  }
-}
-```
-
-### EventJobs - Processamento Assíncrono
-
-Processamento de eventos assincronamente:
-
-```typescript
-export class PersonEventJob extends EventJob<Person> {
-  defineHandlers(): Type<EventHandlerBase>[] {
-    return [InactivePersonHandler]
-  }
-}
-
-@Injectable()
-export class InactivePersonHandler extends EventHandlerBase {
-  async handleEvent(): Promise<void> {
-    const result = await this.repository.readMany(
-      new ReadManyPersonDto({ active: true })
-    )
-    
-    for (const person of result.items) {
-      person.active = false
-      await this.repository.save(person)
-    }
-  }
-}
-
-// Registrar na aplicação
-.addEventJob(InactivePersonHandler)
-```
-
-### Testes Unitários
-
-Setup simplificado com dependências injetadas:
-
-```typescript
-describe('CreatePersonHandler', () => {
-  const app = createUnitTestApp()
-
-  it('should create a person', async () => {
-    const handler = app.get(CreatePersonHandler)
-    const result = await handler.handle(createPersonRequestMockup)
-
-    expect(result.isOk()).toBeTruthy()
-    if (result.isOk()) {
-      expect(result.value).toEqual({
-        id: expect.any(Number),
-      })
-    }
-  })
-})
-```
-
-### Testes E2E
-
-Testes de integração completos:
-
-```typescript
-const app = await createE2ETestApp()
-
-it('should create a person', async () => {
-  const response = await request(app.getHttpServer())
-    .post('/person')
-    .send({
-      name: 'John Doe',
-      phones: [],
-      address: { address: 'Street 1' },
-    })
-
-  expect(response.statusCode).toBe(201)
-  expect(response.body.id).toBeDefined()
-})
-```
-
-## Exemplo Prático Completo
-
-Veja em [docs/EXAMPLE.md](./docs/EXAMPLE.md) um CRUD completo de **Pessoa** implementado com:
-
-- ✅ Entidades (Person, PersonAddress, PersonPhone)
-- ✅ DTOs com paginação (ReadManyPersonDto)
-- ✅ 5 Handlers (Create, Read, ReadMany, Update, Delete)
-- ✅ 5 Controllers REST
-- ✅ Repository com Prisma
-- ✅ Testes unitários e E2E
-- ✅ CronJobs e EventJobs
-- ✅ AutoMapping automático
-- ✅ Validação com Zod
-
-## Estrutura de Projeto Recomendada
-
-Seguindo DDD conforme implementado no exemplo:
-
-```
-apps/
-├── example/              # Projeto exemplo
-│   └── src/
-│       ├── domain/       # Entidades, DTOs, Interfaces
-│       ├── application/  # Handlers, Validators, Mapping
-│       ├── host/         # Controllers, Roteamento
-│       ├── infra/        # Repositories, Database
-│       ├── core/         # Configuração
-│       └── test/         # Setup de testes
-└── koala-nest/           # Biblioteca principal
-
-prisma/
-├── schema.prisma         # Modelo de dados
-├── migrations/           # Histórico de migrações
-└── generated/            # Cliente Prisma gerado
-```
-
-## Configuração de Ambiente
-
-Crie seu `.env`:
-
-```env
-# Banco de dados
-DATABASE_URL=postgresql://user:password@localhost:5432/koala_db
-
-# Aplicação
-NODE_ENV=develop
-
-# Prisma (opcional - habilita logs das queries)
-PRISMA_QUERY_LOG=true
-
-# Swagger/Scalar (opcional)
-SWAGGER_USERNAME=admin
-SWAGGER_PASSWORD=password123
-
-# Redis (opcional - necessário para CronJobs em múltiplas instâncias)
-REDIS_CONNECTION_STRING=redis://localhost:6379
-```
-
-Consulte [docs/02-configuracao-inicial.md](./docs/02-configuracao-inicial.md) para mais detalhes.
-
-## Recursos Adicionais
-
-A biblioteca inclui vários decoradores e utilitários para facilitar o desenvolvimento:
-
-- **@ApiPropertyEnum()** - Documente enums corretamente no Swagger
-- **@ApiPropertyOnlyDevelop()** - Propriedades apenas em ambiente de desenvolvimento
-- **@ApiExcludeEndpointDiffDevelop()** - Endpoints apenas em dev (excluídos em produção)
-- **@Upload()** - Documentação automática de uploads de arquivos
-- **@Cookies()** - Extrai cookies da requisição HTTP
-- **@IsPublic()** - Marca endpoint como público (sem validação de token)
-
-Veja [docs/06-decoradores.md](./docs/06-decoradores.md) para documentação completa.
-
-## Arquitetura
-
-A biblioteca utiliza duas classes principais:
-
-1. **KoalaNestModule** - Módulo NestJS com configuração
-2. **KoalaApp** - Classe fluent para setup da aplicação
-
-Ambas seguem o padrão de **Fluent Interface** para configuração clara e intuitiva.
-
-## Dependências Principais
-
-- `@nestjs/*` - Framework NestJS
-- `@prisma/client` - ORM Prisma
-- `zod` - Validação de dados
-- `ioredis` - Cliente Redis
-- `@nestjs/swagger` - Documentação automática
-
-## Links Importantes
-
-- **[CLI (@koalarx/nest-cli)](https://www.npmjs.com/package/@koalarx/nest-cli)** - Ferramenta oficial para criar projetos rapidamente
-- **[GitHub da Library](https://github.com/igordrangel/koala-nest)** - Repositório principal
-- **[GitHub da CLI](https://github.com/igordrangel/koala-nest-cli)** - Repositório da CLI
-
-## Licença
-
-MIT License © 2023-2025 Igor D. Rangel
-
-## Contribuindo
-
-Contribuições são bem-vindas! Abra uma issue ou pull request no repositório.
-
-## Suporte
-
-Para dúvidas, abra uma issue no repositório ou consulte a [documentação completa](./docs).
-
----
-
-<p align="center">
-  Feito para desenvolvedores NestJS
-</p>

package/core/backgroud-services/cron-service/cron-job.handler.base.d.ts

@@ -1,16 +0,0 @@
-import { ILoggingService } from '../../../services/logging/ilogging.service';
-import { IRedLockService } from '../../../services/redlock/ired-lock.service';
-import { RequestResult } from '../../request-overflow/request-result';
-export type CronJobResponse = RequestResult<Error, null>;
-export interface CronJobSettings {
-    isActive: boolean;
-    timeInMinutes: number;
-}
-export declare abstract class CronJobHandlerBase {
-    private readonly redlockService;
-    private readonly loggingService;
-    constructor(redlockService: IRedLockService, loggingService: ILoggingService);
-    protected abstract run(): Promise<CronJobResponse>;
-    protected abstract settings(): Promise<CronJobSettings>;
-    start(): Promise<void>;
-}