TypeScript library · v2.0.0

@zirion/ioc

A lightweight, dependency-free IoC container for Node.js with constructor injection, lazy resolution, and singleton and request-scoped lifetimes.

TypeScriptNode.jsIoCdependency injection
Read documentation →View on npm ↗GitHub ↗

@zirion/ioc is a compact Inversion of Control container for Node.js applications. It keeps dependency management explicit without bringing runtime dependencies into a project.

What it provides

  • Constructor injection for classes and registered values.
  • Singleton and request-scoped provider lifetimes.
  • Context objects for request-scoped dependencies.
  • Lazy dependency resolution.
  • A fluent container builder and no runtime dependencies.

Install

npm install @zirion/ioc

Continue with the complete Dependency Injection guide for scopes, asynchronous factories, lifecycle hooks, testing patterns, errors, migration notes, and the public API reference.

The package is open source under the MIT license. The current roadmap is available in the repository.

Release history

2.0.0March 10, 2026
  • Made container resolution asynchronous: get() and getOrFail() now return promises.
  • Replaced provider value with an async-capable valueFactory API.
  • Added typed container composition: each add() call carries registered selectors into the resulting container type.
  • Added object selectors and support for factories that return either values or class constructors.
  • Added configurable logging with a default console logger and exported logger interfaces.
  • Added the onInitialized lifecycle hook and build() as an alias for finalize().
  • finalize() now supports registered objects as well as class instances and returns the built container.
1.3.0November 19, 2024
  • Removed the package-level prebuilt container export; consumers now create their own Container instance.
  • Improved return-type inference for class selectors in get() and getOrFail().
  • Simplified package exports and removed the @zirion/ioc/container entry point.
  • Declared Node.js 18+ support and added browser compatibility metadata.
  • Updated documentation and package discovery keywords.
1.2.1September 20, 2024
  • Fixed the finalized lifecycle hook lookup: the container now correctly calls onFinalized().
  • Added test execution to the package release checks.
  • Updated the TypeScript, ESLint, Vitest, and Node.js type toolchain.
1.2.0August 5, 2024
  • Added structured DependencyInjectionError errors and exported error codes for container failures.
  • Added validation for missing and duplicate targets, unknown selectors and scopes, and invalid resolvers.
  • Added explicit errors for missing request contexts and invalid singleton-to-request dependency graphs.
  • Fixed singleton caching so resolved instances are reused.
  • Added utilities for readable selector names, broader test coverage, and coverage reporting.
1.1.2July 14, 2024
  • Maintenance publication aligning the package version metadata with the npm release.
1.1.1July 14, 2024
  • Reworked the package structure and public entry points.
  • Added separate CommonJS, ES module, and declaration builds.
  • Added package documentation, usage examples, and contributing guidelines.
  • Added dependency update and stale-issue automation for the repository.
1.0.0July 14, 2024
  • Initial npm release of the IoC container.
  • Added provider registration and lazy dependency resolution.
  • Added constructor injection with singleton and request-scoped lifetimes.
  • Added context-based caching for request-scoped providers and the onFinalized lifecycle contract.

Interactive example

Try @zirion/ioc

Edit the example and run it locally in your browser. No code is sent anywhere.

Output
Ready. Press Run code or ⌘/Ctrl + Enter.