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

Param	Type	Details
objectArray	Array	An array of objects with ids which determines the parent child relation
config	object	An object which defines the properties which defines the parent child relation for the data objects in the objectArray param. The object has following properties: id - Name of the id property (primary key) parentid - Name of the property which reference the parent object (foreign key)

tree

Properties

Name	Type	Details
rootNode	Node object	Root node for the tree

Methods

addData

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

Usage

addData(objectArray, config);

Arguments

Param	Type	Details
objectArray	Array	An array of objects with ids which determines the node relation
config	object	An object which defines the reference property and the collection name. The object has following properties: referenceid - Name of the referenceid property for the data object (reference primary id of node) collectionname - Name of the property which will hold the array of data object on the node

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

Param	Type	Details
dataObj	object	A data object similar to an object in the data array which was used to build the tree

getNodeById

Gets the node in the tree based on id parameter.

Usage

getNodeById(id);

Arguments

Param	Type	Details
id	Anything	Id value for node. Can be anything but is typically an integer(Number)

node

Properties

Name	Type	Details
children	Array	An array of child nodes
collectionnames	Array	An array of collection name for data added to the node. These data are arrays accessible through properties with names from this collection.
dataObj	object	the data object used to create the node when the tree was build
id	Anything	Id for the node. Can be anything but is typically an integer(Number)
parentid	Anything	Parent id for the node. Can be anything but is typically an integer(Number)

Methods

addChild

Adds a child node to the node

Usage

addChild(child);

Arguments

Param	Type	Details
child	node	Child node

addParent

Sets the parent node for the node

Usage

addParent(parentNode);

Arguments

Param	Type	Details
parentNode	node	Parent node

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

Param	Type	Details
collectionname	String	Name of the collection with data on each node

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

Param	Type	Details
filterFunction	function	Optional. If set, it will only add the data to the result if the function evaluates to true for the given data item

isAncestorOf

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

Usage

isAncestorOf(node);

Arguments

Param	Type	Details
node	node	Node to check for ancestor relation

isDescendantOf

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

Usage

isDescendantOf(node);

Arguments

Param	Type	Details
node	node	Node to check for descendant relation

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

Param	Type	Details
child	node	Child node

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.