Nefarious Pickle Muncher

    tree-util

    1.0.6 • Public • Published

    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.

    Install

    npm i tree-util

    DownloadsWeekly Downloads

    664

    Version

    1.0.6

    License

    MIT

    Unpacked Size

    63.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • gatesmart