hash-me

Hash-me is a node.js module for hash-based collections.

Types of collections

The library separate collections into two types - storage and mapping.

Storage	Mapping
Set	Map
Relation	Connection
Graph	Network

The first row present the basic collection Map and Set. This collections are the basics and only one which use the hash function directly. The rest, more complex, collections are built using Map and Set.

The second row present collections using pair values for index. This collections are used to define some correlation between values. The Relation present pure correlation, while the Connection present additional value describing the correlation.

The third row present collections using its corresponding first and second rows collection. The Graph is a Set of values called nodes with some Relation between the nodes, called edges. The Graph just stores both values and their correlation, while the Network maps additional value to each value and correlation, describing it.

Warning: The Set, Map, Relation, Connection posses linear ordering. This means that elements can be arranged along the line. The order is implementation specific, but there is such an order. For example calling forEach method to any of this collection will call the callback with first element, then with the second and so on. The Graph and the Network posses no such simple ordering. While processing the correlation and values separately give them linear ordering, the graph can be ordered by more complex method in two dimensional grid instead of line. Such ordering present only two basic method for iteration: DFS and BFS. However other algorithms exists for iteration, some of which are faster for more concrete problems. Therefore this library does not currently take responsibility to iterate the second order collections - Graph and Network.

Reference

Note: Reference consist interface definition code with following syntax:

function(arg1:type, arg2:type1|type2):returnType throws exceptionType

Where the arg1 and arg2 are the name of arguments and type is the type expected of list of type joined with a pipe symbol (|) to show alternatives. After the brackets of the argument list, the function definition is followed by a colon symbol (:) and the returnType is one or more types expected function to return. Optionally this may be followed by throws and exceptionType that gives one or more possible exceptions. Detail description of each of the arguments, return type and expected exception is given below the function signature. A special type * is used to represents no type restriction. An ellipsis (...) after the name of arguments tells that more argument of the same type can be specified, e.g. it is variable arguments function. Ellipsis should be used on last argument only.

The library consist entirely of collection classes.

• Set
• Map
• Relation
• Connection
• Graph
• Network

Set

The class store values without repetition. Adding, removing and finding a value from the set is O(1) time, but from the programming point of view it may be a little slower due to imperfect hash function. However hash clashes occurs rarely.

• add
• delete
• equals
• every
• filter
• find
• forEach
• has
• intersection
• isEmpty
• length
• reduce
• some
• subsetOf
• subtract
• union
• values

Set.add

Add any value to the set if the set has no value strictly equals to the given one.

function add(value:*):boolean

Arguments

1. value - Any value to insert into the set.

Return

Returns whether the set has been changed by the operation.

Set.delete

Remove a value from the set if the set does contain a value strictly equals to the given one.

function delete(value:*):boolean

Arguments

1. value - Any value to be removed from the set.

Return

Returns whether the set has been changed by the operation.

Set.equals

Compares two instances of Set class for equality. Two such instances are equal only if they have the same values. Unfortunately this currently works in linear time.

function equals(other:Set):boolean throws TypeError

Arguments

1. other - A Set object to compare to.

Return

Returns true if the both object are instances of Set and contain the same values, or false otherwise.

Exception

• TypeError: If the other arguments is not instance of Set class.

Set.every

Test if all values in the set satisfies a callback function. This function has iteration optimization - it may process only part of the elements and returns early if the return result is known.

function every(callback:Function, this:*):boolean throws TypeError

function callback(value:*, set:Set):boolean

Arguments

1. callback - A function to be called for each of the elements of the set.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for all elements of the Set, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Set.filter

Creates a new Set object, filling it with all elements from this Set which satisfies a callback function.

function filter(callback:Function, this:*):Set throws TypeError

function callback(value:*, set:Set):boolean

Arguments

1. callback - A function to be called for each of the elements of the set.
2. this - A value to be bound to this keyword in the callback.

Return

Returns a Set that satisfies Set.subsetOf this set.

Exception

• TypeError: If the callback argument given is not a function.

Set.find

Search through the values of the set and returns the first value that satisfies a callback function.

function find(callback:Function, this:*):* throws TypeError

function callback(value:*, set:Set):boolean

Arguments

1. callback - A function to be called for each of the elements of the set.
2. this - A value to be bound to this keyword in the callback.

Return

Returns the first value that satisfies the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Set.forEach

Unconditionally call a callback function for every element in the set.

function forEach(callback:Function, this:*):* throws TypeError

function callback(value:*, set:Set):boolean

Arguments

1. callback - A function to be called for each of the elements of the set.
2. this - A value to be bound to this keyword in the callback.

Return

The current Set object.

Exception

• TypeError: If the callback argument given is not a function.

Set.has

Check if a value is stored in the set.

function has(value:*):boolean

Arguments

1. value - Any javascript value to be checked.

Return

Returns true if specified value is in the set, false otherwise.

Set.intersection

Create a new set containing all values that are contained in both this and other set.

function intersection(other:Set):Set throws TypeError

Arguments

1. other - An instance of Set class.

Return

Returns newly created Set object, containing elements that are contained in both current set and other set.

Exception

• TypeError: If the other is not a set.

Set.isEmpty

Checks whether the set is empty, e.g. contains no values. Unlike length, this works in O(1), not in O(n) time.

function isEmpty():boolean

Return

Returns true is the set contains no values.

Set.length

Counts the number of elements in the set. This works on O(n) time so it is expensive operation, however this is preferred than having additional number value for each set, since length operation is expected to be used rarely.

get length():number

Getter

Returns the number of elements in the set.

Set.reduce

Reduces the set to single value based on callback function.

function reduce(callback:Function, initialValue:*, this:*):*

function callback(previousValue:*, currentValue:*, set:Set):*

Arguments

1. callback - A function to be called for each value in the set. On the first call for previousValue is given the value of initialValue and for any subsequent calls - the value returned by the callback from previous call.
2. initialValue - The value to start the reduction.
3. this - A value to be bound to this keyword in the callback.

Return

The reduce method returns the value returned from the last call of the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Set.some

Test if there is element in the set that satisfies a callback function. This function has iteration optimization - it may process only part of the elements and returns early if the return result is known.

function some(callback:Function, this:*):boolean throws TypeError

function callback(value:*, set:Set):boolean

Arguments

1. callback - A function to be called for each of the elements of the set.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for at least one element of the Set, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Set.subsetOf

Checks if current set is subset of other set, e.g. if all elements of the current set are contained in the other set.

function subsetOf(other:Set):boolean throws TypeError

Arguments

1. other - An instance of Set class.

Return

If element in current set that is missing from other set is found - false is returned, otherwise true is returned.

Exception

• TypeError: If the other is not a set.

Set.subtract

Creates a new set with all elements of current set, that are missing from an other set.

function subtract(other:Set):Set throws TypeError

Arguments

1. other - An instance of Set class.

Return

Returns a Set object with all elements from current set, not contained in the other set.

Exception

• TypeError: If the other is not a set.

Set.union

Creates a new set with elements of this and other sets combined.

function union(other:Set):Set throws TypeError

Arguments

1. other - An instance of Set class.

Return

Returns a Set object combined values.

Exception

• TypeError: If the other is not a set.

Set.values

Creates an array containing all elements of the set. The order of elements in the array is implementation specific.

function values():Array

Return

A javascript Array object containing all values in the set, once for each value.

Map

The Map class stores mappings of keys to values similarly to javascript Object class. However the keys can be any type of javascript value - undefined, null, boolean, string, number, object, function and so on. Just like javascript object or dictionaries, it does not allow keys to be repeated. The map compares the keys by strict equality.

• delete
• every
• filter
• find
• findKey
• forEach
• get
• has
• isEmpty
• keys
• length
• merge
• reduce
• set
• some
• values

Map.delete

Removes a mapping from the Map based on the "key" value. If there is no such key, no operation is done.

function delete(key:*):boolean

Arguments

1. key - The key to find the mapping to be removed.

Return

Returns whether the map has been changed by the operation.

Map.every

Test if all mappings in the map satisfies a callback function. This function has iteration optimization - it may process only part of the mappings and returns early if the return result is known.

function every(callback:Function, this:*):boolean throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for all mappings of the Map, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Map.filter

Creates a new Map object, filling it with all mappings from this Map which satisfy a callback function.

function filter(callback:Function, this:*):Map throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

Returns a new Map that have some of the mappings from the original map.

Exception

• TypeError: If the callback argument given is not a function.

Map.find

Search through the mappings of the map and returns the first value of the mapping that satisfies a callback function.

function find(callback:Function, this:*):* throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

Returns the value of first mapping that satisfies the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Map.findKey

Search through the mappings of the map and returns the first key of the mapping that satisfies a callback function.

function find(callback:Function, this:*):* throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

Returns the key of the first mapping that satisfies the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Map.forEach

Unconditionally call a callback function for every mapping in the map.

function forEach(callback:Function, this:*):* throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

The current Map object.

Exception

• TypeError: If the callback argument given is not a function.

Map.get

Get a mapped value for the given key.

function get(key:*):*

Arguments

1. key - The key to find a mapping.

Return

Returns the mapped value at this key or undefined if key is not in the map.

Map.has

Check if the Map have a mapping for the given key.

function has(key:*):boolean

Arguments

1. key - The key to find a mapping.

Return

Returns true if mapping is found, false otherwise.

Map.isEmpty

Checks whether the map have no mappings. Unlike length, this works in O(1), not in O(n) time.

function isEmpty():boolean

Return

Returns true is the map contains no mappings.

Map.keys

Creates an array containing all keys in the map. The order of elements returned is implementation specific.

function keys():Array

Return

A javascript Array object containing all keys from all mappings of the map.

Map.length

Counts the number of mappings in the map. This works on O(n) time so it is expensive operation, however this is preferred than having additional number value for each map, since length operation is expected to be used rarely.

get length():number

Getter

Returns the number of mappings in the map.

Map.merge

Merges the current map with one or more other maps. The merging creates a copy of the current map and iterates the specified maps one by one. If a key for mapping from the iterated map does not exists in merged map, then it is added, otherwise the value for that key is overridden. The value from the first argument override the values in the current map, the value from the second argument override both the values from the current map and the first argument and so on.

function merge(maps...:Map):Map throws TypeError

Arguments

1. maps... - One or more maps to be merged with current map.

Return

Returns new Map containing merged values from all maps.

Exception

• TypeError: If no arguments specified or if any of the arguments specified is not an instance of Map.

Map.reduce

Reduces the map to single value based on callback function.

function reduce(callback:Function, initialValue:*, this:*):*

function callback(previousValue:*, currentValue:*, currentKey:*, map:Map):*

Arguments

1. callback - A function to be called for each mapping in the map. On the first call for previousValue is given the value of initialValue and for any subsequent calls - the value returned by the callback from previous call.
2. initialValue - The value to start the reduction.
3. this - A value to be bound to this keyword in the callback.

Return

The reduce method returns the value returned from the last call of the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Map.set

Sets a value for specific key. If the map does not contain such key, it is added and it is mapped to value specified, otherwise the found key's mapped value is replaced by the current value.

function set(key:*, value:*):boolean

Arguments

1. key - The key to find a mapping.
2. value - The value to become the mapped value for the key.

Return

Returns whether the length of the map has been changed by the operation.

Map.some

Test if there is mapping in the map that satisfies a callback function. This function has iteration optimization - it may process only part of the mappings and returns early if the return result is known.

function some(callback:Function, this:*):boolean throws TypeError

function callback(value:*, key:*, map:Map):boolean

Arguments

1. callback - A function to be called for each of the mappings of the map.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for at least one mapping of the Map, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Map.values

Creates an array containing all values in the map. The order of elements returned is implementation specific. The returned array has the same order as keys method. A values in the returned array may be repeated.

function values():Array

Return

A javascript Array object containing all values from all mappings of the map.

Relation

The relation store a pair a values without repetition. It can be viewed not as a pair of values, but as connection between values. Effectively this is a Set consisting of connection between values or subset of cartesian product of the set of all javascript values. Adding, removing and finding a connection in the relation is O(1) time.

• add
• delete
• equals
• every
• filter
• find
• forEach
• has
• intersection
• isEmpty
• leftOf
• length
• reduce
• rightOf
• some
• subsetOf
• subtract
• union
• values

Relation.add

Add a pair of values to the relation if such pair doesn't exists in the relation, yet.

function add(leftValue:*, rightValue:*):boolean

Arguments

1. leftValue - A value from the left/start set.
2. rightValue - A value from the right/end set.

Return

Returns whether the relation has been changed by the operation.

Relation.delete

Remove a pair of values from the relation.

function delete(leftValue:*, rightValue:*):boolean

Arguments

1. leftValue - A value from the left/start set.
2. rightValue - A value from the right/end set.

Return

Returns whether the relation has been changed by the operation.

Relation.equals

Check if the relation contains the same pairs of values as other relation.

function equals(other:Relation):boolean throws TypeError

Arguments

1. other - A Relation object to compare to.

Return

Returns true if the both object are instances of Relation and contain the same pairs of values, or false otherwise.

Exception

• TypeError: If the other arguments is not instance of Relation class.

Relation.every

Test if all pairs of values in the relation satisfies a callback function. This function has iteration optimization - it may process only part of the pairs and returns early if the return result is known.

function every(callback:Function, this:*):boolean throws TypeError

function callback(leftValue:*, rightValue:*, relation:Relation):boolean

Arguments

1. callback - A function to be called for each of the pairs of the relation.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for all pairs of the Relation, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Relation.filter

Creates a new Relation object, filling it with all pairs from this Relation which satisfies a callback function.

function filter(callback:Function, this:*):Relation throws TypeError

function callback(leftValue:*, rightValue:*, relation:Relation):boolean

Arguments

1. callback - A function to be called for each of the elements of the relation.
2. this - A value to be bound to this keyword in the callback.

Return

Returns a Relation that satisfies Relation.subsetOf this relation.

Exception

• TypeError: If the callback argument given is not a function.

Relation.find

Search through the pairs of the relation and returns the first pair that satisfies a callback function.

function find(callback:Function, this:*):* throws TypeError

function callback(leftValue:*, rightValue:*, relation:Relation):boolean

Arguments

1. callback - A function to be called for each of the elements of the relation.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback function is satisfied, an Array is returned with two indexes: 0 - for the leftValue and 1 - for the rightValue. If no element satisfies the callback - undefined is returned.

Exception

• TypeError: If the callback argument given is not a function.

Relation.forEach

Unconditionally call a callback function for every pair in the relation.

function forEach(callback:Function, this:*):* throws TypeError

function callback(leftValue:*, rightValue:*, relation:Relation):boolean

Arguments

1. callback - A function to be called for each of the elements of the relation.
2. this - A value to be bound to this keyword in the callback.

Return

The current Relation object.

Exception

• TypeError: If the callback argument given is not a function.

Relation.has

Check if a pair is stored in the relation.

function has(value:*):boolean

Arguments

1. value - Any javascript value to be checked.

Return

Returns true if specified value is in the relation, false otherwise.

Relation.intersection

Create a new relation containing all pairs that are contained in both this and other relation.

function intersection(other:Relation):Relation throws TypeError

Arguments

1. other - An instance of Relation class.

Return

Returns newly created Relation object, containing all pairs that are contained in both current relation and other relation.

Exception

• TypeError: If the other is not a relation.

Relation.isEmpty

Checks if the relation contains no pairs. Unlike length, this works in O(1), not in O(n) time.

function isEmpty():boolean

Return

Returns true is the relation contains no pairs.

Relation.leftOf

Extracts a Set containing the left values of all pairs whose right value matches the specified one.

function leftOf(rightValue:*):Set

Arguments

1. rightValue - The value to search in the right set.

Return

A Set containing all values from the left set to which there is a pair whose right value matches rightValue argument. If no such pairs are found, then Set.isEmpty for the returned result is true.

Relation.length

Counts the number of pairs in the relation. This works on O(n) time so it is expensive operation, however this is preferred than having additional number value for each relation, since length operation is expected to be used rarely.

get length():number

Getter

Returns the number of elements in the relation.

Relation.reduce

Reduces the relation to single value based on callback function.

function reduce(callback:Function, initialValue:*, this:*):*

function callback(previousValue:*, leftValue:*, rightValue:*, relation:Relation):*

Arguments

1. callback - A function to be called for each pair in the relation. On the first call for previousValue is given the value of initialValue and for any subsequent calls - the value returned by the callback from previous call.
2. initialValue - The value to start the reduction.
3. this - A value to be bound to this keyword in the callback.

Return

The reduce method returns the value returned from the last call of the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Relation.rightOf

Extracts a Set containing the right values of all pairs whose left value matches the specified one.

function rightOf(leftValue:*):Set

Arguments

1. leftValue - The value to search in the left set.

Return

A Set containing all values from the right set to which there is a pair whose left value matches leftValue argument. If no such pairs are found, then Set.isEmpty for the returned result is true.

Relation.some

Test if there is pair in the relation that satisfies a callback function. This function has iteration optimization - it may process only part of the pairs and returns early if the return result is known.

function some(callback:Function, this:*):boolean throws TypeError

function callback(leftValue:*, rightValue:*, relation:Relation):boolean

Arguments

1. callback - A function to be called for each of the pairs of the relation.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for at least one pair of the Relation, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Relation.subsetOf

Checks if current relation is subset of other relation, e.g. if all pairs of the current relation are contained in the other relation.

function subsetOf(other:Relation):boolean throws TypeError

Arguments

1. other - An instance of Relation class.

Return

If element in current relation, that is missing from other relation, is found - false is returned, otherwise true is returned.

Exception

• TypeError: If the other is not a relation.

Relation.subtract

Creates a new Relation with all pairs of current relation, that are missing from an other relation.

function subtract(other:Relation):Relation throws TypeError

Arguments

1. other - An instance of Relation class.

Return

Returns a Relation object with all pairs from current relation, not contained in the other relation.

Exception

• TypeError: If the other is not a relation.

Relation.union

Creates a new relation with pairs of this and other relations combined.

function union(other:Relation):Relation throws TypeError

Arguments

1. other - An instance of Relation class.

Return

Returns a Relation object combined values.

Exception

• TypeError: If the other is not a relation.

Relation.values

Creates an array containing all pairs of the relation. The order of pairs in the array is implementation specific.

function values():Array

Return

A javascript Array object containing all pairs in the relation. Each pairs is also a javascript Array with index 0 being the leftValue and index 1 - the rightValue.

Connection

The Connection class similarly to Relation class, stores connection between any javascript values, but like the Map class it allows mapping a javascript value to each connection.

• delete
• every
• filter
• find
• findKey
• forEach
• get
• has
• isEmpty
• keys
• length
• merge
• reduce
• set
• some
• values

Connection.delete

Removes a mapping from the Connection based on the pair of keys. If there is no such pair, no operation is done.

function delete(leftKey:*, rightKey:*):boolean

Arguments

1. leftKey - The first value of the pair of keys.
2. rightKey - The second value of the pair of keys.

Return

Returns whether the connection has been changed by the operation.

Connection.every

Test if all mappings in the connection satisfies a callback function. This function has iteration optimization - it may process only part of the mappings and returns early if the return result is known.

function every(callback:Function, this:*):boolean throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for all mapping of the Connection, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Connection.filter

Creates a new Connection object, filling it with all mappings from this Connection which satisfy a callback function.

function filter(callback:Function, this:*):Connection throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

Returns a new Connection that have some of the mappings from the original connection.

Exception

• TypeError: If the callback argument given is not a function.

Connection.find

Search through the mappings of the connection and returns the first value of the mapping that satisfies a callback function.

function find(callback:Function, this:*):* throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

Returns the value of first mapping that satisfies the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Connection.findKey

Search through the mappings of the connection and returns the first pair of keys of the first mapping that satisfies a callback function.

function findKey(callback:Function, this:*):* throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

Returns the pair of keys of the first mapping that satisfies the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Connection.forEach

Unconditionally call a callback function for every mapping in the connection.

function forEach(callback:Function, this:*):* throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

The current Connection object.

Exception

• TypeError: If the callback argument given is not a function.

Connection.get

Get a mapped value for the given pair of keys.

function get(leftKey:*, rightKey:*):*

Arguments

1. leftKey - The first value of the pair of keys.
2. rightKey - The second value of the pair of keys.

Return

Returns the mapped value at this pair of keys or undefined if key is not in the connection.

Connection.has

Check if the Connection have a mapping for the given pair of keys.

function has(leftKey:*, rightKey:*):boolean

Arguments

1. leftKey - The first value of the pair of keys.
2. rightKey - The second value of the pair of keys.

Return

Returns true if mapping is found, false otherwise.

Connection.isEmpty

Checks whether the connection have no mappings. Unlike length, this works in O(1), not in O(n) time.

function isEmpty():boolean

Return

Returns true is the connection contains no mappings.

Connection.keys

Creates an array containing all pair of keys in the connection. The order of elements returned is implementation specific.

function keys():Array

Return

A javascript Array object containing all pair of keys from all mappings of the connection. The pair of keys is also a javascript Array containing leftKey at index 0 and rightKey at index 1.

Connection.length

Counts the number of mappings in the connection. This works on O(n) time so it is expensive operation, however this is preferred than having additional number value for each connection, since length operation is expected to be used rarely.

get length():number

Getter

Returns the number of mappings in the connection.

Connection.merge

Merges the current connection with one or more other connection. The merging creates a copy of the current connection and iterates the specified connections one by one. If a pair of keys for mapping from the iterated connection does not exists in merged connection, then it is added, otherwise the value for that pair of keys is overridden. The value from the first argument override the values in the current connection, the value from the second argument override both the values from the current connection and the first argument and so on.

function merge(connections...:Connection):Connection throws TypeError

Arguments

1. maps... - One or more maps to be merged with current Connection.

Return

Returns new Connection containing merged values from all connection.

Exception

• TypeError: If no arguments specified or if any of the arguments specified is not an instance of Connection.

Connection.reduce

Reduces the connection to single value based on callback function.

function reduce(callback:Function, initialValue:*, this:*):*

function callback(previousValue:*, currentValue:*, leftKey:*, rightKey:*, connection:Connection):*

Arguments

1. callback - A function to be called for each mapping in the connection. On the first call for previousValue is given the value of initialValue and for any subsequent calls - the value returned by the callback from previous call.
2. initialValue - The value to start the reduction.
3. this - A value to be bound to this keyword in the callback.

Return

The reduce method returns the value returned from the last call of the callback function.

Exception

• TypeError: If the callback argument given is not a function.

Connection.set

Sets a value for specific pair of keys. If the connection does not contain such pair, it is added and it is mapped to value specified, otherwise the found pair's mapped value is replaced by the current value.

function set(leftKey:*, rightKey:*, value:*):boolean

Arguments

1. leftKey - The first value of the pair of keys.
2. rightKey - The second value of the pair of keys.
3. value - The value to become the mapped value for the pair of keys.

Return

Returns whether the length of the connection has been changed by the operation.

Connection.some

Test if there is mapping in the connection that satisfies a callback function. This function has iteration optimization

• it may process only part of the mappings and returns early if the return result is known.

function some(callback:Function, this:*):boolean throws TypeError

function callback(value:*, leftKey:*, rightKey:*, connection:Connection):boolean

Arguments

1. callback - A function to be called for each of the mappings of the connection.
2. this - A value to be bound to this keyword in the callback.

Return

If the callback returned true for at least one mapping of the Connection, then true is returned. Otherwise false is returned.

Exception

• TypeError: If the callback argument given is not a function.

Connection.values

Creates an array containing all values in the connection. The order of elements returned is implementation specific. The returned array has the same order as keys method. A values in the returned array may be repeated.

function values():Array

Return

A javascript Array object containing all values from all mappings of the connection.

Graph

The graph is used to store both javascript values and connection between those values. Unlike the Relation, the Graph collection allow some values to be disconnected (and still be in the graph). The javascript values stored in the graph are called nodes and the connection between the values are called edges. The edges are not allowed to lead to nowhere or to lead to javascript values not in the graph.

The Graph class is still beta, more operations expected to be added.

• addEdge
• addNode
• childNodes
• deleteEdge
• deleteNode
• getEdge
• getNode
• hasEdge
• hasNode
• incomingEdges
• isEmpty
• outgoingEdges
• parentNodes

Graph.addEdge

Adds an edge connecting two nodes. If the nodes are not in the graph, they are added. Adding an edge is the same as adding a connection between two values in context of current object (exactly like the Relation do). The direction for the edge is from parent towards the child.

function addEdge(parent:*, child:*):Array

Arguments

1. parent - The value to be used as parentNode.
2. child - The value to be used as childNode.

Return

Return an array with two indexes:

• At index 0 is the number of nodes added to the graph.
• At index 1 is the number of edges added to the graph.

Graph.addNode

Adds a node to the graph. A node is a single value that is not required to have any edges in and out of the graph. Adding a node is similar to adding a value in a Set and if a value is already in the graph, no new nodes are added.

function addNode(value:*):boolean

Arguments

1. value - The value to be added as node to the graph.

Return

Whether the value is actually added to the graph, e.g. if the number of nodes in the graph has changed.

Graph.childNodes

Get all nodes which are the child of the specified node. If the value is not in the graph, empty Set is returned. If the node has no outgoing connections, empty Set is returned. User should check the value with hasNode to find out which result occurred.

function childNodes(parent:*):Set

Arguments

1. parent - The parent value to find all children.

Return

A object instance of Set containing all children values of the specified parent.

Graph.deleteEdge

Removes an edge from the graph, leaving its parent-child nodes disconnected (in that direction).

function deleteEdge(parent:*, child:*):boolean

Arguments

1. parent - The value where the edge points from.
2. child - The value where the edge points to.

Return

Whether the edge was actually removed from the graph.

Graph.deleteNode

Removes a node from the graph. If node is connected to or from other nodes, just removing the node will leave some edges in invalid state - that is they are not coming or going to the graph node. So the method also remove all edges connected to that node. If the value is not in the graph, nothing is removed.

function deleteNode(value:*):Array

Arguments

1. value - The value to be removed from the graph.

Return

Return an array with following indexes:

• At index 0 is the number of nodes removed from the graph.
• At index 1 is the number of edges removed from the graph.

Graph.getEdge

Gets the value mapped to a connection between two nodes in the network. If no edge matching the search is found, undefined is returned.

function getEdge(parent:*, child:*):*

Arguments

1. parent - Where the should should come from.
2. child - Where the edge should go to.

Return

Returns the value mapped for the found edge or undefined if edge is not found. Be aware that undefined can also be mapped to an edge.

Graph.getNode

Gets the value mapped to a node in the network.

function getNode(node:*):*

Arguments

1. node - A value to find in the network.

Return

Returns the value mapped to that node or undefined if node is not found. Be aware that undefined can also be mapped to a node.

Graph.hasEdge

Check if the is edge from parent to the child in the graph.

function hasEdge(parent:*, child:*):boolean

Arguments

1. parent - Where the should should come from.
2. child - Where the edge should go to.

Return

Returns true if such an edge is found, false otherwise.

Graph.hasNode

Check if the value is in the graph.

function hasNode(value:*):boolean

Arguments

1. value - The value to be checked.

Return

Returns true if the value is found in the graph, false otherwise.

Graph.incomingEdges

Gets all edges pointing toward the specified child node. The edges are stored in Relation object. If the child is not in the graph or has no incoming edges - empty Relation is returned. Use hasNode method to check which case is it.

function incomingEdges(child:*):Relation

Arguments

1. child - A value to search all edges which pointing toward it.

Return

Return Relation object with all edges from the graph whose right key is always the specified child node.

Graph.isEmpty

Check if the graph is empty, e.g. it has no nodes.

function isEmpty():boolean

Return

Returns true if the graph has no nodes. In that case it cannot have any edges either.

Graph.outgoingEdges

Gets all edges starting from the specified parent node. The edges are stored in Relation object. If the parent is not in the graph or has no outgoing edges - empty Relation is returned. Use hasNode method to check which case is it.

function outgoingEdges(parent:*):Relation

Arguments

1. parent - A value to search all edges which starting from it.

Return

Return Relation object with all edges from the graph whose left key is always the specified parent node.

Graph.parentNodes

Get all nodes which are the parent of the specified node. If the value is not in the graph, empty Set is returned. If the node has no incoming connections, empty Set is returned. User should check the value with hasNode to find out which result occurred.

function childNodes(child:*):Set

Arguments

1. child - The child value to find all parents.

Return

A object instance of Set containing all parents values of the specified child.

Network

The Network class is similar to Graph class, but unlike it, it doesn't just store the values and connections between them. It uses both values and connections to map javascript values to them. While this is similar to Map (which maps values to values) and Connection (which maps connections to values), this class combines them. This class can be viewed as in-memory graph database, since the graph databases are graphs where each node and each edge can contain a value. Unlike the graph databases, the object can store any javascript value (including functions) and can use a single value in many nodes and connections.

The Network class is still beta, more operations expected to be added.

Naming conventions: While Relation and Graph are mathematical terms, its corresponding mappers required alternative names. Since the world network is a graph (including not only internet, but also intranet networks), it was a good idea to call something similar to graph. In the computer networks nodes are not just indistinguishable objects, they are complex machines with individual characteristics. The connection between those machines also varies in characteristics. Since the Connection and Network classes can represents characteristics about the connections and about the network itself, their names are chosen fairly.

• addEdge
• addNode
• childNodes
• deleteEdge
• deleteNode
• hasEdge
• hasNode
• incomingEdges
• isEmpty
• outgoingEdges
• parentNodes

Network.addEdge

Adds a connection between nodes in the network. If the values specified is not nodes in the network, they are added with mapped value for individual nodes set to undefined.

function addEdge(parent:*, child:*, value:*):Array

Arguments

1. parent - The value to be used as parent node.
2. child - The value to be used as child node.
3. value - The value mapped to the edge.

Return

Return an array with two indexes:

• At index 0 is the number of nodes added to the network.
• At index 1 is the number of edges added to the network.

Network.addNode

Maps a value to a node of the network. Node is added if it is not in the network.

function addNode(node:*, value:*):boolean

Arguments

1. node - The node to which data should be added/replaced.
2. value - The data value to be mapped to the node.

Return

Whether a new node was added to the graph.

Graph.childNodes

Get all nodes which are the child of the specified node. If the value is not in the network, empty Map is returned. If the node has no outgoing connections, empty Map is returned. User should check the value with hasNode to find out which result occurred.

function childNodes(parent:*):Map

Arguments

1. parent - The parent value to find all children.

Return

A object instance of Map containing all children mapping of the specified parent.

Network.deleteEdge

Removes an edge from the network, leaving its parent-child nodes disconnected (in that direction).

function deleteEdge(parent:*, child:*):boolean

Arguments

1. parent - The value where the edge points from.
2. child - The value where the edge points to.

Return

Whether the edge was actually removed from the network.

Network.deleteNode

Removes a node from the network. If node is connected to or from other nodes, just removing the node will leave some edges in invalid state - that is they are not coming or going to the network node. So the method also remove all edges connected to that node. If the value is not in the network, nothing is removed.

function deleteNode(node:*):Array

Arguments

1. node - The value to be removed from the graph.

Return

Return an array with following indexes:

• At index 0 is the number of nodes removed from the graph.
• At index 1 is the number of edges removed from the graph.

Network.hasEdge

Check if the is edge from parent to the child in the network.

function hasEdge(parent:*, child:*):boolean

Arguments

1. parent - Where the should should come from.
2. child - Where the edge should go to.

Return

Returns true if such an edge is found, false otherwise.

Network.hasNode

Check if the node is in the network.

function hasNode(node:*):boolean

Arguments

1. node - The value to be checked.

Return

Returns true if the value is found in the network, false otherwise.

Network.incomingEdges

Gets all edges pointing toward the specified child node. The edges are stored in Connection object. If the child is not in the network or has no incoming edges - empty Connection is returned. Use hasNode method to check which case is it.

function incomingEdges(child:*):Connection

Arguments

1. child - A value to search all edges which pointing toward it.

Return

Return Connection object with all edges from the network whose right key is always the specified child node.

Network.isEmpty

Check if the network is empty, e.g. it has no nodes.

function isEmpty():boolean

Return

Returns true if the network has no nodes. In that case it cannot have any edges either.

Network.outgoingEdges

Gets all edges starting from the specified parent node. The edges are stored in Connection object. If the parent is not in the network or has no outgoing edges - empty Connection is returned. Use hasNode method to check which case is it.

function outgoingEdges(parent:*):Connection

Arguments

1. parent - A value to search all edges which starting from it.

Return

Return Connection object with all edges from the network whose left key is always the specified parent node.

Network.parentNodes

Get all nodes which are the parent of the specified node. If the value is not in the network, empty Map is returned. If the node has no incoming connections, empty Map is returned. User should check the value with hasNode to find out which result occurred.

function childNodes(child:*):Map

Arguments

1. child - The child value to find all parents.

Return

A object instance of Map containing all parents values of the specified child.