js-service/README.md

@e22m4u/js-service

English | Русский

The «Service Locator» implementation for JavaScript.

Installation

npm install @e22m4u/js-service

The module supports ESM and CommonJS standards.

ESM

import {Service} from '@e22m4u/js-service';

CommonJS

const {Service} = require('@e22m4u/js-service');

Purpose

The module offers ServiceContainer and Service classes, which can be used separately or together.

• ServiceContainer - classic version of the service locator
• Service - hides the creation of the container and its distribution

The Service class is convenient when the application has a single entry point created by the new operator. For example, if such a point is the Application class, we could inherit it from the Service class and access other services using the getService method without worrying about creating and storing their instances.

Moreover, if other services also inherit from the Service class, they can refer to each other using the getService method, as if we were passing the service container between them.

ServiceContainer class

Methods:

• get(ctor, ...args) returns an existing or new instance
• has(ctor) checks if a constructor exists in the container
• add(ctor, ...args) adds a constructor to the container
• use(ctor, ...args) adds a constructor and creates its instance
• set(ctor, service) adds a constructor and its instance

get

The get method of the ServiceContainer class creates an instance of the given constructor and saves it for next access following the "singleton" principle.

Example:

import {ServiceContainer} from '@e22m4u/js-service';

// create a new container
const container = new ServiceContainer();

// pass a constructor to the "get" method
// (the Date class is used as an example)
const myDate1 = container.get(Date); // creates an instance
const myDate2 = container.get(Date); // returns existing instance

console.log(myDate1); // Tue Sep 12 2023 19:50:16
console.log(myDate2); // Tue Sep 12 2023 19:50:16
console.log(myDate1 === myDate2); // true

The get method can accept constructor arguments. If the container already has an instance of this constructor, it will be recreated with new arguments.

Example:

const myDate1 = container.get(Date, '2025-01-01'); // creates an instance
const myDate2 = container.get(Date);               // returns existing instance
const myDate3 = container.get(Date, '2025-05-05'); // recreates
console.log(myDate1); // Wed Jan 01 2025 03:00:00
console.log(myDate2); // Wed Jan 01 2025 03:00:00
console.log(myDate3); // Sun May 05 2030 03:00:00

Inheritance

The ServiceContainer constructor takes a parent container as its first parameter, which is used as an alternative if the constructor of the requested instance (service) is not registered in the current one.

class MyService {}

// create the ServiceContainer instance
// and register a new service (MyService)
const parentContainer = new ServiceContainer();
parentContainer.add(MyService);

// provide the previous container as a parent
// for a new one, and check the service existence
// in a child container
const childContainer = new ServiceContainer(parentContainer);
const hasService = childContainer.has(MyService);
console.log(hasService); // true

Service class

Methods:

• getService(ctor, ...args) returns an existing or new instance
• hasService(ctor) checks if a constructor exists in the container
• addService(ctor, ...args) adds a constructor to the container
• useService(ctor, ...args) adds a constructor and creates its instance
• setService(ctor, service) adds a constructor and its instance

A service is just a class instance. However, if a service inherits the Service class, such a service encapsulating the creation of the service container, its storage, and transfer to other services.

Example:

import {Service} from '@e22m4u/js-service';

// the Foo service
class Foo extends Service {
  method() {
    // access to the Bar
    const bar = this.getService(Bar);
    // ...
  }
}

// the Bar service
class Bar extends Service {
  method() {
    // access to the Foo
    const foo = this.getService(Foo);
    // ...
  }
}

// the App service (entry point)
class App extends Service {
  method() {
    // access to Foo and Bar services
    const foo = this.getService(Foo);
    const bar = this.getService(Bar);
    // ...
  }
}

const app = new App();

In the example above, we didn't worry about creating a service container and passing it between services, because this logic is encapsulated in the Service class and its getService method.

getService

The getService method ensures the existence of a single instance of the requested service, rather than creating a new one each time. However, when passing additional arguments, the service will be recreated with these arguments passed to the constructor.

Example:

const foo1 = this.getService(Foo, 'arg'); // creates an instance
const foo2 = this.getService(Foo);        // returns existing instance
console.log(foo1 === foo2);               // true

const foo3 = this.getService(Foo, 'arg'); // recreates instance
const foo4 = this.getService(Foo);        // returns recreated instance
console.log(foo3 === foo4);               // true

Tests

npm run test

License

MIT