Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rubeniskov/traverse-json

A complete traverse json function with iterable interface.
https://github.com/rubeniskov/traverse-json

depth function-iterator iterable iterable-returns iterator javascript json jsonpath minimatch nodejs standard traverse traverse-json

Last synced: 13 days ago
JSON representation

A complete traverse json function with iterable interface.

Host: GitHub
URL: https://github.com/rubeniskov/traverse-json
Owner: rubeniskov
License: mit
Created: 2020-11-23T13:29:04.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2020-12-04T01:26:20.000Z (about 4 years ago)
Last Synced: 2024-12-14T23:41:44.797Z (about 1 month ago)
Topics: depth, function-iterator, iterable, iterable-returns, iterator, javascript, json, jsonpath, minimatch, nodejs, standard, traverse, traverse-json
Language: JavaScript
Homepage: http://rubeniskov.com/blog/en/traverse-json-like-a-king
Size: 82 KB
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # traverse-json

[![unit-testing](https://github.com/rubeniskov/traverse-json/workflows/unit-testing/badge.svg)](https://github.com/rubeniskov/traverse-json/actions?query=workflow%3Aunit-testing)

[![npm-publish](https://github.com/rubeniskov/traverse-json/workflows/npm-publish/badge.svg)](https://github.com/rubeniskov/traverse-json/actions?query=workflow%3Anpm-publish)

[![npm-downloads](https://img.shields.io/npm/dw/traverse-json)](https://www.npmjs.com/package/traverse-json)

[![codecov](https://codecov.io/gh/rubeniskov/traverse-json/branch/master/graph/badge.svg?token=mI2c282XxH)](https://codecov.io/gh/rubeniskov/traverse-json)

[![patreon-donate](https://img.shields.io/badge/patreon-donate-yellow.svg)](https://patreon.com/rubeniskov)

[![github-sponsor](https://img.shields.io/badge/github-donate-yellow.svg)](https://github.com/sponsors/rubeniskov)

[![paypal-sponsor](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://paypal.me/rubeniskov)

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](https://github.com/rubeniskov/mutant-json) which wraps this `traverse-json` to take the advantages of filtering options.

## Installation

### Npm:

```shell

npm install traverse-json --save

```

### Yarn:

```shell

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](#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](#TraverseJsonOptions) | 

**Example**  

```javascript

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](#traversejsonoptions--object)

__{}__

```

[ '/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](#traversejsonoptions--object): 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](#traversejsonoptions--object): false }__

```

[ '/foo', 0 ]

[ '/nested',

  { depth: 1, nested: { depth: 2, nested: [Object] } } ]

[ '/bar', 1 ]

```

### Skips even entries

__{ [step](#traversejsonoptions--object): 2 }__

```

[ '/foo', 0 ]

[ '/bar', 1 ]

```

### Match only the paths ending with _depth_

__{ [test](#traversejsonoptions--object): /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](#traversejsonoptions--object): /nested$/, [nested](#traversejsonoptions--object): 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](#traversejsonoptions--object): "**/{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](#traversejsonoptions--object): ([,value]) => typeof value === 'number' && value >= 3 }__

```

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

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

```

### Traverse recursively through the same key

__{ [test](#traversejsonoptions--object): "@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](#TraverseJsonOptions) | 

**Example**  

```javascript

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](https://www.npmjs.com/package/minimatch) or function to filter properties |



## TraverseJsonEntry : Array.<String, any>

**Kind**: global typedef  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| 0 | string | Object [JSONPointer](https://tools.ietf.org/html/rfc6901) |

| 1 | any | Value |



## TraverseIteratorResult : Object

**Kind**: global typedef  

**Properties**

| Name | Type | Description |

| --- | --- | --- |

| value | [TraverseJsonEntry](#TraverseJsonEntry) | key value pair with the key as a full path of the property following the [json standard path format](https://tools.ietf.org/html/rfc6902#section-3) |

| done | Boolean |  |



## TraverseIterator ⇒ [TraverseIteratorResult](#TraverseIteratorResult)

Function iterator, [see](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next)

[examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Advanced_generators)

**Kind**: global typedef  

| Param | Description |

| --- | --- |

| extra | a object or array to extends the current iteration |