https://github.com/dodevops/js-hierarchy
Proper hierarchy management for Node, Typescript and the Browser.
https://github.com/dodevops/js-hierarchy
browser hierarchy javascript node tree typescript
Last synced: 2 months ago
JSON representation
Proper hierarchy management for Node, Typescript and the Browser.
- Host: GitHub
- URL: https://github.com/dodevops/js-hierarchy
- Owner: dodevops
- License: mit
- Created: 2017-09-02T11:23:19.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2018-08-09T07:59:32.000Z (almost 8 years ago)
- Last Synced: 2025-10-20T08:40:21.772Z (8 months ago)
- Topics: browser, hierarchy, javascript, node, tree, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/js-hierarchy
- Size: 247 KB
- Stars: 1
- Watchers: 6
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-MIT
Awesome Lists containing this project
README
# js-hierarchy
[](https://testingbot.com/builds/190e841358e8e595f6f7c007e8196dd4?auth=2e97049df058e9e19afeb9815cfbd92f)
[](https://travis-ci.org/dodevops/js-hierarchy)
[](https://www.npmjs.com/package/js-hierarchy)
[](https://www.npmjs.com/package/js-hierarchy)
[](https://testingbot.com/builds/190e841358e8e595f6f7c007e8196dd4?auth=2e97049df058e9e19afeb9815cfbd92f)
Proper hierarchy management for Node, Typescript and the Browser.
## Introduction
js-hierarchy enables you to build tree-like data structures and work
with them properly. It supports walking in multiple directions,
storage of arbitrary data and can be used as a base framework for
your special needs.
## Installation
### npm
Install the module using npm:
npm install --save js-hierarchy
If you're using Typescript, you might want to add the following typings:
npm install @types/bluebird @types/loglevel @types/node --save-dev
## Basic usage
### Typescript
The module includes the complete type definitions for Typescript
applications. Simply install the module and you're ready to go:
```typescript
import {SimpleNode} from 'js-hierarchy';
let rootNode: SimpleNode = new SimpleNode('nodeName');
```
### Node.js
After installing the module, use it with require():
```javascript
var hierarchy = require('js-hierarchy');
var rootNode = new hierarchy.SimpleNode('nodeName');
```
### Browser
Install the module and include the browser script:
```html
```
or use the jsDelivr CDN hosted version:
```html
```
With this the global namespace will include a "jshierarchy" object:
```javascript
var rootNode = new jshierarchy.SimpleNode('nodeName');
```
After that, everything's right as working in Node.js.
## Building the hierarchy
The tree-like data structures, that js-hierarchy can build are build
up from "Nodes". There can be several implementations of the Node
interface, but the simplest one is called "SimpleNode".
Just instantiate it to create a new node and give it a name:
```javascript
rootNode = new SimpleNode('nodeName');
```
If a node has no parent, it is considered the "root node". A node can
include a number of children, obviously. Simply use the "addChild"-
method to add one:
```javascript
rootNode = new SimpleNode('nodeName');
rootNode.addChild(new SimpleNode('childNodeName'));
```
Adding the child will automatically set the child's parent to
the node it was added to.
## Storing arbitrary data
Because nodes without any information aren't quite useful, js-hierarchy
supports storing arbitrary data in a key/value manner.
To add a new data to a node, use the method "setData":
```javascript
rootNode = new SimpleNode('nodeName');
rootNode.setData('mykey', 'myvalue');
```
You can also directly set the data when instantiating the node:
```javascript
rootNode = new SimpleNode('nodeName', {'mykey': 'myValue'});
```
Use "getData" to retrieve node data again later:
```javascript
rootNode = new SimpleNode('nodeName', {'mykey': 'myValue'});
console.log(rootNode.getData('mykey'));
// will output: myValue
```
## Walking the tree
Most tree-like structures are used to store hierarchical data
and walk the tree from one node to the upper, lower or sibling nodes.
The "walk" method of a node will just do that and call a user
defined function on each node it encounters. Please note, that only the
directions traversing the tree vertically (Down, Up, and RootDown)
will call the action on the original node.
```javascript
rootNode = new SimpleNode('nodeName', {'testkey': 'value'});
childNode = new SimpleNode('childNodeName', {'testkey': 'childvalue'});
childNode.addChild(new SimpleNode('grandChildNodeName', {'testkey': 'grandChildvalue'}));
rootNode.addChild(childNode);
rootNode.walk(Direction.up, (node) => {
console.log(node.getData('testkey'));
return Bluebird.resolve();
});
// will output 'value', 'childvalue' and 'grandChildvalue'
```
Please look at this example tree:
```
+----------------+
+ | grandchild 3.1 |
| +-------^--------+
down | |
| |
| |
| |
| +---------+ +---------+ +----+----+
v | child 1 | | child 2 | | child 3 |
+---^-----+ +----^----+ +----^----+
^ | | |
| | | |
| | <----+ | +-----> |
up | | left | right |
| | | |
| | | |
| | +--+---+ |
+ +----------+ root +---------+
+------+
```
Now, these directions are available:
* up: Walks through all child nodes. Then to their child nodes and
so on until no node is available anymore (from root to child 1-3
to grandchild)
* down: Walks to the parent node, then the next parent node and so on
until the root node is reached. (from grandchild to child 1-3 to root)
* left: Walks all siblings (the parent node's children) from the current
node to the left (children having a smaller array index) until the
first node is reached (from child2 to child1)
* right: Walks all siblings (the parent node's children) from the current
node to the right (children having a larger array index) until the
last node is reached (from child2 to child3)
* rootUp: Walks the same way "up" would go, but will only call the action
function on its way up. For example, when called from grandchild 3.1, the
action function will encounter "root" first, then "child3" and finally
"grandchild 3.1".
You can also specify an array of directions, meaning that, after the
last node has been reached in the first direction, the next direction
is walked and so on.
The walk method runs asynchronously using [Promises](https://promisesaplus.com/)
in the [Bluebird implementation](http://bluebirdjs.com/docs/getting-started.html).
Thus, the walker returns a fulfilled promise, if every node was walked. Also, the
supplied user function has to return a promise.
## Extending
If you need a specialized nodes with functions suitable for your
usage, you should extend "AbstractNode" and implement "Node".
AbstractNode already has all needed features, so you can just
concentrate on the needed features without caring about the basic
ones.
Please read the
[API documentation](https://dodevops.github.io/js-hierarchy/doc/) for details.
## Building
To test and build this package, simply use grunt:
grunt release
This will run all unit tests and a coverage report.
## Contributing
First of all: Thank you for your will to contribute!
To request a new feature or report a bug, please
create a github issue.
Pull requests are always welcome!
If you can, please submit a pull request adding the feature
or solving the bug you just reported.
While developing for your pull request, please first create a test, that
produces your error or checks your new feature, run the test suite
using
grunt test
to see them fail. Then, solve the bug or implement the feature and
run the tests once again to see them succeed. Please write good tests
and keep the coverage up.
We will review the pull request and optionally comment your code
and probably ask you to fix one or two things, before we can merge
your code.
## Browser compatibility tests
Browser compatibility tests are run using SauceLabs. To run them,
first add this line to your local hosts file:
127.0.0.1 saucelabs.test
Then, when running ```grunt browsertest```, set these two environment
variables:
SAUCE_USERNAME=
SAUCE_ACCESS_KEY=