Nestjs Features Performance

NestJS Features, Scaling, and Performance

Choose the NestJS primitive whose lifecycle matches the concern. Diagnose the limiting resource before optimizing or distributing the system.

Pre-execution conflict guard

Before editing files or running any state-changing command, reconcile active instructions. Read-only inspection may continue.

Prerequisites

Inspect repository instructions, installed versions, bootstrap/transport and deployment configuration, tests, operational contracts, and baseline measurements. Preserve user changes; establish lifecycle, evidence, environment, and authorization before choosing an optimization or delivery action. Read other active skills only when their decisions overlap.

Primary ownership

This skill owns Nest lifecycle, API/error/security contracts, test layers, performance evidence, reliability, observability, and runtime delivery. When installed and relevant, coordinate with:

• nestjs-architecture-principles: module, dependency, data, and transaction boundaries.
• nestjs-oop-design-patterns: object responsibilities, invariants, and patterns.
• nestjs-professional-software-engineering: implementation and verification.
• nestjs-code-audit: read-only quality evidence and deduplicated reporting.
• nestjs-feature-audit: branch-specific roadmap gate and feature reporting.
• nestjs-git-commit-pr-message: authorized Git publication and CI follow-up.

These are decision boundaries, not required dependencies. Retain domain ownership when handing work to another workflow.

Conflict test

Check for incompatible edits/contracts, command order or side effects, competing owners, and unmet version, evidence, authorization, or repository prerequisites. Resolve using explicit user intent, repository contracts, verified runtime constraints, then the narrowest owner. Assign one lead per decision; do not create parallel designs to satisfy incompatible advice. If a material conflict remains, stop before mutation and ask for the smallest missing decision. Audits stay read-only; explicit fix authorization applies in a distinct implementation phase.

Establish the runtime baseline

Before recommending or changing behavior:

1. Read the installed NestJS/Node versions, bootstrap code, adapter, modules, transports, persistence clients, cache/queue setup, and deployment manifests.
2. Trace one representative request, message, or job through guards, pipes, interceptors, handlers, providers, persistence, and external calls.
3. Identify the current symptom and evidence: latency percentiles, throughput, error rate, event-loop delay, CPU, heap/GC, database time, pool saturation, external latency, or queue lag.
4. Define a target and workload. "Make it faster" is not a measurable acceptance criterion.
5. Check framework and library APIs against official documentation and the repository version.

Never claim a performance improvement from code appearance. Measure before and after under a representative workload.

Put behavior in the correct NestJS feature

Use references/feature-selection.md.

General HTTP lifecycle:

request
  -> middleware
  -> guards
  -> interceptors (before)
  -> pipes
  -> controller/resolver + providers
  -> interceptors (after, reverse order)
  -> exception filters for uncaught errors
  -> response

Defaults:

• Middleware: raw protocol preprocessing and correlation context.
• Guard: authentication/authorization decision for an execution context.
• Pipe: input validation and transformation.
• Interceptor: behavior around handler execution, response mapping, timing, tracing, or compatible caching.
• Exception filter: final protocol-specific error mapping.
• Decorator: declarative metadata or extraction of established context, not hidden I/O.
• Provider/application operation: business behavior and orchestration.
• Queue/worker: durable, deferred, bursty, or resource-heavy work.
• Event: a completed fact with independent reactions; choose in-process versus durable delivery explicitly.

For API and transport guidance, load references/api-runtime.md. Use the focused rulebooks for error handling, security, testing, API design, and deployment when those risks are in scope.

Diagnose performance by resource

Use references/performance-diagnosis.md.

Classify the primary constraint before selecting a remedy:

Do not switch to Fastify, add Redis, introduce worker threads, or split services before evidence identifies the bottleneck and compatibility cost is understood.

Scaling rules

Use references/scaling-reliability.md.

1. Keep web replicas stateless; move shared sessions, locks, job state, and coordination to appropriate external systems.
2. Prefer default singleton providers. Request scope propagates through the injection chain and adds per-request allocation; use only for a real lifetime requirement.
3. Bound every collection, page, batch, queue concurrency, retry count, payload, upload, and timeout.
4. Make jobs and message consumers idempotent. Assume duplicate delivery and partial failure.
5. Use exponential backoff with jitter for transient failures; never blindly retry validation, authorization, or invariant errors.
6. Add backpressure. Reject, shed, pause, or queue load instead of allowing unbounded memory and latency growth.
7. Separate user-facing processes from CPU-heavy or slow background work when their capacity profiles differ.
8. Treat caches as derived state. Define key namespace, TTL, invalidation, stampede behavior, and safe fallback.
9. Drain before shutdown: stop accepting work, mark unready, finish or safely requeue in-flight work, then close resources.
10. Scale from service-level objectives and saturation signals, not average CPU alone.

Implementation workflow

Add or change a feature

1. Locate the correct lifecycle stage and existing repository convention.
2. Define the contract, scope, and failure behavior.
3. Implement the smallest provider/component and bind it at the narrowest useful level.
4. Test its behavior in isolation and its ordering/wiring at a boundary.
5. Update OpenAPI/schema, configuration validation, telemetry, and docs when the public or operational contract changes.

Design or repair error handling

1. Inventory every entry point, current public error contract, filter binding, adapter/vendor error, client dependency, and partial side effect.
2. Classify expected business, validation, identity/access, conflict, transient, permanent, cancellation/timeout, and unknown failures without parsing messages.
3. Define the application-owned type/result and translate vendor failures at infrastructure adapters while preserving a safe cause.
4. Map each HTTP, GraphQL, RPC/gRPC, WebSocket, or worker boundary independently; keep one non-sensitive unknown fallback.
5. Define deadlines, cancellation, retry/idempotency, acknowledgement, transaction, and unknown-outcome behavior before adding recovery logic.
6. Bind the narrowest correct NestJS filter/handler and verify hybrid, gateway, adapter, stream, and process-fatal paths as applicable.
7. Test the stable contract, side effects, observability ownership, sensitive-data absence, and restart/recovery behavior.