Node Dependency Injection
Standardize and centralize the way objects are constructed in your application.
Inspired by the battle-tested Symfony DI container, built for Node.js & TypeScript.
---
## 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
```sh
npm install --save node-dependency-injection
```
---
## ๐ Quick Start
Register services and wire them together in seconds:
```js
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:
```ts
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.
```ts
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:
```yaml
# services.yaml
services:
service.example:
class: 'services/ExampleService'
service.mailer:
class: 'services/Mailer'
arguments: ['@service.example']
```
```js
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:
```bash
npm install --save node-dependency-injection-express-middleware
```
```js
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](https://github.com/zazoomauro/node-dependency-injection-express-middleware)
### CLI
Inspect and validate your container from the command line:
```bash
# 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**](https://github.com/zazoomauro/node-dependency-injection/wiki), including guides on:
- [Getting Started](https://github.com/zazoomauro/node-dependency-injection/wiki/GettingStarted)
- [Autowire](https://github.com/zazoomauro/node-dependency-injection/wiki/Autowire)
- [Configuration Files](https://github.com/zazoomauro/node-dependency-injection/wiki/ConfigurationFiles)
- [Compiler Passes](https://github.com/zazoomauro/node-dependency-injection/wiki/CompilerPass)
- [Tagging Services](https://github.com/zazoomauro/node-dependency-injection/wiki/Tagging)
- [Factory](https://github.com/zazoomauro/node-dependency-injection/wiki/Factory)
- [Lazy Services](https://github.com/zazoomauro/node-dependency-injection/wiki/LazyService)
- [Decorators](https://github.com/zazoomauro/node-dependency-injection/wiki/Decorate)
- [And much more...](https://github.com/zazoomauro/node-dependency-injection/wiki)
---
## ๐ค Contributing
Contributions are welcome! Please read the [contribution guide](CONTRIBUTING.md) before submitting a pull request.
- [Open an issue](https://github.com/zazoomauro/node-dependency-injection/issues)
- [View milestones](https://github.com/zazoomauro/node-dependency-injection/milestones)
- [Changelog](CHANGELOG.md)
---
## ๐ Credits
Inspired by the [Symfony](http://symfony.com) Dependency Injection component โ a special thanks to the Symfony team for their outstanding work.
---
MIT License ยท
Made with โค๏ธ by @zazoomauro