Node.js + NestJS

# CLAUDE.md — Node.js + NestJS

## Mental model

- NestJS is opinionated DI + decorator-driven HTTP/microservice framework on top of Express or Fastify.
- Build for **modules**: a feature is a module that imports its dependencies and exports its public surface.
- Don't fight the conventions — when in doubt, do what the docs do.

## Module structure

```
src/users/
  users.module.ts
  users.controller.ts
  users.service.ts
  users.repository.ts
  dto/
    create-user.dto.ts
    update-user.dto.ts
  entities/
    user.entity.ts
  users.controller.spec.ts
  users.service.spec.ts
```

- One module per domain. Modules import other modules to use their providers — never reach into another module's `service` directly.
- Public surface = whatever the module `exports`. Keep it small.

## Providers (services)

- Annotate with `@Injectable()`. Constructor-inject dependencies — never `new` them.
- Services hold business logic. Controllers hold parsing and shape; repositories hold data access.
- Don't put HTTP concepts (status codes, request objects) in services.

## DTOs & validation

- One DTO per request shape. `class-validator` + `class-transformer` decorators on every field.
- Enable the global validation pipe in `main.ts`:
  ```ts
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }))
  ```
- `whitelist: true` strips unknown properties; `forbidNonWhitelisted` rejects them with 400.

## Controllers

- Thin. Decorators declare HTTP route, status code, response type. Body delegates to a service.
- `@HttpCode(204)` for no-content responses. Don't return `void` and let Nest pick.
- Use `@UseGuards(...)` for auth, `@UsePipes(...)` for per-route validation overrides.

## Pipes, guards, interceptors

- **Pipes** transform/validate. Use Nest's built-ins (`ValidationPipe`, `ParseUUIDPipe`) before custom ones.
- **Guards** authorize. One guard per concern.
- **Interceptors** wrap responses (logging, caching, transforms). Don't use them for auth — use guards.

## Configuration

- `@nestjs/config` with a Joi or Zod schema. Validate at boot.
- Inject `ConfigService` into providers; don't read `process.env` directly.

## Testing

- Unit-test services by constructing them with mocked deps. The Nest testing module is for integration tests, not units.
- For controller integration, use `Test.createTestingModule(...)` with overrides for external systems.
- Use **supertest** for full e2e tests against the bootstrapped app.

## Don't

- Don't bypass DI by importing a class and calling `new`.
- Don't put DB queries in controllers.
- Don't write circular module imports. Refactor — they signal a bad boundary.
- Don't expose entities directly in responses. Map to a Response DTO so DB renames don't break clients.