{"id":20668648,"url":"https://github.com/jsonquerylang/jsonquery","last_synced_at":"2025-05-15T14:05:57.379Z","repository":{"id":249394577,"uuid":"830953102","full_name":"jsonquerylang/jsonquery","owner":"jsonquerylang","description":"A lightweight, flexible, and expandable JSON query language","archived":false,"fork":false,"pushed_at":"2025-05-06T16:58:13.000Z","size":707,"stargazers_count":225,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-05-11T22:49:48.496Z","etag":null,"topics":["json","language","query"],"latest_commit_sha":null,"homepage":"https://jsonquerylang.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsonquerylang.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":"2024-07-19T10:33:06.000Z","updated_at":"2025-05-11T19:51:07.000Z","dependencies_parsed_at":"2024-09-17T01:27:13.176Z","dependency_job_id":"3a1d1b69-7c24-46d6-b95b-5121f22a49e5","html_url":"https://github.com/jsonquerylang/jsonquery","commit_stats":null,"previous_names":["josdejong/jsonquery"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonquerylang%2Fjsonquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonquerylang%2Fjsonquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonquerylang%2Fjsonquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonquerylang%2Fjsonquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsonquerylang","download_url":"https://codeload.github.com/jsonquerylang/jsonquery/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355334,"owners_count":22057354,"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":["json","language","query"],"created_at":"2024-11-16T20:10:35.365Z","updated_at":"2025-05-15T14:05:52.371Z","avatar_url":"https://github.com/jsonquerylang.png","language":"TypeScript","readme":"# JSON Query\n\n![JSON Query Logo](https://jsonquerylang.org/frog-756900-100.png)\n\nA small, flexible, and expandable JSON query language.\n\nTry it out on the online playground: \u003chttps://jsonquerylang.org\u003e\n\n![JSON Query Overview](https://jsonquerylang.org/jsonquery-overview.svg)\n\n## Features\n\n- Small: just `3.3 kB` when minified and gzipped! The JSON query engine without parse/stringify is only `1.7 kB`.\n- Feature rich (50+ powerful functions and operators)\n- Easy to interoperate with thanks to the intermediate JSON format.\n- Expressive\n- Expandable\n\n## Documentation\n\nOn this page:\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [JavaScript API](#javascript-api)\n- [Command line interface (CLI)](#command-line-interface-cli)\n- [Development](#development)\n- [License](#license)\n\nExternal pages:\n\n- [JSON Query Documentation](https://jsonquerylang.org/docs/)\n- [JSON Query Function reference](https://jsonquerylang.org/reference/)\n- [JSON Query Test Suite](test-suite/README.md)\n\n## Installation\n\nInstall the JavaScript library via [npm](https://www.npmjs.com/):\n\n```text\nnpm install @jsonquerylang/jsonquery\n```\n\nA Python implementation can be found here: https://github.com/jsonquerylang/jsonquery-python\n\n## Usage\n\n```js\nimport { jsonquery } from '@jsonquerylang/jsonquery'\n\nconst data = {\n  \"friends\": [\n    { \"name\": \"Chris\", \"age\": 23, \"city\": \"New York\" },\n    { \"name\": \"Emily\", \"age\": 19, \"city\": \"Atlanta\" },\n    { \"name\": \"Joe\", \"age\": 32, \"city\": \"New York\" },\n    { \"name\": \"Kevin\", \"age\": 19, \"city\": \"Atlanta\" },\n    { \"name\": \"Michelle\", \"age\": 27, \"city\": \"Los Angeles\" },\n    { \"name\": \"Robert\", \"age\": 45, \"city\": \"Manhattan\" },\n    { \"name\": \"Sarah\", \"age\": 31, \"city\": \"New York\" }\n  ]\n}\n\n// Get the array containing the friends from the object, filter the friends that live in New York,\n// sort them by age, and pick just the name and age out of the objects.\nconst output = jsonquery(data, `\n  .friends \n    | filter(.city == \"New York\") \n    | sort(.age) \n    | pick(.name, .age)\n`)\n// output = [\n//   { \"name\": \"Chris\", \"age\": 23 },\n//   { \"name\": \"Sarah\", \"age\": 31 },\n//   { \"name\": \"Joe\", \"age\": 32 }\n// ]\n\n// The same query can be written in JSON format instead of the text format.\n// Note that the functions `parse` and `stringify` can be used\n// to convert from text format to JSON format and vice versa.\njsonquery(data, [\n  \"pipe\",\n  [\"get\", \"friends\"],\n  [\"filter\", [\"eq\", [\"get\", \"city\"], \"New York\"]],\n  [\"sort\", [\"get\", \"age\"]],\n  [\"pick\", [\"get\", \"name\"], [\"get\", \"age\"]]\n])\n```\n\nThe build in functions can be extended with custom functions, like `times` in the following example:\n\n```js\nimport { jsonquery } from '@jsonquerylang/jsonquery'\n\nconst options = {\n  functions: {\n    times: (value) =\u003e (data) =\u003e data.map((item) =\u003e item * value)\n  }\n}\n\nconst data = [1, 2, 3]\nconst result = jsonquery(data, 'times(3)', options)\n// [3, 6, 9]\n```\n\nDocumentation on the syntax of JSON Query and all supported functions can be found on the website: https://jsonquerylang.org/docs/.\n\n## JavaScript API\n\nThe library exports the following functions:\n\n- [`jsonquery`](#jsonquery) is the core function of the library, which parses, compiles, and evaluates a query in one go.\n- [`compile`](#compile) to compile and evaluate a query.\n- [`parse`](#parse) to parse a query in text format into JSON.\n- [`stringify`](#stringify) to convert a query in JSON into the text format.\n- [`buildFunction`](#buildfunction) a helper function to create a custom function.\n\n### jsonquery\n\nThe function `jsonquery` allows to pass data and a query in one go and parse, compile and execute it:\n\n```text\njsonquery(data: JSON, query: string | JSONQuery, options: JSONQueryOptions) : JSON\n```\n\nHere:\n\n- `data` is the JSON document that will be queried, often an array with objects.\n- `query` is a JSON document containing a [JSON query](https://jsonquerylang.org/docs/), either the text format or the parsed JSON format.\n- `options` is an optional object that can contain the following properties:\n  - `functions` is an optional map with custom function creators. A function creator has optional arguments as input and must return a function that can be used to process the query data. For example:\n\n      ```js\n      const options = {\n        functions: {\n          // usage example: 'times(3)'\n          times: (value) =\u003e (data) =\u003e data.map((item) =\u003e item * value)\n        }\n      }\n      ```\n\n      If the parameters are not a static value but can be a query themselves, the function `compile` can be used to compile them. For example, the actual implementation of the function `filter` is the following:\n\n      ```js\n      const options = {\n        functions: {\n          // usage example: 'filter(.age \u003e 20)'\n          filter: (predicate) =\u003e {\n            const _predicate = compile(predicate)\n            return (data) =\u003e data.filter(_predicate)\n          }\n        }\n      }\n      ```\n\n      You can have a look at the source code of the functions in `/src/functions.ts` for more examples.\n  - `operators` is an optional map with operators, for example `{ eq: '==' }`. The defined operators can be used in a text query. Only operators with both a left and right hand side are supported, like `a == b`. They can only be executed when there is a corresponding function. For example:\n\n      ```js\n      import { buildFunction } from 'jsonquery'\n      \n      const options = {\n        operators: {\n          notEqual: '\u003c\u003e'\n        },\n        functions: {\n          notEqual: buildFunction((a, b) =\u003e a !== b)\n        }\n      }\n      ```\n\nHere an example of using the function `jsonquery`:\n\n```js\nimport { jsonquery } from '@jsonquerylang/jsonquery'\n\nconst data = [\n  { \"name\": \"Chris\", \"age\": 23 },\n  { \"name\": \"Emily\", \"age\": 19 },\n  { \"name\": \"Joe\", \"age\": 32 }\n]\n\nconst result = jsonquery(data, [\"filter\", [\"gt\", [\"get\", \"age\"], 20]])\n// result = [\n//   { \"name\": \"Chris\", \"age\": 23 },\n//   { \"name\": \"Joe\", \"age\": 32 }\n// ]\n```\n\n### compile\n\nThe compile function compiles and executes a query in JSON format. Function `parse` can be used to parse a text query into JSON before passing it to `compile`.\n\n```text\ncompile(query: JSONQuery, options: JSONQueryOptions) =\u003e (data: JSON) =\u003e JSON\n```\n\nExample:\n\n```js\nimport { compile } from '@jsonquerylang/jsonquery'\n\nconst queryIt = compile([\"filter\", [\"gt\", [\"get\", \"age\"], 20]])\n\nconst data = [\n  { \"name\": \"Chris\", \"age\": 23 },\n  { \"name\": \"Emily\", \"age\": 19 },\n  { \"name\": \"Joe\", \"age\": 32 }\n]\n\nconst result = queryIt(data)\n// result = [\n//   { \"name\": \"Chris\", \"age\": 23 },\n//   { \"name\": \"Joe\", \"age\": 32 }\n// ]\n```\n\n### parse\n\nFunction `parse` parses a query in text format into JSON. Function `stringify` can be used to do the opposite.\n\n```text\nparse(query: text, options: JSONQueryParseOptions) : JSONQuery\n```\n\nExample:\n\n```js\nimport { parse } from '@jsonquerylang/jsonquery'\n\nconst text = 'filter(.age \u003e 20)'\nconst json = parse(text)\n// json = [\"filter\", [\"gt\", [\"get\", \"age\"], 20]]\n```\n\n### stringify\n\nFunction `stringify` turns a query in JSON format into the equivalent text format. Function `parse` can be used to parse the text into JSON again.\n\n```text\nstringify(query: JSONQuery, options: JSONQueryStringifyOptions) : string\n```\n\nExample:\n\n```js\nimport { stringify } from '@jsonquerylang/jsonquery'\n\nconst json = [\"filter\", [\"gt\", [\"get\", \"age\"], 20]]\nconst text = stringify(json)\n// text = 'filter(.age \u003e 20)'\n```\n\n### buildFunction\n\nThe function `buildFunction` is a helper function to create a custom function. It can only be used for functions (mostly operators), not for methods that need access the previous data as input.\n\nThe query engine passes the raw arguments to all functions, and the functions have to compile the arguments themselves when they are dynamic. For example:\n\n```ts\nconst options = {\n  operators: {\n    notEqual: '\u003c\u003e'\n  },\n  functions: {\n    notEqual: (a: JSONQuery, b: JSONQuery) =\u003e {\n      const aCompiled = compile(a)\n      const bCompiled = compile(b)\n\n      return (data: unknown) =\u003e {\n        const aEvaluated = aCompiled(data)\n        const bEvaluated = bCompiled(data)\n\n        return aEvaluated !== bEvaluated\n      }\n    }\n  }\n}\n\nconst data = { x: 2, y: 3}\nconst result = jsonquery(data, '(.x + .y) \u003c\u003e 6', options) // true\n```\n\nTo automatically compile and evaluate the arguments of the function, the helper function `buildFunction` can be used:\n\n```ts\nimport { jsonquery, buildFunction } from '@jsonquerylang/jsonquery'\n\nconst options = {\n  operators: {\n    notEqual: '\u003c\u003e'\n  },\n  functions: {\n    notEqual: buildFunction((a: number, b: number) =\u003e a !== b)\n  }\n}\n\nconst data = { x: 2, y: 3}\nconst result = jsonquery(data, '(.x + .y) \u003c\u003e 6', options) // true\n```\n\n### error handling\n\nWhen executing a query throws an error, the library attaches a stack to the error message which can give insight in what went wrong. The stack can be found at the property `error.jsonquery` and has type `Array\u003c{ data: unknown, query: JSONQuery }\u003e`.\n\n```js\nconst data = {\n  \"participants\": [\n    { \"name\": \"Chris\", \"age\": 23, \"scores\": [7.2, 5, 8.0] },\n    { \"name\": \"Emily\", \"age\": 19 },\n    { \"name\": \"Joe\", \"age\": 32, \"scores\": [6.1, 8.1] }\n  ]\n}\n\ntry {\n  jsonquery(data, [\n    [\"get\", \"participants\"],\n    [\"map\", [[\"get\", \"scores\"], [\"sum\"]]]\n  ])\n} catch (err) {\n  console.log(err.jsonquery)\n  // error stack:\n  // [\n  //   {\n  //     \"data\": {\n  //       \"participants\": [\n  //         { \"name\": \"Chris\", \"age\": 23, \"scores\": [7.2, 5, 8.0] },\n  //         { \"name\": \"Emily\", \"age\": 19 },\n  //         { \"name\": \"Joe\", \"age\": 32, \"scores\": [6.1, 8.1] }\n  //       ]\n  //     },\n  //     \"query\": [\n  //       [\"get\", \"participants\"],\n  //       [\"map\", [[\"get\", \"scores\"], [\"sum\"]]]\n  //     ]\n  //   },\n  //   {\n  //     \"data\": [\n  //       { \"name\": \"Chris\", \"age\": 23, \"scores\": [7.2, 5, 8.0] },\n  //       { \"name\": \"Emily\", \"age\": 19 },\n  //       { \"name\": \"Joe\", \"age\": 32, \"scores\": [6.1, 8.1] }\n  //     ],\n  //     \"query\": [\"map\", [[\"get\", \"scores\"], [\"sum\"]]]\n  //   },\n  //   {\n  //     \"data\": { \"name\": \"Emily\", \"age\": 19 },\n  //     \"query\": [[\"get\", \"scores\"], [\"sum\"]]\n  //   },\n  //   {\n  //     \"data\" : undefined,\n  //     \"query\": [\"sum\"]\n  //   }\n  // ]\n}\n```\n\n## Command line interface (CLI)\n\nWhen `jsonquery` is installed globally using npm, it can be used on the command line. To install `jsonquery` globally:\n\n```bash\n$ npm install -g @jsonquerylang/jsonquery\n```\n\nUsage:\n\n```\n$ jsonquery [query] {OPTIONS}\n```\n\nOptions:\n\n```\n--input         Input file name\n--query         Query file name\n--output        Output file name\n--format        Can be \"text\" (default) or \"json\"\n--indentation   A string containing the desired indentation, \n                like \"  \" (default) or \"    \" or \"\\t\". An empty\n                string will create output without indentation.\n--overwrite     If true, output can overwrite an existing file\n--version, -v   Show application version\n--help,    -h   Show this message\n```\n\nExample usage:\n\n```\n$ jsonquery --input users.json 'sort(.age)'\n$ jsonquery --input users.json 'filter(.city == \"Rotterdam\") | sort(.age)'\n$ jsonquery --input users.json 'sort(.age)' \u003e output.json\n$ jsonquery --input users.json 'sort(.age)' --output output.json\n$ jsonquery --input users.json --query query.txt\n$ jsonquery --input users.json --query query.json --format json\n$ cat users.json | jsonquery 'sort(.age)'\n$ cat users.json | jsonquery 'sort(.age)' \u003e output.json\n```\n\n## Development\n\n### JavaScript \n\nTo develop, check out the JavaScript repo, install dependencies once, and then use the following scripts:\n\n```text\nnpm run test\nnpm run test-ci\nnpm run lint\nnpm run format\nnpm run coverage\nnpm run build\nnpm run build-and-test\n```\n\nNote that a new package is published on [npm](https://www.npmjs.com/package/@jsonquerylang/jsonquery) and [GitHub](https://github.com/jsonquerylang/jsonquery/releases) on changes pushed to the `main` branch. This is done using [`semantic-release`](https://github.com/semantic-release/semantic-release), and we do not use the `version` number in the `package.json` file. A changelog can be found by looking at the [releases on GitHub](https://github.com/jsonquerylang/jsonquery/releases).\n\n## License\n\nReleased under the [ISC license](LICENSE.md).\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonquerylang%2Fjsonquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsonquerylang%2Fjsonquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonquerylang%2Fjsonquery/lists"}