Dependency injection in nestrs

nestrs ships a synchronous, type-safe dependency injection container built on Rust’s TypeId system. When you call NestFactory::create::<AppModule>(), the framework traverses the module graph, builds a ProviderRegistry that maps each registered type to a factory, and injects dependencies by resolving Arc<T> fields from that registry. No runtime reflection, no string keys — every injection site is checked at compile time.

How the container works at runtime

ProviderRegistry is the heart of the DI system. It stores one entry per provider type, keyed by TypeId. When a type is requested, the registry calls the factory (the generated Injectable::construct), caches the result if the scope is Singleton, and returns an Arc<T>.

// From nestrs-core/src/lib.rs
pub struct ProviderRegistry {
    entries: HashMap<TypeId, ProviderEntry>,
}

impl ProviderRegistry {
    pub fn get<T>(&self) -> Arc<T>
    where
        T: Send + Sync + 'static,
    { /* resolve, construct, downcast */ }
}

The Module trait’s build() method returns a (ProviderRegistry, Router) pair. NestFactory composes these pairs from the entire module graph into a single registry and a merged Axum router, then wraps the registry in an Arc that is injected as Axum State.

The three provider scopes

Scope	`ProviderScope` variant	Behavior	NestJS equivalent
Singleton	`ProviderScope::Singleton`	One shared `Arc<T>` per application; constructed once, cached in a `OnceLock`	`Scope.DEFAULT`
Transient	`ProviderScope::Transient`	A fresh `Arc<T>` is constructed on every `registry.get::<T>()` call	`Scope.TRANSIENT`
Request	`ProviderScope::Request`	One `Arc<T>` per HTTP request, stored in a task-local cache	`Scope.REQUEST`

Set the scope with the #[injectable] attribute:

use nestrs::prelude::*;

#[injectable]
pub struct SingletonService; // default

#[injectable(scope = "transient")]
pub struct TransientService;

#[injectable(scope = "request")]
pub struct PerRequestService;

`ModuleRef` — dynamic resolution after build

ModuleRef is a thin handle to the root ProviderRegistry after the module graph is constructed. Use it when you need to resolve providers dynamically — for example, in plugins or conditional code — without injecting them as struct fields:

use nestrs::core::{DiscoveryService, ModuleRef};

// Obtain before calling into_router():
// let mref: ModuleRef = app.module_ref();

let discovery = DiscoveryService::new(mref);
let _provider_ids = discovery.get_providers();
let _route_specs = discovery.get_routes(); // useful for OpenAPI / diagnostics

ModuleRef::get::<T>() follows the same scope rules as the container: singletons return the cached instance, transients produce a new one.

// nestrs-core/src/module_ref.rs
impl ModuleRef {
    pub fn get<T: Send + Sync + 'static>(&self) -> Arc<T> {
        self.registry.get()
    }
}

`DiscoveryService`

DiscoveryService exposes two introspection surfaces:

get_providers() — Vec<TypeId> of every registered provider
get_provider_type_names() — debug-friendly Vec<&'static str> type names
get_routes() — all HTTP routes from the global RouteRegistry (useful for OpenAPI generation and diagnostics)

use nestrs::core::{DiscoveryService, ModuleRef};

let discovery = DiscoveryService::new(mref);
for name in discovery.get_provider_type_names() {
    println!("registered: {name}");
}
for route in discovery.get_routes() {
    println!("{} {}", route.method, route.path);
}

nestrs discovery is TypeId- and route-list-oriented. Unlike NestJS, there is no reflection over arbitrary metadata attached to class decorators.

NestJS DI concept mapping

NestJS concept	nestrs equivalent
`@Injectable()`	`#[injectable]`
`@Module({ providers })`	`#[module(providers = [...])]`
Constructor injection	`Arc<T>` fields resolved by `Injectable::construct`
`Scope.DEFAULT`	`ProviderScope::Singleton` (default)
`Scope.TRANSIENT`	`ProviderScope::Transient`
`Scope.REQUEST`	`ProviderScope::Request`
`useValue`	`registry.register_use_value::<T>(Arc<T>)` — or `register_use_value_with_lifecycle` to also drive the value’s `ProviderLifecycle` hooks
`useFactory`	`registry.register_use_factory::<T>(scope, \|reg\| Arc<T>)` — or `register_use_factory_with_lifecycle` for hook-aware factories
`useClass`	`registry.register_use_class::<T>()`
`ModuleRef`	`ModuleRef` from `nestrs::core`
`DiscoveryService`	`DiscoveryService` from `nestrs::core`
`OnModuleInit` / `OnApplicationBootstrap` / `OnApplicationShutdown` / `OnModuleDestroy`	`#[injectable]` async hooks on `Injectable` — and, for `useValue`/`useFactory` providers, the opt-in `ProviderLifecycle` trait (five default no-op hooks) via the `*_with_lifecycle` registration variants
`forwardRef`	`forward_ref::<T>()` in `#[module(imports = [...])]`
`ConfigModule.forRoot`	`ConfigurableModuleBuilder::for_root::<M>(options)`
`ConfigModule.forRootAsync`	`ConfigurableModuleBuilder::for_root_async::<M, _, _>(async_fn).await`

Overriding providers

Two surfaces exist for replacing a provider with a concrete instance, both backed by ProviderRegistry::override_provider::<T>(instance). Before controllers register — DynamicModuleBuilder. Overrides apply after the module graph’s providers are registered but before controllers are registered, so the generated handlers are wired against the overridden instances. This is how tests replace #[crud]’s hidden __PostCrudState provider with one backed by a real connection pool:

use nestrs::core::DynamicModuleBuilder;
use std::sync::Arc;

let dynamic_module = DynamicModuleBuilder::<PostsModule>::new()
    .override_provider::<__PostCrudState>(Arc::new(__PostCrudState::from_pool(pool)))
    .build();

let app = NestApplication::from_registry_and_router(
    std::sync::Arc::new(dynamic_module.registry),
    dynamic_module.router,
);

After the module graph is built — the application handle. NestApplication::registry() borrows the underlying Arc<ProviderRegistry> — the entry point tests use to reach override_provider when replacing a macro-generated #[injectable] state struct on an application they already hold. NestApplication::into_registry_and_router() yields the (registry, router) pair and from_registry_and_router() re-wraps it, so an application can be rebuilt around an overridden registry (the router is safe to reuse: controllers keep Clone Arcs of the state they were mounted with). An override preserves the provider’s declared scope (T::scope()): a request- or transient-scoped provider keeps its per-request / per-resolution semantics, and every resolution hands out the given instance — a request-scoped override therefore shares that one instance across requests. T must implement Injectable; the override entry keeps T’s lifecycle hooks.

Request-scoped providers

Request scope gives each HTTP request its own instance of a provider, isolated from other concurrent requests. This is useful for per-request caches, correlation IDs, or any state that must not leak between requests.

Enabling request scope

Call use_request_scope() on your NestApplication before listening:

NestFactory::create::<AppModule>()
    .use_request_scope()
    .listen_graceful(3000)
    .await;

Marking a provider as request-scoped

#[injectable(scope = "request")]
pub struct RequestContext {
    pub request_id: String,
}

Extracting request-scoped providers in handlers

Use the RequestScoped<T> Axum extractor:

use nestrs::prelude::*;
use std::sync::Arc;

#[routes(state = AppService)]
impl AppController {
    #[get("/trace")]
    pub async fn trace(
        State(service): State<Arc<AppService>>,
        RequestScoped(ctx): RequestScoped<RequestContext>,
    ) -> String {
        format!("request_id={}", ctx.request_id)
    }
}

nestrs stores the request-scoped cache in a tokio::task_local! variable. Every request gets a fresh, empty cache; the first call to registry.get::<T>() for a Request-scoped type within that task constructs and caches the instance for the lifetime of that request.

Without a request scope active, resolving a Request-scoped provider behaves like any other unresolvable provider: registry.try_get::<T>() returns None, while registry.get::<T>() panics with a message naming the fixes. Always enable use_request_scope() on the application before using the RequestScoped extractor.

Background work: `spawn_with_request_scope`

Task-locals do not cross tokio::spawn, so a bare tokio::spawn inside a handler runs with no request scope. Use spawn_with_request_scope for background work that resolves Request-scoped providers:

use nestrs::core::spawn_with_request_scope;

#[routes(state = AppService)]
impl AppController {
    #[get("/later")]
    pub async fn later(RequestScoped(ctx): RequestScoped<RequestContext>) -> String {
        let request_id = ctx.request_id.clone();
        spawn_with_request_scope(async move {
            // Resolves the same `RequestContext` instance the request had
            // at spawn time (snapshot semantics).
            tracing::info!("background job for {request_id}");
        });
        "spawned".to_string()
    }
}

Spawned inside a request, the child receives a snapshot of the request scope: it resolves the same request-scoped instances the request had at spawn time (including any in-flight transaction slot). Values constructed or inserted after the spawn stay private to whichever side created them.
Spawned outside any scope (scheduler, startup job), the child gets a fresh empty scope — request-scoped providers construct per spawned task and are isolated from every other task.
The ability / principal slots are deliberately not carried: row-level authz stays deny-closed in the spawned task unless you explicitly wrap the future with the ability helpers.

Circular provider dependencies

If two providers each depend on the other, nestrs detects the cycle during construction and panics:

Circular provider dependency detected: TypeA -> TypeB -> TypeA

Fixes:

Split the shared concern into a third type that both depend on.
Defer work to on_module_init so construct only wires Arcs without triggering the cycle.
Use register_use_factory with a closure that resolves one side lazily on first use.

There is no forwardRef for individual providers — cycles must be broken in code structure or initialization order.

Get Started

Core Concepts

Guides

Ecosystem

Adapters

CLI

Migration

Dependency injection in nestrs

How the container works at runtime

The three provider scopes

`ModuleRef` — dynamic resolution after build

`DiscoveryService`

NestJS DI concept mapping

Overriding providers

Request-scoped providers

Enabling request scope

Marking a provider as request-scoped

Extracting request-scoped providers in handlers

Background work: `spawn_with_request_scope`

Circular provider dependencies

​How the container works at runtime

​The three provider scopes

​ModuleRef — dynamic resolution after build

​DiscoveryService

​NestJS DI concept mapping

​Overriding providers

​Request-scoped providers

​Enabling request scope

​Marking a provider as request-scoped

​Extracting request-scoped providers in handlers

​Background work: spawn_with_request_scope

​Circular provider dependencies

How the container works at runtime

The three provider scopes

`ModuleRef` — dynamic resolution after build

`DiscoveryService`

NestJS DI concept mapping

Overriding providers

Request-scoped providers

Enabling request scope

Marking a provider as request-scoped

Extracting request-scoped providers in handlers

Background work: `spawn_with_request_scope`

Circular provider dependencies