@monoceros/cluster

Inversion Of Control container

Table of contents

• Install
  • npm
• Usage
  • Register
  • Resolve
  • Working with Superclusters
• API
  • Cluster
  • Register
  • Resolve
  • Types
• Acknowledgements
• License

Install

npm

npm install @monoceros/cluster

Usage

import Cluster from '@monoceros/cluster'

const cluster = new Cluster()

Register

You can register entities to the Cluster by calling .register() with a name and the entity.

const add = (a, b) => a + b

cluster.register('add', add)


// cluster.resolve('add')(1, 2)    // 3

Register as type

You need to specifiy the entity type if you want something other than the default, by passing it through the options parameter of .register().

See types for a list of possibilities

const current = () => ({
  version: Math.random()
})

cluster.register('current', current, {type: Cluster.Singleton})


// const one = cluster.resolve('current')
// one.version    // 0.3345465634534234560654992

// const two = cluster.resolve('current')
// two.version    // 0.3345465634534234560654992

Register dependencies

Functions / Classes depending on others have to pass a list of their dependency names in the option parameter of .register().

Note: dependencies should be passed in the same order as their parameter order in the entity. Dependencies should always be the first parameters of the entity.

Note: entities can be registered in any order.

const add = (a, b) => a + b

const dependend = (d1, a, b, c) => d1(a, b) * c

cluster.register('dependend', dependend, {dependencies: ['add']})
cluster.register('add', add)


// cluster.resolve('dependend')(10, 1, 3)    // 33

Register with arguments

Every argument after the first three arguments applied to .register() will be applied to the entity on calling resolve.

const add = (a, b) => a + b

cluster.register('three', add, {}, 1, 2)


// cluster.resolve('three')()   // 3

Resolve

You can get registered entities from the Cluster by calling .resolve() with the name of the required entity.

// const add = (a, b) => a + b
// cluster.register('add', add)

const resolved = cluster.resolve('add')

resolved(1, 2) // 3

With arguments

You can pass arguments to .resolve. These will automatically be applied to the entity to resolve.

// const add = (a, b) => a + b
// cluster.register('add', add)

const resolved = cluster.resolve('add', 1, 2)

resolved() // 3

Working with Superclusters

You can create clusters within clusters that will resolve requested entities in itself first. If it can't find it in its own entities, it will try to resolve it from the parent cluster.

const parent = new Cluster()

const child = parent.createCluster()

const add = (a, b) => a + b

parent.register('add', add)

child.resolve('add')(1, 2)    // 3

API

import Cluster from '@monoceros/cluster'

Cluster

new Cluster()

Returns instance of Cluster

Register

(name, entity[, options[, ...arguments]])

cluster.register(name, entity, options || {}, ...args)

Register new entity with name.

• name (required) - Registration name, used by .resolve()

• entity (required) - Entity to register

• options (optional) - Object of options.

  • .type (optional) - Register type entity will be resolved with. Accepted values: see types

  • .dependencies (optional) - Array of entity names the current entity depends upon

• ...args (optional) - Any arguments you want a function / class entity to be called with upon calling resolve

Interchanging the options object

if only passing dependencies ór entity type, the options object can be interchanged for directly passing the dependency array or the entity type.

// only passing type
cluster.register(name1, entity1, Cluster.Singleton)

// only passing dependencies
cluster.register(name2, entity2, ['dependency'])

// passing both
cluster.register(name3, entity3, { type: Cluster.Instance, dependencies: ['dependency'] })

Resolve

(name, [, ...arguments])

cluster.resolve(name, ...args)

Resolve registered entities.

• name (required) -- Name of registered entity to resolve

• ...args (optional) - Arguments to apply to entity on caling resolve

Types

| Description | Type | Resolves | Accepted entities | | ----------- | ------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | | default | Cluster.Body | as-is | string, number, object, function, constructor, class | | Singleton | Cluster.Singleton | singleton | function | | Instance | Cluster.Instance | class instance | constructor, class |

Acknowledgements

Cluster was inspired by this article on dependency injection by krasimir

License

MIT @ Folkert-Jan van der Pol