{"id":20315833,"url":"https://github.com/rubeniskov/traverse-json","last_synced_at":"2026-04-29T21:37:12.129Z","repository":{"id":57379304,"uuid":"315324264","full_name":"rubeniskov/traverse-json","owner":"rubeniskov","description":"A complete traverse json function with iterable interface.","archived":false,"fork":false,"pushed_at":"2020-12-04T01:26:20.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-02T01:03:03.260Z","etag":null,"topics":["depth","function-iterator","iterable","iterable-returns","iterator","javascript","json","jsonpath","minimatch","nodejs","standard","traverse","traverse-json"],"latest_commit_sha":null,"homepage":"http://rubeniskov.com/blog/en/traverse-json-like-a-king","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubeniskov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-23T13:29:04.000Z","updated_at":"2023-01-11T03:10:18.000Z","dependencies_parsed_at":"2022-09-02T18:22:48.049Z","dependency_job_id":null,"html_url":"https://github.com/rubeniskov/traverse-json","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubeniskov%2Ftraverse-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubeniskov%2Ftraverse-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubeniskov%2Ftraverse-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubeniskov%2Ftraverse-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubeniskov","download_url":"https://codeload.github.com/rubeniskov/traverse-json/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241818902,"owners_count":20025210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["depth","function-iterator","iterable","iterable-returns","iterator","javascript","json","jsonpath","minimatch","nodejs","standard","traverse","traverse-json"],"created_at":"2024-11-14T18:22:21.312Z","updated_at":"2026-04-29T21:37:07.110Z","avatar_url":"https://github.com/rubeniskov.png","language":"JavaScript","funding_links":["https://patreon.com/rubeniskov","https://github.com/sponsors/rubeniskov","https://paypal.me/rubeniskov"],"categories":[],"sub_categories":[],"readme":"# traverse-json\n\n[![unit-testing](https://github.com/rubeniskov/traverse-json/workflows/unit-testing/badge.svg)](https://github.com/rubeniskov/traverse-json/actions?query=workflow%3Aunit-testing)\n[![npm-publish](https://github.com/rubeniskov/traverse-json/workflows/npm-publish/badge.svg)](https://github.com/rubeniskov/traverse-json/actions?query=workflow%3Anpm-publish)\n[![npm-downloads](https://img.shields.io/npm/dw/traverse-json)](https://www.npmjs.com/package/traverse-json)\n[![codecov](https://codecov.io/gh/rubeniskov/traverse-json/branch/master/graph/badge.svg?token=mI2c282XxH)](https://codecov.io/gh/rubeniskov/traverse-json)\n[![patreon-donate](https://img.shields.io/badge/patreon-donate-yellow.svg)](https://patreon.com/rubeniskov)\n[![github-sponsor](https://img.shields.io/badge/github-donate-yellow.svg)](https://github.com/sponsors/rubeniskov)\n[![paypal-sponsor](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://paypal.me/rubeniskov)\n\nA complete traverse json function with `iterable` interface.\n\n## Motivation\n\nMany 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.\n\n\n## Mutation\n\nFor 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.\n\n## Installation\n\n### Npm:\n```shell\nnpm install traverse-json --save\n```\n### Yarn:\n```shell\nyarn add traverse-json\n```\n## Functions\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ca href=\"#traverseJson\"\u003etraverseJson(obj, [opts])\u003c/a\u003e ⇒ \u003ccode\u003e\u003ca href=\"#TraverseIterator\"\u003eTraverseIterator\u003c/a\u003e\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eCreates a function which traverses an object by its keys and values recursively,\nreturning the iterator result with the full path and its value.\u003c/p\u003e\n\u003cp\u003eBy default options will be parsed as { test: opts } if non object detected\u003c/p\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#createIterator\"\u003ecreateIterator(obj, [opts])\u003c/a\u003e ⇒ \u003ccode\u003eIterable\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eReturns a traverseJson iterable, usefull for use it in a for loop.\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\n## Typedefs\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ca href=\"#TraverseJsonOptions\"\u003eTraverseJsonOptions\u003c/a\u003e : \u003ccode\u003eObject\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#TraverseJsonEntry\"\u003eTraverseJsonEntry\u003c/a\u003e : \u003ccode\u003eArray.\u0026lt;String, any\u0026gt;\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#TraverseIteratorResult\"\u003eTraverseIteratorResult\u003c/a\u003e : \u003ccode\u003eObject\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003c/dd\u003e\n\u003cdt\u003e\u003ca href=\"#TraverseIterator\"\u003eTraverseIterator\u003c/a\u003e ⇒ \u003ccode\u003e\u003ca href=\"#TraverseIteratorResult\"\u003eTraverseIteratorResult\u003c/a\u003e\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003cp\u003eFunction iterator, \u003ca href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next\"\u003esee\u003c/a\u003e\n\u003ca href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Advanced_generators\"\u003eexamples\u003c/a\u003e\u003c/p\u003e\n\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003ca name=\"traverseJson\"\u003e\u003c/a\u003e\n\n## traverseJson(obj, [opts]) ⇒ [\u003ccode\u003eTraverseIterator\u003c/code\u003e](#TraverseIterator)\nCreates a function which traverses an object by its keys and values recursively,\nreturning the iterator result with the full path and its value.\n\nBy default options will be parsed as { test: opts } if non object detected\n\n**Kind**: global function  \n\n| Param | Type |\n| --- | --- |\n| obj | \u003ccode\u003eObject\u003c/code\u003e | \n| [opts] | \u003ccode\u003eString\u003c/code\u003e \\| [\u003ccode\u003eTraverseJsonOptions\u003c/code\u003e](#TraverseJsonOptions) | \n\n**Example**  \n```javascript\nconst traverseJson = require('traverse-json');\n\nconst options = {...};\n\nconst iterator = traverseJson({\n  foo: 0,\n  nested: {\n    depth: 1,\n    nested: {\n      depth: 2,\n      nested: {\n        depth: 3,\n        nested: {\n          depth: 4,\n        },\n      },\n    },\n  },\n  bar: 1,\n}, options);\n\nfor (;;) {\n  const { done, value } = iterator();\n  if (done)\n     break;\n   console.log(value);\n}\n```\n## Outputs\n\n### [Default options](#traversejsonoptions--object)\n\n__{}__\n```\n[ '/foo', 0 ]\n[ '/nested/depth', 1 ]\n[ '/nested/nested/depth', 2 ]\n[ '/nested/nested/nested/depth', 3 ]\n[ '/nested/nested/nested/nested/depth', 4 ]\n[ '/bar', 1 ]\n```\n\n\n### Return eather the nested and flatten values\n\n__{ [nested](#traversejsonoptions--object): true }__\n```\n[ '/foo', 0 ]\n[ '/nested',\n  { depth: 1, nested: { depth: 2, nested: [Object] } } ]\n[ '/nested/depth', 1 ]\n[ '/nested/nested',\n  { depth: 2, nested: { depth: 3, nested: [Object] } } ]\n[ '/nested/nested/depth', 2 ]\n[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]\n[ '/nested/nested/nested/depth', 3 ]\n[ '/nested/nested/nested/nested', { depth: 4 } ]\n[ '/nested/nested/nested/nested/depth', 4 ]\n[ '/bar', 1 ]\n```\n\n\n### Only traverse on depth 1\n\n__{ [recursive](#traversejsonoptions--object): false }__\n```\n[ '/foo', 0 ]\n[ '/nested',\n  { depth: 1, nested: { depth: 2, nested: [Object] } } ]\n[ '/bar', 1 ]\n```\n\n\n### Skips even entries\n\n__{ [step](#traversejsonoptions--object): 2 }__\n```\n[ '/foo', 0 ]\n[ '/bar', 1 ]\n```\n\n\n### Match only the paths ending with _depth_\n\n__{ [test](#traversejsonoptions--object): /depth$/ }__\n```\n[ '/nested/depth', 1 ]\n[ '/nested/nested/depth', 2 ]\n[ '/nested/nested/nested/depth', 3 ]\n[ '/nested/nested/nested/nested/depth', 4 ]\n```\n\n\n### Return eather the nested and flatten values ending with _nested_\n\n__{ [test](#traversejsonoptions--object): /nested$/, [nested](#traversejsonoptions--object): true }__\n```\n[ '/nested',\n  { depth: 1, nested: { depth: 2, nested: [Object] } } ]\n[ '/nested/nested',\n  { depth: 2, nested: { depth: 3, nested: [Object] } } ]\n[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]\n[ '/nested/nested/nested/nested', { depth: 4 } ]\n```\n\n\n### Match only the paths ending with _foo_ or _depth_\n\n__{ [test](#traversejsonoptions--object): \"\u0026#42;\u0026#42;/{depth,foo}\" }__\n```\n[ '/foo', 0 ]\n[ '/nested/depth', 1 ]\n[ '/nested/nested/depth', 2 ]\n[ '/nested/nested/nested/depth', 3 ]\n[ '/nested/nested/nested/nested/depth', 4 ]\n```\n\n\n### Match entries which has a number value equal or greater than 3\n\n__{ [test](#traversejsonoptions--object): ([,value]) =\u003e typeof value === 'number' \u0026\u0026 value \u003e= 3 }__\n```\n[ '/nested/nested/nested/depth', 3 ]\n[ '/nested/nested/nested/nested/depth', 4 ]\n```\n\n\n### Traverse recursively through the same key\n\n__{ [test](#traversejsonoptions--object): \"@nested\" }__\n```\n[ '/nested',\n  { depth: 1, nested: { depth: 2, nested: [Object] } } ]\n[ '/nested/nested',\n  { depth: 2, nested: { depth: 3, nested: [Object] } } ]\n[ '/nested/nested/nested', { depth: 3, nested: { depth: 4 } } ]\n[ '/nested/nested/nested/nested', { depth: 4 } ]\n```\n\u003ca name=\"createIterator\"\u003e\u003c/a\u003e\n\n## createIterator(obj, [opts]) ⇒ \u003ccode\u003eIterable\u003c/code\u003e\nReturns a traverseJson iterable, usefull for use it in a for loop.\n\n**Kind**: global function  \n\n| Param | Type |\n| --- | --- |\n| obj | \u003ccode\u003eObject\u003c/code\u003e | \n| [opts] | [\u003ccode\u003eTraverseJsonOptions\u003c/code\u003e](#TraverseJsonOptions) | \n\n**Example**  \n```javascript\nconst { createIterator } = require('traverse-json');\nconst options = {...}\nconst ientries = createIterator({\n  foo: 0,\n  nested: {\n    depth: 1,\n    nested: {\n      depth: 2,\n       nested: {\n         depth: 3,\n         nested: {\n           depth: 4,\n         },\n       },\n     },\n   },\n  bar: 1,\n}, options);\n\nfor (let [k, v] of ientries) {\n  console.log(k, v);\n}\n````\n### Output\n```\n/foo 0\n/nested/depth 1\n/nested/nested/depth 2\n/nested/nested/nested/depth 3\n/nested/nested/nested/nested/depth 4\n/bar 1\n```\n\u003ca name=\"TraverseJsonOptions\"\u003e\u003c/a\u003e\n\n## TraverseJsonOptions : \u003ccode\u003eObject\u003c/code\u003e\n**Kind**: global typedef  \n**Properties**\n\n| Name | Type | Default | Description |\n| --- | --- | --- | --- |\n| [opts.recursive] | \u003ccode\u003eBoolean\u003c/code\u003e | \u003ccode\u003etrue\u003c/code\u003e | enable/disable nested arrays and objects recursion |\n| [opts.nested] | \u003ccode\u003eBoolean\u003c/code\u003e | \u003ccode\u003efalse\u003c/code\u003e | also emit nested array or objects |\n| [opts.step] | \u003ccode\u003eBoolean\u003c/code\u003e | \u003ccode\u003e1\u003c/code\u003e | the step to increment, default 1 |\n| [opts.test] | \u003ccode\u003eString\u003c/code\u003e \\| \u003ccode\u003efunction\u003c/code\u003e \\| \u003ccode\u003eRegeExp\u003c/code\u003e | \u003ccode\u003efalse\u003c/code\u003e | regexp, string [minimatch](https://www.npmjs.com/package/minimatch) or function to filter properties |\n\n\u003ca name=\"TraverseJsonEntry\"\u003e\u003c/a\u003e\n\n## TraverseJsonEntry : \u003ccode\u003eArray.\u0026lt;String, any\u0026gt;\u003c/code\u003e\n**Kind**: global typedef  \n**Properties**\n\n| Name | Type | Description |\n| --- | --- | --- |\n| 0 | \u003ccode\u003estring\u003c/code\u003e | Object [JSONPointer](https://tools.ietf.org/html/rfc6901) |\n| 1 | \u003ccode\u003eany\u003c/code\u003e | Value |\n\n\u003ca name=\"TraverseIteratorResult\"\u003e\u003c/a\u003e\n\n## TraverseIteratorResult : \u003ccode\u003eObject\u003c/code\u003e\n**Kind**: global typedef  \n**Properties**\n\n| Name | Type | Description |\n| --- | --- | --- |\n| value | [\u003ccode\u003eTraverseJsonEntry\u003c/code\u003e](#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) |\n| done | \u003ccode\u003eBoolean\u003c/code\u003e |  |\n\n\u003ca name=\"TraverseIterator\"\u003e\u003c/a\u003e\n\n## TraverseIterator ⇒ [\u003ccode\u003eTraverseIteratorResult\u003c/code\u003e](#TraverseIteratorResult)\nFunction iterator, [see](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next)\n[examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Advanced_generators)\n\n**Kind**: global typedef  \n\n| Param | Description |\n| --- | --- |\n| extra | a object or array to extends the current iteration |\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubeniskov%2Ftraverse-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubeniskov%2Ftraverse-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubeniskov%2Ftraverse-json/lists"}