jsaturday_tree

Description

Simple in-memory tree structure to represent hierarchical data.

The tree is defined by:

• n nodes; each node is an Object contains arbitrary data, and two special fields: _id (unique node id) and _parent (id of parent node). If no parent node is given, it is automatically assigned to orphanParent (... I know...)
• One root node, with _id = 'ROOT'
• One orphanParent node, (default _id = 'ORPHANS') connected under 'ROOT' node.
• One parent for each node, or zero parents (in this case node will be connected to orphan node).

New features

• v 1.1.2 bug fix: in createNode(node), node is passed by copy.
• v 1.1 added optional callbacks for addNode(), removeNode(), and updateNode(). Updated unit tests.

Installation

$ npm i jsaturday_tree

Test

$ npm test

Api

// Constructor
var Tree = require('jsaturday_tree');
var roles = new Tree(options);

// Add node
roles.addNode(nodeObject, <function(err, node){...}>);

// Remove node
roles.removeNode(nodeId, <newParentId>, <function(err, success){...}>);

// Update node
roles.updateNode(nodeObject, <function(err, node){...}>);

// Initialize / reinitialize
roles.initialize();

// Get copy of all nodes / a selected node after computing children
var nodesArray = roles.getAllCopy();
var nodeObject = roles.getNodeCopy(nodeId);

Please check the follow examples as API documentation.

Examples

// Require Tree object
var Tree = require('jsaturday_tree');

//-----------------------------------------------------------------
// Options
//-----------------------------------------------------------------
var options = {
    // How long (sec) data structure will keep as computed in the memory
    TTL: 60, // default = 0 => no cache
    
    // Parent nodes for nodes without parent, by default it is
    // 'ORPHANS', connected to 'ROOT'
    orphanParentId: 'MyORPHAN' // default = ORPHANS
};

//-----------------------------------------------------------------
// Constructor
//-----------------------------------------------------------------
var roles = new Tree(options);

//-----------------------------------------------------------------
// Add nodes
//-----------------------------------------------------------------
// (for each added node cache is automatically flushed)
// Note: 'ROOT' node and orphan node will be automatically created before
// initialization, if they was not provided by user.
roles.addNode({
    _id: 'NODE1',
    _parent: 'ROOT',
    attribute1: ...
});
roles.addNode({
    _id: 'NODE2',
    _parent: 'NODE1',
    attribute1: ... ,
    attribute2: ... ,
});

// This is an ORPHAN node
roles.addNode({
    _id: 'NODE3'
});

roles.addNode({
    _id: 'NODE4',
    _parent: 'ROOT',
});

roles.addNode({
    _id: 'NODE5',
    _parent: 'NODE4',
    value: 1
});

//-----------------------------------------------------------------
// Initialize data structure
//-----------------------------------------------------------------
// It resets cache and computes children. This method is
// called automatically if new node was added / removed, so probably you
// will never use.
roles.initialize();

//-----------------------------------------------------------------
// Get data structure.
//-----------------------------------------------------------------
// Returns a COPY node objects, with _children attribute computed
var all = roles.getAllCopy();

//-----------------------------------------------------------------
// Up and Down chains
//-----------------------------------------------------------------
// Return array of node ids from required nodeId to ROOT
var node1UpIds = roles.getUp('NODE1');      // => ['NODE1', 'ROOT']
var node3UpIds = roles.getUp('NODE3');      // => ['NODE3', 'MyORPHAN']

// Return array of node ids from required nodeId to leaves
var node1DownIds = roles.getDown('NODE1');  // => ['NODE1', 'NODE2']

//-----------------------------------------------------------------
// Removing a node
//-----------------------------------------------------------------
// Removing a node and set a new parent for all the children
roles.removeNode('NODE1', 'ROOT');
var node2UpIdNow = roles.getUp('NODE2');      // => ['NODE2', 'ROOT']

// Removing a node and move all children to orphan node
roles.removeNode('NODE4');
var node5UpIdNow = roles.getUp('NODE5');      // => ['NODE5', 'MyORPHAN']

//-----------------------------------------------------------------
// Get node content (it will pass A COPY!)
//-----------------------------------------------------------------
var node5CloneA = roles.getNodeCopy(NODE5);
// node5CloneA = {_id: "NODE5", _parent: "MyORPHAN", value: 1}
node5CloneA.value = 2;
// node5Clone = {_id: "NODE5", _pare nt: "MyORPHAN", value: 2}
var node5CloneB = roles.getNodeCopy(NODE5);
// node5CloneB = {_id: "NODE5", _parent: "MyORPHAN", value: 1}

//-----------------------------------------------------------------
// Update node content (it will save a COPY of passed object!)
//-----------------------------------------------------------------
roles.updateNode(node5CloneA);
// Internal NODE5 = {_id: "NODE5", _pare nt: "MyORPHAN", value: 2}
node5CloneA.value = 3;
// Internal NODE5 = {_id: "NODE5", _pare nt: "MyORPHAN", value: 2}