📖 Documentação

Acesse a documentação completa e interativa em: nest.koalarx.com

🤖 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

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

🎯 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 | Exemplo prático completo - API CRUD com todas as camadas DDD | | CLI Reference | Guia da CLI oficial - Forma rápida de criar projetos | | Guia de Instalação | Como instalar e configurar a biblioteca | | Configuração Inicial | Setup do projeto com KoalaNestModule e KoalaApp | | Tratamento de Erros | Sistema robusto de tratamento e filtros de exceção | | Features Avançadas | Cron Jobs, Event Handlers, Redis, Transações e Padrões de Autenticação | | Decoradores | @IsPublic, @Upload, @Cookies e mais | | Guia Bun | Por que Bun e como usá-lo | | Prisma Client | Integração com Prisma | | 🤖 Extensão MCP | 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:

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

# 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

# Com Bun (Recomendado - Mais rápido)
bun install @koalarx/nest

# Ou com npm (Alternativa)
npm install @koalarx/nest

2. Criar Módulo Principal

// 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

// 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

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 para implementação completa.

AutoMapping Automático

Converte Request → Entity → Response transparentemente:

// 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:

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:

@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:

// 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:

@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:

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:

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:

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 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:

# 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 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 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) - Ferramenta oficial para criar projetos rapidamente
• GitHub da Library - Repositório principal
• GitHub da 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.