NestJS Enterprise Backend APIs · Lekcja

Punkty rozszerzeń za pomocą Module Reference API

Imperatywnie rozwiązuj zależności o określonym zakresie za pomocą ModuleRef, aby obsługiwać rozszerzenia firm trzecich.

Lekcja 4 z 413 kroki

Punkty rozszerzeń za pomocą Module Reference API to bezpłatna lekcja NestJS Enterprise Backend APIs na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej NestJS Enterprise Backend APIs, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs NestJS Enterprise Backend APIs zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

Why ModuleRef Exists

NestJS resolves dependencies declaratively: you list providers in a constructor and the container wires them. But a plugin host can't know its extensions at compile time. You need to ask the container for a provider imperatively, at runtime.

ModuleRef is the DI container's public handle. It lets you:

Retrieve an existing singleton by token (get).
Resolve a scoped (REQUEST / TRANSIENT) instance on demand (resolve).
Instantiate a class that was never registered as a provider (create).

This is the foundation for plugin architectures and hexagonal extension points where adapters are chosen dynamically.

Injecting ModuleRef

ModuleRef is itself an injectable. Add it to any provider's constructor and Nest hands you the reference to the module instance that owns this provider.

Note that you cannot call get() in the constructor body if the dependency isn't ready yet — prefer onModuleInit for eager lookups so the whole module tree is constructed first.

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

moduleRef.get(token) returns an already-instantiated singleton-scoped provider. It is synchronous and returns the same instance every call.

By default the lookup is scoped to the current module.
Pass { strict: false } to search the entire application (useful when the provider lives in another module that wasn't imported here).

get() throws if the token is request- or transient-scoped — those require resolve().

// 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

Request- and transient-scoped providers do not have a single instance, so get() can't return one. Use the asynchronous resolve() instead.

Each call to resolve() returns a brand-new transient sub-tree by default. Two calls give two different instances — important when a plugin must not share mutable state.

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

Sometimes you want several resolve() calls to share the same request-scoped instances — for example all plugins handling one request should see the same RequestContext.

Pass a contextId to bind resolutions together. Generate one with ContextIdFactory.create() and reuse it.

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

When you create your own contextId outside the normal HTTP pipeline, request-scoped providers that inject REQUEST have nothing to receive. You must register the payload manually with registerRequestByContextId.

This is the key trick for running request-scoped plugins inside cron jobs, queues, or WebSocket handlers where no Express request exists.

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

Plugins often ship classes the host never declared as providers. moduleRef.create(SomeClass) instantiates such a class while still injecting its constructor dependencies from the container.

The result is not cached — every call builds a fresh instance.
The class itself does not need an @Injectable() registration, but its dependencies must be resolvable in the module graph.

This is how you load a plugin class by name and still give it access to core services.

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

Combine a multi-provider token with ModuleRef to build an extension point. Plugins self-register under one injection token; the host resolves them and dispatches by capability.

The EXTENSIONS array is collected by Nest at boot; ModuleRef is reserved for lazy or scoped lookups the array can't express.

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

In hexagonal design the core depends on a port (interface) and stays ignorant of adapters. ModuleRef lets you pick the concrete adapter at runtime from configuration — the classic strategy-by-token pattern.

Use non-strict get() with a string token so the adapter can live in any imported module.

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

Strip away the framework and the contract is just: register adapters by key, then resolve one on demand. This standalone TypeScript program mirrors what ModuleRef.get does over a token registry — useful for unit-testing the dispatch logic in isolation.

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

Use ModuleRef deliberately — it is an escape hatch, not a default.

Don't call get() in a constructor for providers that may not exist yet; use onModuleInit.
Never get() a scoped provider — it throws; use resolve().
Remember resolve() and create() are async and uncached; awaiting in a hot path costs allocations.
Prefer constructor injection when the dependency is known statically — ModuleRef hides the graph from static analysis and tests.
Tie request-scoped resolutions to one contextId and register the request payload off-pipeline.

Quick Check

You need to obtain an instance of a REQUEST-scoped provider from a queue consumer where no HTTP request exists, and all plugins for that job must share the same request-scoped state. Which approach is correct?

Odpowiedz w interaktywnej lekcji

Recap

You learned to resolve dependencies imperatively for plugin and hexagonal extension points:

get(token, { strict }) — synchronous singleton lookup, optionally across the whole app.
resolve(token, contextId?) — async scoped resolution; a shared contextId ties instances into one sub-tree.
registerRequestByContextId — injects a synthetic request so request-scoped providers work off-pipeline.
create(Class) — instantiates an unregistered plugin class while still injecting its dependencies.

Reach for ModuleRef only when the dependency is dynamic; prefer plain constructor injection everywhere else.

Bezpłatny start

Ucz się TypeScript dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 20
Lekcje: 76

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Punkty rozszerzeń za pomocą Module Reference API” jest bezpłatna?

Tak — pełny tekst „Punkty rozszerzeń za pomocą Module Reference API” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu NestJS Enterprise Backend APIs, przejdź na CoddyKit PRO. Kurs NestJS Enterprise Backend APIs zawiera 4 lekcji w sumie.

Co nauczysz się w „Punkty rozszerzeń za pomocą Module Reference API”?

Imperatywnie rozwiązuj zależności o określonym zakresie za pomocą ModuleRef, aby obsługiwać rozszerzenia firm trzecich. Ćwiczysz NestJS Enterprise Backend APIs z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć NestJS Enterprise Backend APIs?

Nie wymagamy żadnego doświadczenia. NestJS Enterprise Backend APIs w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Punkty rozszerzeń za pomocą Module Reference API”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji NestJS Enterprise Backend APIs?

Tak. Każda lekcja NestJS Enterprise Backend APIs zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Porty i adaptery dla izolacji domeny
Dynamiczna rejestracja dostawców za pomocą DiscoveryService
Moduły ładowane leniwie i przełączniki funkcji
Punkty rozszerzeń za pomocą Module Reference API

← Powrót do NestJS Enterprise Backend APIs