Ulixes

The Lightweight Dependency Injection package in the Angular and NestJs style for Node.Js based on the inversion of control (IoC).

Installation

npm install ulixes

Examples

Simple injection

import { Injectable, Inject, Injector } from 'ulixes';

@Injectable()
class Finger {
  constructor() {
  }

  public getName(): string {
    return 'thumb';
  }
}

@Injectable()
class Hand {
  constructor(public finger: Finger) {
  }
}

@Injectable()
class Body {
  constructor(public leftHand: Hand) {
  }
}

const app = {}; // any object for being a root for the injector or undefined for use global object
const injector = Injector.create(app, [Body, Hand, Finger]);
const body = injector.instantiate(Body);
expect(body.leftHand.finger.getName()).equal('thumb');

UseValue injection

import { Injectable, Inject, Injector } from 'ulixes';

@Injectable()
class Finger {
  constructor(private name: string) {
    this.name = this.name || 'thumb';
  }

  public getName(): string {
    return this.name;
  }
}

@Injectable()
class Hand {
  constructor(public finger: Finger) {
  }
}

@Injectable()
class Body {
  constructor(public leftHand: Hand) {
  }
}

const indexFinger = new Finger('index');
const injector = Injector.create(null /* using global */, [
  Body,
  Hand,
  { provide: Finger, useValue: indexFinger },
]);
const body = injector.instantiate(Body);
expect(body.leftHand.finger.getName()).equal('index');

UseClass injection

import { Injectable, Inject, Injector } from 'ulixes';

@Injectable()
class Finger {
  constructor(private name: string) {
    this.name = this.name || 'thumb';
  }

  public getName(): string {
    return this.name;
  }
}

class MiddleFinger extends Finger {
  constructor() {
    super('middle');
  }
}

@Injectable()
class Hand {
  constructor(public finger: Finger) {
  }
}

@Injectable()
class Body {
  constructor(public leftHand: Hand) {
  }
}

const injector = Injector.create(null /* using global */, [
  Body,
  Hand,
  { provide: Finger, useClass: MiddleFinger },
]);
const body = injector.instantiate(Body);
expect(body.leftHand.finger.getName()).equal('middle');

UseFactory injection

import { Injectable, Inject, Injector } from 'ulixes';

@Injectable()
class Finger {
  constructor(private name: string) {
    this.name = this.name || 'thumb';
  }

  public getName(): string {
    return this.name;
  }
}

@Injectable()
class Hand {
  constructor(public finger: Finger) {
  }
}

@Injectable()
class Body {
  constructor(public leftHand: Hand) {
  }
}

const injector = Injector.create(null /* using global */, [
  Body,
  Hand,
  { provide: Finger, useFactory: () => new Finger('middle') },
]);
const body = injector.instantiate(Body);
expect(body.leftHand.finger.getName()).equal('middle');

Inject param by token

import { Injectable, Inject, Injector } from 'ulixes';

@Injectable()
class Nail {
  public color = 'transparent';

  constructor(@Inject('NAIL_COLOR') color: string) {
    this.color = color;
  }
}

@Injectable()
class Finger {
  constructor(public nail: Nail) {
  }
}

@Injectable()
class Hand {
  constructor(public finger: Finger) {
  }
}

@Injectable()
class Body {
  constructor(public leftHand: Hand) {
  }
}

const injector = Injector.create(null /* using global */, [
  Body,
  Hand,
  Finger,
  Nail,
  { provide: 'NAIL_COLOR', useValue: 'black' },
]);
const body = injector.instantiate(Body);
expect(body.leftHand.finger.nail.color).equal('black');

Documentation

Decorator @Injectable(options)

Marks the classes as injectable.

Option

Option | Required | Type | Default | Description --- | --- | --- | --- | --- alias | no | string | undefined | Alias name of the injectable class, reserved providers | no | TProvider[] | undefined | Providers for the injectable class

Decorator @Inject(token)

Marks parameters of the injectable classes as injectable with a specific token.

Param | Required | Type | Default | Description --- | --- | --- | --- | --- token | yes | string | - | String representation of the token with which parameter of the injectable type could be injected

Injector

The Injector class builds the injection tree and resolve all dependencies. Supports unlimited level of dependencies. This DI approach has inspired by angular and nest.js dependency injection, but realized pretty simple for using outside of the bulky frameworks.

The tree traversal starts from root type (constructor or class) and going on to it's params of dependencies and so on. At the every level makes scope object. Scope stores its own unique providers for using in the lower levels for resolving instances.

Options

Option | Required | Type | Default | Description --- | --- | --- | --- | --- strictProviders | no | boolean | true | In the strict providers mode all injectable classes must be mentioned in providers debug | no | boolean | false | On / Off debugger mode