Grama NPM | npm.io

grama

Pass grama an array of nodes with parent/child relationships and ask her questions about their ancestry.

const askGrama = require('grama')

const grama = askGrama({
    nodes: [
        { id: 10, tid: 3 }
      , { id: 11, tid: 3 }
      , { id: 12, tid: 3 }
      , { id: 13, tid: 11 }
      , { id: 14, tid: 11 }
      , { id: 15, tid: 13 }
      , { id: 16, tid: 13 } ]
    , id: 'id'
    , parentId: 'tid'
})

console.log('Closest ancestor of 15 and 16 is', grama.closestCommonAncestor(15, 16))
console.log('Closest ancestor of 15 and 11 is', grama.closestCommonAncestor(15, 11))
console.log('Closest ancestor of 16 and 13 is', grama.closestCommonAncestor(16, 13))

Closest ancestor of 15 and 16 is 13
Closest ancestor of 15 and 11 is 3
Closest ancestor of 16 and 13 is 11

Installation

npm install grama

Table of Contents generated with DocToc

API

grama.commonAncestors

Returns all common ancestors of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

Parameters

id1 (String | Number) the first id
id2 (String | Number) the second id

grama.closestCommonAncestor

Returns the id of the closest ancestor of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

When using the predicate a return value of false will cause grama to look for the next closest common ancestor, i.e. the returned id is not of the actual closest ancestor, but the closest one that matches the predicate.

Parameters

id1 (String | Number) the first id
id2 (String | Number) the second id
$0 Object options
- $0.predicate Function? a function that if supplied needs to return true in order to accept the common ancestor. If not supplied the actual closest common ancestor is accepted. (optional, default null)

Returns (String | Number) the id of the closest common ancestor or null if it doesn't exist

grama.furthestCommonAncestor

Returns the id of the furthest ancestor of id1 and id2. If either id1 or id2 are not found in the ancestry an error is thrown.

When using the predicate a return value of false will cause grama to look for the next furthest common ancestor, i.e. the returned id is not of the actual furthest ancestor, but the furthest one that matches the predicate.

Parameters

id1 (String | Number) the first id
id2 (String | Number) the second id
$0 Object options
- $0.predicate Function? a function that if supplied needs to return true in order to accept the common ancestor. If not supplied the actual furthest common ancestor is accepted. (optional, default null)

Returns (String | Number) the id of the furthest common ancestor or null if it doesn't exist

grama.closestAncestor

Finds the closes ancestor that matches the predicate. If two ancestors match the predicate and have the same distance, the first one found is returned.

Therefore this function is non-deterministic since it depends on the order in which ancestors were added.

Parameters

id (String | Number) the id of the node whose ancestors to evaluate
predicate Function a function that needst to return true if the ancestor satisfies the criteria

Returns (String | Number) the id of the first ancestor matching the predicate

grama.allAncestors

Finds all ancestors that match the predicate.

Parameters

id (String | Number) the id of the node whose ancestors to evaluate
predicate Function a function that needst to return true if the ancestor satisfies the criteria

Returns Set<(String | Number)> the ids of all ancestors matching the predicate

grama.closestDescendant

Finds the closes descendant that matches the predicate. If two descendants match the predicate and have the same distance, the first one found is returned.

Therefore this function is non-deterministic since it depends on the order in which descendants were added.

Parameters

id (String | Number) the id of the node whose descendants to evaluate
predicate Function a function that needst to return true if the descendant satisfies the criteria

Returns (String | Number) the id of the first descendant matching the predicate

grama.allDescendants

Finds all descendants that match the predicate.

Parameters

id (String | Number) the id of the node whose descendants to evaluate
predicate Function a function that needst to return true if the descendant satisfies the criteria

Returns Set<(String | Number)> the ids of all descendants matching the predicate

grama.closestSibling

Finds the closest sibling to the node with the provided id that matches the predicate.

It's not exactly a sibling but any node that is a descendant of an ancestor of the node with the provided id.

We consider the siblings closest if the distance from the node at id to the common ancestor is shortest.

For instance in the example below we are trying to find the closest sibling of WriteStream:Close. Our predicate looks for anything that is a WriteStream:Write.

WriteStream:Write2 is considered a closer sibling since the common ancestor Read2 is at a shorter distance to WriteStream:Close than Read1 which is the ancestor of the other WriteStream:Write1.

           -- ReadStream:Open -- Read1 -- Read2 -- Read3 -- WriteStream:Close
         /                           \          \
Parent                                \           -- WriteStream:Write2
         \                              -- WriteStream:Write1
           -- WriteStream:Open

Parameters

id (String | Number) the id of the node whose closest sibling we are trying to find
predicate Function needs to return true in order to determine a node as a sibling, it is invoked with ({ descendantId, descendantDistance, ancestorId, ancestorDistance }).

Returns (String | Number) the id of the closest sibling matching the predicate

grama.allSiblings

Finds the all siblings to the node with the provided id that match the predicate.

It's not exactly a sibling but any node that is a descendant of an ancestor of the node with the provided id.

For instance in the example below we are trying to find all siblings to WriteStream:Close that start with WriteStream. The result would include WriteStream:Write2, WriteStream:Write1 and WriteStream:Open.

           -- ReadStream:Open -- Read1 -- Read2 -- Read3 -- WriteStream:Close
         /                           \          \
Parent                                \           -- WriteStream:Write2
         \                              -- WriteStream:Write1
           -- WriteStream:Open

Parameters

id (String | Number) the id of the node whose siblings we are trying to find
predicate Function needs to return true in order to determine a node as a sibling, it is invoked with ({ descendantId, descendantDistance, ancestorId, ancestorDistance }).

Returns Set<(String | Number)> the ids of the siblings matching the predicate

grama.has

Determines if the given id is part of the nodes that were passed to grama.

Parameters

id (String | Number) the id we are verifying

Returns Boolean true if so otherwise false

grama.get

Retrieves the node with the given id from the nodes that were passed to grama.

Parameters

id (String | Number) the id we are trying to get

Returns Object the node with the supplied id or null if not found

askGrama

Creates grama who will tell you about the ancestry of the nodes you passed.

Parameters

$0 Object options
- $0.nodes Array<Object> the nodes to be added to the ancestry
- $0.id String the name of the property that returns the id of each node
- $0.parentId String the name of the property that returns the id of the parent of each node