vorarbeiter

A simple service container

Installation

npm install vorarbeiter

Basic usage

1. Create some services:

interface Car {
  getDriverName(): string;
}

class CarImpl implements Car {
  constructor(private readonly driver: Driver) {}
  getDriverName() {
    return this.driver.getName();
  }
}

interface Driver {
  getName(): string;
}

class DriverImpl implements Driver {
  getName() {
    return "Michael Schumacher";
  }
}

1. Explain to Service Container how to create services, use factories for this:

class CarFactory implements ServiceFactory {
  create(container: ServiceContainer): CarImpl {
    const driver = container.get("driver");
    return new CarImpl(driver);
  }
}

1. Create Service Specification:

import { createServiceSpecBuilder } from "vorarbeiter";

const specBuilder = createServiceSpecBuilder();

specBuilder.set("car", new CarFactory());
specBuilder.set("driver", () => new DriverImpl());

const spec = specBuilder.getServiceSpec();

If creating a service is trivial, as for driver, we can simply pass a function as a factory. As for class based factory we can pass ServiceContainer as a function parameter.

1. Create Service Container with this Service Specification:

import { createServiceContainer } from "vorarbeiter";

const serviceContainer = createServiceContainer(spec);

1. Get some service and call its method:

const car: Car = serviceContainer.get("car");

console.log(car.getDriverName());

1. Get string "Michael Schumacher".

Service scope

Shared

By default, services have global scope. It means that the same service will be shared across whole application.

Example:

let serviceInstance1;
let serviceInstance2;
// In some part of our application we get a service
serviceInstance1 = serviceContainer.get("myService");
// In some another part of our application we get a service again
serviceInstance2 = serviceContainer.get("myService");

console.log(serviceInstance1 === serviceInstance2); // true

Scoped

Sometimes we need to have service uniqueness within a specific scope, for example, within one user request. To do that we should specify the Context Resolver when configure Service Specification. Resolving result of the Context Resolver should be any object. To imitate situation when we have two different contexts we can use AsyncLocalStorage from "node:async_hooks" package.

Example:

const asyncLocalStorage = new AsyncLocalStorage<object>();
specBuilder
  .set("myScopedService", () => ({ serviceName: "Awesome service" }))
  .scoped(() => asyncLocalStorage.getStore());

const serviceContainer = createServiceContainer(specBuilder.getServiceSpec());

let scopedService1;
{
  let scopedService2;

  asyncLocalStorage.run({}, () => {
    scopedService1 = serviceContainer.get("myScopedService");
    scopedService2 = serviceContainer.get("myScopedService");
  });
  console.log(scopedService1 === scopedService2);
}

{
  let scopedService3;
  let scopedService4;
  asyncLocalStorage.run({}, () => {
    scopedService3 = serviceContainer.get("myScopedService");
    scopedService4 = serviceContainer.get("myScopedService");
  });
  console.log(scopedService1 === scopedService3);
  console.log(scopedService3 === scopedService4);
}

// Output:
// true
// false
// true

Transient

Sometimes we need get new instance of a service each time we get it. To do this, we should make the service as transient.

Example:

const specBuilder = createServiceSpecBuilder();
specBuilder.set("myService", () => ({ serviceName: "My service" })).transient();

const spec = specBuilder.getServiceSpec();

const serviceContainer = createServiceContainer(spec);

console.log(serviceContainer.get("myService") === serviceContainer.get("myService")); // false

Injection after service creation

The most common type of injection is constructor injection. This type of injection occurs when creating service. But sometimes we want to inject after the service has been created. For this we can specify Service Injector for the service:

specBuilder.set("injectorService", () => {
  return new class {
    car!: Car;
    driver!: Driver;
    setDriver(driver: Driver) {
      this.driver = driver;
    }
  };
}).withInjector((service, container) => {
  service.car = container.get("car");
  service.setDriver(container.get("driver"));
});

This way we can perform property and setter injection.

Middlewares

We can wrap service resolving in middlewares:

const specBuilder = createServiceSpecBuilder();

function middleware1(next: Next): Next {
  return function<T>(id: ServiceId): T {
    console.log(`middleware1 start`);
    const service: T = next(id);
    console.log(`middleware1 end`);
    return service;
  }
}

function middleware2(next: Next): Next {
  return function<T>(id: ServiceId): T {
    console.log(`middleware2 start`);
    const service: T = next(id);
    console.log(`middleware2 end`);
    return service;
  }
}

specBuilder.addMiddleware(middleware1, middleware2);

const spec = specBuilder.getServiceSpec();

serviceContainer.get("someService");

// Output:
// middleware2 start
// middleware1 start
// middleware1 end
// middleware2 end