REQUEST‑scoped Providers vs Custom Parameter Decorators for Per‑Request State

When to choose each approach

Use a REQUEST‑scoped provider when the request‑local data must be shared across multiple nested services or injected into other classes that are part of the same request tree. This avoids passing the value manually through method arguments.

Use a custom parameter decorator when you only need read‑only access to request metadata (e.g., user ID, headers) inside a controller or a single service method, and the value does not need to be propagated to other dependencies.

How NestJS propagates a REQUEST‑scoped provider

For each incoming request NestJS creates a child DI container scoped to that request. When a REQUEST‑scoped provider is requested, NestJS instantiates a single instance and injects the same instance into every dependent class in the request’s dependency tree. If a singleton service tries to depend on that provider, NestJS throws a resolution error during bootstrap:

Error: Nest can't resolve dependencies of the SingletonService (?).
Please make sure that the argument RequestScopedDto at index [0] is available in the Root context.

This error occurs because singletons are created once at application start, before any request scope exists.

Measurable performance differences

• REQUEST‑scoped provider: adds one object allocation per request (plus any dependencies of that object). Under sustained concurrent traffic this increases GC pressure and can raise pause times proportionally to request rate and object size.
• Parameter decorator: creates no extra objects; it merely reads from the existing ExecutionContext. GC impact is limited to the request’s native objects (e.g., the HTTP request).
• In practice, the difference is negligible for small primitives (e.g., a user ID string) but becomes measurable when the request‑local state holds large objects or complex graphs. Load‑testing with tools like Artillery or k6, while monitoring Node.js GC metrics (e.g., gc.pause_ms and heap used), will show the relative overhead.

Missing diagnostic detail that could change the recommendation

If you are unsure whether the request‑local state is large enough to affect GC, profile the average size of the object you intend to store (e.g., via process.memoryUsage() before and after creating it). If the size exceeds a few kilobytes per request, consider whether a parameter decorator combined with a lightweight service or a request‑scoped provider is more appropriate.