IoC for Javascript & Node.js

Collection

new Collection(values)

Create a new collection.

Parameters
Name Type Argument Description
values
object
 optional 

Values to add in the collection.
Throws
Type Description
TypeError

If the arguments values is provided is not an object.
Example 
var items = new Collection();

Properties

_container :object

Items container. All values of the collection are stored in the container.

Methods

keys()

Get all keys of the collection.

Returns
Type Description
array

An array of keys.
Example 
items.keys();

has(key)

Checks if an item exists

Parameters
Name Type Description
key
string

The key of the item to check.
Throws
Type Description
TypeError

If key is not a string.
Returns
Type Description
bool

true if exists, false otherwise.
Example 
items.set('keyName', 'any value');

if(items.has('keyName')) {
  console.log('has `keyName`');
}

remove(key)

Remove an item.

Parameters
Name Type Description
key
string

The key of item to remove.
Throws
Type Description
TypeError

If key is not a string.
Returns
Type Description
Collection

The current ìnstance.
Example 
items.set('keyName', 'any value');

// true
console.log(items.has('keyName'));

items.remove('keyName');

// false
console.log(items.has('keyName'));

set(key, value)

Set an item.

Parameters
Name Type Description
key
string

Key name.
value
mixed

The value.
Throws
Type Description
TypeError

If key is not a string.
Returns
Type Description
Collection

The current ìnstance.
Example 
items.set('hello', 'Hello World!');

// Hello World!
console.log(items.get('hello'));

setAll(values)

Set all items of the collection. All collection is overwritten by the given set of items.

Parameters
Name Type Description
values
values

The new values of the collection.
Throws
Type Description
TypeError

If values is not an object.
Returns
Type Description
Collection

The current ìnstance.
Example 
items.setAll({
  a: 'value 1',
  b: 'value 2',
  c: 'value 3'
});

addAll(values)

Add all items in the collection.

items.addAll({ a: 'value 1', b: 'value 2', c: 'value 3' });

Parameters
Name Type Description
values
object

The values to add. The existing values are overwritten, the other items are preserved.
Throws
Type Description
TypeError

If values is not an object or if a key is not a string.
Returns
Type Description
Collection

The current ìnstance.

addOnce(key, value, skip_if_exists)

Add once an item in the collection. Identical to Collection.set() method, except the item is added only if it is not already defined in the collection.

Parameters
Name Type Argument Description
key
string

The key name.
value
mixed

The value.
skip_if_exists
bool
 optional 

Defines the behavior if the given key exists:

  • if truthy, nothing happens and the item already defined is not overwritten
  • if falsy (by default) an Error is thrown
Throws
Type Description
TypeError

If key is not a string.

Error

If an item is already defined with the same key and skip_if_exists is not truthy.
Returns
Type Description
Collection

The current ìnstance.
See also
Collection.addOnceAll() Collection.set()

addOnceAll(values, skip_if_exists)

Add all items in the collection only if not already defined.

Parameters
Name Type Argument Description
values
object

Identical to Collection.addAll() method.
skip_if_exists
bool
 optional 

Defines the behavior if an item exists:

  • if truthy, nothing happens and the item already defined is not overwritten
  • if falsy (by default) an Error is thrown
Throws
Type Description
TypeError

If values is not an object or if a key is not a string.

Error

If an item is already defined and skip_if_exists is not truthy.
Returns
Type Description
Collection

The current ìnstance.
See also
Collection.addOnce() Collection.addAll()

merge(values, values)

Merge values (recursive) in the collection.

Parameters
Name Type Argument Description
values
object

Values to merge.
values
object
 optional  repeatable 

Zero, one or several other objects.
Throws
Type Description
TypeError

If values is not an object.
Returns
Type Description
Collection

The current ìnstance.

getAll()

Get all items of the collection.

Returns
Type Description
object

All items defined in the collection.

get(key, default_value, strict)

Get an item value.

If the item is a function, the fonction is called and get() returns the value returned by the function called.

If you want the raw value, uses Collection.raw().

Parameters
Name Type Argument Description
key
string

The key of the item
default_value
mixed
 optional 

The default value if the item does not exist (default_value is ignored if strict is truthy).
strict
bool
 optional 

If truthy and the item does not exist, throws an Error (default_value is ignored if strict is truthy).
Throws
Type Description
TypeError

If key is not a string.

Error

If strict is truthy and the item does not exist.
Returns
Type Description
mixed

The item value (if defined).
mixed

Returns default_value if:

  • a default value is defined
  • strict is not truthy
  • the item (key) does not exist
Example 
items.addAll({
  a: 'value of "a"',
  b: function() {
    'value of "b"'
  }
});

// value of "a", string
console.log(items.get('a'), typeof items.get('a'));

// value of "b", string
console.log(items.get('b'), typeof items.get('b'));

// value of "a", string
console.log(items.raw('a'), typeof items.raw('a'));

// [Function], function
console.log(items.raw('b'), typeof items.raw('b'));
See also
Collection.raw() Collection.apply() Collection.invoke()

raw(key, default_value, strict)

Get an item.

Parameters
Name Type Argument Description
key
string

The key of the item
default_value
mixed
 optional 

The default value if the item does not exist (default_value is ignored if strict is truthy).
strict
bool
 optional 

If truthy and the item does not exist, throws an Error (default_value is ignored if strict is truthy).
Throws
Type Description
TypeError

If key is not a string.

Error

If strict is truthy and the item does not exist.
Returns
Type Description
mixed

The item value (if defined).
mixed

Returns default_value if:

  • a default value is defined
  • strict is not truthy
  • the item (key) does not exist
Example 
items.set('multiply', function(a, b) {
  return a * b;
});

var multiply = items.raw('multiply');

// returns 8
multiply(2, 4);

// or directly
// returns 8
items.raw('multiply')(2, 4);

// or equivalent by injection

// returns 8
items.inject('multiply', function(multiply) {
  return multiply(2, 4);
});

// returns 8
items.apply(function() {
  return this.multiply(2, 4);
});
See also
Collection.get() Collection.apply() Collection.inject()

inject(deps, fn)

Call a function with dependencies injection.

Unlike Collection.invoke(), the raw value of each dependency is passed to fn.

Parameters
Name Type Argument Description
deps
string
array
function

Dependencies to inject as arguments of the function (fn). Or only a function that receives in first argument the container of Collection instance.
fn
function
 optional 

Function to call. Dependencies are passed as arguments in the order of declaration. If deps is a function, this argument is ignored.
Throws
Type Description
TypeError

If a key is not a string.
Returns
Type Description
mixed

The value returned by the given function.
Example 
items.set('multiply', function(a, b) {
  return a * b;
});

// returns 8
items.inject('multiply', function(multiply) {
  return multiply(2, 4);
});

// or equivalent

// return 8
items.apply(function() {
  return this.multiply(2, 4);
});

// returns 8
items.raw('multiply')(2, 4);
See also
Collection.invoke() Collection.raw() Collection.apply()

invoke(deps, fn)

Call a function with dependencies injection.

Unlike Collection.inject(), the returned value of each dependency is passed to fn.

Parameters
Name Type Argument Description
deps
string
array
function

Dependencies to call and inject the returned value as arguments of the function (fn). Or only a function that receives in first argument the container of Collection instance.
fn
function
 optional 

Function to call. Dependencies are passed as arguments in the order of declaration. If deps is a function, this argument is ignored.
Throws
Type Description
TypeError

If a key is not a string.
Returns
Type Description
mixed

The value returned by the given function.
Example 
items.addAll({
  name: 'Nico',
  hello: function(){
    return 'Hello ' + this.name;
  }
});

items.invoke('hello', function(hello) {

  // Hello Nico
  console.log(hello);
});
See also
Collection.get() Collection.inject() Collection.apply()

apply(bindable, arguments)

Calls a given function by binding the scope (this) to the container (Collection._container).

The javascript function implements natively the methods call() and apply().

It is possible that bindable argument is not a function, in this case it is necessary that the object implements call(container) and apply(container, args), then handles the logic.

Parameters
Name Type Argument Description
bindable
function
object

Function or object to call and whose the scope (this) will bind to container.
arguments
mixed
 optional  repeatable 

Zero, one or more arguments passed to bindable.
Returns
Type Description
mixed

The value returned by bindable.
Example 
var fn = function() {
  return this === items._container;
};

// true
console.log(items.apply(fn));
See also
Collection.inject() Collection.invoke()

wrap(value)

Wrap a value. Useful to avoid calling a function in the implementation of a provider or a factory.

Parameters
Name Type Description
value
mixed

The value to wrap.
Returns
Type Description
function

value wrapped by a function
See also
Collection.singleton() Collection.provider() Collection.factory()

singleton(key, fn)

Create a singleton (function shared).

Parameters
Name Type Description
key
string

The key (function identifier).
fn
function

The function, executed once, after the value is returned when is again called.
Throws
Type Description
TypeError

If key is not a string or if fn is not a function.
Returns
Type Description
Collection

The current ìnstance.
See also
Collection.provider() Collection.factory() Collection.wrap()

provider(key, deps, fn)

Create a provider that supports dependencies injection. When the item key is called, it calls the function fn by passing dependencies deps.

This method defines a function that returns the result of Collection.inject(deps, fn).

Parameters
Name Type Argument Description
key
string

The key (provider identifier).
deps
string
array
function

See Collection.inject().
fn
function
 optional 

See Collection.inject().
Throws
Type Description
TypeError

If key is not a string or if a given key in deps is not a string.
Returns
Type Description
Collection

The current ìnstance.
Example 
items.set('hello', function() {
  return 'Hello World!';
});

items.provider('sayHello', ['hello'], function(hello) {
  return hello();
});

// 'Hello World!'
items.get('sayHello');

// or with the scope in any injector
items.apply(function() {

  // 'Hello World!'
  console.log(this.sayHello);
});
See also
Collection.inject() Collection.factory() Collection.singleton() Collection.wrap()

factory(key, deps, fn)

Create a factory that supports dependencies injection. When the item key is called, it calls the function fn by passing dependencies deps.

This method defines a function that returns the result of Collection.invoke(deps, fn).

Parameters
Name Type Argument Description
key
string

The key (factory identifier).
deps
string
array
function

See Collection.invoke().
fn
function
 optional 

See Collection.invoke().
Throws
Type Description
TypeError

If key is not a string or if a given key in deps is not a string.
Returns
Type Description
Collection

The current ìnstance.
Example 
items.set('hello', function() {
  return 'Hello World!';
});

items.factory('sayHello', ['hello'], function(hello) {
  return hello;
});

// 'Hello World!'
items.get('sayHello');

// or with the scope in any injector
items.apply(function() {

  // 'Hello World!'
  console.log(this.sayHello);
});
See also
Collection.invoke() Collection.provider() Collection.singleton() Collection.wrap()