README.md

traverse-json

A complete traverse json function with iterable interface.

Motivation

Many time I've encontered with the difficult task of traverse a object with nested properties by filtering some of them using a single function, so a traverse-json solves this using multiple options for traversing.

Mutation

For mutation this library is part of mutant-json which wraps this traverse-json to take the advantages of filtering options.

Installation

Npm:

npm install traverse-json --save

Yarn:

yarn add traverse-json

Functions

traverseJson(obj, [opts]) ⇒ TraverseIterator

Creates a function which traverses an object by its keys and values recursively, returning the iterator result with the full path and its value.

By default options will be parsed as { test: opts } if non object detected

createIterator(obj, [opts]) ⇒ Iterable

Returns a traverseJson iterable, usefull for use it in a for loop.

Typedefs

TraverseJsonOptions : Object

TraverseJsonEntry : Array.<String, any>

TraverseIteratorResult : Object

TraverseIterator ⇒ TraverseIteratorResult

Function iterator, see examples

traverseJson(obj, [opts]) ⇒ TraverseIterator

Creates a function which traverses an object by its keys and values recursively, returning the iterator result with the full path and its value.

By default options will be parsed as { test: opts } if non object detected

Kind: global function

Param	Type
obj	Object
[opts]	String | TraverseJsonOptions

Example

const traverseJson = require('traverse-json');

const options = {...};

const iterator = traverseJson({
  foo: 0,
  nested: {
    depth: 1,
    nested: {
      depth: 2,
      nested: {
        depth: 3,
        nested: {
          depth: 4,
        },
      },
    },
  },
  bar: 1,
}, options);

for (;;) {
  const { done, value } = iterator();
  if (done)
     break;
   console.log(value);
}

Outputs

Default options

{}

[ '/foo', 0 ]
[ '/nested/depth', 1 ]
[ '/nested/nested/depth', 2 ]
[ '/nested/nested/nested/depth', 3 ]
[ '/nested/nested/nested/nested/depth', 4 ]
[ '/bar', 1 ]

Return eather the nested and flatten values

{ nested: true }

[ '/foo', 0 ]
[ '/nested',
  { depth: 1, nested: { depth: 2, nested: [Object] } } ]
[ '/nested/depth', 1 ]
[ '/nested/nested',
  { depth: 2, nested: { depth: 3, nested: [Object] } } ]
[ '/nested/nested/depth', 2 ]
[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]
[ '/nested/nested/nested/depth', 3 ]
[ '/nested/nested/nested/nested', { depth: 4 } ]
[ '/nested/nested/nested/nested/depth', 4 ]
[ '/bar', 1 ]

Only traverse on depth 1

{ recursive: false }

[ '/foo', 0 ]
[ '/nested',
  { depth: 1, nested: { depth: 2, nested: [Object] } } ]
[ '/bar', 1 ]

Skips even entries

{ step: 2 }

[ '/foo', 0 ]
[ '/bar', 1 ]

Match only the paths ending with depth

{ test: /depth$/ }

[ '/nested/depth', 1 ]
[ '/nested/nested/depth', 2 ]
[ '/nested/nested/nested/depth', 3 ]
[ '/nested/nested/nested/nested/depth', 4 ]

Return eather the nested and flatten values ending with nested

{ test: /nested$/, nested: true }

[ '/nested',
  { depth: 1, nested: { depth: 2, nested: [Object] } } ]
[ '/nested/nested',
  { depth: 2, nested: { depth: 3, nested: [Object] } } ]
[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]
[ '/nested/nested/nested/nested', { depth: 4 } ]

Match only the paths ending with foo or depth

{ test: "**/{depth,foo}" }

[ '/foo', 0 ]
[ '/nested/depth', 1 ]
[ '/nested/nested/depth', 2 ]
[ '/nested/nested/nested/depth', 3 ]
[ '/nested/nested/nested/nested/depth', 4 ]

Match entries which has a number value equal or greater than 3

{ test: ([,value]) => typeof value === 'number' && value >= 3 }

[ '/nested/nested/nested/depth', 3 ]
[ '/nested/nested/nested/nested/depth', 4 ]

Traverse recursively through the same key

{ test: "@nested" }

[ '/nested',
  { depth: 1, nested: { depth: 2, nested: [Object] } } ]
[ '/nested/nested',
  { depth: 2, nested: { depth: 3, nested: [Object] } } ]
[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]
[ '/nested/nested/nested/nested', { depth: 4 } ]

createIterator(obj, [opts]) ⇒ Iterable

Returns a traverseJson iterable, usefull for use it in a for loop.

Kind: global function

Param	Type
obj	Object
[opts]	TraverseJsonOptions

Example

const { createIterator } = require('traverse-json');
const options = {...}
const ientries = createIterator({
  foo: 0,
  nested: {
    depth: 1,
    nested: {
      depth: 2,
       nested: {
         depth: 3,
         nested: {
           depth: 4,
         },
       },
     },
   },
  bar: 1,
}, options);

for (let [k, v] of ientries) {
  console.log(k, v);
}

Output

/foo 0
/nested/depth 1
/nested/nested/depth 2
/nested/nested/nested/depth 3
/nested/nested/nested/nested/depth 4
/bar 1

TraverseJsonOptions : Object

Kind: global typedef
Properties

Name	Type	Default	Description
[opts.recursive]	Boolean	true	enable/disable nested arrays and objects recursion
[opts.nested]	Boolean	false	also emit nested array or objects
[opts.step]	Boolean	1	the step to increment, default 1
[opts.test]	String | function | RegeExp	false	regexp, string minimatch or function to filter properties

TraverseJsonEntry : Array.<String, any>

Kind: global typedef
Properties

Name	Type	Description
0	string	Object JSONPointer
1	any	Value

TraverseIteratorResult : Object

Kind: global typedef
Properties

Name	Type	Description
value	TraverseJsonEntry	key value pair with the key as a full path of the property following the json standard path format
done	Boolean

TraverseIterator ⇒ TraverseIteratorResult

Function iterator, see examples

Kind: global typedef

Param	Description
extra	a object or array to extends the current iteration