DI containers in production: resolution graphs, circular deps, and when not to

A container is a graph resolver

What does a container actually do under those decorators — and why does that matter when things go wrong? Strip away the decorators and a DI container does one thing: it reads the dependency declarations, builds a directed graph, and instantiates in dependency order — leaves first, then the things that depend on them, up to the root. This is a topological sort. To create OrderService(db, payments), it must first create db and payments; to create those it resolves their dependencies, recursively. For singletons it does this once and caches the instance, so the second consumer of db gets the same object. The container is the automated composition root from earlier in the unit — the one place that knows concretions, now mechanized.

Why circular dependencies break it

A topological sort only exists for a directed acyclic graph. If A depends on B and B depends on A, there is no “leaves first” order: to build A you need B, but to build B you need A. The container detects the cycle and refuses, which is the Hook’s error. Frameworks offer an escape hatch — NestJS’s forwardRef(() => Other) — that breaks the deadlock by deferring one side’s resolution until after construction. But the escape hatch is a smell, not a solution: a cycle almost always means two classes that should be one, or a missing third class that both should depend on. Reaching for forwardRef to silence the error preserves the design flaw.

Eager vs lazy: when failure surfaces

Containers differ on when they instantiate. Eager instantiation builds the whole singleton graph at startup, before serving traffic — NestJS does this by default. Lazy instantiation creates each provider on first use. The tradeoff is when bad configuration bites: eager startup means a missing env var or unresolvable dependency crashes the boot — loud, immediate, before any user is affected. Lazy means the same misconfiguration hides until the first request hits that code path, possibly hours later, possibly only on one endpoint. For server applications the senior preference is overwhelmingly eager: pay a slightly slower boot to convert a 3 a.m. runtime page into a deploy-time failure your CI catches.

The hidden costs

A container is not free. It adds startup time (building the graph), a learning and debugging tax (stack traces run through framework resolution code, and “cannot resolve” errors are their own skill to read), and a temptation toward hidden global state — the container becomes a place to stash singletons that are really just globals with extra steps. For a small service, a CLI, or a serverless function with a tiny graph, hand-wiring in a composition root — plain new calls in one file at the entry point — is often clearer and faster than a container. The container earns its cost when the graph is large, lifetimes are mixed, and the wiring would otherwise be a sprawling manual mess. “Use a DI container” is a scale decision, not a default.

Quantify the cost so the decision is not a vibe. Hand-wired construction — new calls in one file — completes in microseconds; the graph is built before the event loop even spins. A reflection-and-decorator container instead reads metadata for every provider at boot: a NestJS app with a few hundred providers commonly spends tens to low-hundreds of milliseconds resolving and instantiating its graph at startup. On a long-running server that one-time tax is invisible against months of uptime — pay 150ms once, amortize it to zero. In a serverless function it is the opposite: that same 150ms lands on every cold start, billed per millisecond and felt as p99 latency by the unlucky request that triggered the cold init, which is why heavy reflective containers are a poor fit for Lambda-style workloads and teams there often hand-wire or use a compile-time DI approach that does the resolution at build time instead of boot. The break-even is roughly: graph under ~10 objects with uniform lifetimes → hand-wire and skip the framework tax; graph of dozens-to-hundreds with mixed scopes and a long-lived process → the container’s automation is worth its startup cost. Match the tool to the deployment shape, not to habit.