tree-tools v1.4.4

Tree-Tools

Tools to manage deeply nested collection tree structures.

See the API reference for a full list of functionality.

Goals:

• Provide a simple API to manipulate and operate on tree structures
• Closely mirror Lodash's API wherever possible to minimize confusion
• No dependencies (except Lodash)

Install (NodeJS)

Install via

npm install tree-tools

Then just use as

var treeTools = require('tree-tools');

treeTools.flatten(treeTools.find(tree, {path: '/bar/baz'}));

Install (AngularJS)

1. Include dist/ngTreeTools.js somewhere in your build chain
2. Add ngTreeTools as a module in your main angular.module('app', [modules]) list
3. Require the module as TreeTools in your controller e.g. app.controller('myController', function($scope, TreeTools) { // Controller // })

API

In all the examples below the example tree structure is similar to the main test case.

treeTools.find(tree, query, options)

Find a single node deeply within a tree structure. Query can be any valid Lodash matching object or a function.

treeTools.find(tree, {path: '/bar/baz'});

Since this function is really just a convenience wrapper around parents() see that function definition for available options.

treeTools.filter(tree, query, options)

Return a copy of a tree while filtering nodes. Query can be any valid Lodash matching object or a function.

treeTools.find(tree, (node, index) => matchingExpression);

Options are:

treeTools.flatten(tree)

Return all branches of a tree as a flat array. The array is returned as a shallow copy, allowing mutation via forEach or map iterators.

treeTools.flatten(treeTools.find(tree, {path: '/bar/baz'}));

Options are:

treeTools.parents(tree, query, options)

Utility function to deep search a tree structure for a matching query and find parents up to the given query. If found this function will return an array of all generations with the found branch as the last element of the array.

treeTools.parents(tree, {path: '/bar/baz'})

Options are:

treeTools.children(tree, query, options)

Utility function to deep search a tree structure for a matching query and find all children after the given query. If found this function will return an array of all child elements NOT including the query element.

treeTools.children(tree, {path: '/foo'});

Options are:

treeTools.hasChildren(branch, options)

Utility function to determines whether a given node has children.

treeTools.hasChildren(someBranch); // Returns a boolean

Options are:

treeTools.hasSome(tree, query)

Utility function to determine if an item matching query exists deep within a given tree.

treeTools.hasSome(tree, {someKey: someValue});
treeTools.hasSome(tree, (v, k) => { ... });

treeTools.resolve(tree, options)

Recursively walk a tree evaluating all functions (promise compatible) and inserting their values. Should a node return a promise it will be waited on before evaluating it along with its children, recursively.

treeTools.resolve(complexTreeWithPromises)
	.then(tree => {...})

Options are:

treeTools.sortBy(tree, propertyName)

Utility function to sort tree by specific property or an array of properties. propertyName can be a string or an array of strings.

// Sort an outer array of families with all children in `name` order
treeTools.sortBy(families, 'name');