instances-container
Simple instances or services container for JavaScript.
Introduction
instances-container is a super simple, light, and zero dependencies of service locator for JavaScript. When your project using instances-containers, you can to easily:
- Make a singleton instance under the hood.
- Only create instances when needed a.k.a lazy load.
- Easy to destroy to free up your memory.
- Easy to use.
Installation
You can easily install using npm:
npm install instances-container
The Simplest Example
The simplest way to use an instance container looks like this:
const { createContainer } = require('instances-container');
// class to be register
class Engine {}
// create container also register the class
const container = createContainer({ Class: Engine });
// engine is an instance of Engine class
const engine = container.getInstance('Engine');
// it's a singleton under the hood
const engine2 = container.getInstance('Engine');
console.log(engine === engine2); // trueMore Samples
Registering classes that have parameters
const { createContainer } = require('instances-container')
class Engine {}
class Car {
constructor(engine, power) {
this.engine = engine;
this.power = power;
}
}
// register multiple class while creating container
const container = createContainer([
{
Class: Engine,
},
// register Car class which need pass parameter
{
Class: Car,
parameter: {
dependencies: [
{
internal: 'Engine', // use internal instance
},
{
concrete: 4, // use concrete value
},
],
},
},
]);
// getting Car instance
const car = container.getInstance('Car');
console.log(car instanceof Car); // true
console.log(car.engine instanceof Engine); // true
console.log(car.power); // 10Registering class have a proxy parameter (destructuring)
const { createContainer } = require('instances-container')
class Engine {}
class Car {
// proxy parameter
constructor({ engine, power }) {
this.engine = engine;
this.power = power;
}
}
// register multiple class while creating container
const container = createContainer([
{
Class: Engine,
},
// register Car class which need pass parameter
{
Class: Car,
parameter: {
injectType: 'destructuring', // set injectType to 'destructuring' to inject parameter with proxy technique
dependencies: [
{
name: 'engine', // should set name property to dependency if using 'destructuring'
internal: 'Engine', // use internal instance
},
{
name: 'power',
concrete: 4, // use concrete value
},
],
},
},
]);
// getting Car instance
const car = container.getInstance('Car');
console.log(car instanceof Car); // true
console.log(car.engine instanceof Engine); // true
console.log(car.power); // 10Registering class with custom key
const { createContainer } = require('instances-container')
class Engine {}
const container = createContainer({
key: 'MyEngine', // key use for getting instance
Class: Engine,
});
const myEngine = container.getInstance('MyEngine');
console.log(myEngine instanceof Engine); // trueRegistering class lately
const { createContainer } = require('instances-container')
const container = createContainer();
class Engine {}
// Register class Engine lately
container.register({ Class: Engine });
const engine = container.getInstance('Engine');
console.log(engine instanceof Engine); // true
API Documentation
createServer(options)
Used to create an instance of Container. The options parameter is InstanceOption or InstanceOption[], which means you also can register a single or multiple class while creating a container.
Example: creating a container and registering a single class into it.
const { createContainer } = require('instances-container');
class Engine {}
const container = createContainer({ Class: Engine });Example: creating container and registering multiple class into it.
const { createContainer } = require('instances-container');
class Engine {}
class Oil {}
const container = createContainer([ { Class: Engine }, { Class: Oil }]);createContainer() will return instance of Container.
Container
The container returned from createContainer has some methods.
container.getInstance(key)
Get instance from the registered class using a key.
Example:
const { createContainer } = require('instances-container');
class Engine {}
class Oil {}
const container = createContainer([ { Class: Engine }, { Class: Oil }]);
// get Engine instance
const engine = container.getInstance('Engine');
// get Oil instance
const oil = container.getInstance('Oil');container.register(options)
Register a single or multiple class to a subject container. The options is InstanceOption or InstanceOption[].
Example:
const { createContainer } = require('instances-container');
const container = createContainer();
class Engine {}
// register an Engine class after container creation
container.register({ Class: Engine });container.destroyInstance(key)
Every registered class that has been accessed will create an instance in container.instances[key].INSTANCE.
The container.destroyInstance(key) is used to delete the instance of the registered class to free up some memory.
Example:
const { createContainer } = require('instances-container');
class Engine {}
const container = createContainer({ Class: Engine });
container.getInstance('Engine');
console.log(container.instances.Engine.INSTANCE instanceof Engine); // true
container.destroyInstance('Engine');
console.log(container.instances.Engine.INSTANCE === undefined); // truecontainer.destroyAllInstances(key)
Used to delete all the instances of the registered class to free up some memory.
Example:
const { createContainer } = require('instances-container');
class Engine {}
class Oil {}
const container = createContainer([{ Class: Engine }, { Class: Oil }]);
container.getInstance('Engine');
container.getInstance('Oil');
console.log(container.instances.Engine.INSTANCE instanceof Engine); // true
console.log(container.instances.Oil.INSTANCE instanceof Oil); // true
container.destroyAllInstances()
console.log(container.instances.Engine.INSTANCE === undefined); // true
console.log(container.instances.Oil.INSTANCE === undefined); // trueInstanceOption
InstanceOption is an option passed to createContainer or container.register.
| property | Type | Description |
|---|---|---|
| key | string (optional) | Key for getting or delete an instance from the container. Will use Class.name for default. |
| Class | class or function | The class or function constructor is to be registered to the container. |
| parameter |
ParameterOption (optional)
|
The property is used to define the parameter options of the class to be registered. If not set, that means the class doesn't require any parameters. |
ParameterOption
ParameterOption is the option required by InstanceOption to define parameter property.
| property | Type | Description |
|---|---|---|
| injectType |
"parameter" or "destructuring" (optional)
|
The type of technique used in assigning parameters to the Class. The default is "parameter", but you can change it to "destructuring". |
| Dependencies | Dependencies[] |
Option to put a value that is a dependency (parameter) of the Class. |
Dependency
Dependency is needed to define the dependency value used by ParameterOption.
| property | Type | Description |
|---|---|---|
| name | string (optional) | Object dependency parameter name. Only define when you are using destructuring inject type. |
| concrete | any (optional) | Using a concrete value for dependency. It can be anything. Cannot be set together with internal property. |
| internal | string (optional) | Using internal value (from container) for dependency. The string is the key of class. Cannot be set together with concrete property. |