Ligature

Ligature is a service injection framework specifically designed for use with Typescript and Node.js.

As part of an web server startup it's common to have a few asynchronous tasks that must be performed in a particular order. For example, an application might connect to a database, fetch some initial data, and only then is it in a state where it can serve content.

Installation

$ npm install ligature

Ligature requires that experimentalDecorators and emitDecoratorMetadata both be set to true in the tsconfig.json.

Usage

Services

Define a service that extend the Services class and implement an init method.

import { Service } from 'ligature';

export default class FooService extends Service {

  init () {
    console.log('FooService has been initialized');
  }
  
  doSomething () {
  
  }

}

That service can then be injected into other services using the @inject decorator.

import { Service } from 'ligature';
import FooService from './foo';

@inject
foo: FooService;

export default class BarService extends Service {

  init () {
    console.log('BarService has been initialized');
    this.foo.doSomething();
  }
  
}

Then initialize all the services using the ServiceLoader.

import { ServiceLoader } from 'ligature';
import FooService from './foo';
import BarService from './bar';

ServiceLoader.getInstance().init([FooService, BarService]).then(() => {
  console.log('Services started!');
}, (err) => {
  console.log('Could not start services', err);
});

Ligature determines the correct order in which the services must be started, and invokes the init method on each on in the correct order.

Finally services can be accessed from the ServiceLoader with the get method.

let foo = ServiceLoader.getInstance().get(FooService);

Consumers

Ligature also provides a Consumer class, which is similar to a Service except Consumers cannot be injected into other Services or Consumers.

import { Consumer } from 'ligature';
import FooService from './foo';

@inject
foo: FooService;

export default class FooConsumer extends Consumer {

  init () {
    console.log('FooConsumer has been initialized');
  }
  
}

Passing options to Service init method

Any options map keyed off of the Service can be passed into the ServiceLoader's init method.

let initOptions = new Map();
initOptions.set(Express, { foo: 'bar' });

let loader = await ServiceLoader.getInstance().init([Express, ...routes], initOptions);

When the corresponding Service is initialized, its init method will be passed the specified options.

Advanced Usage

In addition to the init method, Ligature allows an optional done method on each service and consumer. The done method is executed in reverse order from init. For example, if services A, B, and C are initialized in the order A => B => C, then the done method is called in the order C => B => A.

An example of where the done method is useful is when creating a service to start an Express app (See the express-app in example). There's an Express service which exposes the express app, and routes are implemented as Consumers that depend on the Express service. Since error middleware must be registered last, that's handled within the done method to ensure it's registered last.