Service Locator for Catberry Framework

Description

The entire architecture of the Catberry Framework is based on Service Locator pattern. It means that there is only one Service Locator (module registry) in a Catberry application and all application's and framework's modules are resolved from the locator when you start the application.

In case of Catberry Framework, starting an application means to call getMiddleware method in server.js or startWhenReady in browser.js. Before that moment feel free to register your own modules-services into Service Locator.

Usage

Registering your Implementations

For example, you have a class that implement something:

class Cat {
	// constructor always has the only argument – the Service Locator.
	constructor(locator) {
		this.berry = locator.resolve('berry');
	}
}

And you might have an "old style" class definition using constructor and prototype:

// constructor always has the only argument – the Service Locator.
function Berry(locator) {
	// config is always registered in a Catberry application.
	this.berryType = locator.resolve('config').berryType;
}

So, you need to register these implementations into the locator before starting an application.

Registering in browser.js script:

const catberry = require('catberry');
const config = require('./browser-config');
const cat = catberry.create(config);

// when you have created an instance of the Catberry application
// you can register your modules in the Service Locator.
cat.locator.register('cat', Cat);
cat.locator.register('berry', Berry);

// you can register services only before the cat.startWhenReady() method is called
cat.startWhenReady();

Registering in server.js script:

const catberry = require('catberry');
const config = require('./server-config');
const cat = catberry.create(config);
const connect = require('connect');
const http = require('http');
const app = connect();

// when you have created an instance of the Catberry application
// you can register your modules in the Service Locator.
cat.locator.register('cat', Cat);
cat.locator.register('berry', Berry);

// you can register services only before cat.getMiddleware() method is called
app.use(cat.getMiddleware());
app.use(connect.errorHandler());
http
	.createServer(app)
	.listen(config.server.port || 3000);

All cat-components and stores in a Catberry application are registered automatically into the Service Locator. So, you don't need to do that on your own.

Using Implementations

As far as every module's constructor has the only argument – the Service Locator, you can resolve all modules-dependencies while creating new instances of these modules using locator argument:

class Cat {
	// constructor always has the only argument – the Service Locator.
	constructor(locator) {
		// you custom modules
		this.berry = locator.resolve('berry');
		// Catberry's modules
		this.config = locator.resolve('config');
		this.logger = locator.resolve('logger');
	}
}

Also, you can share the same instance across all modules in the application:

cat.locator.register('cat', Cat);
// Berry will be a singleton
cat.locator.register('berry', Berry, true);

const cat1 = cat.locator.resolve('cat');
const cat2 = cat.locator.resolve('cat');

console.log(cat1.berry === cat2.berry); // true

Or if you have an instance itself instead of its constructor you can do following:

cat.locator.register('cat', Cat);
// Berry is registered as an instance
cat.locator.registerInstance('berry', {berryType: 'black'});

const cat1 = cat.locator.resolve('cat');
const cat2 = cat.locator.resolve('cat');

console.log(cat1.berry === cat2.berry); // true

Another possible options is to register a list of implementations and to resolve all the instances as a list:

cat.locator.register('cat', BlackCat);
cat.locator.register('cat', WhiteCat);
cat.locator.register('cat', OrangeCat);

const allTheCats = cat.locator.resolveAll('cat');

console.log(allTheCats[0] instanceof OrangeCat); // true
console.log(allTheCats[1] instanceof WhiteCat); // true
console.log(allTheCats[2] instanceof BlackCat); // true

Please keep in mind that the last registered implementation will be the first in the resolved list.

Interface

Catberry's Service Locator implementation has following methods:

/**
 * Implements a Service Locator pattern.
 */
class ServiceLocator {
	/**
	 * Registers a new type name in the service locator.
	 * @param {string} type The type name used as a key for resolving instances.
	 * @param {Function} implementation The implementation (constructor or class)
	 * which creates instances of the specified type name.
	 * @param {boolean?} isSingleton If true then the only instance will
	 * be created on the first "resolve" call and next calls will
	 * return this instance.
	 */
	register(type, implementation, isSingleton) {}

	/**
	 * Registers a single instance for the specified type.
	 * @param {string} type The type name for resolving the instance.
	 * @param {Object} instance The instance to register.
	 */
	registerInstance(type, instance) {}

	/**
	 * Resolves the last registered implementation by the type name.
	 * @param {string} type The type name to resolve.
	 * @returns {Object} The instance of the specified type name.
	 */
	resolve(type) {}

	/**
	 * Resolves all registered implementations by the type name.
	 * @param {string} type The type name for resolving instances.
	 * @returns {Array} The list of instances of the specified type name.
	 */
	resolveAll(type) {}

	/**
	 * Unregisters all registrations of the specified type name.
	 * @param {string} type The type name for deleting the registrations.
	 */
	unregister(type) {}
}

Contributing

There are a lot of ways to contribute:

• Give it a star
• Join the Gitter room and leave a feedback or help with answering users' questions
• Submit a bug or a feature request
• Submit a PR

Denis Rechkunov [email protected]