immutable-tree v0.2.0

Immutable Tree (deprecated)

Please note, that this library is no longer under active development and its repository and npm package will get deleted eventually. If you look for a replacement, please check out immutable-treeutils.

0.2.0

This CommonJS module is written on top of Facebook's ImmutableJS and the >immutable-cursors module and provides helpers to access and traverse ImmutableJS tree data structure with a DOM-inspired interface.

It is written in ES2015, the ES5/ES3 distribution is built with Babel.

It imposes some very basic conventions on your data structure, but I tried to make everything as low-level and configurable as possible. Still, these two conditions that need to be met remain:

• A tree can have only one root node.
• Every node has to provide a unique identifier value under a key that is the same for all nodes in the tree.
• Child nodes have to be stored under a key that is the the same for all nodes containing children.

Getting started

You should feel comfortable working with cursors on ImmutableJS data structures, so if you don't I strongly recommend you to get familiar with the concepts of both ImmutableJS and >immutable-cursors first.

Install and setup

Install the package from npm:

npm install immutable-tree

Import the module and provide some state:

import Immutable from 'immutable';
import Cursor from 'immutable-tree';

let data = Immutable.fromJS({
	id: 'root',
	name: 'My Documents',
	type: 'folder'
	childNodes: [
		{
			id: 'node-1',
			name: 'Pictures',
			type: 'folder',
			childNodes: [
				{
					id: 'node-2',
					name: 'Me in Paris',
					type: 'image'
				},
				{
					id: 'node-3',
					name: 'Barbecue July 2015',
					type: 'image'
				}
			]
		},
		{
			id: 'node-4',
			name: 'Music',
			childNodes: [
				{
					id: 'node-5',
					name: 'Pink Floyd - Wish You Were Here',
					type: 'audio'
				},
				{
					id: 'node-6',
					name: 'The Doors - People Are Strange',
					type: 'audio'
				}
			]
		}
	]
});

Retrieve a root cursor using >Cursor.treeFrom:

let cursor = Cursor.from(data);
cursor.firstChild().get('name');
// 'Pictures'

Find an element by id.

cursor.getById('node-5').name()
// 'Pink Floyd - Wish You Were Here'

I will add more in-depth docs as soon as I find time to do so. The test coverage is quite ok and verbose, so to get a little more insight, it might be helpful to just run the tests and read the logs or, as usual, read the source.

Development

Get the source:

git clone https://github.com/lukasbuenger/immutable-cursors

Install dependencies:

npm install

Lint the code:

npm run lint

Run the tests:

npm test

Build ES5/ES3:

npm run build

Build the docs / README:

npm run docs

Update all local dependencies:

npm run update-dependencies

Roadmap

• API Docs
• Annotate source Flow

License

See LICENSE file.