traverse

What is traverse?

The traverse npm package is a comprehensive tool for traversing and transforming JavaScript objects. It allows you to easily navigate through objects, arrays, and other nested structures, and apply functions to their elements. It's particularly useful for manipulating complex data structures, applying transformations, and extracting information in a flexible manner.

What are traverse's main functionalities?

Traversing and modifying objects

This feature allows you to traverse through an object and modify elements. In the code sample, the value 2 in the array under key 'a' is updated to 222.

var traverse = require('traverse');
var obj = { a: [1, 2, 3], b: 4 };
traverse(obj).forEach(function (x) {
    if (x === 2) this.update(222);
});

Cloning and transforming objects

This feature enables deep cloning of objects with the option to apply transformations during the cloning process. In the example, all numbers in the object are multiplied by 100.

var traverse = require('traverse');
var obj = { a: 1, b: [2, 3] };
var clone = traverse(obj).map(function (node) {
    if (typeof node === 'number') this.update(node * 100);
});

Extracting specific elements

This feature is useful for extracting leaf nodes from a complex object structure. The code sample demonstrates how to collect all leaf nodes (elements without child nodes) into an array.

var traverse = require('traverse');
var obj = { a: 1, b: { c: 2, d: [3, 4] } };
var leaves = traverse(obj).reduce(function (acc, x) {
    if (this.isLeaf) acc.push(x);
    return acc;
}, []);

Other packages similar to traverse

lodash

Lodash is a utility library that provides functions for common programming tasks, including object manipulation. While it offers some similar functionalities for traversing and manipulating objects, it's more general-purpose compared to traverse, which is specifically designed for deep traversal and transformation of objects.

ramda

Ramda is a functional programming library that emphasizes immutability and side-effect free functions. It includes utilities for working with objects in a functional manner. Compared to traverse, Ramda offers a broader set of functional programming tools but might require more setup for deep object traversal and transformation tasks.

README

traverse

Traverse and transform objects by visiting every node on a recursive walk.

examples

transform negative numbers in-place

negative.js

var traverse = require('traverse');
var obj = [ 5, 6, -3, [ 7, 8, -2, 1 ], { f : 10, g : -13 } ];

traverse(obj).forEach(function (x) {
    if (x < 0) this.update(x + 128);
});

console.dir(obj);

Output:

[ 5, 6, 125, [ 7, 8, 126, 1 ], { f: 10, g: 115 } ]

collect leaf nodes

leaves.js

var traverse = require('traverse');

var obj = {
    a : [1,2,3],
    b : 4,
    c : [5,6],
    d : { e : [7,8], f : 9 },
};

var leaves = traverse(obj).reduce(function (acc, x) {
    if (this.isLeaf) acc.push(x);
    return acc;
}, []);

console.dir(leaves);

Output:

[ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

context

Each method that takes a callback has a context (its this object) with these attributes:

this.node

The present node on the recursive walk

this.path

An array of string keys from the root to the present node

this.parent

The context of the node's parent. This is undefined for the root node.

this.key

The name of the key of the present node in its parent. This is undefined for the root node.

this.isRoot, this.notRoot

Whether the present node is the root node

this.isLeaf, this.notLeaf

Whether or not the present node is a leaf node (has no children)

this.level

Depth of the node within the traversal

this.circular

If the node equals one of its parents, the circular attribute is set to the context of that parent and the traversal progresses no deeper.

this.update(value)

Set a new value for the present node.

this.remove()

Remove the current element from the output. If the node is in an Array it will be spliced off. Otherwise it will be deleted from its parent.

this.delete()

Delete the current element from its parent in the output. Calls delete even on Arrays.

this.before(fn)

Call this function before any of the children are traversed.

this.after(fn)

Call this function after any of the children are traversed.

this.pre(fn)

Call this function before each of the children are traversed.

this.post(fn)

Call this function after each of the children are traversed.

methods

.map(fn)

Execute fn for each node in the object and return a new object with the results of the walk. To update nodes in the result use this.update(value).

.forEach(fn)

Execute fn for each node in the object but unlike .map(), when this.update() is called it updates the object in-place.

.reduce(fn, acc)

For each node in the object, perform a left-fold with the return value of fn(acc, node).

If acc isn't specified, acc is set to the root object for the first step and the root element is skipped.

.deepEqual(obj)

Returns a boolean, whether the instance value is equal to the supplied object along a deep traversal using some opinionated choices.

Some notes:

• RegExps are equal if their .toString()s match, but not functions since functions can close over different variables.

• Date instances are compared using .getTime() just like assert.deepEqual().

• Circular references must refer to the same paths within the data structure for both objects. For instance, in this snippet:

var a = [1];
a.push(a); // a = [ 1, *a ]

var b = [1];
b.push(a); // b = [ 1, [ 1, *a ] ]

a is not the same as b since even though the expansion is the same, the circular references in each refer to different paths into the data structure.

However, in:

var c = [1];
c.push(c); // c = [ 1, *c ];

c is equal to a in a deepEqual() because they have the same terminal node structure.

• Arguments objects are not arrays and neither are they the same as regular objects.

• Instances created with new of String, Boolean, and Number types are never equal to the native versions.

.paths()

Return an Array of every possible non-cyclic path in the object. Paths are Arrays of string keys.

.nodes()

Return an Array of every node in the object.

.clone()

Create a deep clone of the object.

installation

Using npm: npm install traverse

Or check out the repository and link your development copy: git clone http://github.com/substack/js-traverse.git cd js-traverse npm link .

You can test traverse with "expresso":http://github.com/visionmedia/expresso (npm install expresso): js-traverse $ expresso

100% wahoo, your stuff is not broken!

hash transforms

This library formerly had a hash transformation component. It has been moved to the hashish package.