Registry / serialization / object-traversal

object-traversal

library1.0.1jsnpmunverified

The `object-traversal` package provides a flexible and highly performant utility for depth-first or breadth-first traversal of JavaScript objects. Currently at stable version 1.0.1, the library maintains an active release cadence, with recent updates fixing minor issues after a major breaking change. Its key differentiators include exceptional speed, claiming to traverse over 20 million nodes per second and being approximately 10 times faster than popular alternatives, along with extensive configurability options for traversal order, maximum depth, and cycle handling. The library is lightweight with zero external dependencies, making it suitable for both Node.js (>=10) and browser environments, and it ships with full TypeScript support, providing robust type definitions for callbacks and options.

serialization

npm install object-traversal

github ↗package ↗

INSTALL

IMPORT

SIG · OBJECT-TRAVERSAL

object-traversal

serializationjavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

traverse

✓ import { traverse } from 'object-traversal';

✗ const { traverse } = require('object-traversal');

Primary named export for the traversal function. ESM is preferred, but CommonJS `require` is also supported.

TraversalCallback

✓ import type { TraversalCallback } from 'object-traversal';

TypeScript type definition for the callback function signature.

TraversalCallbackContext

✓ import type { TraversalCallbackContext } from 'object-traversal';

TypeScript type definition for the context object passed to the callback function.

Demonstrates how to use `traverse` to modify an object in-place by doubling all numeric values and finding a specific node while halting traversal early.

import { traverse, TraversalCallbackContext } from 'object-traversal'; const exampleObject = { name: 'Hello World!', age: 1, accounts: 2, friends: 3, nested: { value: 10, list: [1, 2, { deep: 5 }], }, arr: [{ num: 42 }], }; function doubleNumbers({ parent, key, value, meta }: TraversalCallbackContext) { // `parent` and `key` are null for the root object. // Only modify if we are inside an object/array property. if (parent && key && typeof value === 'number') { parent[key] = value * 2; console.log(`Doubled ${meta.nodePath}: ${value} -> ${parent[key]}`); } } console.log('Original object:', JSON.stringify(exampleObject, null, 2)); // Perform in-place modification traverse(exampleObject, doubleNumbers, { traversalType: 'depth-first', // Explicitly set for clarity (default is 'depth-first') pathSeparator: '/', // Use a different separator for demonstration }); console.log('\nModified object:', JSON.stringify(exampleObject, null, 2)); // Example of finding a node and halting traversal let foundNodePath: string | null = null; traverse(exampleObject, ({ value, meta }) => { if (value === 84) { // Searching for the doubled value of 42 foundNodePath = meta.nodePath; return true; // Halt traversal once found } }, { haltOnTruthy: true }); console.log(`\nFound value 84 at path: ${foundNodePath}`);

Debug

Known issues

breakingThe property `meta.currentPath` within the `TraversalCallbackContext` was renamed to `meta.nodePath` in version 1.0.0.

fix

Update all callback function implementations to reference `meta.nodePath` instead of `meta.currentPath`.

affects: >=1.0.0

gotchaBy default, `cycleHandling` is enabled (`true`) to prevent infinite loops when traversing objects with circular references. Disabling it (`false`) will allow re-visiting nodes but requires manual cycle detection or guarantees of acyclic graphs.

fix

If re-visiting nodes is essential and you can manage cycles, set `cycleHandling: false` in `TraversalOpts`. Otherwise, rely on the default to avoid infinite loops.

affects: >=0.1.0

gotchaThe `haltOnTruthy` option, when `true`, will stop traversal as soon as the callback function returns a truthy value. This is powerful for searches but can lead to incomplete traversals if not intended.

fix

If a full traversal is always required, ensure `haltOnTruthy` is explicitly set to `false` in `TraversalOpts`. When searching, return `true` from the callback to optimize performance by halting early.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot set properties of null (setting 'key')

Attempting to assign to `parent[key]` when `parent` or `key` is `null`, which occurs when the callback is invoked for the root object itself.

fix

Add a check within the callback function to ensure `parent` and `key` are not `null` before attempting to modify `parent[key]`. For example: `if (parent && key && typeof value === 'number') { parent[key] = value * 2; }`.

ReferenceError: traverse is not defined

The `traverse` function was not correctly imported or accessed from the package.

fix

For ESM, use `import { traverse } from 'object-traversal';`. For CommonJS in Node.js, use `const { traverse } = require('object-traversal');`. Ensure your project's module resolution is correctly configured.

Property 'currentPath' does not exist on type '{ nodePath?: string | null; ... }'

Attempting to access `meta.currentPath` within the callback context after upgrading to version 1.0.0, which renamed the property.

fix

Update your code to use the new property name `meta.nodePath` instead of `meta.currentPath`.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/DevimalPlanet/object-traversal ↗

packagehttps://www.npmjs.com/package/object-traversal ↗