Simple but powerfull library for building and working with tree structures.
- 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.
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.
npm install tree-util
The methods in the API either belong to the tree_util, the tree or the node.
Builds a tree based on an object array and a config object which defines the id relation properties.
buildTrees(objectArray, config);
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:
|
Name | Type | Details |
rootNode | Node object | Root node for the tree |
Adds data to the nodes based on config object which defines the reference id.
addData(objectArray, config);
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:
|
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.
createNode(dataObj);
Param | Type | Details |
dataObj | object | A data object similar to an object in the data array which was used to build the tree |
Gets the node in the tree based on id parameter.
getNodeById(id);
Param | Type | Details |
id | Anything | Id value for node. Can be anything but is typically an integer(Number) |
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) |
Adds a child node to the node
addChild(child);
Param | Type | Details |
child | node | Child node |
Sets the parent node for the node
addParent(parentNode);
Param | Type | Details |
parentNode | node | Parent node |
Gets all the ancestor nodes
getAncestors();
Gets all the descendant nodes
getDescendants();
Gets the data added to the collections specified by name for the node and its descendants (added through method addData on the tree)
getRecursiveCollection(collectionname);
Param | Type | Details |
collectionname | String | Name of the collection with data on each node |
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.
getRecursiveNodeData(filterFunction);
Gets the data added to the node (added through method addData on the tree)
getSingleNodeData();
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 |
Returns true if the current node is ancestor of the input parameter node
isAncestorOf(node);
Param | Type | Details |
node | node | Node to check for ancestor relation |
Returns true if the current node is descendant of the input parameter node
isDescendantOf(node);
Param | Type | Details |
node | node | Node to check for descendant relation |
Returns true if the current node is a leaf node
isLeaf();
Removes all descendants from the node
removeAllDescendants();
Removes the child node from the node
removeChild(child);
Param | Type | Details |
child | node | Child node |
Removes the parent and removes the node from the parents child array
removeParent();
(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.