{"id":15655610,"url":"https://github.com/sagold/json-query","last_synced_at":"2025-08-15T02:31:22.165Z","repository":{"id":13115091,"uuid":"73640351","full_name":"sagold/json-query","owner":"sagold","description":"Query and transform your json data using an extended glob-pattern.","archived":false,"fork":false,"pushed_at":"2024-06-16T10:03:30.000Z","size":922,"stargazers_count":24,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T07:33:50.890Z","etag":null,"topics":["glob-pattern","json","json-pointer","library","npm-package","query"],"latest_commit_sha":null,"homepage":"","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/sagold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2016-11-13T20:16:25.000Z","updated_at":"2024-09-06T15:26:32.000Z","dependencies_parsed_at":"2024-10-23T04:57:56.397Z","dependency_job_id":"c6c7f9fd-05fc-44f0-834c-781d9b9cd63d","html_url":"https://github.com/sagold/json-query","commit_stats":{"total_commits":171,"total_committers":7,"mean_commits":"24.428571428571427","dds":"0.17543859649122806","last_synced_commit":"2a6f6d2533237a69d0f8ad9e09e67509754c6cea"},"previous_names":["sagold/gson-query"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/sagold/json-query","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sagold","download_url":"https://codeload.github.com/sagold/json-query/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sagold%2Fjson-query/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269713884,"owners_count":24463244,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["glob-pattern","json","json-pointer","library","npm-package","query"],"created_at":"2024-10-03T13:00:02.814Z","updated_at":"2025-08-15T02:31:21.847Z","avatar_url":"https://github.com/sagold.png","language":"TypeScript","readme":"\u003ch1 align=\"left\"\u003e\u003cimg src=\"./docs/sagold-json-query.png\" width=\"100%\" alt=\"@sagold/json-query\"\u003e\u003c/h1\u003e\n\n\u003cp align=\"left\"\u003e\u003cb\u003e\u003ccode\u003ejson-query\u003c/code\u003e lets you quickly select values, patterns or types from json-data. Its input requires a simple string, describing a concise query into your data.\u003c/b\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e | \u003ca href=\"#quick-introduction\"\u003eIntroduction\u003c/a\u003e | \u003ca href=\"#api\"\u003eApi\u003c/a\u003e | \u003ca href=\"#about-patterns\"\u003eAbout patterns\u003c/a\u003e | \u003ca href=\"#further-examples\"\u003eFurther examples\u003c/a\u003e | \u003ca href=\"#breaking-changes\"\u003eBreaking changes\u003c/a\u003e\n\u003c/p\u003e\n\n**install**\n\n`yarn add @sagold/json-query`\n\n\n## Features\n\n- [json-pointer](https://github.com/sagold/json-pointer) syntax `#/list/0/id`\n- glob-patterns for properties (`*`, `**`)\n- regex-support for properties `{any.*}`\n- pattern-support for inifinite recursion `/tree(/nodes/*)+/value`\n- or-patterns `/node((/left), (/right))`\n- finite search in circular-data `**`\n- lookahead-rules to test selected property `?property:value` and regex values `?property:{\\d+}`\n- and typechecks `/value?:array`\n\n\n## Quick introduction\n\nBasically, a **query** is a json-pointer, which describes a path of properties into the json-data\n\n```js\nimport { get } from \"@sagold/json-query\";\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object/a/id\"); // [\"id-a\"]\n```\n\n\nBut each property may also be a glob-pattern or a regular expression:\n\n`*` selects all direct children\n\n```js\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object/*/id\"); // [\"id-a\", \"id-b\"]\n```\n\n\n`**` selects all values\n\n```js\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object/**\");\n// [ { a: { id: \"id-a\" }, b: { id: \"id-b\" } }, { id: \"id-a\" }, \"id-a\", { id: \"id-b\" }, \"id-b\" ]\n```\n\n\n`{}` calls a regular expression\n\n```js\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/{obj.*}/{.*}/id\"); // [\"id-a\", \"id-b\"]\n```\n\n\u003e Note. Regular expressions within strings, have to escape any backslashes, e.g. instead of `{\\d}` you need to pass `{\\\\d}`\n\n\n**lookahead** rules are used to validate the current value based on its properties\n\n`?child` tests if a childProperty is defined\n\n```js\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object/*?id\"); // [{ id: \"id-a\" }, { id: \"id-b\" }]\n```\n\n\n`?child:value` tests if a childProperty matches a value\n\n```js\nconst input = { object: { a: { id: \"id-a\" }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object/*?id:id-b\"); // [{ id: \"id-b\" }]\n```\n\nlookahead rules can also be negated `?child:!value`, tested by regex `?child:{^re+}`, combined `?child\u0026\u0026other` or joined `?child||other`. Undefined may be tested with `?property:undefined`, per default `undefined` is excluded from matches.\n\n\n**typechecks** can be used to query certain data-types\n\n`?:\u003ctype\u003e`, where `\u003ctype\u003e` may be any of `[\"boolean\", \"string\", \"number\", \"object\", \"array\", \"value\"]`\n\n```js\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/**?:string\"); // [\"id-b\"]\n```\n\n`?:value` will match all types except *objects* and *arrays*\n\n```js\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/**?:value\"); // [33, \"id-b\"]\n```\n\n\n**patterns** can be used to combine queries into a single result (*OR*) and to build up results from recursive queries (*+*)\n\nQueries can be grouped by parenthesis, where `/a/b/c = /a(/b)(/c) = /a(/b/c)`.\n\n`((/a), (/b))` resolves both queries on the previous result\n\n```js\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nconst values = get(input, \"/object((/a), (/b))\"); // [{ id: 33 }, { id: \"id-b\" }]\n```\n\nand the result may be queried further\n\n```js\nget(input, \"/object((/a), (/b))/id\"); // [33, \"id-b\"]\nget(input, \"/object((/a), (/b))/id?:number\"); // [33]\n```\n\n`(/a)+` will repeat the grouped query for all possible results\n\n```js\nconst input = {\n    id: 1,\n    a: { // first iteration\n        id: 2,\n        a: { // second iteration\n            id: 3\n            a: 4 // last iteration\n        }\n    }\n};\n\nconst values = get(input, \"/(/a)+\"); // [{ id: 2, a: { id: 3, a: 4 } }, { id: 3, a: 4 }, 4]\n```\n\n\n**escaping properties** In case you have special characters in property-names or values, you can escape any value using doubled-quotes `\"\u003cvalue\u003e\"`:\n\n- escape property-name: `'/root/*/\"strange/property\"'` is split to `[\"root\", \"*\", \"strange/property\"]`\n- escape query-property `'/root/*?\"strange/property\":42'`\n- escape query-value `'/root/*?id:\"#/pointer/value\"'`\n\n\n## API\n\n*json-query* exposes `get`, `set`, `remove` and a `split`-helper\n\nmethod  | signature                                                         | description\n--------|-------------------------------------------------------------------|------------------------------\nget     | (input:any, query:string, returnType?:string\\|function)           | query data, returns results\nset     | (input:any, query:string, value:string\\|function, replace?:string)| set value, returns modified input\nsplit   | (query: string)                                                   | returns a list properties and queries\nremove  | (input:any, query: string, returnRemoved?:boolean)                | delete query targets, returns input\n\n\n### get\n\nper default, *get* returns a list of all values\n\n```js\nimport { get } from \"@sagold/json-query\";\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\nconst values = get(input, \"/**?:value\"); // [33, \"id-b\"]\n```\n\nUsing the optional value `returnType` you can change the result type to the following options\n`[\"all\", \"value\", \"pointer\", \"map\"]`. The string values can also be accessed as property on `get`: `get.ALL, get.VALUE, get.POINTER, get.MAP`:\n\n\nreturnType  | description\n------------|------------------------------------------------------------------\n\"value\"     | returns all matched values of the query `[33, \"id-b\"]`\n\"pointer\"   | returns json-pointer to results `[\"#/object/a\", \"#/object/b\"]`\n\"map\"       | returns an pairs of `jsonPointer: resultValue` as an object\n\"all\"       | returns a list, where each result is an array of `[value, keyToValue, parentObject, jsonPointer]`\nfunction    | callback with `(value, keyToValue, parentObject, jsonPointer) =\u003e {}`. If a value is returned, the result will be replaced by the return-value\n\n\n```js\nimport { get } from \"@sagold/json-query\";\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nget(input, \"/**?:value\", get.VALUE); // [33, \"id-b\"]\nget(input, \"/**?:value\", get.POINTER); // [\"#/object/a/id\", \"#/object/b/id\"]\nget(input, \"/**?:value\", get.MAP); // { \"#/object/a/id\": 33, \"#/object/b/id\": \"id-b\" }\n\nget(input, \"/**?:value\", get.ALL);\n// [\n//    [33, \"id\", { id: 33 }, \"#/object/a/id\"],\n//    [\"id-b\", \"id\", { id: \"id-b\" }, \"#/object/b/id\"]\n// ]\n\nget(input, \"/**?:value\", (value, key, parent, pointer) =\u003e `custom-${pointer}`);\n// [\"custom-#/object/a/id\", \"custom-#/object/b/id\"]\n```\n\n\n### remove\n\n**remove** deletes any match from the input data.\nNote: the input will be modified. If this is unwanted behaviour, copy your data up front.\n\n```js\nimport { remove } from \"@sagold/json-query\";\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nremove(input, \"/object/*/id\"); // { object: { a: {}, b: {} } };\n```\n\nPer default, the input object is returned. Setting the optional argument `returnRemoved = true`, will return a list of the removed items\n\n```js\nimport { remove } from \"@sagold/json-query\";\nconst input = { object: { a: { id: 33 }, b: { id: \"id-b\" } } };\n\nremove(input, \"/object/*/id\", true); // [ 33, \"id-b\" ]\n```\n\n\n### set\n\n**set** inserts given input-value on result and creates missing properties and arrays.\nNote: Any expanding queries like `*` or patterns will not create any intermediate values\n\n`set` has the following signature\n\n```ts\nset(input:any, query:string, value:string\\|function, force?:string): any\n```\n\ninstead of value, you can also pass a function to generate the values to set:\n\n```ts\nvalue(pointerOfParent:string, lastPropertyName:string, parentObject:string, pointerAtValue:string): any\n```\n\n\nCreate data from simple properties\n\n```js\nimport { set } from \"@sagold/json-query\";\n\nconst result = set({}, \"/object/id\", 42); // { object: { id: 42 }}\n```\n\nAdd properties to multiple existing objects\n\n```js\nimport { set } from \"@sagold/json-query\";\n\nconst result = set({ list: [ { id: 1 }, { id: 2 } ] }, \"/list/*/index\", 42);\n// { list: [ { id: 1, index: 42 }, { id: 2, index: 42 } ] }\n```\n\nOr using a value-function\n\n```js\nimport { set } from \"@sagold/json-query\";\n\nconst result = set({ list: [ { id: 1 }, { id: 2 } ] }, \"/list/*/index\",\n    ( _, _, parent) =\u003e `id-${parent.id}`\n);\n// { list: [ { id: 1, index: \"id-1\" }, { id: 2, index: \"id-2\" } ] }\n```\n\nCurrently, `set` will not override simple values\n\n```js\nimport { set } from \"@sagold/json-query\";\n\nconst result = set({ value: 2 }, \"/value/id\", 3);\n// { value: 2 }\n```\n\nAnd queries will not add values to the data\n```js\nimport { set } from \"@sagold/json-query\";\n\nconst result = set({ a: { id: 2 } }, \"((/a), (/b))/id\", true);\n// { a: { id: true } }\n```\n\nWhen working with arrays, you have to choose between the following actions\n\n- insert item at index *1*: `/list/[1]/id`\n- replace item at index *1*: `/list/1/id`\n- append item `/list/[]/id`\n\nUsing the `force` option, you can enforce insertion or replacement, independent of the syntax (same for the whole query)\n\n```js\nset(data, \"/list/[1]/id\", 42, set.REPLACE_ITEMS); // will always replace index\n// and\nset(data, \"/list/1/id\", 42, set.INSERT_ITEMS); // will always insert at index\n```\n\nNumbers will always be interpreted as arrays\n\n```js\nset({}, \"/list/0/id\", 42); // { list: [{ id: 42 }]}\nset({}, \"/list/[]/id\", 42); // { list: [{ id: 42 }]}\nset({}, \"/list/[0]/id\", 42); // { list: [{ id: 42 }]}\n\n// but setting an index is respected\nset({}, \"/list/2/id\", 42); // { list: [undefined, undefined, { id: 42 }]}\n```\n\nIn order to treat numbers as objects, escape them using double-quotes\n\n```js\nset({}, '/list/\"2\"/id', 42); // { list: { 2: { id: 42 } } }\n// or \"/list/\\\"2\\\"/id\"\n```\n\n\n## About patterns\n\nPattern-queries enable selection of recursive patterns and offer a way to build up a collection of data for further filterung. A pattern uses brackets `()` to identify repeatable structures and offers multiple selections for the same data-entry.\n\nUsing a pattern-query like `#/tree((/left),(/right))*` will recursively select all *left* and *right*-nodes. e.g.\n\n```js\nconst data = {\n  tree: {\n    left: {\n      id: \"1\",\n      left: { id: \"2\" },\n      right: { id: \"3\" }\n    },\n    right: {\n      id: \"4\"\n    }\n  }\n};\n\nconst result = get(data, \"#/tree((/left),(/right))*/id\");\n// [\"1\", \"2\", \"3\", \"4\"]\n```\n\n**Note** that each pattern-queries is resovled using `query.get` and thus supports all mentioned features.\n\nOne use-case for pattern-queries can be found in json-schema specification. Any definition in `#/defs` may reference itself or be referenced circular. A linear query cannot describe the corresponding data, but pattern-queries might be sufficient.\n\n\n#### details\n\nA pattern is a simple group defined by brackets: `#/a(/b)/c`, which is identical to `#/a/b/c`. But a group may also have a quantifier `+`: `#/a(/b)+/c`. Using a quantifier, the query within the pattern will be applied as long as it matches any data. Its combined result will then be passed to `/c`.\n\ne.g. applying the pattern `#/a(/b)+/c` on the following input data:\n\n```js\nconst input = {\n  a: {\n    b: {\n      c: \"1\",\n      b: {\n        c: \"2\",\n        b: {}\n      }\n    }\n  }\n};\n```\n\nwill first select property `a` and then repeatedly select property `b`: `[a/b, a/b/b, a/b/b/b]`. This result is filtered by `c`, which will return `[\"1\", \"2\"]` (the last `b`-object has no property `c`).\n\nPatterns can also be used for **OR**-operations. An *OR* is identified by a semicolon `,` and must be within and between patterns, like `((/a/b),(/c))`. **Not valid** patterns are *(/a/b, /c)* and *r/(/a/b),(/c)/f*.\n\nCurrently, using **OR** is *commutative* in a sense that `((/a),(/b)) = ((/b),(/a))`, (with a different ordering of the resulting set), *distributive* so that `/a((/b), (/c)) = ((/a/b), (/a/c))`. **Parenthesis** without a quantifier are *associative*, e.g. `#/a/b/c = #/a(/b)/c = #/a(/b/c) = #/a(/b)(/c)`. Thus, a pattern `((/b)(/c))+` can also be written like `(/b/c)+`.\n\n\n## further examples\n\nfor further examples refer to the unit tests\n\n- [query.delete](https://github.com/sagold/json-query/blob/master/test/unit/delete.test.js)\n- [query.get](https://github.com/sagold/json-query/blob/master/test/unit/get.test.js)\n- [query.set](https://github.com/sagold/json-query/blob/master/test/unit/set.test.js)\n- [query.split](https://github.com/sagold/json-query/blob/master/test/unit/split.test.js)\n\n\n## Breaking Changes\n\n- with version `v5.0.0` package has been rename to `@sagold/json-query`\n- with version `v4.0.0` (2019/10/01)\n    - the api has been simplified to methods `query.get` and `query.delete` (removed `run` and `pattern`)\n- with version `v3.0.0`\n    - the syntax has changed to es6, which might require code transpilation\n    - queries for root-pointer (`#`, `#/`, `/`) now callback root object with `(rootObject, null, null, \"#\")`\n- with `v2.0.0` a negated filter (lookahead), e.g. `*?valid:!true` will not return objects where `valid === undefined`. To match objects with missing properties you can still query them explicitly with `*?valid:!true||valid:undefined`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagold%2Fjson-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsagold%2Fjson-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsagold%2Fjson-query/lists"}