Tree-surgeon NPM

node-tree-surgeon

Tools for editing tree structures using a relational model.

General purpose:

Trees are represented internally with two sets: (relational structure)

Relations: [{"Parent":id, "Child":id, "Kind":any, ...}, ...]
Nodes: [{... your data ... }, ...]

Functions given to split a POJO into this structure, and merge the structure into a POJO.

Names of object tree parts, as used below:

{ // this object is the parent, it has one property "I" = "am parent"

    "I" : "am parent", // properties (whose values are not objects) remain
                       //   on the containing object.

    "Kind" : // properties (whose values are objects) become relationships.
             // The key becomes the kind of the relation.
    {
        // this object is the child
        "Property" : "Value"
    }
}

Properties with array values are treated one of two ways:

{
    "JustAProperty" : ["hello", 1,2,3], // first element is NOT an object.
                                        // Entire array is a single value,
                                        //   one of the parent's properties
    "OneToMany" : [
        {"child":1}, // First element is an object. All elements are
                     //   considered children of the parent. Kind is 'OneToMany'
        {"child":2}  // There is no way to express many-to-one, and
                     //   putting this in the relational structure is not supported.
    ]
}

Operations on POJO structure:

Assuming var tree = require('tree-surgeon');

Input

decompose -- turn a normal js object tree into the relational structure

`tree.decompose(obj, excludedKinds, relationDecorator, useEmptyRelations);`
- `obj` The object to be decomposed for relational operations. This should be a simple object, as returned by `JSON.parse`
- `excludedKinds` An array of property names. These properties and their sub-trees will not be decomposed
- `relationDecorator` A function to read node as they are decomposed and inject data into the relations table. This data can be used in subsequent operations.
- `useEmptyRelations` Bool, default false. If `true`, empty arrays will be treated as object nodes with no children.

Returns a relational structure.

Operations on the relational structure:

Assuming

    var tree = require('tree-surgeon');
    var relational = tree.decompose(my_object);

Output

compose -- convert a relational structure back into a plain object. Any manipulations of the relational structure will take effect.
```
`relational.compose()` or `tree.compose(relational)`

This is the fastest output function.
```
render -- pass each node through a function, and each kind name through a function and compose tree from the results. Manipulations of the relational structure will take effect, and both property names and object contents can be manipulated during output.
```
`relational.render(renderNodeFunc, renderKindFunc)`
- `renderNodeFunc` function that takes (node, path, id) and returns the rendered object contents
- `renderKindFunc` function that takes (kind, path) and returns the output property name
```

harvest -- return an object of composed sub-trees by kind, keyed by a parent node value

`relational.harvest(kind, idSelector)`
- `kind` the target property names to extract
- `idSelector` a function that takes the object nodes and returns a unique new property name

gather -- return an array of sub-trees

gatherByKind -- subtrees selected by property name

`relational.gatherByKind(kind)`
- `kind` the target property names to extract

gatherByNode -- subtrees selected by a function

`relational.gatherByNode(selector)`
- `selector` function that takes a node and returns `bool`. The subtrees of node that result in `true` will be returned.

Navigation

parentIdOf -- get parent ID from child ID, or null if not found

`relational.parentIdOf(childId)`
- `childId` the ID of a node
returns the parent ID, or `null` if this was the root node

getChildrenOf -- get an array of node IDs for the given parent ID

`relational.getChildrenOf(parentId)`
- `parentId` the ID of a node
returns an array of all child nodes' IDs. Returns empty array if a leaf node was passed.

getChildrenByKindOf - get an array of child node IDs for a given parent where the child is a specified type. Kind can be a string, or a where predicate on the relationship (an object with exact value matches)

`relational.getChildrenByKindOf(parentId, kind)`
- `parentId` the ID of a node
- `kind` selector for the children to be included
   - string: pick children with a matching property name
   - object: pick children whose relation object matches properties on the selector object
   - function: given the relation object, pick where the function returns `true`

getNode -- return the node data for a given ID

`relational.getNode(id)`
- `id` the ID of a node

getPathOf -- give the Kind path for a given node ID

`relational.getPathOf(nodeId)`
- `nodeId` the ID of a node

forEachByKind -- given a Kind execute the supplied function for all nodes of that kind. Kind can be a string, or a where predicate

`relational.forEachByKind(kind, actionFunc)`
- `kind` selector for the children to be included
   - string: pick children with a matching property name
   - object: pick children whose relation object matches properties on the selector object
   - function: given the relation object, pick where the function returns `true`
- `actionFunc` function of `(node, id)` to execute for each matching node. Any return is ignored. Any changes made to the node data is retained.

Manipulation

Normalise -- removes any relationships or nodes that are not reachable from the root, but keeps node and relation indexes consistent.
```
`relational.normalise()`
```
prune -- remove subtrees by relationship kind. Kind can be a string, or a where predicate on the relationship (an object with exact value matches)
```
`relational.prune(kind)`
- `kind` property name or relation match to remove.
```
- pruneAfter -- remove subtrees by relationship kind, but keep the immediate children. Kind can be a string, or a where predicate
```
`relational.pruneAfter(kind)`
- `kind` property name or relation match. The children of matches will be removed
```
- pruneAllBut -- remove subtrees that don't match a set of kinds. Supports only array of string kinds.
```
`relational.pruneAllBut(kind)`
- `kind` property name or relation match. All non-matching relations will be removed
```

chop -- remove subtrees by data predicate

`relational.chop(filterFunc)`
- `filterFunc` function of `(node, id)`. If this returns a truthy value, node will be removed, else node will be kept

chopAfter -- remove subtrees by data predicate, but keep the matched children

`relational.chopAfter(filterFunc)`
- `filterFunc` function of `(node, id)`. If this returns a truthy value, all children of the matched node will be removed

chopByKind -- remove subtrees of a specified 'kind' by data predicate. Kind can be a string, or a where predicate

`relational.chopByKind(kind, filterFunc)`
- `kind` property name or relation match. Matched nodes will be included in the filter
- `filterFunc` function of `(node, id)`. If this returns a truthy value, node will be removed, else node will be kept

chopChildless -- remove nodes which have no children (ie. leaves) by data predicate

`relational.chopChildless(filterFunc)`
- `filterFunc` function of `(node, id)`. All leaf nodes will be passed to this function. If this returns a truthy value, node will be removed.

chopNodesByIds -- remove nodes and their subtrees by their IDs

`relational.chopNodesByIds(ids)`
- `ids` an array of node ids. All these nodes and their subtrees will be removed.

MergeUp -- remove a relationship and one node by merging data from child to parent. Subtree remains
- mergeUpByKind -- select merge targets by relationship kind. Kind can be a string or a where predicate
```
`relational.mergeUpByKind(kind)`
- `kind` target property or relation match. Matching nodes will be merged into their parents
```
- mergeUpByNode -- select merge targets by applying a predicate to nodes
```
`relational.mergeUpByNode(predFunc)`
- `predFunc` function to select nodes. Matching nodes will be merged into their parents
```

MergeDown -- remove a relationship and one node by merging data from parent to child. Subtree remains

mergeDownByKind -- select merge targets by relationship kind. Kind can be a string or a where predicate

`relational.mergeDownByKind(kind)`
- `kind` target property or relation match. Matching nodes' data will be copied into their parents, then the matching node removed.

mergeDownByNode -- select merge targets by applying a predicate to nodes

`relational.mergeUpByNode(predFunc)`
- `predFunc` function to select nodes. Matching nodes' data will be copied into their parents, then the matching node removed.

Fuse -- remove a node by merging into it's parent and child (by supplied function). This is a generalisation of merge up/down.

fuseByNode -- remove a node picked by a predicate on that node

`relational.fuseByNode(nodeFunc, pickForParentFunc, pickForChildFunc)`
- `nodeFunc` function to pick nodes to fuse
- `pickForParentFunc` function that is given node data, and returns the data to copy into the parent node
- `pickForChildFunc` function that is given node data, and returns the data to copy into the child node.

fuseByKind -- remove a node picked by kind. Kind can be a string or a where predicate

`relational.fuseByKind(kind, pickForParentFunc, pickForChildFunc)`
- `kind` target property or relation match. Matching nodes will be removed, but sub-trees will remain
- `pickForParentFunc` function that is given node data, and returns the data to copy into the parent node
- `pickForChildFunc` function that is given node data, and returns the data to copy into the child node.

flipRelationship -- given a parent kind, a child kind, and an equality function for children; swap parents⇔children, grouping children by equality. The new child kind can be a string or a where predicate, but the new parent kind can only be a string.

`relational.flipRelationship(newChildKind, newParentKind, newParentHashFunc)`
- `newChildKind` property name that is currently the parent node, and should be flipped to being a parent
- `newParentKind` property name that is currently the child node, and should be flipped to being a child
- `newParentHashFunc` function that takes a node and returns a comparable value (preferable a number)

reverseByRelation -- make children into parents and parents into children. This is a more complex and powerful version of flipRelationship. Have a look in the test cases for examples.
reduce -- reduce objects to a single value from inside them, by kind or node predicate ({a:[{x:1},{x:2}]} -> {a:[1,2]})
editByKind -- given a kind name and an editor function, change all immediate children of that kind. Kind can be a string or a where predicate
removeEmptyNodes -- recursively remove nodes which contain only null or undefined. This can remove entire subtrees that contain only empty children

Unimplemented

graft -- insert new subtrees
disconnect -- the opposite of Fuse, place a new node between a parent and child
fork -- move some of the values of a node into a new or existing sibling
move -- move some of the values of a node into an existing sibling, or do nothing
editPath -- given a path of kinds and a func node→node, replace data at those paths
fuseAway -- remove a node by connecting it's parents to it's children, losing the data in the selected nodes
fuseAwayByNode
fuseAwayByKind

Note:

To run istanbul on Windows, use istanbul cover C:\Users\[username]\AppData\Roaming\npm\node_modules\mocha\bin\_mocha -- -R spec

Todo:

optimisations
a good way to find subtrees based on paths, and perform operations based on results
bring .d.ts file up-to-date with available features
syntax should allow chaining of functions
extend with kind and predicate functions
some way of mutating kind when fusing/merging?