{"id":19307363,"url":"https://github.com/bonnevoyager/nested-objects-util","last_synced_at":"2025-04-22T12:36:33.467Z","repository":{"id":49605194,"uuid":"109893362","full_name":"BonneVoyager/nested-objects-util","owner":"BonneVoyager","description":"A module to filter and diff complex nested objects having circular references.","archived":false,"fork":false,"pushed_at":"2024-06-17T05:52:13.000Z","size":157,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-26T14:44:37.414Z","etag":null,"topics":["circular-references","download","flattened-json","flattened-objects","huge-nested-objects","javascript","javascript-tools","json","json-diff","json-files","json-parser","json-parsing","json-path-getter","json-values","nested-objects","nested-properties","stringify"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BonneVoyager.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-07T21:32:05.000Z","updated_at":"2024-06-17T05:52:09.000Z","dependencies_parsed_at":"2024-06-19T05:23:03.326Z","dependency_job_id":"fd191312-15b7-454b-86b2-3ae5e83c281f","html_url":"https://github.com/BonneVoyager/nested-objects-util","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/BonneVoyager%2Fnested-objects-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonneVoyager%2Fnested-objects-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonneVoyager%2Fnested-objects-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BonneVoyager%2Fnested-objects-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BonneVoyager","download_url":"https://codeload.github.com/BonneVoyager/nested-objects-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222916893,"owners_count":17057483,"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":["circular-references","download","flattened-json","flattened-objects","huge-nested-objects","javascript","javascript-tools","json","json-diff","json-files","json-parser","json-parsing","json-path-getter","json-values","nested-objects","nested-properties","stringify"],"created_at":"2024-11-10T00:10:39.843Z","updated_at":"2024-11-10T00:10:40.641Z","avatar_url":"https://github.com/BonneVoyager.png","language":"JavaScript","readme":"# nested-objects-util\n\nA minimalist inspection module to filter and diff complex nested objects having circular references.\n\nIt was implemented to filter out some values from inconveniently nested objects with circular references and then diff them.\n\nIt's designed to work both on nodejs and browser without any dependencies or additional polyfills.\n\nPerformance is currently not the key feature of this module, so please use more optimised libraries for e.g. deep equal.\n\n## Installation\n\n```\nnpm install --save nested-objects-util\n\nyarn add nested-objects-util\n```\n\nOr just copy `index.min.js` into the console and start using `NestedObjectsUtil` object.\n\n## Usage\n\n```js\nconst nestedObjectsUtil = require('nested-objects-util')\n```\n\n#### nestedObjectsUtil.flatten(object: object, sortKeysFlag = false): object\n\nFlatten object by keys composed from own nested properties.\n\n```js\nnestedObjectsUtil.flatten({\n  keyA: {\n    keyE: ['value3', 'value4'],\n    keyF: null,\n    keyD: 'value2',\n    keyB: {\n      keyC: 'value'\n    }\n  }\n})\n```\n\nreturns:\n\n```js\n{\n  \"keyA.keyE.0\": \"value3\",\n  \"keyA.keyE.1\": \"value4\",\n  \"keyA.keyF\": null,\n  \"keyA.keyD\": \"value2\",\n  \"keyA.keyB.keyC\": \"value\"\n}\n```\n\nwith sortKeys=true it would return:\n\n```js\n{\n  \"keyA.keyB.keyC\": \"value\",\n  \"keyA.keyD\": \"value2\",\n  \"keyA.keyE.0\": \"value3\",\n  \"keyA.keyE.1\": \"value4\",\n  \"keyA.keyF\": null\n}\n```\n\n#### nestedObjectsUtil.unflatten(object: object): object\n\nUnflatten object by keys composed from own nested properties.\n\n```js\nnestedObjectsUtil.unflatten({\n  'keyA.keyB.keyC': 'value',\n  'keyA.keyD': 'value2'\n})\n```\n\nreturns:\n\n```js\n{\n  \"keyA\": {\n    \"keyB\": {\n      \"keyC\": \"value\"\n    },\n    \"keyD\": \"value2\"\n  }\n}\n```\n\n#### nestedObjectsUtil.accessProperty(keys: string|string[], parent = global window): any\n\nAccess object's nested property.\n\n```js\nconst nestedObject = {\n  keyA: {\n    keyB: {\n      keyC: 'value'\n    }\n  }\n}\nnestedObjectsUtil.accessProperty('keyA.keyB.keyC', nestedObject)\n```\n\nreturns:\n\n```js\n\"value\"\n```\n\n#### nestedObjectsUtil.discardCircular(object: object, stringifyFlag = false): object|string\n\nDiscard circular references (to avoid \"Converting circular structure to JSON\" error).\n\n```js\nconst a = {\n  b: 1\n}\na.c = a\nnestedObjectsUtil.discardCircular(a)\n```\n\nreturns:\n\n```js\n{\n  \"b\": 1,\n  \"c\": \"~\"\n}\n```\n\n#### nestedObjectsUtil.filterValue(object: object, query: any|any[], flattenFlag = false): object\n\nFilter a nested object by value or values (if array passed). Strict comparison is performed.\n\n```js\nconst a = {\n  b: {\n    c: 'str',\n    d: 'str2'\n  },\n  e: 'str',\n  f: {\n    g: {\n      h: 'str',\n      i: 'str3'\n    },\n    j: 'str4'\n  },\n  k: ['str', 'str5']\n}\na.l = a.b\nnestedObjectsUtil.filterValue(a, 'str')\n```\n\nreturns:\n\n```js\n{\n  \"b\": {\n    \"c\": \"str\"\n  },\n  \"e\": \"str\",\n  \"f\": {\n    \"g\": {\n      \"h\": \"str\"\n    }\n  },\n  \"k\": [\"str\"]\n}\n```\n\nor with flattenFlag = true\n\n```js\nnestedObjectsUtil.filterValue(a, 'str', true)\n```\n\nreturns:\n\n```js\n{\n  \"b.c\": \"str\",\n  \"e\": \"str\",\n  \"f.g.h\": \"str\",\n  \"k.0\": \"str\"\n}\n```\n\n#### nestedObjectsUtil.downloadStringified(object: object, space = 2): string|undefined\n\nOn browser with HTML5 download API: stringify, format and download the object.\n\nElse: return stringified text.\n\n```js\nconst a = {\n  b: 1,\n  c: {\n    d: 2,\n    e: 2\n  }\n}\na.f = a\na.g = a.f\nconst obj = nestedObjectsUtil.discardCircular(a)\nnestedObjectsUtil.downloadStringified(obj)\n```\n\nreturns:\n\n```js\n{\n  \"b\": 1,\n  \"c\": {\n    \"d\": 2,\n    \"e\": 2\n  },\n  \"f\": \"~\",\n  \"g\": \"~\"\n}\n```\n\n#### nestedObjectsUtil.areObjectsEqual(objectA: object, objectB: object, skipProperties?: string[]): boolean\n\nCompare two objects against each other after discarding circular references, flattening and ordering keys.\n\n```js\nconst objectA = {\n  keyA: {\n    keyB: {\n      keyC: 'value'\n    },\n    keyD: 'value2',\n    keyE: ['value3', 'value4']\n  }\n}\nobjectA.circular = objectA\nconst objectB = {\n  keyA: {\n    keyE: ['value3', 'value4'],\n    keyD: 'value2',\n    keyB: {\n      keyC: 'value'\n    }\n  }\n}\nobjectB.circular = objectB\nnestedObjectsUtil.areObjectsEqual(objectA, objectB)\n```\n\nreturns:\n\n```js\ntrue\n```\n\nIt is also possible to skip certain properties when comparing the objects by providing an array to string properties.\n\n```js\nconst objectA = {\n  keyA: {\n    keyB: {\n      keyC: 'value'\n    },\n    keyD: 'value2',\n    keyE: ['value3', 'value4']\n  }\n}\nobjectA.circular = objectA\nconst objectB = {\n  keyA: {\n    keyB: {\n      keyC: 'DIFFERENT_VALUE'\n    },\n    keyD: 'value2',\n    keyE: ['value3', 'value4']\n  }\n}\nobjectB.circular = objectB\nnestedObjectsUtil.areObjectsEqual(objectA, objectB, ['keyA.keyB.keyC'])\n```\n\nreturns:\n\n```js\ntrue\n```\n\n#### nestedObjectsUtil.getObjectsDiff(objectA: object, objectB: object, sortKeysFlag = false, flattenFlag = false): object\n\nGet the properties which differ between object A and object B and return only those from object B.\n\n```js\nconst objectA = {\n  keyA: {\n    keyB: {\n      keyC: 'value'\n    },\n    keyD: 'value2',\n    keyE: ['value3']\n  }\n}\nobjectA.circular = objectA\nconst objectB = {\n  keyA: {\n    keyB: {\n      keyC: 'value'\n    },\n    keyD: 'value2_CHANGED',\n    keyE: ['value3_CHANGED']\n  }\n}\nobjectB.circular = objectB\nnestedObjectsUtil.getObjectsDiff(objectA, objectB)\n```\n\nreturns:\n\n```js\n{\n  \"keyA\": {\n    \"keyD\": \"value2_CHANGED\",\n    \"keyE\": [\"value3_CHANGED\"]\n  }\n}\n```\n\n## Example browser usage\n\nIn the browser, NestedObjectsUtil object is exposed either to window or with AMD.\n\nFilter out 'abcd' value from the flattened object and download stringified JSON via HTML5 API with:\n\n```js\nconst object = NestedObjectsUtil.filterValue(App.SomeHugeObject, 'abcd', true)\nNestedObjectsUtil.downloadStringified(object)\n```\n\nDiscar circular references from the object, then flatten and download it.\n\n```js\nlet object = NestedObjectsUtil.discardCircular(App.SomeHugeObject)\nobject = NestedObjectsUtil.flatten(object)\nNestedObjectsUtil.downloadStringified(object)\n```\n\n## Test\n\n```\nnpm run test\n\nyarn test\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnevoyager%2Fnested-objects-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonnevoyager%2Fnested-objects-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnevoyager%2Fnested-objects-util/lists"}