Dislocator

A Service Locator implementation for JavaScript.

Installation

$ npm install dislocator

Usage

A ServiceLocator is a registry for services. It can be passed around in your application and help you make more decoupled applications, as well as making swapping services out when testing code.

// Creating a service locator instance
import ServiceLocator from 'dislocator';

const serviceLocator = new ServiceLocator();

serviceLocator.register('config', { name: "World" });

serviceLocator.register('greeter', (serviceLocator) => {
  const config = serviceLocator.get('config');

  return () => {
    return `Hello ${config.name}!`;
  }
})

// Using the service locator

function sayHi(serviceLocator) {
  const greeter = serviceLocator.greeter;
  console.log(greeter());
}

sayHi(); // logs: Hello World!

class Dislocator

Default export from the CJS and ESM builds as well as in the UMD build when used in CJS or AMD contexts. Accessible on window.Dislocator if loaded in the browser without a module loader.

constructor()

The constructor accepts no options.

const serviceLocator = new Dislocator();

register(name: string, serviceCreator:any) => this

Method for registering a service.

The name must be a string that contains only letters (both upper- and lowercase) and numbers.

The serviceCreator argument can be a literal value (e.g. an object) or a function. Functions passed as serviceCreators will not be invoked until the service is requested; meaning that serviceCreator functions must return the service instance synchroniuosly.

serviceLocator.register('config', { value: "my config value" });
serviceLocator.register('myService', () => {
  return new MyService();
});

serviceCreator functions get passed a reference to the Dislocator instance as the only argument.

serviceLocator.register('myService', (services) => {
  const config = services.get('config');
  return new MyService(config);
});

The register methods can be chained as the dislocator instance is returned.

serviceLocator
  .register('someService', () => {})
  .register('anotherService', () => {});

get(name: string) => any

Returns an instance of the requested service.

serviceLocator.get('myService');

Services can also be retrieved through getters on the Dislocator instance.

serviceLocator.get('myService') === serviceLocator.myService; // => true

If you attempt to retrieve a service that is not registered both methods will result in an Error being thrown.

try {
  serviceLocator.get('noSuchService');
} catch (e) {
  // e: `Error: No registration named "noSuchService"`
}

Dislocator does circular dependency detection when instantiating services.

const serviceLocator = new Dislocator();

serviceLocator
  .register('serviceA', () => {
    const b = serviceLocator.get('serviceB');
    return new ServiceA(b);
  })
  .register('serviceB', () => {
    const a = serviceLocator.get('serviceA');
    return new ServiceB(a);
  });

try {
  serviceLocator.get('serviceA');
} catch (e) {
  // e: `Error: Circular dependency detected (serviceA -> serviceB -> serviceA)`
}

unregister(name: string) => this

Remove a registered service and any instantiated versions of it. Can be chained.

serviceLocator
  .unregister('someService')
  .unregister('anotherService');

isRegistered(name: string) => boolean

Checks if a service is registered.

serviceLocator.isRegistered('someService'); // => false

serviceLocator.register('someService', () => {});

serviceLocator.isRegistered('someService'); // => true

serviceLocator.unregister('someService');

serviceLocator.isRegistered('someService'); // => false

names() => array<string*>

Returns a list of names of the registered services.

serviceLocator
  .register('someService', () => {})
  .register('anotherService', () => {});

serviceLocator.names(); // => ['someService', 'anotherService']

use(serviceProvider: function) => this

Allows you to modularize functions that register services.

const serviceLocator = new Dislocator();

serviceLocator.register('config', myConfigObject);

serviceLocator.use(require('./services/myService'));

// File: services/myService.js

const MyService = require('../MyService');

module.exports = function myServiceProvider(serviceLocator) {
  serviceLocator.register('myService', () => {
    return new MyService();
  });
};

License

MIT