README.md

Qi Nodes

http://drkibitz.github.io/qi-nodes/

Base implementation for composite patterns in JavaScript.

Usage

Any object with its property of "root" set, qualifies as a rooted node. The root property is simply propagated up and down the leaves.

The module itself is a rooted NodeObject.

var nodes = require('qi-nodes');
console.log(nodes.root === nodes);
// > true

The previous fact doesn't limit you from having more rooted trees.

var root = nodes.createRoot();
console.log(root.root === nodes);
// > false

There are many ways to work with the API, but they follow the same pattern.

// pretty straight forward
n1 = root.append(nodes.create());
n2 = nodes.create().appendTo(root);

// The last argument is always the node context
n3 = nodes.append(nodes.create(), root);   // In this case it's the parent
n4 = nodes.appendTo(root, nodes.create()); // In this case it's the child

// Automatically append a newly created node by passing the parent to the create method.
n5 = nodes.create(root);

// > root -> n1, n2, n3, n4, n5, n6

Use instances of NodeObject to automatically use "this" as the node context. Which means the default value of the last optional argument in methods (With the exception of the create method), will be itself.

var singleNode = nodes.create();
n3 = singleNode.swap(n3);
// root -> n1, n2, singleNode, n4, n5, n6

The API works with generic objects. This is possible because members are simply property based. The only reason to use or extend the NodeObject constructor is if you like that flavor of API.

var root2 = nodes.createRoot(),
	n2_1 = nodes.append({}, root2),
    n2_2 = nodes.append({}, n2_1),
    n2_3 = nodes.append({}, n2_2);
// root2 -> n2_1 -> n2_2 -> n2_3

n2_3 = nodes.swap(n2_3, n2_1);
// root2 -> n2_3 -> n2_2 -> n2_1

Create a class that extends NodeObject as normal.

function MyNodeExtended() {}
MyNodeExtended.prototype = Object.create(nodes.NodeObject.prototype, {
	constructor: {value: MyNodeExtended}
});

var root = MyNodeExtended.prototype.createRoot();
var node = root.create(root);

console.log(root instanceof MyNodeExtended); // true
console.log(node instanceof MyNodeExtended); // true

Assign (mixin) the NodeObject prototype.

function MyNodeAssigned() {}
Object.assign(MyNodeAssigned.prototype, nodes.NodeObject.prototype);

var root = MyNodeAssigned.prototype.createRoot();
var node = root.create(root);

console.log(root instanceof MyNodeAssigned); // true
console.log(node instanceof MyNodeAssigned); // true

Swap nodes from one tree to another.

var root3 = nodes.createRoot();
    n3_1 = nodes.create(root3),
    n3_2 = nodes.create(n3_2),
    n3_3 = nodes.create(n3_3);
// root3 -> n3_1 -> n3_2 -> n3_3

n2_2 = n3_2.swap(n2_2);
// root2 -> n2_3 -> n3_2 -> n2_1
// root3 -> n3_1 -> n2_2 -> n3_3