Iteration

It is possible to iterate on the three following things:

Iteration methods

The library basically proposes three ways to iterate:

  • Methods returning arrays of keys.
  • Methods using callbacks.
  • Methods creating JavaScript iterators for lazy consumption (yet to be implemented!).

Adjacency

Those methods iterate over the graph's adjacency, i.e. once per edge in the graph.

Examples

const graph = new Graph();

graph.mergeEdge('Thomas', 'Elizabeth');
graph.mergeEdge('John', 'Thomas');

// Using the callback method
graph.forEach(
  (source, target, sourceAttributes, targetAttributes, edge, edgeAttributes) => {
  console.log(source, target);
});

// Using the iterator
for (const [source, target, ...] of graph.adjacency())
  console.log(source, target);

// Iterating over the graph itself is actually the same
for (const [source, target, ...] of graph)
  console.log(source, target);

#.forEach

Iterates over the graph's adjacency using a callback.

Arguments

  • callback function: callback to use.

Callback arguments

  • source string: source node's key.
  • target string: target node's key.
  • sourceAttributes object: source node's attributes.
  • targetAttributes object: target node's attributes.
  • edge string: edge's key.
  • edgeAttributes object: edge's attributes.

#.adjacency

Returns an iterator over the graph's adjacency.

Entries

  • source string: source node's key.
  • target string: target node's key.
  • sourceAttributes object: source node's attributes.
  • targetAttributes object: target node's attributes.
  • edge string: edge's key.
  • edgeAttributes object: edge's attributes.

Nodes

Those methods iterate over the graph's nodes.

Examples

const graph = new Graph();

graph.addNode('Thomas');
graph.addNode('Elizabeth');

// Using the array-returning method:
graph.nodes();
>>> ['Thomas', 'Elizabeth']

// Using the callback method
graph.forEachNode((node, attributes) => {
  console.log(node, attributes);
});

// Using the iterator
for (const [node, attributes] of graph.nodeEntries()) {
  console.log(node, attributes);
}

#.nodes

Returns an array of node keys.

#.forEachNode

Iterates over each node using a callback.

Arguments

  • callback function: callback to use.

Callback arguments

  • key string: the node's key.
  • attributes object: the node's attributes.

#.nodeEntries

Returns an iterator over the graph's nodes.

Entries

  • key string: the node's key.
  • attributes object: the node's attributes.

Edges

These methods iterate over the graph's edges.

Examples

const graph = new Graph();

graph.addNodesFrom(['Thomas', 'Rosaline', 'Emmett', 'Catherine', 'John', 'Daniel']);
graph.addEdgeWithKey('T->R', 'Thomas', 'Rosaline');
graph.addEdgeWithKey('T->E', 'Thomas', 'Emmett');
graph.addEdgeWithKey('C->T', 'Catherine', 'Thomas');
graph.addEdgeWithKey('R->C', 'Rosaline', 'Catherine');
graph.addEdgeWithKey('J->D1', 'John', 'Daniel');
graph.addEdgeWithKey('J->D2', 'John', 'Daniel');

// Using the array-returning methods:
graph.edges();
>>> ['T->R', 'T->E', 'C->T', 'R->C']

graph.edges('Thomas');
>>> ['T->R', 'T->E', 'C->T']

graph.edges('John', 'Daniel');
>>> ['J->D1', 'J->D2']

// Using the callback methods
graph.forEachEdge(
  (edge, attributes, source, target, sourceAttributes, targetAttributes) => {
    console.log(`Edge from ${source} to ${target}`);
});

// And the counterparts
graph.forEachEdge('Thomas', callback);
graph.forEachEdge('John', 'Daniel', callback);

// Using the iterators
for (const [edge, attributes, ...] of graph.edgeEntries()) {
  console.log(edge, attributes);
}

#.edges

Returns an array of relevant edge keys.

Counterparts

#.inEdges
#.outEdges
#.inboundEdges (in + undirected)
#.outboundEdges (out + undirected)
#.directedEdges
#.undirectedEdges

Arguments

  1. None: iterate over every edge.
  2. Using a node's key: will iterate over the node's relevant attached edges.

    • node any: the related node's key.
  3. Using source & target: will iterate over the relevant edges going from source to target.

    • source any: the source node's key.
    • target any: the target node's key.

#.forEachEdge

Iterates over relevant edges using a callback.

Counterparts

#.forEachInEdge
#.forEachOutEdge
#.forEachInboundEdge (in + undirected)
#.forEachOutboundEdge (out + undirected)
#.forEachDirectedEdge
#.forEachUndirectedEdge

Arguments

  1. Callback: iterate over every edge.

    • callback function: callback to use.
  2. Using a node's key: will iterate over the node's relevant attached edges.

    • node any: the related node's key.
    • callback function: callback to use.
  3. Using source & target: will iterate over the relevant edges going from source to target.

    • source any: the source node's key.
    • target any: the target node's key.
    • callback function: callback to use.

Callback arguments

  • key string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object= attributes of the edge's target.

#.edgeEntries

Returns an iterator over relevant edges.

Counterparts

#.inEdgeEntries
#.outEdgeEntries
#.inboundEdgeEntries (in + undirected)
#.outboundEdgeEntries (out + undirected)
#.directedEdgeEntries
#.undirectedEdgeEntries

Arguments

  1. None: iterate over every edge.
  2. Using a node's key: will iterate over the node's relevant attached edges.

    • node any: the related node's key.
  3. Using source & target: will iterate over the relevant edges going from source to target.

    • source any: the source node's key.
    • target any: the target node's key.

Entries

  • key string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object= attributes of the edge's target.

Neighbors

These methods iterate over the neighbors of the given node or nodes.

Examples

const graph = new Graph();

graph.addNodesFrom(['Thomas', 'Rosaline', 'Emmett', 'Catherine', 'John', 'Daniel']);
graph.addEdge('Thomas', 'Rosaline');
graph.addEdge('Thomas', 'Emmett');
graph.addEdge('Catherine', 'Thomas');
graph.addEdge('Rosaline', 'Catherine');
graph.addEdge('John', 'Daniel');
graph.addEdge('John', 'Daniel');

// Asking whether two nodes are neighbors
graph.neighbors('Thomas', 'Rosaline');
>>> true

// Using the array-returning methods
graph.neighbors('Thomas');
>>> ['Rosaline', 'Emmett', 'Catherine']

// Using the callback methods
graph.forEachNeighbor('Thomas', function(neighbor, attributes) {
  console.log(neighbor, attributes);
});

// Using the iterators
for (const [neighbor, attributes] of graph.neighborEntries()) {
  console.log(neighbor, attributes);
}

#.neighbors

Returns an array of relevant neighbor keys.

Counterparts

#.inNeighbors
#.outNeighbors
#.inboundNeighbors (in + undirected)
#.outboundNeighbors (out + undirected)
#.directedNeighbors
#.undirectedNeighbors

Arguments

  1. Using a node's key: will iterate over the node's relevant neighbors.

    • node any: the node's key.
  2. Using two nodes' keys: will return whether the two given nodes are neighbors.

    • node1 any: first node.
    • node2 any: second node.

#.forEachNeighbor

Iterates over the relevant neighbors using a callback.

Counterparts

#.forEachInNeighbor
#.forEachOutNeighbor
#.forEachInboundNeighbor (in + undirected)
#.forEachOutboundNeighbor (out + undirected)
#.forEachDirectedNeighbor
#.forEachUndirectedNeighbor

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • key string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.neighborEntries

Returns an iterator over the relevant neighbors.

Counterparts

#.inNeighborEntries
#.outNeighborEntries
#.inboundNeighborEntries (in + undirected)
#.outboundNeighborEntries (out + undirected)
#.directedNeighborEntries
#.undirectedNeighborEntries

Arguments

  1. Using a node's key: will iterate over the node's relevant neighbors.

    • node any: the node's key.
  2. Using two nodes' keys: will return whether the two given nodes are neighbors.

    • node1 any: first node.
    • node2 any: second node.

Entries

  • key string: the neighbor's key.
  • attributes object: the neighbor's attributes.