node-dependency-injection/README.md

The NodeDependencyInjection component allows you to standardize and centralize the way objects are constructed in your application.

<p align="center">
  <img src="assets/logo.png" alt="Node Dependency Injection" width="480" />
</p>

<h1 align="center">Node Dependency Injection</h1>

<p align="center">
  <strong>Standardize and centralize the way objects are constructed in your application.</strong><br/>
  Inspired by the battle-tested <a href="http://symfony.com">Symfony</a> DI container, built for Node.js &amp; TypeScript.
</p>

<p align="center">
  <a href="https://badge.fury.io/js/node-dependency-injection"><img src="https://badge.fury.io/js/node-dependency-injection.svg" alt="Npm Version" /></a>
  <img src="https://github.com/zazoomauro/node-dependency-injection/actions/workflows/build.yml/badge.svg" alt="Build Status" />
  <a href="https://codecov.io/gh/zazoomauro/node-dependency-injection"><img src="https://codecov.io/gh/zazoomauro/node-dependency-injection/branch/master/graph/badge.svg?token=faEAqrimPR" alt="Code Coverage" /></a>
  <a href="https://www.npmjs.com/package/node-dependency-injection"><img src="https://img.shields.io/npm/dm/node-dependency-injection.svg" alt="Npm Downloads" /></a>
  <a href="https://snyk.io/test/github/zazoomauro/node-dependency-injection"><img src="https://snyk.io/test/github/zazoomauro/node-dependency-injection/badge.svg" alt="Known Vulnerabilities" /></a>
  <a href="https://github.com/zazoomauro/node-dependency-injection/blob/master/LICENCE"><img src="https://img.shields.io/npm/l/node-dependency-injection.svg" alt="License" /></a>
</p>

---

## 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 &amp; 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.

---

<p align="center">
  <a href="https://github.com/zazoomauro/node-dependency-injection/blob/master/LICENCE">MIT License</a> &nbsp;·&nbsp;
  Made with ❤️ by <a href="https://twitter.com/zazoomauro">@zazoomauro</a>
</p>