{"id":20597729,"url":"https://github.com/triggerdotdev/json-hero-path","last_synced_at":"2025-04-15T00:15:36.752Z","repository":{"id":57122530,"uuid":"429755149","full_name":"triggerdotdev/json-hero-path","owner":"triggerdotdev","description":"An easy way to query and filter JSON objects","archived":false,"fork":false,"pushed_at":"2022-04-27T19:57:45.000Z","size":354,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T00:15:25.936Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/triggerdotdev.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":"2021-11-19T10:22:02.000Z","updated_at":"2024-01-31T06:00:44.000Z","dependencies_parsed_at":"2022-08-24T14:59:30.032Z","dependency_job_id":null,"html_url":"https://github.com/triggerdotdev/json-hero-path","commit_stats":null,"previous_names":["jsonhero-io/json-hero-path"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-hero-path","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-hero-path/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-hero-path/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triggerdotdev%2Fjson-hero-path/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triggerdotdev","download_url":"https://codeload.github.com/triggerdotdev/json-hero-path/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981268,"owners_count":21193147,"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":[],"created_at":"2024-11-16T08:23:41.874Z","updated_at":"2025-04-15T00:15:36.731Z","avatar_url":"https://github.com/triggerdotdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON Hero Path\n\nA TypeScript/JavaScript library that provides a simple way of accessing objects inside JSON using paths\n\n## How to install\n\n`npm install @jsonhero/path`\n\n## Getting started\n\n### Importing\n\nYou can require\n\n```js\nconst { JSONHeroPath } = require('@jsonhero/path');\n```\n\nOr if you're using TypeScript:\n\n```js\nimport { JSONHeroPath } from '@jsonhero/path';\n```\n\n### Sample object\n\nGiven the following JSON variable called `employees`\n\n```js\nlet employees = {\n  people: [\n    {\n      name: 'Matt',\n      age: 36,\n      favouriteThings: ['Monzo', 'The Wirecutter', 'Jurassic Park'],\n    },\n    {\n      name: 'James',\n      age: 39,\n      favouriteThings: ['Far Cry 1', 'Far Cry 2', 'Far Cry 3'],\n    },\n    {\n      name: 'Eric',\n      age: 38,\n      favouriteThings: ['Bitcoin'],\n    },\n    {\n      name: 'Dan',\n      age: 34,\n      favouriteThings: ['Frasier'],\n    },\n  ],\n  count: 4,\n};\n```\n\n### Simple queries\n\nA simple query to get the 2nd person's name. Note that you can just include index numbers to access array items (0 = first item)\n\n```js\nlet path = new JSONHeroPath('$.people.1.name');\nlet name = path.first(employees);\n//name = 'James'\n\nlet names = path.all(employees);\n//names = ['James']\n```\n\nLet's get all the people\n\n```js\nlet path = new JSONHeroPath('$.people');\nlet allPeople = path.all(employees);\n//allPeople is set to the array of people\n```\n\nThere are only two methods you can perform with a path:\n\n- `first()` returns the first matching result\n- `all()` returns all the matching results in an array\n\nA `$` is placed at the start of a path. If you don't add this, it will just do it automatically for you.\n\n### Wildcard queries\n\nLet's get all the names\n\n```js\nlet path = new JSONHeroPath('$.people.*.name');\nlet allNames = path.all(employees);\n//allNames = ['Matt', 'James', 'Eric', 'Dan']\n```\n\nNow everyone's favourite things\n\n```js\nlet path = new JSONHeroPath('$.people.*.favouriteThings.*');\nlet allFavouriteThings = path.all(employees);\n//allFavouriteThings = ['Monzo', 'The Wirecutter', 'Jurassic Park', 'Far Cry 1', 'Far Cry 2', 'Far Cry 3', 'Bitcoin', 'Frasier']\n```\n\n### Array slice queries\n\nWe can slice arrays (in the exact same way as the JavaScript .slice() function).\n\nOffset the start index\n\n```js\nlet path = new JSONHeroPath('$.people.[1:]');\nlet skipFirstPerson = path.all(employees);\n// skipFirstPerson will have everyone but the first person in\n```\n\nRestrict the end index\n\n```js\nlet path = new JSONHeroPath('$.people.[1:2]');\nlet justTheSecondPerson = path.all(employees);\n// justTheSecondPerson will have only the second person in (start index is 1 and the end won't include index 2)\n```\n\nNegative end indexes remove items from the end of an array\n\n```js\nlet path = new JSONHeroPath('$.people.[:-1]');\nlet excludeLastPerson = path.all(employees);\n// excludeLastPerson will have everyone except the last person\n```\n\n### Getting the result value as well as the paths\n\n```js\nlet path = new JSONHeroPath('$.people.*.favouriteThings.*');\n\n// pass this optional object with `includePath` set to true\nlet results = path.all(testObject1, { includePath: true });\n\nlet firstResult = results[0];\n//this variable will be an object like this\n//{\n//  value: 'Monzo',\n//   path: a JSONHeroPath for this element\n//}\n```\n\n### Getting parent, root and children paths from a path\n\n```js\nlet path = new JSONHeroPath('$.people.*.favouriteThings');\n\nlet parent = path.parent;\n// will be a new path: '$.people.*'\n\nlet root = path.root;\n// will be a new path: '$'\n\nlet child = path.child('2');\n//will be a new path: '$.people.*.favouriteThings.2'\n```\n\n### Accessing components from a path\n\nA path is an array of path components. You can access them directly if you'd like.\n\nYou can check if a component is an array type, which is true for wildcards and indexes (e.g. 0)\n\n```js\nlet path = new JSONHeroPath('$.people.2.favouriteThings.*');\n\nlet rootComponent = path.components[0];\nlet rootComponentIsArray = rootComponent.isArray;\n//is false\n\nlet personIndexComponent = path.components[2];\nlet personIndexComponentIsArray = personIndexComponent.isArray;\n//is true\n\nlet wildcardComponent = path.components[4];\nlet wildcardComponentIsArray = wildcardComponent.isArray;\n//is true\n```\n\n## Updating values at a path\n\nYou can update values in an object at the specified path.\n\n### Setting new values (overwriting existing values at a path)\n\nOverwriting a single object at a path:\n\n```js\nlet path = new JSONHeroPath('$.people.1');\n//this will overwrite the entire object at that path\npath.set(employees, {\n  name: 'James',\n  age: 100,\n  favouriteThings: ['Far Cry 1', 'Far Cry 2', 'Far Cry 3', 'Far Cry 4', 'Far Cry 5', 'Far Cry 6'],\n});\n```\n\nThis will overwrite all the objects at the path:\n\n```js\nlet path = new JSONHeroPath('$.people.*.favouriteThings');\n//this will set everyone's favourite things to be an array with just Jurassic Park in it\npath.set(employees, ['Jurassic Park']);\n```\n\n### Merging values\n\nYou can merge values into arrays and objects.\n\nFor an array this will append the passed in values to the end of the array\n\n```js\nlet path = new JSONHeroPath('$.people.*.favouriteThings');\n//this will add Groundhog Day and Milkshakes to everyone's favourite things\npath.merge(employees, ['Groundhog Day', 'Milkshakes']);\n```\n\nFor an object, this will overwrite properties that already exist and add any that don't\n\n```js\nlet path = new JSONHeroPath('$.people.*');\n//this will update everyone's age to be 21 and add a new hairColour property with a value of Brown\npath.merge(employees, {\n  age: 21,\n  hairColour: 'Brown',\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-hero-path","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriggerdotdev%2Fjson-hero-path","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriggerdotdev%2Fjson-hero-path/lists"}