tessl/npm-traverse

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

—

Pending

Overview

Eval results

Files

Object Traversal

Name: tessl/npm-traverse
Author: tessl

Core traversal methods for iterating through object structures with callback functions. These methods visit every node in the object tree and provide rich context information for transformation and analysis.

Capabilities

forEach Method

Executes a callback function for each node in the object, modifying the original object in-place when this.update() is called.

/**
 * Execute callback for each node, modifying object in-place
 * @param {Function} callback - Function called for each node
 * @returns {*} The original object (potentially modified)
 */
traverse(obj).forEach(callback)

// Functional version
traverse.forEach(obj, callback, options)

Usage Examples:

const traverse = require('traverse');

// Transform negative numbers in-place
const obj = { a: 1, b: -2, c: [3, -4] };
traverse(obj).forEach(function (x) {
    if (typeof x === 'number' && x < 0) {
        this.update(Math.abs(x));
    }
});
// obj is now: { a: 1, b: 2, c: [3, 4] }

// Remove specific values
const data = { items: [1, null, 2, undefined, 3] };
traverse(data).forEach(function (x) {
    if (x === null || x === undefined) {
        this.remove();
    }
});

map Method

Creates a new object by executing a callback function for each node. The original object remains unchanged.

/**
 * Create new object by applying callback to each node
 * @param {Function} callback - Function called for each node
 * @returns {*} New transformed object
 */
traverse(obj).map(callback)

// Functional version  
traverse.map(obj, callback, options)

Usage Examples:

const traverse = require('traverse');

// Transform array values
const original = { numbers: [1, 2, 3], text: 'hello' };
const doubled = traverse(original).map(function (x) {
    if (typeof x === 'number') {
        return x * 2;
    }
});
// Result: { numbers: [2, 4, 6], text: 'hello' }
// original is unchanged

// Convert strings to uppercase
const result = traverse({ a: 'hello', b: { c: 'world' } }).map(function (x) {
    if (typeof x === 'string') {
        return x.toUpperCase();
    }
});

reduce Method

Performs a left-fold reduction on the object, accumulating a single value by visiting each node.

/**
 * Reduce object to single value using left-fold
 * @param {Function} callback - Reducer function (acc, node) => newAcc
 * @param {*} [initialValue] - Optional initial accumulator value
 * @returns {*} Final accumulated value
 */
traverse(obj).reduce(callback, initialValue)

// Functional version
traverse.reduce(obj, callback, initialValue)

Usage Examples:

const traverse = require('traverse');

// Sum all numbers in nested structure
const data = { a: 1, b: [2, 3], c: { d: 4, e: [5] } };
const sum = traverse(data).reduce(function (acc, x) {
    return typeof x === 'number' ? acc + x : acc;
}, 0);
// Result: 15

// Collect all string values
const obj = { name: 'Alice', details: { city: 'NYC', country: 'USA' } };
const strings = traverse(obj).reduce(function (acc, x) {
    if (typeof x === 'string') acc.push(x);
    return acc;
}, []);
// Result: ['Alice', 'NYC', 'USA']

// Count nodes by type
const counts = traverse(data).reduce(function (acc, x) {
    const type = typeof x;
    acc[type] = (acc[type] || 0) + 1;
    return acc;
}, {});

Traverse Constructor

Creates a Traverse instance that can be used to call methods. Both traverse(obj) and new traverse(obj) work identically.

/**
 * Create traverse instance for an object
 * @param {*} obj - Object to traverse
 * @param {TraverseOptions} [options] - Optional traversal options
 * @returns {Traverse} Traverse instance
 */
function traverse(obj, options)

// Constructor form (identical behavior)
new traverse(obj, options)

interface TraverseOptions {
  immutable?: boolean;      // Create immutable copies during traversal
  includeSymbols?: boolean; // Include symbol properties in traversal  
}

Usage Examples:

const traverse = require('traverse');

// Constructor approach
const t = traverse({ a: 1, b: 2 });
const result = t.map(x => typeof x === 'number' ? x * 2 : x);

// Direct approach (equivalent)
const result2 = traverse({ a: 1, b: 2 }).map(x => typeof x === 'number' ? x * 2 : x);

// With options
const t2 = traverse(obj, { includeSymbols: true, immutable: true });

Options

immutable Option

When set to true, creates immutable copies during traversal operations.

// Without immutable - may modify object during traversal
traverse(obj).forEach(function (x) { /* ... */ });

// With immutable - preserves original during internal operations
traverse(obj, { immutable: true }).forEach(function (x) { /* ... */ });

includeSymbols Option

When set to true, includes symbol properties in the traversal.

const sym = Symbol('test');
const obj = { a: 1, [sym]: 2 };

// Default - symbols ignored
traverse(obj).nodes(); // Gets: [obj, 1]

// Include symbols
traverse(obj, { includeSymbols: true }).nodes(); // Gets: [obj, 1, 2]

Install with Tessl CLI