key-tree 🔑🌲

Simple keyed tree data structure
831 bytes gzipped

Usage

A tree where each node has a string as a key, and an array of values. Nodes can simply be refered by their qualified path. Nodes at any level can easily be accessed/mutated using their key path.

const tree = new KeyTree();
tree.add('cars', ['toyota', 'bmw', 'honda', 'ford']);
tree.add('cars.models.colors', ['red', 'green', 'blue']);
tree.add('cars.models', ['sedan', 'suv']);

You can get specific values at the node or all the values under the node (all children).

tree.get('cars.models'); // ['sedan', 'suv']
tree.getSub('cars.models'); // ['sedan', 'suv', 'red', 'green', 'blue']

Or get all the values of the node and all parent nodes

tree.get('cars.models'); // ['sedan', 'suv']
tree.getSup('cars.models'); // ['sedan', 'suv', 'toyota', 'bmw', 'honda', 'ford']

Example use case

I recently used this to map a set of observer callbacks. So if a.b.c is modified then invoke the appropriate callbacks. But if a.b is modified, invoke callbacks associated with a.b, a.b.c, a.b.d.

Install

Download the latest from dist folder

or from npm:

npm install --save key-tree

API

This defines a KeyTree class

constructor([options, values])

Basic tree

const tree = new KeyTree();

options is an optional argument that can be used to define a custom delimiter for key paths. Default is '.'

const tree = new KeyTree({ separator: '|' });
tree.add('cars|models', 'sedan');

values is an optional argument to seed the tree

let tree = new KeyTree(null, {
  'cars': ['toyota', 'bmw', 'honda', 'merc'],
  'animals': 'dogs',
  'cars.models': ['sedan', 'suv']
})

add(keyPath, value)

Add value(s) to the node at the specified keyPath. value can be a single object or an array of objects.

tree.add('cars.models', 'sedan');
tree.add('cars.models', ['suv', 'atv'];

get(keyPath)

Returns an array of values at the specified keyPath. An empty array is returned if there are no values.

getSub(keyPath [, grouped])

Returns all the values at the specified key path and the values of all the children of that node. By default, the result is a combined array.

if grouped is specified and is set to true, the result is an object grouped by various key paths.

getSup(keyPath [, grouped])

Returns all the values at the specified key path and the values of all its parent nodes up to the root. By default, the result is a combined array.

if grouped is specified and is set to true, the result is an object grouped by various key paths.

remove(keyPath, value)

Removes the specified value from the specified keyPath. Returns true if value existed and was removed.

removeKey(keyPath)

Removes the node at the specified keyPath and all its children. Returns true if there was a node at the path

removeChildren(keyPath)

Remove all the children of a node.

clearKey(keyPath [, clearChildren])

Clear all the values associated with the specified node. Optionally, if clearChildren is set to true, all the children values are also cleared.

License

MIT License (c) Preet Shihn

pshihn/key-tree