Collection

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()