feat(core): defer initialization connected microservice

[isaryy]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Build related changes
• CI related changes
• Other... Please describe:

What is the current behavior?

Currently, when using app.connectMicroservice(), the microservice is immediately initialized inside the method call. This creates several limitations:

1. Limited configuration options: Microservice settings can only be applied through inheritAppConfig option and must be set before calling .connectMicroservice()
2. No post-connection configuration: Adding global handlers, pipes, filters, interceptors, etc. to the returned INestMicroservice object is ineffective because initialization has already completed
3. Confusing developer experience: The API suggests that you can configure the microservice after connection, but this doesn't work as expected

Example of current limitation:

const app = await NestFactory.create(AppModule);

// This works - configuration before connection
app.useGlobalPipes(new ValidationPipe());

const microservice = app.connectMicroservice(options, { 
  inheritAppConfig: true 
});

// This DOESN'T work - microservice is already initialized
microservice.useGlobalFilters(new ExceptionFilter()); // ❌ Has no effect

Issue Number: N/A

What is the new behavior?

Added a new deferInitialization option to NestHybridApplicationOptions that allows delaying microservice initialization until .listen() is called.

New API:

const app = await NestFactory.create(AppModule);

const microservice = app.connectMicroservice(options, { 
  deferInitialization: true 
});

// Now you can configure the microservice before it's initialized
microservice.useGlobalPipes(new ValidationPipe());
microservice.useGlobalFilters(new GlobalExceptionFilter());
microservice.useGlobalInterceptors(new LoggingInterceptor());
microservice.useGlobalGuards(new AuthGuard());

// Initialization happens here
await microservice.listen() || await app.startAllMicroservices();

Benefits:

• ✅ Allows post-connection configuration of global handlers
• ✅ Provides more flexibility in microservice setup
• ✅ Maintains backward compatibility (default behavior unchanged)
• ✅ Enables better separation of concerns between connection and configuration
• ✅ More intuitive developer experience

Implementation Details

Interface Changes

Added deferInitialization property to NestHybridApplicationOptions:

export interface NestHybridApplicationOptions {
  inheritAppConfig?: boolean;
  deferInitialization?: boolean; // New option
}

Code Changes

Modified connectMicroservice method in NestApplication:

public connectMicroservice<T extends object>(
  microserviceOptions: T,
  hybridAppOptions: NestHybridApplicationOptions = {},
): INestMicroservice {
  // ... existing code ...
  
  if (!hybridAppOptions.deferInitialization) {
    instance.registerListeners();
    instance.setIsInitialized(true);
    instance.setIsInitHookCalled(true);
  }
  
  // ... existing code ...
}

Does this PR introduce a breaking change?

• Yes
• No

The change is fully backward compatible. When deferInitialization is not specified or set to false, the behavior remains exactly the same as before.

Testing

Added comprehensive tests covering:

1. Default behavior preservation - ensures existing functionality works unchanged
2. Deferred initialization - verifies that microservice is not initialized when deferInitialization: true
3. Manual initialization - confirms that deferred microservices can be properly initialized later

Other information

Migration

No migration is required. Existing code continues to work without changes. To use the new feature, simply add deferInitialization: true to the options:

// Before (still works)
const microservice = app.connectMicroservice(options);

// New feature
const microservice = app.connectMicroservice(options, { 
  deferInitialization: true 
});

[coveralls]

Pull Request Test Coverage Report for Build c1e68828-0cf7-4679-b5b7-3c91f82e3b76

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 88.94%

---

Totals
Change from base Build cbdbfe31-770d-4936-b123-f113ab433f9c:	0.0%
Covered Lines:	7197
Relevant Lines:	8092

---

💛 - Coveralls

[kamilmysliwiec]

LGTM