hashtree

Build up "hash of hashes" in javascript and access the data contained.

For documentation of the methods provided see the Doc

The module can be used in Node, AMD / RequireJS or straight in a browser.

Motivation

I'm a big fan of perl hashes. Unfortunately in javascript building up and accessing hash-of-hashes is not as straightforward as in perl. This lib tries to solve this by providing methods to easily build up those.

Interface

Two interfaces are offered either using a prototype function HashTree or a functional interface using hashTree both offering the same functionality.

To access the values in the hashtree you use the keys either with a dot concatenated string or an array. E.g. 'key.subkey' or [ 'key', 'subkey' ] .

Basic Operations

Basic operations use the methods

• set - Sets a value in the hashtree obj according to keys.
• get - Gets a value in the hashtree obj according to keys.
• delete - Deletes a value in the hashtree obj according to keys.

var ht = require('./hashtree').hashTree;

var r, 
	obj = { "one": 1 };

/// add a new branch `obj.two.three` and set its value to 3 using dot-notation for keys
ht.set(obj, 'two.three', 3);
// => obj = { one: 1, two: { three: 3 } }

/// add a new branch `obj.four.five` and set its value to 5 using array notation for keys
ht.set(obj, [ 'four', 'five' ], 5);
// => obj = { one: 1, two: { three: 3 }, four: { five: 5 } }

/// set objects - note this replaces existing branches
ht.set(obj, 'two', { six: 6 } );
// => obj = { one: 1, two: { six: 6 }, four: { five: 5 } }

/// get the value stored in `obj.two` using dot-notation for keys
r = ht.get(obj, 'two');
// => r = { six: 6 }

/// get the value stored in `obj.four.five` using array notation for keys
r = ht.get(obj, [ 'four', 'five' ]);
// => r = 5

/// you can also set arrays
ht.set(obj, 'arr', [ 26, 27, 28 ]);
// => obj = { one: 1, two: { three: 3 }, four: { five: 5 }, arr: [ 26, 27, 28 ] }

/// and delete branches
ht.delete(obj, 'four');
// => obj = { one: 1, two: { three: 3 }, arr: [ 26, 27, 28 ] }

/// or items from arrays
ht.delete(obj, 'arr.1');
// => obj = { one: 1, two: { three: 3 }, arr: [ 26, , 28 ] }

Manipulate Values in the hashtree

To manipulate values in the hashtree use the methods

• setAll - Sets all leafes of the hashtree on obj to value.
• use - use a reference from the hashtree to make operations upon.
• sort - sort the hashtree.

var ht = require('./hashtree').hashTree;

var r, 
	obj = { one: { a: 1, b: 2, c: 3 } };
r = ht.setAll(obj, 'one', 0);
// => r = true 
// => obj = { one: { a: 0, b: 0, c: 0 } }

To manipulate values in the hashtree without having to constantly use get and set methods use the use method. All operations can be chained.

var ht = require('./hashtree').hashTree;

var r, obj = {};
r = ht.use(obj, 'one.a', 7) // sets the value to '7'
        .inc()              // increments by one
        .dec()              // decrements by one
        .add(10)            // add 10
        .sub(5)             // subtract 5
        .mul(200)           // multiply by 2
        .div(3)             // divide by 3
        .mod(70)            // modulo 7
        .get();             // finally get the value        
// => r = 30
// => obj = { one: { a: 30 } }

Sorting a hash tree does not make a lot of sense. It does not change anything. But for human eyes, e.g. on exporting to YAML or JSON, sorted patterns are easier to read (at least for me).

var ht = require('./hashtree').hashTree;

// sort in decending order
function descSorter(a, b) { 
    return (a > b) ? -1 : ( a == b ? 0 : 1);
}

var r, 
    obj = { 
        a: { a: 1, b: 2, c: 2 }, 
        e: { a: 1, b: 2, c: 2 }, 
        d: { a: 1, b: 2, z: 3 }
    };
// sort in decending order
r = ht.sort(obj, descSorter);
// => obj = { 
//  e: { c: 2, b: 2, a: 1 },
//  d: { z: 3, b: 2, a: 1 },
//  a: { c: 2, b: 2, a: 1 } }

Additionally two hashtrees can be compared with diff or diffToBase.

var ht = require('hashtree').hashTree;

ht.diff({one:{two:{a:1,b:2}},two:2}, {one:{two:{a:1,b:3}},two:2});
// => { diff1: {one:{two:{b:2}}}, diff2: {one:{two:{b:3}}} }

ht.diffToBase({one:{two:{a:1,b:2}},two:2}, {one:{two:{a:1,b:3}},two:2});
// => {one:{two:{b:3}}}

HashTree

All methods are offered also as a prototype function.

var HashTree = require('hashtree').HashTree;

var r;
var ht = new HashTree({ 'one': 1 }); 
ht.set('two.three', 3);

r = ht.get('two');
// => r = { three: 3 }
ht.delete('two');

ht.use('three.four').inc().add(3);

/// return the hashtree object
r = ht.tree();
// => r = { one: 1, three: { four: 4 } }

License

Copyright (c) 2014- commenthol

Software is released under MIT.