https://github.com/nodesource/grama
Pass grama an array of nodes with parent/child relationships and ask her questions about their ancestry.
https://github.com/nodesource/grama
Last synced: 8 months ago
JSON representation
Pass grama an array of nodes with parent/child relationships and ask her questions about their ancestry.
- Host: GitHub
- URL: https://github.com/nodesource/grama
- Owner: nodesource
- License: mit
- Archived: true
- Created: 2017-02-27T19:33:40.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2017-03-01T20:33:16.000Z (almost 9 years ago)
- Last Synced: 2025-04-10T14:17:09.391Z (9 months ago)
- Language: JavaScript
- Homepage: https://nodesource.github.io/grama
- Size: 1.15 MB
- Stars: 4
- Watchers: 3
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# grama [](http://travis-ci.org/nodesource/grama)
Pass grama an array of nodes with parent/child relationships and ask her questions about their ancestry.
```js
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](https://github.com/thlorenz/doctoc)*
- [API](#api)
- [grama.commonAncestors](#gramacommonancestors)
- [grama.closestCommonAncestor](#gramaclosestcommonancestor)
- [grama.furthestCommonAncestor](#gramafurthestcommonancestor)
- [grama.closestAncestor](#gramaclosestancestor)
- [grama.allAncestors](#gramaallancestors)
- [grama.closestDescendant](#gramaclosestdescendant)
- [grama.allDescendants](#gramaalldescendants)
- [askGrama](#askgrama)
- [License](#license)
## [API](https://nodesource.github.io/grama)
### 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the first id
- `id2` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the first id
- `id2` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the second id
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
- `$0.predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the first id
- `id2` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the second id
- `$0` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
- `$0.predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose ancestors to evaluate
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function that needst to return `true` if the
ancestor satisfies the criteria
Returns **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the first ancestor matching the predicate
### grama.allAncestors
Finds all ancestors that match the predicate.
**Parameters**
- `id` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose ancestors to evaluate
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function that needst to return `true` if the
ancestor satisfies the criteria
Returns **[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)<([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose descendants to evaluate
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function that needst to return `true` if the
descendant satisfies the criteria
Returns **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the first descendant matching the predicate
### grama.allDescendants
Finds all descendants that match the predicate.
**Parameters**
- `id` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose descendants to evaluate
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function that needst to return `true` if the
descendant satisfies the criteria
Returns **[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)<([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose closest sibling we are trying to find
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** needs to return `true` in order to determine a node as a sibling,
it is invoked with `({ descendantId, descendantDistance, ancestorId, ancestorDistance })`.
Returns **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the node whose siblings we are trying to find
- `predicate` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** needs to return `true` in order to determine a node as a sibling,
it is invoked with `({ descendantId, descendantDistance, ancestorId, ancestorDistance })`.
Returns **[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)<([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id we are verifying
Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id we are trying to get
Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options
- `$0.nodes` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** the nodes to be added to the ancestry
- `$0.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the name of the property that returns the id of each node
- `$0.parentId` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the name of the property that returns the id of the parent of each node
Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** an instance of Grama
## License
MIT