Baobab
JavaScript & TypeScript persistent and optionally immutable data tree with cursors.
Install / Use
/learn @Yomguithereal/BaobabREADME
Baobab
Baobab is a JavaScript & TypeScript persistent and immutable (at least by default) data tree supporting cursors and enabling developers to easily navigate and monitor nested data through events.
It is mainly inspired by functional zippers (such as Clojure's ones) and by Om's cursors.
It aims at providing a centralized model holding an application's state and can be paired with React easily through mixins, higher order components, wrapper components or decorators (available there).
Fun fact: A Baobab, or Adansonia digitata, is a very big and magnificent African tree.
Summary
Example
var Baobab = require('baobab');
var tree = new Baobab({
palette: {
colors: ['yellow', 'purple'],
name: 'Glorious colors'
}
});
var colorsCursor = tree.select('palette', 'colors');
colorsCursor.on('update', function() {
console.log('Selected colors have updated!');
});
colorsCursor.push('orange');
Installation
If you want to use Baobab with node.js or browserify/webpack etc., you can use npm.
npm install baobab
# Or if you need the latest dev version
npm install git+https://github.com/Yomguithereal/baobab.git
If you want to use it in the browser, just include the minified script located here.
Note that the library comes along with its own declaration files so you can use it comfortably with TypeScript also.
<script src="baobab.min.js"></script>
Or install with bower:
bower install baobab
The library (as a standalone) currently weighs ~8kb gzipped.
Usage
Basics
Instantiation
Creating a tree is as simple as instantiating Baobab with an initial data set.
var Baobab = require('baobab');
var tree = new Baobab({hello: 'world'});
// Retrieving data from your tree
tree.get();
>>> {hello: 'world'}
Cursors
Then you can create cursors to easily access nested data in your tree and listen to changes concerning the part of the tree you selected.
// Considering the following tree
var tree = new Baobab({
palette: {
name: 'fancy',
colors: ['blue', 'yellow', 'green']
}
});
// Creating a cursor on the palette
var paletteCursor = tree.select('palette');
paletteCursor.get();
>>> {name: 'fancy', colors: ['blue', 'yellow', 'green']}
// Creating a cursor on the palette's colors
var colorsCursor = tree.select('palette', 'colors');
colorsCursor.get();
>>> ['blue', 'yellow', 'green']
// Creating a cursor on the palette's third color
var thirdColorCursor = tree.select('palette', 'colors', 2);
thirdColorCursor.get();
>>> 'green'
// Note that you can also perform subselections if needed
var colorCursor = paletteCursor.select('colors');
Updates
A baobab tree can obviously be updated. However, one has to understand that, even if you can write the tree synchronously, update events won't be, at least by default, fired until next frame.
If you really need to fire an update synchronously (typically if you store a form's state within your app's state, for instance), your remain free to use the tree.commit() method or tweak the tree's options to fit your needs.
Important: Note that the tree, being a persistent data structure, will shift the references of the objects it stores in order to enable immutable comparisons between one version of the state and another (this is especially useful when using strategies as such as React's pure rendering).
Example
var tree = new Baobab({hello: 'world'});
var initialState = tree.get();
tree.set('hello', 'monde');
// After asynchronous update...
assert(initialState !== tree.get());
- tree/cursor.set
- tree/cursor.unset
- tree/cursor.push
- tree/cursor.unshift
- tree/cursor.concat
- tree/cursor.pop
- tree/cursor.shift
- tree/cursor.splice
- tree/cursor.apply
- tree/cursor.merge
- tree/cursor.deepMerge
<h5 id="set">tree/cursor.set</h5>
Replaces value at the given key or the cursor's value altogether if no value is supplied.
It will also work if you want to replace a list's item.
// Replacing the cursor's value
var newValue = cursor.set(newValue);
// Setting a precise key
var newValue = cursor.set('key', newValue);
// Setting a nested key
var newValue = cursor.set(['one', 'two'], newValue);
var newValue = cursor.select('one', 'two').set(newValue);
var newValue = cursor.select('one').set('two', newValue);
Unsets the given key.
It will also work if you want to delete a list's item.
// Removing data at cursor
cursor.unset();
// Removing a precise key
cursor.unset('key');
// Removing a nested key
cursor.unset(['one', 'two']);
Pushes a value into the selected list. This will of course fail if the selected node is not a list.
// Pushing a value
var newList = cursor.push(newValue);
// Pushing a value in the list at key
var newList = cursor.push('key', newValue);
// Pushing into a nested path
var newList = cursor.push(['one', 'two'], newValue);
var newList = cursor.select('one', 'two').push(newValue);
var newList = cursor.select('one').push('two', 'world');
Unshifts a value into the selected list. This will of course fail if the selected node is not a list.
// Unshifting a value
var newList = cursor.unshift(newValue);
// Unshifting a value in the list at key
var newList = cursor.unshift('key', newValue);
// Unshifting into a nested path
var newList = cursor.unshift(['one', 'two'], newValue);
var newList = cursor.select('one', 'two').unshift(newValue);
var newList = cursor.select('one').unshift('two', newValue);
Concatenates a list into the selected list. This will of course fail if the selected node is not a list.
// Concatenating a list
var newList = cursor.concat(list);
// Concatenating a list in the list at key
var newList = cursor.concat('key', list);
// Concatenating into a nested path
var newList = cursor.concat(['one', 'two'], list);
var newList = cursor.select('one', 'two').concat(list);
var newList = cursor.select('one').concat('two', list);
Removes the last item of the selected list. This will of course fail if the selected node is not a list.
// Popping the list
var newList = cursor.pop();
// Popping the list at key
var newList = cursor.pop('key');
// Popping list at path
var newList = cursor.pop(['one', 'two']);
var newList = cursor.select('one', 'two').pop();
var newList = cursor.select('one').pop('two');
Removes the first item of the selected list. This will of course fail if the selected node is not a list.
// Shifting the list
var newList = cursor.shift();
// Shifting the list at key
var newList = cursor.shift('key');
// Shifting list at path
var newList = cursor.shift(['one', 'two']);
var newList = cursor.select('one', 'two').shift();
var newList = cursor.select('one').shift('two');
Splices the selected list. This will of course fail if the selected node is not a list.
The splice specifications works the same as for Array.prototype.splice.
There is one exception though: Per specification, splice deletes no values if the deleteCount argument is not parseable as a number.
The splice implementation of Baobab instead throws an error, if the given deleteCount argument could not be parsed.
// Splicing the list
var newList = cursor.splice([1, 1]);
// Omitting the deleteCount argument makes splice delete no elements.
var newList = cursor.splice([1]);
// Inserting an item etc.
var newList = cursor.splice([1, 0, 'newItem']);
var newList = cursor.splice([1, 0, 'newItem1', 'newItem2']);
// Splicing the list at key
var newList = cursor.splice('key', [1, 1]);
// Splicing list at path
var newList = cursor.splice(['one', 'two'], [1, 1]);
var newList = cursor.select('one', 'two').splice([1, 1]);
var newList = cursor.select('one').splice('two', [1, 1]);
Applies the given function to the selected value.
var inc = function(nb) {
return nb + 1;
};
// Applying the function
var newList = cursor.apply(inc);
// Applying the function at key
var newList = cursor.apply('k
