Solving NestJS Circular Dependencies in Microservices

A comprehensive guide to fixing the dreaded “Cannot read properties of undefined” error when using forwardRef in NestJS microservices with TCP transport.

TL;DR

The Problem: Using forwardRef() in NestJS services causes repositories and dependencies to become undefined when called via Microservice TCP transport.

The Solution: Eliminate forwardRef entirely by using:

1. Facade Pattern for intra-module workflows
2. EventEmitter for cross-module communication
3. Message Queues for cross-service communication

---

Problem Overview

The Symptoms

When calling a service via Microservice TCP transport that uses forwardRef, you’ll encounter:

TypeError: Cannot read properties of undefined (reading 'find')

The this.typeOrmRepository or other dependencies become undefined in the method being called.

Observable Behavior

Call Method	Result
Direct HTTP API call (e.g., GET /data-owner-bc/v1/resources)	✅ Works perfectly
Via Microservice TCP (e.g., consumer → data-owner)	❌ Repository/Services are undefined

Diagnostic Log Pattern

Controller visitRepository ---> Repository { ... }  # ✅ Controller has repo
data ---> { ... }
repo visitRepo ---> undefined                       # ❌ Service has NO repo
DEBUG CONSTRUCTOR Repo: Repository { ... }          # 🔴 Constructor called AFTER method!

Critical Issue

The DEBUG CONSTRUCTOR is printed AFTER the method is called, indicating NestJS is using a partially initialized instance.

---

Root Cause Analysis

The Core Issue: forwardRef + Microservice Context

The problem occurs when using forwardRef() in service constructors called via Microservice transport.

Problematic Architecture

┌─────────────────┐         ┌─────────────────┐
│   VisitModule   │◄───────►│  PatientModule  │
│                 │forwardRef│                 │
└────────┬────────┘         └────────┬────────┘
         │                           │
         ▼                           ▼
┌─────────────────┐         ┌─────────────────┐
│  VisitsService  │────────►│ PatientsService │
│                 │forwardRef│                 │
│  + 4 more       │         └─────────────────┘
│  forwardRef     │
└─────────────────┘
         │
         ▼
    💥 Microservice message arrives
    💥 Everything is undefined!

Problematic Code Example

@Injectable()
export class VisitsService extends BaseServiceOperations<Visit, CreateVisitDTO, UpdateVisitDTO> {
    constructor(
        @InjectRepository(Visit, AppDatabases.APP_CORE)
        visitRepository: Repository<Visit>,

        // ⚠️ forwardRef causes undefined in Microservice context
        @Inject(forwardRef(() => VisitOrdersService))
        private readonly visitOrdersService: VisitOrdersService,
        @Inject(forwardRef(() => PatientInsurancesService))
        private readonly patientInsurancesService: PatientInsurancesService,
        @Inject(forwardRef(() => PatientsService))
        private readonly patientsService: PatientsService,
        @Inject(forwardRef(() => AssessmentsService))
        private readonly assessmentsService: AssessmentsService,
    ) {
        super(visitRepository, {...});
    }
}

Why Only in Microservice Context?

HTTP vs Microservice Initialization

The difference lies in when NestJS initializes dependencies versus when they’re accessed.

┌─────────────────────────────────────────────────────────────────────────────┐
│ ✅ HTTP Context (Normal Behavior)                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  [App Bootstrap] ──────────────────────────────────────────────────────►    │
│        │                                                                     │
│        ├─► Resolve all providers                                            │
│        ├─► Resolve forwardRefs                                              │
│        └─► app.listen() ← Everything ready 100%                             │
│                    │                                                         │
│                    ▼                                                         │
│              [HTTP Request arrives]                                          │
│                    │                                                         │
│                    └─► Service ready 100% ✅                                 │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ ❌ Microservice TCP Context (Problematic)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  [App Bootstrap] ──────────────────────────────────────────────────────►    │
│        │                                                                     │
│        ├─► Resolve providers (in progress...)                               │
│        │         │                                                           │
│        │         │    [TCP Message arrives!] ← Doesn't wait for bootstrap   │
│        │         │           │                                               │
│        │         │           ▼                                               │
│        │         │    [NestJS needs Service]                                │
│        │         │           │                                               │
│        │         │           ├─► Instance exists (partially initialized)    │
│        │         │           │                                               │
│        │         │           └─► Uses that instance! ⚠️                      │
│        │         │                      │                                    │
│        │         │                      ▼                                    │
│        │         │              [Method called]                              │
│        │         │                      │                                    │
│        │         │              this.repo = undefined ❌                     │
│        │         │              this.service = undefined ❌                  │
│        │         │              (constructor not finished!)                  │
│        │                                                                     │
│        ├─► Still resolving forwardRefs...                                   │
│        └─► (Too late, method already called)                                │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Key Insight

The problem isn’t the Repository — it’s ready from the start.

The problem is forwardRef preventing NestJS from completing the constructor in time.

When a Microservice message arrives → NestJS sends a partially initialized instance → Everything is undefined.

---

Solution 1: Facade Pattern

The Concept

Instead of Services talking directly to each other (requiring forwardRef), create an Orchestrator Service to coordinate complex workflows.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              ❌ Before (Problematic)                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│    ┌──────────────┐  forwardRef   ┌──────────────┐                         │
│    │VisitsService │◄─────────────►│PatientsService│                         │
│    │              │               │              │                          │
│    │ + forwardRef │               └──────────────┘                          │
│    │   - VisitOrders                                                        │
│    │   - Assessments     💥 Circular Dependency                             │
│    │   - VitalSigns      💥 Repository = undefined                          │
│    │   - Patients        💥 Microservice unusable                           │
│    └──────────────┘                                                         │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                            ✅ After (Facade Pattern)                         │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│                    ┌─────────────────────────────────┐                      │
│                    │   VisitOperationsService        │                      │
│                    │   (Facade / Orchestrator)       │                      │
│                    │                                 │                      │
│                    │   • Complex workflows           │                      │
│                    │   • Transaction management      │                      │
│                    │   • Cross-service coordination  │                      │
│                    └───────────────┬─────────────────┘                      │
│                                    │                                         │
│                                    │ inject (No forwardRef needed!)         │
│                                    ▼                                         │
│    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                     │
│    │VisitsService │  │ Assessments  │  │ Patients     │                     │
│    │(Pure CRUD)   │  │ Service      │  │ Service      │                     │
│    │              │  │ (Pure CRUD)  │  │ (Pure CRUD)  │                     │
│    │No forwardRef │  │              │  │              │                     │
│    └──────────────┘  └──────────────┘  └──────────────┘                     │
│                                                                              │
│    ✅ No Circular Dependency                                                 │
│    ✅ One-way dependencies only                                              │
│    ✅ Microservice works 100%                                                │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Key Principles

Principle	Description
Separation of Concerns	Each Service manages CRUD for its own Entity only
One-way Dependencies	Dependencies flow from Facade down to Services only
No forwardRef	Absolutely no forwardRef anywhere
Single Orchestrator	All complex workflows live in one Facade

Refactoring Steps

Step 1: Create VisitOperationsService (Facade)

/**
 * Facade/Orchestrator Service for managing complex workflows.
 *
 * Acts as a "manager" that orchestrates multiple Services
 * without creating Circular Dependencies.
 */
@Injectable()
export class VisitOperationsService {
    constructor(
        private readonly dataSource: DataSource,
        // Inject all services — NO forwardRef needed!
        private readonly visitsService: VisitsService,
        private readonly assessmentsService: AssessmentsService,
        private readonly vitalSignsService: VitalSignsService,
        private readonly visitOrdersService: VisitOrdersService,
        private readonly visitRightsService: VisitRightsService,
        private readonly groupOrdersService: GroupOrdersService,
        private readonly patientsService: PatientsService,
        private readonly patientInsurancesService: PatientInsurancesService,
    ) {}

    /**
     * Complex workflow requiring multiple services.
     * Uses a Transaction for data consistency.
     */
    async upsertAssessmentExamination(
        data: CreateAssessmentExaminationDTO,
        currentUser: IUserSession,
    ): Promise<Assessment> {
        const queryRunner = this.dataSource.createQueryRunner();
        await queryRunner.connect();
        await queryRunner.startTransaction();

        try {
            const visit = await this.getOrCreateVisit(queryRunner, data, currentUser);
            const assessment = await this.upsertAssessment(queryRunner, visit, data, currentUser);
            await this.createVitalSigns(queryRunner, assessment, visit, data, currentUser);

            await queryRunner.commitTransaction();
            return assessment;
        } catch (error) {
            await queryRunner.rollbackTransaction();
            throw error;
        } finally {
            await queryRunner.release();
        }
    }

    // ... private helper methods
}

Step 2: Simplify VisitsService (Pure CRUD)

/**
 * VisitsService — Pure CRUD Service for Visit Entity.
 *
 * Handles CRUD operations for Visit entity only.
 * Complex workflows use VisitOperationsService instead.
 *
 * NO forwardRef anywhere!
 */
@Injectable()
export class VisitsService extends BaseServiceOperations<Visit, CreateVisitDTO, UpdateVisitDTO> {
    constructor(
        logger: LogsService,
        configService: ConfigService,
        @InjectRepository(Visit, AppDatabases.APP_CORE)
        visitRepository: Repository<Visit>,
        // External microservice clients only — NO forwardRef!
        @Inject(AppMicroservice.SystemAdmin.name)
        private readonly systemAdminService: ClientProxy,
    ) {
        super(visitRepository, { ... });
    }

    // Pure CRUD + simple queries only
    async findTodayVisit(resourceId: string, startOfDay: Date, endOfDay: Date): Promise<Visit | null> {
        return this.repo.findOne({
            where: {
                resource_id: resourceId,
                visit_date: Between(startOfDay, endOfDay),
                is_deleted: false,
            },
        });
    }
}

Step 3: Update Controller

@Controller()
export class VisitEventsController {
    constructor(
        // Use Facade instead of VisitsService directly
        private readonly visitOperationsService: VisitOperationsService,
    ) {}

    @MessagePattern({ cmd: AppMicroservice.DataOwner.cmd.VisitEvents.UpsertAssessmentExamination })
    async upsertAssessmentExamination(@Payload() payload: IMicroservicePayload<...>): Promise<Assessment> {
        return this.visitOperationsService.upsertAssessmentExamination(
            payload.payload.data,
            payload.payload.current_user,
        );
    }
}

Step 4: Update Module

@Module({
    imports: [
        PatientModule,  // No forwardRef needed anymore!
        TypeOrmModule.forFeature([Visit, ...], AppDatabases.APP_CORE),
    ],
    providers: [
        // Pure CRUD Services — no dependencies between them
        VisitsService,
        AssessmentsService,
        VitalSignsService,
        VisitOrdersService,
        GroupOrdersService,
        VisitRightsService,

        // Facade — injects all services
        VisitOperationsService,
    ],
    exports: [
        VisitsService,
        AssessmentsService,
        VisitOperationsService,
    ],
})
export class VisitModule {}

When to Use Facade Pattern

✅ Use Facade	❌ Don’t Use Facade
Workflow requires multiple services	Simple CRUD operations
Transactions across entities	Queries within single entity
Complex business logic	No cross-service communication
Data consistency is critical

Deep Dive: Facade as a Transactional Boundary

The Facade Pattern isn’t just about fixing circular dependencies — it serves as a critical Transactional Boundary.

Consider a real-world scenario: Onboarding a new resource. This single action touches multiple domains:

1. Resource Domain: Update status to ‘Active’, assign ID.
2. Billing Domain: Open a new account.
3. Records Domain: Create an initial record.
4. Notification Domain: Alert the account manager.

Without a Facade, ResourceService would need to depend on BillingService, RecordsService, and NotificationService, creating a massive web of circular dependencies.

Solution with ResourceOnboardingFacade:

@Injectable()
export class ResourceOnboardingFacade {
    constructor(
        private readonly dataSource: DataSource,
        private readonly resourceService: ResourceService,
        private readonly billingService: BillingService,
        private readonly recordsService: RecordsService,
        private readonly notificationService: NotificationService,
    ) {}

    async onboardResource(resourceId: string, roomNumber: string, user: IUserSession) {
        const queryRunner = this.dataSource.createQueryRunner();
        await queryRunner.connect();
        await queryRunner.startTransaction();

        try {
            // 1. Update Resource (pass QueryRunner for transaction)
            const resource = await this.resourceService.activate(
                queryRunner,
                resourceId,
                'ACTIVE',
            );

            // 2. Open Billing Account
            await this.billingService.openAccount(queryRunner, resourceId, user.id);

            // 3. Create Initial Record
            await this.recordsService.createOnboardingRecord(queryRunner, resource, user.id);

            // Commit only if all above succeed
            await queryRunner.commitTransaction();

            // 4. Notifications (outside transaction — event-based)
            await this.notificationService.notifyAccountManager(resource);

            return resource;
        } catch (err) {
            await queryRunner.rollbackTransaction();
            throw err;
        } finally {
            await queryRunner.release();
        }
    }
}

This keeps ResourceService completely ignorant of BillingService, eliminating circular dependencies while ensuring data integrity.

---

Solution 2: Event-Driven Architecture

Another powerful approach is using Event-Driven Architecture to reduce coupling between Services.

Using NestJS EventEmitter (In-Process)

Best for communication within the same application.

Installation

npm install @nestjs/event-emitter

Setup in AppModule

import { EventEmitterModule } from '@nestjs/event-emitter';

@Module({
    imports: [
        EventEmitterModule.forRoot({
            wildcard: true,
            delimiter: '.',
            maxListeners: 10,
            verboseMemoryLeak: true,
        }),
    ],
})
export class AppModule {}

Create Event DTOs

events/visit-created.event.ts

export class VisitCreatedEvent {
    constructor(
        public readonly visitId: string,
        public readonly resourceId: string,
        public readonly createdBy: string,
        public readonly createdAt: Date,
    ) {}
}

// events/assessment-requested.event.ts
export class AssessmentRequestedEvent {
    constructor(
        public readonly visitId: string,
        public readonly resourceId: string,
        public readonly assessmentData: {
            chief_complaint: string;
            urgency_code: string;
            vital_signs: any[];
        },
        public readonly requestedBy: string,
    ) {}
}

Emit Events from Service

visits.service.ts

import { EventEmitter2 } from '@nestjs/event-emitter';

@Injectable()
export class VisitsService {
    constructor(
        private readonly eventEmitter: EventEmitter2,
        @InjectRepository(Visit, AppDatabases.APP_CORE)
        private readonly visitRepo: Repository<Visit>,
        // NO forwardRef!
    ) {}

    async createVisit(data: CreateVisitDTO, currentUser: IUserSession): Promise<Visit> {
        const visit = this.visitRepo.create(data);
        const savedVisit = await this.visitRepo.save(visit);

        // ✅ Emit event instead of calling other services directly
        this.eventEmitter.emit(
            'visit.created',
            new VisitCreatedEvent(
                savedVisit.id,
                savedVisit.resource_id,
                currentUser.id,
                savedVisit.created_at,
            ),
        );

        return savedVisit;
    }

    async requestAssessment(
        visitId: string,
        assessmentData: any,
        currentUser: IUserSession,
    ): Promise<void> {
        // ✅ Emit event for AssessmentsService to handle
        this.eventEmitter.emit(
            'assessment.requested',
            new AssessmentRequestedEvent(
                visitId,
                assessmentData.resource_id,
                {
                    chief_complaint: assessmentData.chief_complaint,
                    urgency_code: assessmentData.urgency_code,
                    vital_signs: assessmentData.vital_signs,
                },
                currentUser.id,
            ),
        );
    }
}

Listen to Events in Other Services

assessments.service.ts

import { OnEvent } from '@nestjs/event-emitter';

@Injectable()
export class AssessmentsService {
    constructor(
        @InjectRepository(Assessment, AppDatabases.APP_CORE)
        private readonly assessmentRepo: Repository<Assessment>,
        // NO forwardRef!
    ) {}

    // ✅ Listen to event and process when received
    @OnEvent('visit.created')
    async handleVisitCreated(event: VisitCreatedEvent): Promise<void> {
        console.log(`Visit created: ${event.visitId} for resource: ${event.resourceId}`);
        // No need to inject VisitsService at all!
    }

    @OnEvent('assessment.requested')
    async handleAssessmentRequested(event: AssessmentRequestedEvent): Promise<void> {
        const assessment = this.assessmentRepo.create({
            visit_id: event.visitId,
            resource_id: event.resourceId,
            chief_complaint: event.assessmentData.chief_complaint,
            urgency_code: event.assessmentData.urgency_code,
            created_by: event.requestedBy,
        });

        await this.assessmentRepo.save(assessment);
    }

    // ✅ Using wildcard patterns
    @OnEvent('visit.*')
    async handleAllVisitEvents(event: any): Promise<void> {
        console.log('Visit event received:', event);
    }
}

Async Event Processing

@OnEvent('assessment.requested', { async: true })
async handleAssessmentRequestedAsync(event: AssessmentRequestedEvent): Promise<void> {
    // This task runs async without blocking the main thread
    await this.processLongRunningTask(event);
}

Using Message Queues (Cross-Process / Cross-Service)

Best for communication between microservices in separate processes.

Example with Redis + Bull Queue

npm install @nestjs/bull bull
npm install @types/bull -D

Setup

app.module.ts

import { BullModule } from '@nestjs/bull';

@Module({
    imports: [
        BullModule.forRoot({
            redis: {
                host: 'localhost',
                port: 6379,
            },
        }),
        BullModule.registerQueue({
            name: 'assessment-queue',
        }),
    ],
})
export class AppModule {}

Producer (Enqueue Job)

visits.service.ts

import { InjectQueue } from '@nestjs/bull';
import { Queue } from 'bull';

@Injectable()
export class VisitsService {
    constructor(
        @InjectQueue('assessment-queue')
        private readonly assessmentQueue: Queue,
    ) {}

    async createVisitWithAssessment(data: CreateVisitDTO): Promise<Visit> {
        const visit = await this.createVisit(data);

        // ✅ Enqueue job instead of calling service directly
        await this.assessmentQueue.add(
            'create-assessment',
            {
                visitId: visit.id,
                resourceId: visit.resource_id,
                assessmentData: data.assessment,
            },
            {
                attempts: 3,
                backoff: 5000,
                removeOnComplete: true,
            },
        );

        return visit;
    }
}

Consumer (Process Job)

assessment.processor.ts

import { OnQueueFailed, Process, Processor } from '@nestjs/bull';
import { Job } from 'bull';

/**
 * Assessment Queue Processor.
 * Processes jobs from the 'assessment-queue' independently.
 */
@Processor('assessment-queue')
export class AssessmentProcessor {
    constructor(
        @InjectRepository(Assessment, AppDatabases.APP_CORE)
        private readonly assessmentRepo: Repository<Assessment>,
        // NO forwardRef needed!
    ) {}

    @Process('create-assessment')
    async handleCreateAssessment(job: Job): Promise<void> {
        const { visitId, resourceId, assessmentData } = job.data;

        const assessment = this.assessmentRepo.create({
            visit_id: visitId,
            resource_id: resourceId,
            ...assessmentData,
        });

        await this.assessmentRepo.save(assessment);
    }

    @OnQueueFailed()
    async handleFailed(job: Job, error: Error): Promise<void> {
        console.error(`Job ${job.id} failed:`, error.message);
    }
}

Comparison: Facade vs EventEmitter vs Message Queue

Feature	Facade Pattern	EventEmitter	Message Queue (Bull)
Scope	In-process	In-process	Cross-process
Transaction Support	✅ Excellent support	❌ Difficult to implement	❌ Difficult to implement
Persistence	N/A (synchronous)	❌ Lost on restart	✅ Persisted in Redis
Retry Mechanism	Manual implementation	❌ Manual implementation	✅ Built-in with backoff
Complexity	Low	Low	Medium
Performance	Fast (direct call)	Very fast (in-memory)	Slower (network + Redis)
Best Use Case	Complex workflows requiring transactions	Simple decoupling, fire-and-forget	Distributed systems, background jobs
Error Handling	Try-catch blocks	Custom error listeners	Built-in failed job handlers

Event-Driven Architecture Pattern

┌─────────────────┐     emit      ┌──────────────┐
│  VisitsService  │──────────────►│  Event Bus   │
│                 │               │ (EventEmitter│
│  Creates Visit  │               │  or Queue)   │
└─────────────────┘               └──────┬───────┘
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
                    ▼                    ▼                    ▼
           ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
           │ Assessments    │  │ Notifications  │  │ Audit Logs     │
           │ Service        │  │ Service        │  │ Service        │
           │ @OnEvent()     │  │ @OnEvent()     │  │ @OnEvent()     │
           └────────────────┘  └────────────────┘  └────────────────┘

Benefits:

• No circular dependencies — Services don’t know about each other
• Independent services — Each service operates autonomously
• Easy to extend — Add new listeners without modifying existing code
• Loose coupling — Producer doesn’t care who consumes the event

---

Solution 3: Cross-Module forwardRef with EventEmitter

Common Scenario

When a Service in one Module needs to call a Service in another Module, creating a Circular Dependency:

┌─────────────────────────────────────────────────────────────────────────────┐
│                      ❌ Cross-Module Circular Dependency                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────────────┐              ┌─────────────────────┐              │
│   │     VisitModule     │  forwardRef  │    PatientModule    │              │
│   │                     │◄────────────►│                     │              │
│   │  ┌───────────────┐  │              │  ┌───────────────┐  │              │
│   │  │ VisitsService │──┼──────────────┼─►│PatientsService│  │              │
│   │  │ Needs to call │  │              │  │ Needs to call │  │              │
│   │  │patientsService│  │              │  │ visitsService │  │              │
│   │  └───────────────┘  │              │  └───────────────┘  │              │
│   └─────────────────────┘              └─────────────────────┘              │
│                                                                              │
│   💥 Requires forwardRef at BOTH Module AND Service level                   │
│   💥 Microservice call arrives → undefined immediately                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Problematic Code Example

visit.module.ts

@Module({
    imports: [
        forwardRef(() => PatientModule), // ❌ forwardRef at Module level
    ],
    providers: [VisitsService],
    exports: [VisitsService],
})
export class VisitModule {}

// visits.service.ts
@Injectable()
export class VisitsService {
    constructor(
        @Inject(forwardRef(() => PatientsService)) // ❌ forwardRef at Service level
        private readonly patientsService: PatientsService,
    ) {}

    async createVisit(data: CreateVisitDTO): Promise<Visit> {
        const patient = await this.patientsService.findById(data.patient_id);
        // ❌ In microservice context: this.patientsService is undefined!
    }
}

Critical Problem

Double forwardRef (Module + Service level) almost guarantees undefined dependencies when microservice messages arrive before NestJS completes the initialization cycle.

Solution: Use EventEmitter Instead of forwardRef

┌─────────────────────────────────────────────────────────────────────────────┐
│                   ✅ Solution: Event-Driven Communication                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────────────┐              ┌─────────────────────┐              │
│   │     VisitModule     │              │    PatientModule    │              │
│   │  ┌───────────────┐  │    emit      │  ┌───────────────┐  │              │
│   │  │ VisitsService │──┼─────────────►│  │PatientsService│  │              │
│   │  │ emit:         │  │  Event Bus   │  │ @OnEvent:     │  │              │
│   │  │patient.validate│ │              │  │patient.validate│ │              │
│   │  └───────────────┘  │              │  └───────────────┘  │              │
│   │                     │              │                     │              │
│   │  ┌───────────────┐  │              │  ┌───────────────┐  │              │
│   │  │ @OnEvent:     │◄─┼──────────────┼──│ emit:         │  │              │
│   │  │visit.requested│  │              │  │visit.requested│  │              │
│   │  └───────────────┘  │              │  └───────────────┘  │              │
│   └─────────────────────┘              └─────────────────────┘              │
│                                                                              │
│   ✅ No forwardRef required                                                  │
│   ✅ Modules are completely independent                                      │
│   ✅ Microservice works 100% reliably                                        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Refactoring Steps

Step 1: Create Shared Events

libs/common/events/resource.events.ts

export class ResourceValidateRequestEvent {
    constructor(
        public readonly resourceId: string,
        public readonly requestId: string, // For correlating response
    ) {}
}

export class ResourceValidateResponseEvent {
    constructor(
        public readonly requestId: string,
        public readonly isValid: boolean,
        public readonly resource: Resource | null,
        public readonly error?: string,
    ) {}
}

// libs/common/events/visit.events.ts
export class VisitsByResourceRequestEvent {
    constructor(
        public readonly resourceId: string,
        public readonly requestId: string,
    ) {}
}

export class VisitsByResourceResponseEvent {
    constructor(
        public readonly requestId: string,
        public readonly visits: Visit[],
    ) {}
}

Step 2: Create Event Helper Service

libs/common/services/event-request.service.ts

import { Injectable } from '@nestjs/common';
import { EventEmitter2 } from '@nestjs/event-emitter';
import { v4 as uuidv4 } from 'uuid';

/**
 * Helper service for request-response pattern using EventEmitter.
 * Simulates synchronous service calls using asynchronous events.
 */
@Injectable()
export class EventRequestService {
    private readonly pendingRequests = new Map<
        string,
        {
            resolve: (value: any) => void;
            reject: (error: any) => void;
            timeout: NodeJS.Timeout;
        }
    >();

    constructor(private readonly eventEmitter: EventEmitter2) {}

    /**
     * Emit an event and wait for response.
     * Implements request-response pattern via EventEmitter.
     */
    async emitAndWait<TRequest, TResponse>(
        requestEvent: string,
        responseEvent: string,
        payload: TRequest,
        timeoutMs: number = 5000,
    ): Promise<TResponse> {
        const requestId = uuidv4();

        return new Promise((resolve, reject) => {
            const timeout = setTimeout(() => {
                this.pendingRequests.delete(requestId);
                reject(new Error(`Event request timeout: ${requestEvent}`));
            }, timeoutMs);

            this.pendingRequests.set(requestId, { resolve, reject, timeout });

            const handler = (response: any) => {
                if (response.requestId === requestId) {
                    clearTimeout(timeout);
                    this.pendingRequests.delete(requestId);
                    this.eventEmitter.off(responseEvent, handler);
                    resolve(response);
                }
            };
            this.eventEmitter.on(responseEvent, handler);

            this.eventEmitter.emit(requestEvent, { ...payload, requestId });
        });
    }
}

Step 3: Refactor VisitsService (NO forwardRef)

@Injectable()
export class VisitsService {
    constructor(
        @InjectRepository(Visit, AppDatabases.APP_CORE)
        private readonly visitRepo: Repository<Visit>,
        private readonly eventEmitter: EventEmitter2,
        private readonly eventRequest: EventRequestService,
        // ✅ NO forwardRef(() => PatientsService) needed!
    ) {}

    async createVisit(data: CreateVisitDTO, currentUser: IUserSession): Promise<Visit> {
        // ✅ Use Event instead of calling resourcesService.findById() directly
        const validateResponse = await this.eventRequest.emitAndWait<
            ResourceValidateRequestEvent,
            ResourceValidateResponseEvent
        >('resource.validate.request', 'resource.validate.response', { resourceId: data.resource_id });

        if (!validateResponse.isValid) {
            throw new BadRequestException(
                validateResponse.error || `Resource ${data.resource_id} not found`,
            );
        }

        return this.visitRepo.save(
            this.visitRepo.create({ ...data, created_by: currentUser.id }),
        );
    }

    // ✅ Listen for "get visits by resource" requests from other modules
    @OnEvent('visits.by-resource.request')
    async handleVisitsByResourceRequest(event: VisitsByResourceRequestEvent): Promise<void> {
        const visits = await this.visitRepo.find({
            where: { resource_id: event.resourceId, is_deleted: false },
        });

        this.eventEmitter.emit(
            'visits.by-resource.response',
            new VisitsByResourceResponseEvent(event.requestId, visits),
        );
    }
}

Step 4: Refactor ResourcesService (NO forwardRef)

@Injectable()
export class ResourcesService {
    constructor(
        @InjectRepository(Resource, AppDatabases.APP_CORE)
        private readonly resourceRepo: Repository<Resource>,
        private readonly eventEmitter: EventEmitter2,
        private readonly eventRequest: EventRequestService,
        // ✅ NO forwardRef(() => VisitsService) needed!
    ) {}

    @OnEvent('resource.validate.request')
    async handleResourceValidateRequest(event: ResourceValidateRequestEvent): Promise<void> {
        try {
            const resource = await this.resourceRepo.findOne({
                where: { id: event.resourceId, is_deleted: false },
            });

            this.eventEmitter.emit(
                'resource.validate.response',
                new ResourceValidateResponseEvent(event.requestId, !!resource, resource),
            );
        } catch (error) {
            this.eventEmitter.emit(
                'resource.validate.response',
                new ResourceValidateResponseEvent(event.requestId, false, null, error.message),
            );
        }
    }

    async getResourceWithVisits(resourceId: string) {
        const resource = await this.resourceRepo.findOne({
            where: { id: resourceId, is_deleted: false },
        });

        if (!resource) {
            throw new NotFoundException(`Resource ${resourceId} not found`);
        }

        // ✅ Use Event instead of calling visitsService.findByResourceId() directly
        const visitsResponse = await this.eventRequest.emitAndWait<
            VisitsByResourceRequestEvent,
            VisitsByResourceResponseEvent
        >('visits.by-resource.request', 'visits.by-resource.response', { resourceId });

        return { ...resource, visits: visitsResponse.visits };
    }
}

Step 5: Update Modules (NO forwardRef)

visit.module.ts

@Module({
    imports: [
        CommonModule, // ✅ Provides EventEmitterModule and EventRequestService
        TypeOrmModule.forFeature([Visit], AppDatabases.APP_CORE),
        // ✅ NO forwardRef(() => ResourceModule) needed!
    ],
    providers: [VisitsService],
    exports: [VisitsService],
})
export class VisitModule {}

// resource.module.ts
@Module({
    imports: [
        CommonModule, // ✅ Provides EventEmitterModule and EventRequestService
        TypeOrmModule.forFeature([Resource], AppDatabases.APP_CORE),
        // ✅ NO forwardRef(() => VisitModule) needed!
    ],
    providers: [ResourcesService],
    exports: [ResourcesService],
})
export class ResourceModule {}

Simplified Version (Fire-and-Forget Pattern)

If you don’t need to wait for a response:

@Injectable()
export class VisitsService {
    constructor(
        @InjectRepository(Visit)
        private readonly visitRepo: Repository<Visit>,
        private readonly eventEmitter: EventEmitter2,
    ) {}

    async createVisit(data: CreateVisitDTO): Promise<Visit> {
        const visit = await this.visitRepo.save(this.visitRepo.create(data));

        // ✅ Fire-and-forget: Notify other modules asynchronously
        this.eventEmitter.emit('visit.created', {
            visitId: visit.id,
            resourceId: visit.resource_id,
        });

        return visit;
    }
}

// resources.service.ts — listen for side effects
@Injectable()
export class ResourcesService {
    @OnEvent('visit.created')
    async handleVisitCreated(event: { visitId: string; resourceId: string }): Promise<void> {
        // Update resource's last activity date
        await this.resourceRepo.update(event.resourceId, {
            last_activity_at: new Date(),
        });
    }
}

Comparison: forwardRef vs EventEmitter

Aspect	forwardRef	EventEmitter
Microservice Compatibility	❌ Breaks immediately	✅ Works perfectly
Coupling	High (tight coupling)	Low (loose coupling)
Testing	Difficult (must mock many services)	Easy (mock EventEmitter only)
Debugging	Hard (circular dependencies obscure flow)	Easy (trace event flow)
Sync/Async	Synchronous	Asynchronous (requires handling)
Transaction Support	Easy (direct calls)	Requires careful design

---

Best Practices

1. Golden Rule: Never Use forwardRef in Services Called via Microservice

// ❌ DON'T DO THIS — Will break when called via Microservice
@Injectable()
export class VisitsService {
    constructor(
        @Inject(forwardRef(() => PatientsService))
        private readonly patientsService: PatientsService, // undefined in microservice context!
    ) {}
}

// ✅ DO THIS INSTEAD — No forwardRef, inject only what you need
@Injectable()
export class VisitsService {
    constructor(
        @InjectRepository(Visit, AppDatabases.APP_CORE)
        private readonly visitRepo: Repository<Visit>,
        // Use EventEmitter or Facade Pattern for cross-module communication
    ) {}
}

2. Separate Services by Responsibility

✅ GOOD — Single Responsibility Principle:
├── VisitsService              (Pure CRUD for Visit)
├── AssessmentsService         (Pure CRUD for Assessment)
├── ResourcesService           (Pure CRUD for Resource)
├── VisitOperationsService     (Facade for complex workflows within module)
└── EventRequestService        (Cross-module communication)

❌ BAD — God Service Anti-pattern:
└── VisitsService              (Does everything + filled with forwardRef)

3. Choose Solution Based on Use Case

Situation	Solution
Within Same Module + Complex workflow + Needs Transaction	Facade Pattern
Cross-Module (different modules)	EventEmitter
Fire-and-forget, don’t need to wait for result	EventEmitter (async)
Cross-service communication (different microservices)	Message Queue
Background jobs	Message Queue

4. Decision Tree

                    ┌───────────────────────────┐
                    │ Need to call another      │
                    │ Service?                  │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │ Within the same Module?   │
                    └─────────────┬─────────────┘
                                  │
              ┌───────────────────┼───────────────────┐
              │ YES               │                   │ NO
              ▼                   │                   ▼
    ┌───────────────────┐        │       ┌─────────────────────┐
    │ Complex workflow? │        │       │ Use EventEmitter     │
    └─────────┬─────────┘        │       └─────────────────────┘
              │                   │
    ┌─────────┼─────────┐        │
    │ YES     │         │ NO     │
    ▼         │         ▼        │
┌──────────┐  │   ┌──────────┐   │
│ Facade   │  │   │ Direct   │   │
│ Pattern  │  │   │ Inject   │   │
└──────────┘  │   └──────────┘   │
              │ (No forwardRef    │
              │  if no circular)  │
              └───────────────────┘

5. Debug Checklist

When you encounter Repository/Service undefined errors in Microservice context:

• Check for forwardRef in Service constructors
• If forwardRef within same Module → Use Facade Pattern
• If forwardRef across Modules → Use EventEmitter
• Remove forwardRef from both Service and Module level
• Verify no circular imports between Modules
• Ensure proper module imports in app.module.ts
• Check TypeORM feature imports match correct database

---

Summary

Root Cause

1. Service has forwardRef in constructor
               ↓
2. Microservice TCP message arrives before dependencies fully resolve
               ↓
3. NestJS sends partially initialized instance
               ↓
4. All properties in instance = undefined

Quick Reference

Scenario	Solution	Example
Within Module + Transaction	Facade Pattern	VisitsService + AssessmentsService → VisitOperationsService
Cross-Module	EventEmitter	VisitModule ↔ ResourceModule
Cross-Microservice	Message Queue	data-owner-bc ↔ data-consumer-bc
Fire-and-forget	EventEmitter	Audit logs, Notifications

Golden Rule

NEVER use forwardRef in Services called via Microservice

1. forwardRef + Microservice = Breaks when TCP message arrives
2. Within Same Module → Use Facade Pattern
3. Cross-Module → Use EventEmitter
4. Cross-Microservice → Use Message Queue
5. Separate Services into Pure CRUD — No complex dependencies

---

References

• NestJS Circular Dependency
• NestJS Event Emitter
• NestJS Queues (Bull)
• Facade Pattern — Refactoring Guru