Incorrect lifecycle behavior of transient service

[albert-mirzoyan]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

The onModuleInit hook is called on an transient service at bootstrap without constructing an instance (aka constructor is not called, DI is not processed) if the service is used in the request scoped Controller.

Minimum reproduction code

https://github.com/albert-mirzoyan/reproducible-transient-init/tree/main

Steps to reproduce

1. Uncomment the injection of RequestService in the controller's constructor:
   //private readonly requestService: RequestService
2. (Optional) Decorate the controller with @Controller({ scope: Scope.REQUEST })
3. Restart the application.

Expected behavior

The hook TransientService.onModuleInit() should not be called if the instance is not constructed, and when it is constructed in request scope, the hook will not be called anyway.

NestJS version

11.0.1

Packages versions

  "dependencies": {
    "@nestjs/common": "^11.0.1",
    "@nestjs/core": "^11.0.1",
    "@nestjs/platform-express": "^11.0.1",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.1"
  },

Node.js version

22.16.0

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

No response

[micalevisk]

and I got the same behavior on NestJS v10

Invoking any lifecycle hook without creating the instance of the class first do not make sense to me. Not sure if we this is expected tho

[micalevisk]

Now I see that this is probably expected but I don't know why is this:

nest/packages/core/hooks/on-module-init.hook.ts

Lines 49 to 63 in 3876179

	const nonTransientInstances = getNonTransientInstances(instances);
	await Promise.all(callOperator(nonTransientInstances));
	const transientInstances = getTransientInstances(instances);
	await Promise.all(callOperator(transientInstances));
	// Call the instance itself
	const moduleClassInstance = moduleClassHost.instance;
	if (
	moduleClassInstance &&
	hasOnModuleInitHook(moduleClassInstance) &&
	moduleClassHost.isDependencyTreeStatic()
	) {
	await moduleClassInstance.onModuleInit();
	}

at https://github.com/nestjs/nest/blob/master/packages/core/injector/instance-wrapper.ts we have few Object.create(this.metatype!.prototype) which is why an object of TransientService ends up being created without calling its constructor function, and ends up being in the transientInstances array above

[albert-mirzoyan]

The AppController itself is in the REQUEST scope (implicit or explicit), so its instance is not created at bootstrap. Therefore, there is no reason for its dependency TransientService to be created, nor for onModuleLoad to be called on empty object.

[albert-mirzoyan]

While debugging this issue, I noticed another manifestation of what is presumably the same issue.
When a transient service uses another transient service, such as
AppController (SINGLETON) => TransientService (TRANSIENT) => DeepTransientService (TRANSIENT),
the TransientService is constructed and its onModuleInit() is properly called.
However, DeepTransientService is never constructed, yet DeepTransientService.onModuleInit() is called on an empty object. As a result, the TransientService instance ends up with a deepTransientService property that is an empty object (no proper DI).

Unlike REQUEST scope, where onModuleInit should not be called according to the documentation, in this scenario I would expect the chain to be created and initialized as it would be for a singleton.

[par333k]

There's a design conflict between transient providers and bootstrap lifecycle management. Transient instances are meant to be "created on-demand", but calling lifecycle hooks during bootstrap contradicts this principle.

  // packages/core/hooks/on-module-init.hook.ts
  const transientInstances = getTransientInstances(instances);
  await Promise.all(callOperator(transientInstances)); // Problem here

During bootstrap, getTransientInstances() returns unresolved prototype objects, and onModuleInit() gets called on these prototypes.

I propose completely removing transient lifecycle calls from bootstrap:

  // Proposed: Remove transient hooks from bootstrap
  // Transient instances get lifecycle hooks when actually instantiated (dynamic injection)

Transient instances are actually created at these moments:

1. When Controllers/Providers are first requested and need dependencies
2. When ModuleRef.resolve() is called
3. When instances are created in request-scoped contexts

I considered calling lifecycle hooks dynamically at these points.

Expected Issues

1. Test Failures: Existing tests that expect transient lifecycle during bootstrap may break
2. Breaking Change: Current code using onModuleInit in transient providers might be affected
3. Increased Complexity: Adding dynamic lifecycle management increases code complexity

Benefits

1. Aligns with transient's "on-demand" nature
2. Completely fixes onModuleInit calls without constructor
3. Ensures design consistency

What are your thoughts on this approach?

Specifically, I'm curious about this.

1. Are you currently using lifecycle hooks with transient providers?
2. Would it be problematic if transient lifecycle hooks aren't called during bootstrap?
3. Or would you prefer handling lifecycle at dynamic injection points?
4. How do you see this change affecting existing applications?

[mag123c]

Reproduction Test

import { Controller, Get, Injectable, Module, OnModuleInit, Scope } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { expect } from 'chai';

describe('Transient Service Lifecycle Bug', () => {
  it('should not call onModuleInit on transient service when used in request-scoped controller', async () => {
    let onModuleInitCalled = false;
    let constructorCalled = false;

    @Injectable({ scope: Scope.TRANSIENT })
    class TransientService implements OnModuleInit {
      constructor() {
        constructorCalled = true;
        console.log('TransientService constructor called');
      }

      onModuleInit() {
        onModuleInitCalled = true;
        console.log('TransientService onModuleInit called');
        if (!constructorCalled) {
          throw new Error('onModuleInit called before constructor!');
        }
      }

      getData() {
        return 'test data';
      }
    }

    @Controller({ scope: Scope.REQUEST })
    class RequestScopedController {
      constructor(private readonly transientService: TransientService) {}

      @Get()
      getData() {
        return this.transientService.getData();
      }
    }

    @Module({
      controllers: [RequestScopedController],
      providers: [TransientService],
    })
    class TestModule {}

    const moduleRef = await Test.createTestingModule({
      imports: [TestModule],
    }).compile();

    const app = moduleRef.createNestApplication();
    await app.init();

    // The bug: onModuleInit is called even though the transient service 
    // was not instantiated (constructor not called)
    expect(constructorCalled).to.be.false;
    expect(onModuleInitCalled).to.be.true; // This is the bug!

    await app.close();
  });
});

Test Result:

Error: onModuleInit called before constructor!

Root Cause Analysis

After analyzing the codebase, I've identified the exact flow causing this issue:

1. Bootstrap Process (packages/core/nest-application-context.ts)

   • During app.init(), the framework calls callInitHook()

2. Module Init Hook (packages/core/hooks/on-module-init.hook.ts)

   export async function callModuleInitHook(module: Module): Promise<void> {
     // ... 
     const transientInstances = getTransientInstances(instances);
     await Promise.all(callOperator(transientInstances)); // <-- Problem here
   }

3. Getting Transient Instances (packages/core/injector/helpers/transient-instances.ts)

   export function getTransientInstances(instances: [InjectionToken, InstanceWrapper][]): InstanceWrapper[] {
     return iterate(instances)
       .filter(([_, wrapper]) => wrapper.isDependencyTreeStatic())
       .map(([_, wrapper]) => wrapper.getStaticTransientInstances())
       .flatten()
       .filter(item => !!item)
       .map(({ instance }: any) => instance)
       .toArray() as InstanceWrapper[];
   }

4. The Issue (packages/core/injector/instance-wrapper.ts)

   • getStaticTransientInstances() returns instances from transientMap even when they haven't been properly constructed
   • When a transient service is injected into a request-scoped controller, the service metadata exists but the instance itself is not created until a request arrives
   • However, the lifecycle hook is called on this "phantom" instance during bootstrap

Why This Happens

• Request-scoped controllers are not instantiated during bootstrap - they wait for actual requests
• Transient services injected into these controllers also shouldn't be instantiated
• But the current implementation tries to call lifecycle hooks on ALL transient instances found in the metadata, regardless of whether they've been actually constructed

Proposed Solution

As @par333k suggested, we should skip lifecycle hooks for transient services during bootstrap. Here's why this makes sense:

Pros:

1. Conceptually correct: Transient services are meant to have independent lifecycles per instance
2. Fixes the bug: Prevents calling hooks on non-existent instances
3. Consistent behavior: Aligns with how request-scoped services work

Cons:

1. Breaking change: Existing applications might rely on onModuleInit being called for transient services
2. Migration needed: Users would need to handle initialization differently for transient services

Alternative Solutions

1. Check instance existence before calling hooks (Less breaking)

   // In getStaticTransientInstances()
   return iterate(instances)
     .map(item => item.get(STATIC_CONTEXT))
     .filter(item => !!item && !!item.instance) // Check if instance actually exists
     .toArray();

2. Lazy initialization for transient services (More complex)

   • Initialize transient services only when they're first accessed
   • Track initialization state per instance

Recommendation

I recommend going with the first alternative solution as a immediate fix (checking instance existence), and consider the complete removal of bootstrap lifecycle hooks for transient services as a major version change.

The immediate fix would be minimal and non-breaking:

// packages/core/injector/instance-wrapper.ts
public getStaticTransientInstances() {
  if (!this.transientMap) {
    return [];
  }
  const instances = [...this.transientMap.values()];
  return iterate(instances)
    .map(item => item.get(STATIC_CONTEXT))
    .filter(item => !!item && !!item.instance) // Add instance check
    .toArray();
}

This ensures we only call lifecycle hooks on transient instances that have actually been constructed.

Would love to hear the team's thoughts on this approach. Happy to submit a PR with tests if this direction looks good.

[kamilmysliwiec]

@mag123c the suggested fix with item.get(STATIC_CONTEXT) looks OK

[mag123c]

created PR #15571

[kamilmysliwiec]

Let's track this here #15571