documentation.md

Classes

Tree

Class Tree

Typedefs

KeyField : string

defaults 'key'

ChildrenField : string

defaults 'children'

TreeNode : Object

Tree

Class Tree

Kind: global class

• Tree
  • new Tree([nodes], [keyField], [childrenField])
  • .setData(nodes)
  • .toJSON() ⇒ Array.<TreeNode>
  • .toString([indent]) ⇒ string
  • .walker(iterator, [nodes], [mode], [breakable])
  • .hasChildren(nodeOrKey) ⇒ boolean
  • .isBranch(nodeOrKey) ⇒ boolean
  • .isRoot(nodeOrKey) ⇒ boolean
  • .isFirstChild(nodeOrKey) ⇒ boolean
  • .isLastChild(nodeOrKey) ⇒ boolean
  • .getNode(key) ⇒ TreeNode | null
  • .contains(parent, child) ⇒ boolean
  • .containsDeeply(parent, child) ⇒ boolean
  • .getParent(key, [nodes]) ⇒ TreeNode | null
  • .siblingsAndSelf(nodeOrKey, [nodes]) ⇒ Array.<TreeNode>
  • .siblings(nodes, nodeOrKey) ⇒ Array.<TreeNode>
  • .prevSiblings(nodeOrKey, [nodes]) ⇒ TreeNode | null
  • .nextSiblings(nodeOrKey, [nodes]) ⇒ TreeNode | null
  • .nextSiblingsAll(nodeOrKey, [nodes]) ⇒ TreeNode | null
  • .prevSiblingsAll(nodeOrKey, [nodes]) ⇒ TreeNode | null
  • .indexOf(siblings, nodeOrKey) ⇒ number
  • .append(node, [tagart])
  • .prepend(node, [tagart])
  • .insertBefore(node, target)
  • .insertAfter(node, target)
  • .forward(node)
  • .backward(node)
  • .remove(node)
  • .removeNodes(node)
  • .levelUp(node)
  • .levelDown(node)
  • .findNodes(nodes, predicate, [parents]) ⇒ Array.<TreeNode>
  • .filterNode(node, predicate, [parents]) ⇒ TreeNode | null
  • .filterNodes(predicate, [nodes], [parents]) ⇒ Array.<TreeNode>
  • .sortNode(node, compareFunction, [parents]) ⇒ TreeNode
  • .sortNodes(compareFunction, [nodes], [parents]) ⇒ Array.<TreeNode>
  • .mapNode(node, mapFunction, [parents]) ⇒ TreeNode

new Tree([nodes], [keyField], [childrenField])

Creates an instance of Tree.

Param	Type	Default	Description
[nodes]	Array	[]	tree data.
[keyField]	KeyField	'key'	Key fieldname of each tree node (value of key should be unique in all tree nodes.)
[childrenField]	ChildrenField	'children'	children field name of tree node.

Example (Install)

npm install @colin-luo/tree

Example (Typescript)

with default data structure: {key: '', children: []}.

import Tree from '@colin-luo/tree';

const data = [
  {key: 'a', label: 'A', icon: 'a.svg'},
  {key: 'b', label: 'B', icon: 'b.svg', children: [
    {key: 'b-a', label: 'B-A', icon: 'b-a.svg'},
    {key: 'b-b', label: 'B-B', icon: 'b-b.svg'},
  ]},
  {key: 'c', label: 'C', icon: 'c.svg', children: []},
];

const tree = new Tree(data);

with custom data structure: {id: '', members: []}.

import Tree from '@colin-luo/tree';

type KeyField = 'id';
type ChildrenField = 'members';
type NodeProps = {
  label: string;
  icon: string;
}

const data = [
  {id: 'a', label: 'A', icon: 'a.svg'},
  {id: 'b', label: 'B', icon: 'b.svg', members: [
    {id: 'b-a', label: 'B-A', icon: 'b-a.svg'},
    {id: 'b-b', label: 'B-B', icon: 'b-b.svg'},
  ]},
  {id: 'c', label: 'C', icon: 'c.svg', members: []},
];

const tree = new Tree<NodeProps, KeyField, ChildrenField>(data, 'id', 'members');

Example (Javascript)

import Tree from '@colin-luo/tree';

const data = [
  {key: 'a', label: 'A', icon: 'a.svg'},
  {key: 'b', label: 'B', icon: 'b.svg', children: [
    {key: 'b-a', label: 'B-A', icon: 'b-a.svg'},
    {key: 'b-b', label: 'B-B', icon: 'b-b.svg'},
  ]},
  {key: 'c', label: 'C', icon: 'c.svg', children: []},
];

const tree = new Tree(data);
const tree2 = new Tree(data, 'key', 'children');

@.setData(nodes)

---

set tree nodes.

Kind: instance method of Tree

Param	Type
nodes	Array.<TreeNode>

Example (Example usage of `setData`.)

const treeData = [
  {key: 'foo', text: 'foo'},
  {key: 'bar', text: 'bar', children: {
    {key: 'baz', text: 'baz'},
  }},
];
tree.setData(treeData);

@.toJSON() ⇒ Array.<TreeNode>

Get tree as JSON.

Kind: instance method of Tree

@.toString([indent]) ⇒ string

---

Get tree as string.

Kind: instance method of Tree
Returns: string -

string

Param	Type	Default
[indent]	number	4

Example (Typescript)

const treeData: string = tree.toString();

Example (Javascript use 4 space indents.)

const treeData = tree.toString(4);

@.walker(iterator, [nodes], [mode], [breakable])

---

Touch every node in tree.

Kind: instance method of Tree

Param	Type	Default	Description
iterator	function		(node, index, level) => void; If return true and breakable if true will break traversing.
[nodes]	Array.<Node> | null	'null'	Nodes to traversing, defaults is root nodes of the tree.
[mode]	'depth' | 'breadth'	'depth'	Indicates depth-first or breadth-first priority when traversing.
[breakable]	boolean	false	Break traversing when iterator return true;

Example (echo nodes)

const iterator = function(node, index, parent, level) {
 console.log(node)
};

tree.walker(iterator, null, 'depth');

Example
break when iterator(...) return true.

const iterator = function(node, index, parent, level) {
  if (node.key === 'bar') {
    return true;
  }
};

tree.walker(iterator, null, 'depth');

@.hasChildren(nodeOrKey) ⇒ boolean

---

Checks if a node contains children.

Kind: instance method of Tree

Param	Type
nodeOrKey	TreeNode | String

Example

tree.hasChildren('nodeKey'); // return true || false
tree.hasChildren({ key: 'bar' }); // return false
tree.hasChildren({ key: 'bar', children: [] }); // return false
tree.hasChildren({ key: 'bar', children: [{ key: '...'}] }); // return true

@.isBranch(nodeOrKey) ⇒ boolean

---

Checks if a node has children property (whether the children's length is 0 or not)

Kind: instance method of Tree

Param	Type
nodeOrKey	TreeNode | String

Example

tree.isBranch('nodeKey'); // return true || false
tree.isBranch({key: '' }); // return false
tree.isBranch({key: '', children: [] }); // return true

@.isRoot(nodeOrKey) ⇒ boolean

Checks if given node is the root.

Kind: instance method of Tree

Param	Type
nodeOrKey	TreeNode | string

@.isFirstChild(nodeOrKey) ⇒ boolean

Checks if given node is the first child.

Kind: instance method of Tree

Param	Type
nodeOrKey	TreeNode | string

@.isLastChild(nodeOrKey) ⇒ boolean

Checks if given node is the last child.

Kind: instance method of Tree

Param	Type
nodeOrKey	TreeNode | string

@.getNode(key) ⇒ TreeNode | null

---

Get single node with a specific key.

Kind: instance method of Tree

Param	Type
key	string

@.contains(parent, child) ⇒ boolean

---

Checks if a node contains another node as children.

Kind: instance method of Tree

Param	Type	Description
parent	string | TreeNode	Parent node or key of parent node.
child	string | TreeNode	Child node or key of child node.

@.containsDeeply(parent, child) ⇒ boolean

---

Checks if a node contains another node deeply.

Kind: instance method of Tree

Param	Type	Description
parent	string | TreeNode	Parent node or key of parent node.
child	string | TreeNode	Child node or key of child node.

@.getParent(key, [nodes]) ⇒ TreeNode | null

---

Get parent node by given key.

Kind: instance method of Tree
Returns: TreeNode | null -

return parent node of given key.

Param	Type	Description
key	string	node key.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.siblingsAndSelf(nodeOrKey, [nodes]) ⇒ Array.<TreeNode>

---

Get siblings and itself of given key or node.

Kind: instance method of Tree
Returns: Array.<TreeNode> -

return siblings node and itself of given node or key.

Param	Type	Description
nodeOrKey	string	node ke y.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.siblings(nodes, nodeOrKey) ⇒ Array.<TreeNode>

---

Get siblings of given key or node.

Kind: instance method of Tree
Returns: Array.<TreeNode> -

return siblings node of given node or key.

Param	Type	Description
nodes	Array.<TreeNode>	Tree root nodes or specific nodes.
nodeOrKey	string	node or key of node.

@.prevSiblings(nodeOrKey, [nodes]) ⇒ TreeNode | null

---

Get node before of given node.

Kind: instance method of Tree
Returns: TreeNode | null -

return previous siblings node of given key or NULL.

Param	Type	Description
nodeOrKey	string	node key.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.nextSiblings(nodeOrKey, [nodes]) ⇒ TreeNode | null

---

Get next node of given node.

Kind: instance method of Tree
Returns: TreeNode | null -

return next siblings node of given key or null.

Param	Type	Description
nodeOrKey	string	node or key.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.nextSiblingsAll(nodeOrKey, [nodes]) ⇒ TreeNode | null

---

Get all next siblings node of given node or key.

Kind: instance method of Tree
Returns: TreeNode | null -

return next siblings node of given key or null.

Param	Type	Description
nodeOrKey	string	node key.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.prevSiblingsAll(nodeOrKey, [nodes]) ⇒ TreeNode | null

---

Get all previous siblings of given node.

Kind: instance method of Tree
Returns: TreeNode | null -

return next siblings node of given key or null.

Param	Type	Description
nodeOrKey	string	node or key.
[nodes]	Array.<TreeNode>	Tree root nodes or specific nodes.

@.indexOf(siblings, nodeOrKey) ⇒ number

---

Get index of node.

Kind: instance method of Tree

Param	Type
siblings	Array.<TreeNode>
nodeOrKey	TreeNode | string

@.append(node, [tagart])

---

Append a new node into target node as end.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode	A new node to append.
[tagart]	TreeNode | string	where for appending to.

@.prepend(node, [tagart])

---

Prepend a node into target node at head.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode	A new node to prepend.
[tagart]	TreeNode | string	Where to prepend.

@.insertBefore(node, target)

---

Insert a new node before target node

Kind: instance method of Tree

Param	Type
node	TreeNode
target	TreeNode | string

@.insertAfter(node, target)

---

Insert a new node after target node

Kind: instance method of Tree

Param	Type
node	TreeNode
target	TreeNode | string

@.forward(node)

---

Exchange location with the previous node.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.backward(node)

---

Exchange location with the next node.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.remove(node)

---

Remove the given node

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.removeNodes(node)

---

Remove the given nodes.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.levelUp(node)

---

Move the given node to the back of the parent node as the sibling of the parent node.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.levelDown(node)

---

Move the given node down to end of children of previous siblings.

Kind: instance method of Tree

Param	Type	Description
node	TreeNode | string	Node or key.

@.findNodes(nodes, predicate, [parents]) ⇒ Array.<TreeNode>

---

Find nodes via a custom function.

Kind: instance method of Tree

Param	Type	Default
nodes	Array.<TreeNode>
predicate	NodesFinder.<TreeNode>
[parents]	Array.<TreeNode>	[]

@.filterNode(node, predicate, [parents]) ⇒ TreeNode | null

---

Filter for a single node and its children.

Kind: instance method of Tree

Param	Type	Default
node	TreeNode
predicate	NodesFinder.<TreeNode>
[parents]	Array.<TreeNode>	[]

@.filterNodes(predicate, [nodes], [parents]) ⇒ Array.<TreeNode>

---

Filter the given list of nodes and their children.

Kind: instance method of Tree

Param	Type	Default
predicate	NodesFinder.<TreeNode>
[nodes]	Array.<TreeNode>	this.nodes
[parents]	Array.<TreeNode>	[]

@.sortNode(node, compareFunction, [parents]) ⇒ TreeNode

---

Sort children of givin node and return a new node with sorted children.

Kind: instance method of Tree

Param	Type	Default
node	TreeNode
compareFunction	NodeSorter.<TreeNode>
[parents]	Array.<TreeNode>	[]

@.sortNodes(compareFunction, [nodes], [parents]) ⇒ Array.<TreeNode>

---

Sort node list and their children.

Kind: instance method of Tree

Param	Type	Default
compareFunction	NodeSorter.<TreeNode>
[nodes]	Array.<TreeNode>
[parents]	Array.<TreeNode>	[]

@.mapNode(node, mapFunction, [parents]) ⇒ TreeNode

---

Map node

Kind: instance method of Tree

Param	Type	Default
node	TreeNode
mapFunction	NodeMapper.<TreeNode>
[parents]	Array.<TreeNode>	[]

KeyField : string

defaults 'key'

Kind: global typedef

ChildrenField : string

defaults 'children'

Kind: global typedef

TreeNode : Object

Kind: global typedef
Properties

Name	Type
key	KeyField
children	ChildrenField
others	Any