@archware/di
v1.1.2
Published
Lightweight dependency injection for TypeScript
Downloads
15
Readme
About
@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.
Motivation
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.
What about InversifyJS?
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:
It puts interfaces first
The goal is to encourage healthy project architecture and established principles. It is enabled by putting interfaces at the center.
It is designed with simplicity in mind.
By making less assumptions and deciding where the flexibility really needs to be, there's less maintenance and almost no learning curve.
It has minimal public API
This guides the user better towards the preferred solution and reduces confusion. Spend less time browsing the docs and more writing the code.
Get started
- Install the package:
npm install @archware/di --save
- Set
tsconfig.json
flags:
{
"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);
Documentation
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:
Resolving a class
import { Resolvable } from '@archware/di';
// 1. Decorate
@Resolvable()
class Car { }
// 2. Resolve
injector.resolve(Car);
Resolving an interface implementation
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);
Declaring a class is a singleton
import { Resolvable } from '@archware/di';
@Resolvable({
singleton: true
})
class Car { }
Resolving a generic value that's not a class
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');
Providing a non-class value as a constructor parameter
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'
Overriding an interface implementation
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);
Support
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.
Contributing
Thanks for considering to contribute!
Feel free to drop us a line at [email protected]
Contributing guide will be prepared soon.
Author
Created by archware.io software house
License
MIT, Copyright © 2022 Archware Limited and contributors