Skip to content

rubeniskov/traverse-json

Folders and files

NameName
Last commit message
Last commit date

Latest commit

5dbe590 · Dec 4, 2020

History

35 Commits
Dec 4, 2020
Nov 23, 2020
Nov 23, 2020
Nov 23, 2020
Dec 4, 2020
Dec 4, 2020
Dec 4, 2020
Dec 4, 2020
Nov 27, 2020
Dec 4, 2020
Dec 1, 2020
Dec 1, 2020

Repository files navigation

traverse-json

unit-testing npm-publish npm-downloads codecov patreon-donate github-sponsor paypal-sponsor

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
TraverseIteratorTraverseIteratorResult

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

{}

[ '/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