tree-util

Simple but powerfull library for building and working with tree structures.

Features

• Building tree structures based on data with parent child relations by id
• Methods for determining ancestor and descendant relations between nodes
• Methods for adding data to and getting data from tree structures
• General methods for working with trees
• Heavily tested

Easy to build tree structures where the data items has a parent child relation through id properties. An example of a data source with parent child relation can be a table in a relational database.

Examples

Building the tree.

var tree_util = require('tree-util')

// An array where the items has a parent child reference using id properties
var items = [{ id : 1 }, { id : 2, parentid : 1 }, { id : 3, parentid : 1 },
             { id : 4, parentid : 1 }, { id : 5, parentid : 3 }];

// Config object to set the id properties for the parent child relation
var standardConfig =  { id : 'id', parentid : 'parentid'};

// Creates an array of trees. For this example there will by only one tree
var trees = tree_util.buildTrees(items, standardConfig);

Determine ancestor or descendant relationships

// Contiued from example above
var tree = trees[0];
var rootNode = tree.rootNode;
var leafNode = tree.getNodeById(5);

var isDescendant = leafNode.isDescendantOf(rootNode); //returns true
var isAncestor = rootNode.isAncestorOf(leafNode); //returns true

Add data to the nodes based on reference id property and get data using a filter function

// Contiued from example above

var itemDataArray = [{ itemid : 1, value : 2, referenceid : 4 },
                     { itemid : 2, value : 5, referenceid : 5 },
                     { itemid : 3, value : 3, referenceid : 1 },  
                     { itemid : 4, value : 1, referenceid : 1 }];
var addDataConfig = { referenceid : 'referenceid', collectionname : 'items' };

tree.addData(itemDataArray, addDataConfig);

var nodeWithCollection = tree.getNodeById(1);
var nodeItems = nodeWithCollection.items; // returns an array with two objects

var filterFunction = function(data) {
    return (data && data.value && data.value > 1);
}

nodeWithCollection.getRecursiveNodeData(filterFunction); // returns an array with three objects

And many more methods and properties for working with tree structures. See API reference below for more information.

Installation

npm install tree-util

API Reference

The methods in the API either belong to the tree_util, the tree or the node.

tree_util

Methods

buildTrees

Builds a tree based on an object array and a config object which defines the id relation properties.

Usage

buildTrees(objectArray, config);

Arguments

tree

Properties

Methods

addData

Adds data to the nodes based on config object which defines the reference id.

Usage

addData(objectArray, config);

Arguments

createNode

Creates a node based on a data object. The data object must comply to the config when the tree was built. The new node must have an parent id which matches an id of a node in the tree.

Usage

createNode(dataObj);

Arguments

getNodeById

Gets the node in the tree based on id parameter.

Usage

getNodeById(id);

Arguments

node

Properties

Methods

addChild

Adds a child node to the node

Usage

addChild(child);

Arguments

addParent

Sets the parent node for the node

Usage

addParent(parentNode);

Arguments

getAncestors

Gets all the ancestor nodes

Usage

getAncestors();

getDescendants

Gets all the descendant nodes

Usage

getDescendants();

getRecursiveCollection

Gets the data added to the collections specified by name for the node and its descendants (added through method addData on the tree)

Usage

getRecursiveCollection(collectionname);

Arguments

getRecursiveNodeData

Gets the data added to the node and its descendants (added through method addData on the tree). The method takes an optional paramter, filterFunction, which can be used to filter the data result.

Usage

getRecursiveNodeData(filterFunction);

getSingleNodeData

Gets the data added to the node (added through method addData on the tree)

Usage

getSingleNodeData();

Arguments

isAncestorOf

Returns true if the current node is ancestor of the input parameter node

Usage

isAncestorOf(node);

Arguments

isDescendantOf

Returns true if the current node is descendant of the input parameter node

Usage

isDescendantOf(node);

Arguments

isLeaf

Returns true if the current node is a leaf node

Usage

isLeaf();

removeAllDescendants

Removes all descendants from the node

Usage

removeAllDescendants();

removeChild

Removes the child node from the node

Usage

removeChild(child);

Arguments

removeParent

Removes the parent and removes the node from the parents child array

Usage

removeParent();

License

(The MIT License)

Copyright (c) 2016 Kristian Marheim Abrahamsen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.