@archware/di is a lightweight inversion of control (IoC) solution for TypeScript projects.
It designed to work seamlessly with object oriented architectures.
It aims to be flexible, but easy to understand.
It can be used in any modern environment, be it browser or Node.
One of the strongest advantages of object oriented programming is interfaces. They allow defining strong architectural boundaries, which is the cornerstone of any maintainable piece of software.
Dependency Inversion, Interface Segregation and Open/Closed principle are the SOLID principles this library aims to encourage.
InversifyJS is a well known IoC solution for TypeScript. Why create another instead of contributing?
There are a few differences that this project deliberately creates:
The goal is to encourage healthy project architecture and established principles. It is enabled by putting interfaces at the center.
By making less assumptions and deciding where the flexibility really needs to be, there's less maintenance and almost no learning curve.
This guides the user better towards the preferred solution and reduces confusion. Spend less time browsing the docs and more writing the code.
- Install the package:
npm install @archware/di --save- Set
tsconfig.jsonflags:
{
"compilerOptions": {
"emitDecoratorMetadata": true,
"experimentalDecorators": true
}
}- Decorate and resolve:
import { Resolvable, Injector } from '@archware/di';
const injector = new Injector();
// 1. Decorate dependency
@Resolvable()
class Engine { }
// 2. Decorate the resolved class
@Resolvable()
class Car {
constructor(engine: Engine) { }
}
// 3. Resolve
const car = injector.resolve(Car);The full reference page will soon be shared. It will include detailed explanations, complex usage guides and library architecture.
For now please refer to common usecase cheatsheets below:
import { Resolvable } from '@archware/di';
// 1. Decorate
@Resolvable()
class Car { }
// 2. Resolve
injector.resolve(Car);import { Resolvable } from '@archware/di';
import { asImplementation } from '@archware/di/register';
class Car {
constructor(engine: Engine) { }
}
// 1. Preserve interface as runtime value
// by declaring an abstract class with same name
interface Engine {
start(): void;
}
abstract class Engine { }
// 2. Decorate the implementation
@Resolvable()
class V8Engine implements Engine {
start() { }
}
// 3. Register the implementation
injector.register(asImplementation(Engine, V8Engine));
// 4. Get the car with a V8 engine :)
injector.resolve(Car);import { Resolvable } from '@archware/di';
@Resolvable({
singleton: true
})
class Car { }import { Resolvable } from '@archware/di';
import { asValue } from '@archware/di/register';
// 1. Use asValue to correlate some arbitrary token to a value
injector.register(asValue('PI', Math.PI));
// 2. Resolve using the token
const pi = injector.resolve('PI');import { Resolvable, Inject } from '@archware/di';
import { asValue } from '@archware/di/register';
// 1. Use asValue to correlate some arbitrary token to a value
injector.register(asValue('NAME', 'John'));
@Resolvable()
class Person {
constructor(
// 2. Pass the token to @Inject()
@Inject('NAME') public name: string,
) { }
}
const person = injector.resolve(Person); // person.name will be 'John'import { Resolvable, Inject } from '@archware/di';
import { asImplementation } from '@archware/di/register';
interface Engine {
start(): void;
}
abstract class Engine { }
@Resolvable()
class V8Engine implements Engine {
start() { }
}
@Resolvable()
class ElectricEngine implements Engine {
start() { }
}
@Resolvable()
class Car {
constructor(engine: Engine) { }
}
@Resolvable()
class SportsCar {
constructor(
// 1. Provide the chosen implementation to @Inject() decorator
@Inject(V8Engine) engine: Engine
) { }
}
// This will be overriden by @Inject()
injector.register(asImplementation(Engine, ElectricEngine));
// 2. Get the car with V8Engine
injector.resolve(SportsCar);
// This will still return a Car with ElectricEngine
injector.resolve(Car);We encourage you to create an issue if you want to:
- raise a bug
- request a feature
- ask for usage advice
- post a general question
We'll try out best to find a viable solution.
Thanks for considering to contribute!
Feel free to drop us a line at [email protected]
Contributing guide will be prepared soon.
Created by archware.io software house
MIT, Copyright © 2022 Archware Limited and contributors