@pelevesque/tree

tree

Creates an editable JSON tree structure.

Node Repository

https://www.npmjs.com/package/@pelevesque/tree

Installation

npm install @pelevesque/tree

Tests

Command	Description
npm test or npm run test	All Tests Below
npm run cover	Standard Style
npm run standard	Coverage
npm run unit	Unit Tests

Methods

• ini reinitialize
• add adds a node
• del deletes a node
• set sets custom properties on a node
• get gets a custom property from a node
• cup runs a callback up the tree
• cdn runs a callback down the tree

Usage

Introduction

Every node in a tree has three properties: id, parentId, and children. ids and parentIds are generated and handled automatically. They are reserved properties. children is an array of child nodes. You can also add your own custom properties to nodes.

Below is an example of a node without children:

{
  id: 23,
  parentId: 12,
  children: []
}

Initialization

When initializing a tree, a root node will be created. It has an id = 0 and a parentId = null. You can also add custom properties upon initialization.

format: new Tree(props)

// initialize without custom properties
const tree = new Tree()

// creates this tree (just a root)
{
  id: 0,
  parentId: null,
  children: []
}

// initialize with custom properties
const tree = new Tree({
  enemy: 'jack',
  lover: 'jill'
})

// creates this tree (just a root)
{
  id: 0,
  parentId: null,
  children: [],
  enemy: 'jack',
  lover: 'jill'
}

Reinitialization

You can reinitialize the tree with the ini method.

format: tree.ini(props)

// these are the same
const tree = new Tree()

tree.ini()

// these are the same
const tree = new Tree({
  enemy: 'jack',
  lover: 'jill'
})

tree.ini({
  enemy: 'jack',
  lover: 'jill'
})

Adding Nodes

To add a node, you must provide a parentId indicating where to add it. Providing custom properties is optional. The id of the newly added node is returned so that it can be used to add children.

format: const id = tree.add(parentId, props)

// add an empty node to the root
const id = tree.add(0)

// add an empty node on parentId 3
const id = tree.add(3)

// add a node with a custom property on parentId 5
const id = tree.add(5, {boss: 'jess'})

Deleting Nodes

To delete a node and all its children, you simply need to provide the node's id.

format: tree.del(id)

// delete node 5 and all its children
tree.del(5)

Setting Node Custom Properties

To set a node's custom properties, you must provide the node's id and one or many custom properties.

format: tree.set(id, props)

// set custom properties on node 6
tree.set(6, {game: 'juno', score: 13})

Note: Setting custom properties does not overwrite previously set custom properties that use other keys. Only values with the same keys are overwritten.

Getting a Custom Property from a Node

To get a property value from a node, you must provide the node's id and the property's name.

format: const prop = tree.get(id, prop)

// get the value of the game property on node 6
const game = tree.get(6, 'game')

Running a Callback Up the Tree

cup, for callback + up, is used to run a callback upwards through the tree. It starts on a node and propagates to all the descendants of that node. If you don't provide a node id to start from, it will start from the root and propagate throughout the entire tree.

format: tree.cup(callback(node), id)

// run a callback on the entire tree
tree.cup(function(node) {
    node.selected = true
})

// run a callback from node id 11
tree.cup(function(node) {
    node.hovering = true
    if (node.selected) {
        node.score++
    }
}, 11)

Running a Callback Down the Tree

cdn, for callback + down (dn are the outer letters of down and up upside down), is used to run a callback downwards through the tree. It starts on a node and runs through all the ancestors until it reaches the root. You must provide the node id to start from.

format: tree.cdn(callback(node), id)

// run a callback from node 12 down to the root
tree.cdn(function(node) {
    node.selected = true
}, 12)

Retrieving the Tree Object

You can retrieve the tree object using:

tree.root

Example

const tree = new Tree()

const A = tree.add(0)
const B = tree.add(0)
const C = tree.add(0)
const D = tree.add(C, {boss: 'john'})
tree.cup(function(node) {
    node.lover = 'jess'
})
tree.set(A, {friend: 'jill'})
tree.set(B, {friend: 'jake'})
tree.cdn(function(node) {
    node.enemy = 'joss'
}, C)
const enemy = tree.get(0, 'enemy')
tree.del(3)