จุดขยายด้วย API อ้างอิงโมดูล

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.

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.