Extension Points with the Module Reference API

Why ModuleRef Exists

Injecting ModuleRef

import { Injectable, OnModuleInit } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { AuditService } from './audit.service';

@Injectable()
export class PluginHost implements OnModuleInit {
  private audit: AuditService;

  constructor(private readonly moduleRef: ModuleRef) {}

  onModuleInit() {
    // Safe here: all providers are already instantiated.
    this.audit = this.moduleRef.get(AuditService);
  }
}

get() — Retrieving Singletons

// Same module — strict (default)
const local = this.moduleRef.get(LocalCache);

// Anywhere in the app graph — non-strict
const global = this.moduleRef.get(ConfigService, { strict: false });

// String / Symbol tokens work too
const driver = this.moduleRef.get<StorageDriver>('STORAGE_DRIVER', {
  strict: false,
});

resolve() — Scoped Instances

import { Injectable } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { TenantProcessor } from './tenant.processor'; // @Injectable({ scope: Scope.TRANSIENT })

@Injectable()
export class JobRunner {
  constructor(private readonly moduleRef: ModuleRef) {}

  async run() {
    const a = await this.moduleRef.resolve(TenantProcessor);
    const b = await this.moduleRef.resolve(TenantProcessor);
    console.log(a === b); // false — distinct transient instances
  }
}

Sharing a Scoped Sub-Tree with contextId

import { ContextIdFactory, ModuleRef } from '@nestjs/core';

const contextId = ContextIdFactory.create();

const ctx = await this.moduleRef.resolve(RequestContext, contextId);
const svc = await this.moduleRef.resolve(ReportService, contextId);
// ctx and svc share the SAME request-scoped sub-tree

const other = await this.moduleRef.resolve(ReportService, contextId);
console.log(svc === other); // true — same contextId reuses the instance

Registering the Request Payload

import { ContextIdFactory, ModuleRef, REQUEST } from '@nestjs/core';

const contextId = ContextIdFactory.create();

// Inject a synthetic 'request' for this context
this.moduleRef.registerRequestByContextId({ tenantId: 'acme' }, contextId);

// Now request-scoped providers resolve correctly off the queue
const handler = await this.moduleRef.resolve(TenantHandler, contextId);
await handler.process();

create() — Instantiating Unregistered Classes

import { Injectable } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';

// Shipped by a third party, never in any providers array
class SlackNotifier {
  constructor(private readonly http: HttpClient) {}
  notify(msg: string) { return this.http.post('/slack', { msg }); }
}

@Injectable()
export class ExtensionLoader {
  constructor(private readonly moduleRef: ModuleRef) {}

  async load() {
    // http is injected from the container, SlackNotifier is not registered
    const plugin = await this.moduleRef.create(SlackNotifier);
    return plugin;
  }
}

A Token-Driven Plugin Registry

import { Inject, Injectable } from '@nestjs/common';

export const EXTENSIONS = Symbol('EXTENSIONS');

export interface Extension {
  readonly name: string;
  handle(event: unknown): Promise<void>;
}

@Injectable()
export class ExtensionDispatcher {
  constructor(@Inject(EXTENSIONS) private readonly exts: Extension[]) {}

  async dispatch(name: string, event: unknown) {
    const ext = this.exts.find((e) => e.name === name);
    if (!ext) throw new Error(`No extension: ${name}`);
    await ext.handle(event);
  }
}

Hexagonal Adapters Chosen at Runtime

import { Injectable } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';

export interface PaymentPort {
  charge(cents: number): Promise<string>;
}

@Injectable()
export class PaymentFacade {
  constructor(private readonly moduleRef: ModuleRef) {}

  private adapterToken(provider: string) {
    return `PAYMENT_ADAPTER_${provider.toUpperCase()}`;
  }

  pick(provider: string): PaymentPort {
    // e.g. PAYMENT_ADAPTER_STRIPE registered in StripeModule
    return this.moduleRef.get<PaymentPort>(this.adapterToken(provider), {
      strict: false,
    });
  }
}

Modeling the Lifecycle in Plain TS

interface PaymentPort {
  charge(cents: number): string;
}

class StripeAdapter implements PaymentPort {
  charge(cents: number): string {
    return `stripe:charged ${cents}`;
  }
}

class PaypalAdapter implements PaymentPort {
  charge(cents: number): string {
    return `paypal:charged ${cents}`;
  }
}

class Registry {
  private map = new Map<string, PaymentPort>();
  register(key: string, port: PaymentPort): void {
    this.map.set(key, port);
  }
  get(key: string): PaymentPort {
    const p = this.map.get(key);
    if (!p) throw new Error(`No adapter: ${key}`);
    return p;
  }
}

const registry = new Registry();
registry.register('stripe', new StripeAdapter());
registry.register('paypal', new PaypalAdapter());

const chosen = 'paypal';
console.log(registry.get(chosen).charge(1999));
console.log(registry.get('stripe').charge(500));

Pitfalls & Best Practices

Quick Check

Recap