@rokkit.ts/dependency-injection
Version:
TypeScript dependency injection library using decorators for the rokkit.ts framework and other projects
141 lines (100 loc) • 4.59 kB
Markdown
# rokkit.ts-dependency-injection
[](https://travis-ci.com/rokkit-ts/rokkit.ts-dependency-injection)
TypeScript dependency injection library using decorators for the rokkit.ts framework and other projects.
It provides a simple API to register classes and create instances of them.
The instances are handled in one container called `RokkitDI`.
## Install and Build
To install the package:
```bash
npm install @rokkit.ts/dependency-injection
```
## Usage
You can use two different ways of using the whole package.
The first way is to register your classes by decorators.
The second way is to use the native API of the RokkitDI container.
### Using Decorators
The following example show a simple usage of the package.
The first listing shows the class that you want to be injected.
```typescript
import { Injectable, Inject } from '@rokkit.ts/dependency-injection'
@Injectable()
class DecoratedClass {
public foo: string
public bar: number
constructor(@Inject('test') foo: string, @Inject(0.11) public bar: number) {
this.foo = foo
this.bar = bar
}
}
```
After annotating the class, we can retrieve an singleton or an instance by the `RokkitDI`.
With this injector we could now create an instance of the corresponding class.
```typescript
import { RokkitDI } from '@rokkit.ts/dependency-injection'
const instance: DecoratedClass = RokkitDI.singletonOf('DecoratedClass')
console.log(`Foo: ${instance.foo}, Bar: ${instance.bar}`)
// Output: Foo: test, Bar: 0.11
```
#### Automatic Constructor Argument scanning
The package provides the ability to scan classes arguments automatically. If any constructor argument is not decorated with the <code>@Inject
(value:
any)</code> annotation, the base container tries to create automatically an instance for it.
#### Code Example
The first listing shows two classes the "FirstDecoratedClass" class has a dependency for the second class
"SecondDecoratedClass". Note that both class are annotated as <code>@Injectable</code>, but only the second class
has <code>@Inject</code>
annotation present on the constructor. The package will now scan all user source code files for the constructor
argument and automatically adds the found arguments. This allows you to create an instance of "FirstDecoratedClass"
without annotating the constructor with a specific value for user object.
By default the source code scan will look for the source code directory "./src". If you want to change this behavior
set the environment variable <code>SRC_SCAN_DIR</code> to you preferable directory before starting your application.
```typescript
import { Injectable, Inject } from '@rokkit.ts/dependency-injection'
@Injectable()
class FirstDecoratedClass {
public classDependency: SecondDecoratedClass
constructor(classDependency: SecondDecoratedClass) {
this.classDependency = classDependency
}
}
@Injectable()
class SecondDecoratedClass {
public foo: string
public bar: number
constructor(@Inject('test') foo: string, @Inject(0.11) public bar: number) {
this.foo = foo
this.bar = bar
}
}
```
### Use the native API
The native API let's you easy register an injectable class on the `RokkitDi` container.
In order to register a class you need to provide its arguments.
```typescript
import { RokkitDI } from '@rokkit.ts/dependency-injection'
class AClass {
constructor(public foo: string, bar: number)
}
RokkitDI.registerInjectable(AClass, [
{ index: 0, type: 'string', value: 'test' },
{ index: 1, type: 'number', value: 0.11 }
])
const instance: AClass = RokkitDI.singletonOf('AClass')
console.log(`Foo: ${instance.foo}, Bar: ${instance.bar}`)
// Output: Foo: test, Bar: 0.11
```
## API Description
| Decorators | |
| :--------: | :--------------------------------------------- |
| Methods: | <code>@Injectable(contextName?: string)</code> |
| | <code>@Inject(value: any)</code> |
| Class: | RokkitDI |
| :------: | :------------------------------------------ |
| Methods: | <code>registerInjectable(Class)</code> |
| | <code>singletonOf(className: string)</code> |
| | <code>instanceOf(className: string)</code> |
## Contribution
If you want to contribute to the project, please don't hesitate to send feedback, create issues or a pull request for
open ones.
## License
Rokkit.ts-dependency-injection is Open Source software released under the MIT License.