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

Typedefs

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 string 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 |