Why Node Dependency Injection?

Managing dependencies manually leads to tightly coupled, hard-to-test code. Node Dependency Injection gives you a powerful, flexible IoC container that wires your application together — keeping your classes clean, your tests simple, and your architecture solid.

✨ Features

| | | |---|---| | 🔄 Autowire — zero-config DI for TypeScript | 📁 Config files — YAML, JSON or JS | | 🏭 Factory pattern — flexible service creation | 🏷️ Service tagging — group & inject by tag | | 💤 Lazy services — instantiate only when needed | 🎨 Decorators — wrap services transparently | | ⚡ Compiler passes — transform the container at build time | 🔒 Private services — encapsulate internals | | 🌳 Parent / Abstract services — share config via inheritance | 🧩 Non-shared services — new instance per call | | 🌿 Environment parameters — %env(VAR)% support | 🗑️ Deprecation warnings — mark services as deprecated | | 📦 Express middleware — first-class web framework support | 🖥️ CLI — inspect & validate your container |

🚀 Installation

npm install --save node-dependency-injection

🏁 Quick Start

Register services and wire them together in seconds:

import { ContainerBuilder } from 'node-dependency-injection'
import Mailer from './services/Mailer'
import ExampleService from './services/ExampleService'

const container = new ContainerBuilder()

container.register('service.example', ExampleService)
container.register('service.mailer', Mailer).addArgument('service.example')

await container.compile()

const mailer = container.get('service.mailer')

🔄 Autowire (TypeScript)

Zero-configuration dependency injection — NDI reads your TypeScript type annotations and wires everything automatically:

import { ContainerBuilder, Autowire } from 'node-dependency-injection'

const container = new ContainerBuilder(false, '/path/to/src')
const autowire = new Autowire(container)
await autowire.process()
await container.compile()

// Retrieve by class — no string IDs needed
import SomeService from '@src/service/SomeService'
const service = container.get(SomeService)

Production tip: dump the autowired config to a YAML file and load it directly in prod — no TypeScript scanning overhead.

if (process.env.NODE_ENV === 'development') {
  const autowire = new Autowire(container)
  autowire.serviceFile = new ServiceFile('/dist/services.yaml')
  await autowire.process()
} else {
  const loader = new YamlFileLoader(container)
  await loader.load('/dist/services.yaml')
}
await container.compile()

📁 Configuration Files

Prefer declarative config? Use YAML, JSON or JS:

# services.yaml
services:
  service.example:
    class: 'services/ExampleService'

  service.mailer:
    class: 'services/Mailer'
    arguments: ['@service.example']

import { ContainerBuilder, YamlFileLoader } from 'node-dependency-injection'

const container = new ContainerBuilder()
const loader = new YamlFileLoader(container)
await loader.load('/path/to/services.yaml')
await container.compile()

const mailer = container.get('service.mailer')

📦 Ecosystem

Express Middleware

Use NDI seamlessly with Express — retrieve the container directly from any request:

npm install --save node-dependency-injection-express-middleware

import NDIMiddleware from 'node-dependency-injection-express-middleware'
import express from 'express'

const app = express()
app.use(new NDIMiddleware({ serviceFilePath: 'services.yaml' }).middleware())

Express Middleware Documentation

CLI

Inspect and validate your container from the command line:

# Validate a config file
ndi config:check /path/to/services.yaml

# Inspect a specific service
ndi container:service /path/to/services.yaml service.mailer

📖 Documentation

The full documentation lives in the project wiki, including guides on:

• Getting Started
• Autowire
• Configuration Files
• Compiler Passes
• Tagging Services
• Factory
• Lazy Services
• Decorators
• And much more...

🤝 Contributing

Contributions are welcome! Please read the contribution guide before submitting a pull request.

• Open an issue
• View milestones
• Changelog

🙏 Credits

Inspired by the Symfony Dependency Injection component — a special thanks to the Symfony team for their outstanding work.