README

Traversal map

Iterate through all elements in a object or array calling a callback function.

Features

Blazing fast
Types out of the box
No dependencies
Tiny

Installation Using npm

npm install traversal-map

Example Usage

import traversalMap from 'traversal-map';

const data = {
  a: 1,
  b: 2,
  c:  {
    d: 3,
    e: [ 'a', 'b', 'c' ]
  }
};

traversalMap(data, (value: any, keyOrIndex: string | number, path: string) => {
  console.log(`${value} / ${keyOrIndex} / ${path}`);
});

/*
  1 / a / a
  2 / b / b
  [object Object] / c / c
  3 / d / c.d
  a.b.c / e / c.e
  a / 0 / c.e[0]
  b / 1 / c.e[1]
  c / 2 / c.e[2]
*/

Api

  traversalMap(target, callbackFn, options?);

Parameter	Type	Description
target	Object or Array or ArrayLike*	The object which will be traversed
callbackFn	(value: any, keyOrIndex?: string or number, path?: string) => any	- value: Value of the current position. - keyOrIndex `optional`: Identifier of the current position, key for object and index for arrays. - path `optional`: Path to the current position.
options?	useDotNotationOnKeys: boolean	Default true. When set to false insted of this: `a.b.c` You will get `['a']['b']['c']`

? = Optional paramter.

* = ArrayLike is an object whitch is neither null nor a function (Definition of function in ./util/typeCheckers/isFunction) and it has a lenght property of type number.

Flow Control

You can modify the flow of the iteration returning special numbers:

10: Break the iteration at the current depth skyping remaining sibling elements.

11: Break the iteration.

20: Skip child elements of the current element.

Testing

npm run test            // Run tests once
npm run test-with-cover // Run tests once and get coverage information
npm run test-watch      // Tests in watch mode

Debugging:

If you want to debug then code, putting you have to launch Debug Jest Tests from vscode. You can uncoment the debug test in ./src/index.test.ts if you don't know where to start. If the breakpoints aren't hit try putting a debugger on the test first and once it gets hit you can start debuggin the code.

About

I needed to iterate over a deeply nested object and gather the path to each property, so I looked around and found for-each-safe. I liked the idea so I clonned, migrated it to Typescript, added tests and made it faster and smaller (mine is less safe than the original as it checks for less edgy cases, but for my purpose and the majority of people out there, is more than enough).

Usage no npm install needed!