nestjs-performance

# Performance Tuning

## **Priority: P1 (OPERATIONAL)**

High-performance patterns and optimization techniques for NestJS applications.

## Workflow: Performance Audit

1. **Switch to Fastify** — Replace Express with `FastifyAdapter` for ~2x throughput.
2. **Enable compression** — Add Gzip/Brotli middleware.
3. **Audit provider scopes** — Ensure no unintended `REQUEST` scope chains.
4. **Add query projections** — Use `select: []` on all repository queries.
5. **Profile overhead** — Benchmark Total Duration, DB Execution, and API Overhead.

## Fastify + Compression Setup

See [implementation examples](references/example.md)

- **Keep-Alive**: Configure `http.Agent` keep-alive settings to reuse TCP connections for upstream services.

## Scope & Dependency Injection

- **Default Scope**: Adhere to `SINGLETON` scope (default).
- **Request Scope**: AVOID `REQUEST` scope unless absolutely necessary.
  - **Pro Tip**: A single request-scoped service makes its entire injection chain request-scoped.
  - **Solution**: Use **Durable Providers** (`durable: true`) for multi-tenancy.
- **Lazy Loading**: Use `LazyModuleLoader` for heavyweight modules (e.g., Admin panels).

## Caching Strategy

- **Application Cache**: Use `@nestjs/cache-manager` for computation results.
  - **Deep Dive**: See **[Caching & Redis](../nestjs-caching/SKILL.md)** for L1/L2 strategies and Invalidation patterns.
- **HTTP Cache**: Set `Cache-Control` headers for client-side caching (CDN/Browser).
- **Distributed**: In microservices, use Redis store, not memory store.

## Queues & Async Processing

- **Offloading**: Never block the HTTP request for long-running tasks (Emails, Reports, webhooks).
- **Tool**: Use `@nestjs/bull` (BullMQ) or RabbitMQ (`@nestjs/microservices`).
  - **Pattern**: Producer (Controller) -> Queue -> Consumer (Processor).

## Serialization

- **Warning**: `class-transformer` is CPU expensive.
- **Optimization**: For high-throughput READ endpoints, consider manual mapping or using `fast-json-stringify` (built-in fastify serialization) instead of interceptors.

## Database Tuning

- **Projections**: Always use `select: []` to fetch only needed columns.
- **N+1**: Prevent N+1 queries by using `relations` carefully or `DataLoader` for Graph/Field resolvers.
- **Connection Pooling**: Configure pool size (e.g., `pool: { min: 2, max: 10 }`) in config to match DB limits.

## Profiling & Scaling

- **API Overhead vs DB Execution**: Use an "Execution Bucket" strategy to continuously benchmark `Total Duration`, `DB Execution Time`, and `API Overhead`.
  - **Total Baseline**: Excellent (< 50ms), Acceptable (< 200ms), Poor (> 500ms). _Exception: Authentication routes (e.g. bcrypt/argon2) should take 300-500ms intentionally._
  - **DB Execution Baseline**: Excellent (< 5ms), Acceptable (< 30ms), Poor (> 100ms - implies missing index or N+1 problem).
  - **API Overhead Baseline**: Excellent (< 20ms), Poor (> 100ms - implies heavy synchronous processing or serialization blocking Node's event loop).
- **Offloading**: Move CPU-heavy tasks (Image processing, Crypto) to `worker_threads`.
- **Clustering**: For non-containerized environments, use `ClusterModule` to utilize all CPU cores. In K8s, prefer ReplicaSets.


## Anti-Patterns

- **No REQUEST scope without evaluation**: One REQUEST-scoped provider makes the entire chain request-scoped.
- **No CPU tasks in HTTP handler**: Offload image/crypto work to `worker_threads` or BullMQ.
- **No unprojected queries**: Always `select: []` the needed columns to avoid serializing unused data.