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:

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.

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.

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 @Inject (value: any) 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 @Injectable, but only the second class has @Inject 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 SRC_SCAN_DIR to you preferable directory before starting your application.

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.

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:	`@Injectable(contextName?: string)`
	`@Inject(value: any)`

Class:	RokkitDI
Methods:	`registerInjectable(Class)`
	`singletonOf(className: string)`
	`instanceOf(className: string)`

Contribution

All kinds of contributions are welcome, no matter how big or small. Before you start to contribute please read our Code of Conduct.

In order to submit any contribution check out our contribution guidelines.

License

Rokkit.ts-dependency-injection is Open Source software released under the MIT License.

rokkit-ts/rokkit.ts-dependency-injection