Lifecycle Hooks Execution Order does not respect Provider Dependencies within the Same Module

[ori88c]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

NestJS ensures a topological instantiation order for providers based on their dependency graph (i.e., new MyProvider(...) respects dependencies). However, this ordering is not enforced for asynchronous lifecycle hooks, such as:

• onModuleInit (initialization)
• onModuleDestroy (teardown)
  Currently, all providers within the same module are initialized and destroyed concurrently (Promise.all), disregarding their dependency relations:
  https://github.com/nestjs/nest/blob/master/packages/core/hooks/on-module-init.hook.ts#L50
  This is surprising because modules are initialized sequentially in topological order, ensuring a safeguard against race conditions. The "distance" terminology likely follows BFS levels, akin to Khan's algorithm:
  https://github.com/nestjs/nest/blob/master/packages/core/nest-application-context.ts#L405-L408
  

  nest/integration/hooks/e2e/on-app-shutdown.spec.ts

  Line 23 in 2d4b2c8

  it('should sort modules by distance (topological sort) - DESC order', async () => {

Describe the solution you'd like

Feature Request

Lifecycle hooks within a module should execute sequentially in a topological (for init) and reverse-topological (for teardown) order to ensure:

• During initialization: A provider’s dependencies have fully initialized (onModuleInit resolved) before its own onModuleInit executes.
• During teardown: A provider’s dependents have fully torn down (onModuleDestroy resolved) before its own onModuleDestroy executes.

This would improve lifecycle orchestration and prevent potential race-conditions.

Teachability, documentation, adoption, migration strategy

Ideally, the Lifecycle Hooks documentation will explicitly clarify the following points:

• Module Initialization Order: Modules are initialized sequentially in topological order during the init phase and reverse-topological order during teardown.
• Provider Initialization: Within each module, providers' onModuleInit hooks are invoked sequentially in topological order.
• Provider Teardown: Within each module, providers' onModuleDestroy hooks are invoked sequentially in reverse-topological order.

This clarification will help developers better understand the precise execution flow of lifecycle hooks.

What is the motivation / use case for changing the behavior?

Comparison with Other Popular Dependency-Injection Framework

My suggestion aligns with Spring's default behavior:
https://docs.spring.io/spring-framework/reference/core/beans/factory-nature.html
"The order of startup and shutdown invocations can be important. If a "depends-on" relationship exists between any two objects, the dependent side starts after its dependency, and it stops before its dependency".

Use Case Example

Consider a module with two providers:

1. A Kafka client provider that establishes a connection in onModuleInit().
2. A Kafka publisher provider (built on top of the client) that creates a test topic in onModuleInit().

Issue

Since both providers belong to the same module, Nest does not guarantee a topological execution order for their lifecycle hooks. This leads to potential failures:

• Initialization (onModuleInit): The publisher may attempt to publish before the client has established a connection.
• Teardown (onModuleDestroy): The publisher may attempt to send messages after the client has disconnected.

Current Approach to Mitigate the Issue

Developers can implement custom lifecycle coordination layers, but this undermines NestJS’s built-in orchestration capabilities. A practical workaround is to place each provider with an asynchronous onModuleInit or onModuleDestroy hook into its own dedicated module - effectively creating one-provider modules.
However, this approach introduces significant downsides: excessive modularity and fragmentation, as logically related providers become scattered across multiple modules.

[kamilmysliwiec]

As the name of the lifecycle hook suggests, it triggers on the module initialization meaning provider dependencies are not taken into account. We'd need to add a new hook if we wanted to introduce such a feature.

[ori88c]

As the name of the lifecycle hook suggests, it triggers on the module initialization meaning provider dependencies are not taken into account. We'd need to add a new hook if we wanted to introduce such a feature.

Terminology-wise, the term "module init" does not inherently convey an initialization policy - whether concurrent or sequential. Just as "task scheduling" does not specify whether it refers to recurring or one-time execution.
The decision to apply a sequential policy for module initialization while using a concurrent policy for providers within a module is an implementation detail.
Regardless of the outcome of this feature request, I believe this implementation detail ("meaning provider dependencies are not taken into account") is worth highlighting in the documentation:
https://docs.nestjs.com/fundamentals/lifecycle-events

Introducing additional hooks, such as onProviderInit, would not necessarily clarify execution order either, as the name alone would not indicate whether providers are initialized sequentially.

A flexible and intuitive approach could be to introduce an optional argument to app.init() and/or app.listen() (or extend an existing option) that allows users to define their desired execution policy. For example:

interface IModuleOptions {
  // ...
  moduleHooksExecutionPolicy: 'sequential' | 'concurrent';
}

This approach keeps the API clean and eliminates the need for additional lifecycle hooks. Would this be a reasonable consideration?

[Kohbrax]

I stumbled across this too, here is a corresponding example: https://stackblitz.com/edit/nestjs-typescript-starter-lvebtqub?file=src%2Fapp.module.ts

At least we should clarify this behaviour inside the docs. (eg here: https://docs.nestjs.com/fundamentals/lifecycle-events#asynchronous-initialization)

In my opinion the sequencial processing of modules in module init is the "more javascript way" in this case. I'd assume, that there are other developers experiencing this without even knowing, that there is a race condition involved.

[WillianAgostini]

As the name of the lifecycle hook suggests, it triggers on the module initialization meaning provider dependencies are not taken into account. We'd need to add a new hook if we wanted to introduce such a feature.

Good point. Following the idea of a new lifecycle hook called onProviderInit. This hook would be triggered before all providers' onModuleInit within the same module.

By default, onProviderInit could run sequentially, supporting synchronous and asynchronous execution and respecting the order defined in the module's providers array. This would give developers more control over provider initialization, especially in cases where dependency order matters.

[ori88c]

A deeper look into the "kernel" shows that provider dependencies are taken into account, with explicit sequential init/teardown in two key cases:
A. Non-transient vs transient providers:
https://github.com/nestjs/nest/blob/master/packages/core/hooks/on-module-init.hook.ts#L49-L53
B. The onModuleInit of the module class itself, which is invoked sequentially after all its providers have completed their own onModuleInit:
https://github.com/nestjs/nest/blob/master/packages/core/hooks/on-module-init.hook.ts#L62

Same behavior applies to onModuleDestroy. The fact that sequential execution was deliberately ensured for those edge cases, contradicts the claim that onModuleInit should disregard provider dependencies. Since a module represents a sub-graph, with providers as its nodes, it makes sense for its lifecycle hooks to be context-aware, ensuring the integrity of the module's providers.

While GPT's responses should be taken with caution, here’s its take on the matter:

[kamilmysliwiec]

Don't get me wrong, but I think you might be overreacting. GPT doesn't handle this question well either—it references hooks like ngOnInit (from Angular), which trigger on component initialization (considering the topological order - which in this case makes sense). In contrast, onModuleInit, as the name suggests, triggers on module initialization, so the provider's initialization order isn't relevant.

I'm open to changing this behavior if needed, but trying to argue that onModuleInit should work differently is pointless—it's simply a design decision.

[ori88c]

A. This thread is about re-evaluating this design decision. Design decisions should address real-world complexities. As the framework evolves, it’s natural to revisit past choices.

B. Adding more hooks to patch the shortcomings of existing ones is like using deodorant instead of taking a shower - it only masks deeper issues.

C. The name onModuleInit does not convey a specific initialization policy. It vaguely implies that this function is used at some point during the module's initialization phase. I understand your perspective and original intention. However, given the two existing edge cases where you chose to initialize / teardown sequentially, it’s worth reconsidering the policy and responsibilities of onModuleInit / onModuleDestroy.

[kamilmysliwiec]

What if someone has, let's say, 3 providers in 1 module and, upon the host module initialization (in the onModuleInit), each one of these providers needs to perform some operations, be it creating snapshots of their corresponding DB tables? These operations need to be performed async (not one by one). Note that provider A depends on B, and provider B depends on C.

[ori88c]

What if someone has, let's say, 3 providers in 1 module and, upon the host module initialization (in the onModuleInit), each one of these providers needs to perform some operations, be it creating snapshots of their corresponding DB tables? These operations need to be performed async (not one by one). Note that provider A depends on B, and provider B depends on C.

Not an issue:

• Providers A, B, and C can avoid implementing onModuleInit, or at least exclude the part that requires concurrent execution (e.g., creating snapshots).
• Instead, they can each expose a createTableSnapshot() method. But who should trigger this method?
• Since the Module itself has its own onModuleInit, it can handle this by invoking Promise.all to execute snapshot creation concurrently:

await Promise.all([a.createTableSnapshot(), b.createTableSnapshot(), c.createTableSnapshot()]);

Alternatively, instead of managing this directly in the Module's hook, a dedicated provider (e.g., SnapshotsInitializer) can be introduced to encapsulate this logic within its own onModuleInit.

Enforcing sequential execution shifts control to developers, allowing them to choose which operations should run concurrently by delegating them to a designated provider or handling them within the module’s onModuleInit.

It's also important to consider the semantic meaning of the 'depends on' relationship:
Provider A cannot fully 'depend on' Provider B if B is still in an intermediate state. If both can be initialized concurrently, that stage of initialization does not semantically honor the 'depends on' relationship, which justifies handling that part elsewhere.

By the way, the same argument applies to module initialization, which already follows a topological execution order. Some modules are entirely independent, yet their initialization hooks execute sequentially.

[kamilmysliwiec]

Well, it is an issue. My point with this question was to highlight that your suggestion would introduce a breaking change.

Saying that a dedicated provider (e.g., SnapshotsInitializer) can be introduced applies to your case as well—a dedicated provider like KafkaInitializer could be introduced to orchestrate the connection initialization and topic creation sequentially.