{"id":26720845,"url":"https://github.com/sanack/node-jq","last_synced_at":"2025-05-16T03:04:04.609Z","repository":{"id":9112369,"uuid":"60918486","full_name":"sanack/node-jq","owner":"sanack","description":" Node.js wrapper for jq","archived":false,"fork":false,"pushed_at":"2024-10-01T14:03:58.000Z","size":4851,"stargazers_count":288,"open_issues_count":14,"forks_count":51,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-13T09:08:43.727Z","etag":null,"topics":["jq","json","nodejs"],"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/sanack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["davesnx","mackermans"]}},"created_at":"2016-06-11T17:12:53.000Z","updated_at":"2025-05-11T14:43:33.000Z","dependencies_parsed_at":"2024-01-24T14:28:08.545Z","dependency_job_id":"6d570a40-d51c-44c7-9170-a194a29b83d4","html_url":"https://github.com/sanack/node-jq","commit_stats":{"total_commits":395,"total_committers":28,"mean_commits":"14.107142857142858","dds":0.7468354430379747,"last_synced_commit":"1c2ee5afc17b07cb9be8cc71e73a247e4de0cfe9"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanack%2Fnode-jq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanack%2Fnode-jq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanack%2Fnode-jq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanack%2Fnode-jq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanack","download_url":"https://codeload.github.com/sanack/node-jq/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459084,"owners_count":22074604,"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":["jq","json","nodejs"],"created_at":"2025-03-27T19:25:57.584Z","updated_at":"2025-05-16T03:03:59.598Z","avatar_url":"https://github.com/sanack.png","language":"TypeScript","funding_links":["https://github.com/sponsors/davesnx","https://github.com/sponsors/mackermans"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cbr/\u003e\n\u003cimg width=\"300\" alt=\"node-jq logo\" src=\"docs/assets/logo-with-margin.png\" /\u003e\n\n![https://www.npmjs.com/package/node-jq](https://img.shields.io/npm/dm/node-jq.svg?maxAge=3600)\n![https://www.npmjs.com/package/node-jq](https://img.shields.io/npm/v/node-jq.svg?maxAge=3600)\n![https://codeclimate.com/github/sanack/node-jq/coverage](https://codeclimate.com/github/sanack/node-jq/badges/coverage.svg)\n![https://github.com/sanack/node-jq/actions/workflows/ci.yml](https://github.com/sanack/node-jq/actions/workflows/ci.yml/badge.svg)\n\n[node-jq](https://github.com/sanack/node-jq) is a Node.js wrapper for [jq](https://jqlang.github.io/jq/) - a lightweight and flexible command-line JSON processor\n\n---\n\n## Installation\n\n```bash\n$ npm install node-jq --save\n# or\n$ yarn add node-jq\n```\n\n## Fast\n\nYou can use `jq` directly after installing it:\n\n```bash\nnpx node-jq '.foo' package.json\n```\n\n## Advanced installation\n\nBy default, `node-jq` downloads `jq` during the installation process with a post-install script. Depending on your SO downloads from [https://github.com/jqlang/jq/releases] into `./node_modules/node-jq/bin/jq` to avoid colisions with any global installation. Check #161 #167 #171 for more information. You can safely rely on this location for your installed `jq`, we won't change this path without a major version upgrade.\n\nIf you want to skip the installation step of `jq`, you can set `NODE_JQ_SKIP_INSTALL_BINARY` to `true` or ignore the post-install script from the installation `npm install node-jq --ignore-scripts`.\n\n```bash\nexport NODE_JQ_SKIP_INSTALL_BINARY=true\nnpm install node-jq\n```\n\n```bash\nnpm install node-jq --ignore-scripts\n```\n\n## Usage\n\n### jq example\n\nUsually in your CLI using `jq`:\n\n```bash\njq \".abilities[].moves\" bulbasaur.json\n```\n\nand you get\n\n```bash\n{\n  \"name\": \"heartgold-soulsilver\",\n  \"power\": \"10\"\n}\n{\n  \"name\": \"platinum\",\n  \"power\": \"50\"\n}\n{\n  \"name\": \"diamond-pearl\",\n  \"power\": \"99\"\n}\n```\n\n#### node-jq equivalent\n\nWith `node-jq` you could run it programmatically and interact with the output as a [JavaScript Object](http://javascript.info/tutorial/objects):\n\n\u003e NOTE: Take care of the filter that you are using with `jq`, mapping an array or any other iterative output isn't a valid JavaScript Object, that might fail at parse-time.\n\n```javascript\nconst jq = require('node-jq')\n\nconst filter = '.abilities[].moves'\nconst jsonPath = '/path/to/bulbasaur.json'\nconst options = {}\n\njq.run(filter, jsonPath, options)\n  .then((output) =\u003e {\n    console.log(output)\n    /*\n      {\n        \"name\": \"heartgold-soulsilver\",\n        \"power\": \"10\"\n      },\n      {\n        \"name\": \"platinum\",\n        \"power\": \"50\"\n      },\n      {\n        \"name\": \"diamond-pearl\",\n        \"power\": \"99\"\n      }\n    */\n  })\n  .catch((err) =\u003e {\n    console.error(err)\n    // Something went wrong...\n  })\n```\n\n## Options\n\n### path to jq binary\n\nBy default, the `jq` binary installed with the package is used. If you have special needs or want to use another binary in a different\npath you can set the environment variable `JQ_PATH` to override the binary path.\n\n### input\n\n|  Description  |  Type  |             Values             |  Default |\n|:-------------:|:------:|:------------------------------:|:--------:|\n| Type of input | string | `'file'`, `'json'`, `'string'` | `'file'` |\n\n#### `input: 'file'`\n\nRun the jq query against a **JSON file**.\n\n```javascript\njq.run('.', '/path/to/file.json').then(console.log)\n// { \"foo\": \"bar\" }\n```\n\n#### `input: 'file'` with multiple files\n\nRun jq query against multiple **JSON files**.\n\n```javascript\njq.run('.', ['/path/to/file.json','path/to/other_file.json']).then(console.log)\n// { \"foo\": \"bar\" }\n// { \"otherFoo\": \"andBar\" }\n```\n\n#### `input: 'json'`\n\nRun the `jq` query against an **Object**.\n\n```javascript\njq.run('.', { foo: 'bar' }, { input: 'json' }).then(console.log)\n// { \"foo\": \"bar\" }\n\n```\n\n#### `input: 'string'`\n\nRun the jq query against a **String**.\n\n```javascript\njq.run('.', '{ foo: \"bar\" }', { input: 'string' }).then(console.log)\n// { \"foo\": \"bar\" }\n```\n\n---\n\n### output\n\n| Description    | Values                                        | Default    |\n|:--------------:|:---------------------------------------------:|:----------:|\n| Type of output | `'pretty'`, `'json'`, `'compact'`, `'string'` | `'pretty'` |\n\n#### `output: 'pretty'`\n\nReturn the output as a **String**.\n\n```javascript\njq.run('.', '/path/to/file.json', { output: 'string' }).then(console.log)\n// {\n//   \"foo\": \"bar\"\n// }\n```\n\n#### `output: 'json'`\n\nReturn the output as an **Object**.\n\n```javascript\njq.run('.', '/path/to/file.json', { output: 'json' }).then(console.log)\n// { foo: 'bar' }\n```\n\n#### `output: 'compact'|'string'`\n\nReturn the output as a **String**.\n\n```javascript\njq.run('.', '/path/to/file.json', { output: 'compact' }).then(console.log)\n// {\"foo\":\"bar\"}\njq.run('.', '/path/to/file.json', { output: 'string' }).then(console.log)\n// {\"foo\":\"bar\"}\n```\n\n---\n\n### slurp\n\n|         Description          |     Values      | Default |\n|:----------------------------:|:---------------:|:-------:|\n| Read input stream into array | `true`, `false` | `false` |\n\n#### `slurp: true`\n\nRead input stream into array.\n\n```javascript\njq.run('.', ['/path/to/file.json','/path/to/other_file.json'], { output: 'json', slurp: true }).then(console.log)\n// [\n//   {\n//     \"foo\": \"bar\"\n//   },\n//   {\n//     \"otherFoo\": \"andBar\"\n//   }\n// ]\n```\n\n### sort\n\n|         Description                   |     Values      | Default |\n|:-------------------------------------:|:---------------:|:-------:|\n| Sort object keys in alphabetical order| `true`, `false` | `false` |\n\n#### `sort: true`\n\nSorts object keys alphabetically.\n\n```javascript\njq.run('.', ['/path/to/file.json'], { output: 'json', sort: true }).then(console.log)\n// {\n//   \"a\": 2,\n//   \"b\": 1\n// },\n```\n\n### args\n\n|         Description                   |        Values        |   Default   |\n|:-------------------------------------:|:--------------------:|:-----------:|\n| Send custom args to the jq command    | `[object]`           | `undefined` |\n\n#### `args: { myfruit: { hello: 'orange'}, myfruit2: \"banana\" }`\n\nAdds the `--argjson myfruit \"{ 'hello': 'orange' }\" --arg myfruit2 orange` arguments to the internal jq command\n\n```javascript\njq.run('{\"fruit\":$myfruit,\"fruit2\":$myfruit2}', ['/path/to/file.json'], { output: 'json', sort: true, args: { myfruit: { hello: 'orange' }, myfruit2: \"banana\" } }).then(console.log)\n// {\n//   fruit: { \n//      hello: \"orange\" \n//   },\n//   fruit2: \"banana\"\n// }\n```\n\n### cwd\n\n|           Description            |   Values   |    Default    |\n|:--------------------------------:|:----------:|:-------------:|\n| Set working dir for `jq` process | valid path | process.cwd() |\n\n\n```javascript\njq.run('.', ['file.json'], { output: 'json', sort: true }, '/path/to').then(console.log)\n// {\n//   \"a\": 2,\n//   \"b\": 1\n// },\n```\n\n### detached\n\n|             Description              |     Values      | Default  |\n|:------------------------------------:|:---------------:|:--------:|\n| Run `jq` process as detached process | `true`, `false` | `false`  |\n\nBy default `jq` process will run 'attached' to the main process. That means that any interrupt signal main process receives will be propagated to `jq` process. For example, if main process receives `SIGTERM`, `jq` will also receive it and exit immediately.\n\nHowever, in some cases you might **not** want `jq` to exit immediately and let it exit normally. For example, if you want to implement a graceful shutdown - main process receives `SIGTERM`, it finishes processing current json file and exits after processing is completed.\n\nTo achieve that run `jq` detached and NodeJS will not propagate `SIGTERM` to `jq` process allowing it to run until it completes.\n\n```javascript\njq.run('.', ['file.json'], { output: 'json', sort: true }, undefined, true).then(console.log)\n// {\n//   \"a\": 2,\n//   \"b\": 1\n// },\n```\n\n## Projects using **node-jq**\n\n- **[atom-jq](https://github.com/sanack/atom-jq)**: an [Atom](https://atom.io/) package for manipulating JSON\n- **[json-splora](https://github.com/wellsjo/JSON-Splora)**: an [Electron](http://electron.atom.io/) implementation for manipulating JSON\n- [Check more](https://github.com/sanack/node-jq/network/dependents?package_id=UGFja2FnZS0xNTIxMzU1MQ%3D%3D)\n\n## Why?\n\nWhy would you want to manipulate JavaScript Objects with `jq` inside a nodejs app, when there are tools like [ramda](https://ramdajs.com) or [lodash](lodash.com)?\n\nThe idea was to port `jq` in node to be able to run it as-is. `node-jq` doesn't try to replace `Array`/`Object` filters, maps, transformations, and so on.\n\nOur primary goal was to make `jq` syntax available inside an [Atom](https://atom.io/) extension: [atom-jq](https://github.com/sanack/atom-jq).\n\nOther than that, `jq` is an interesting CLI tool to quickly parse and manipulate the response of an API, such as:\n\n```bash\ncurl 'https://jsonplaceholder.typicode.com/comments' | jq '.[].postId'\n```\n\nThere are also people dealing with complex use-cases, and some of them want to port their bash scripts to node:\n\n- [ilya-sher.org/2016/05/11/most-jq-you-will-ever-need](https://ilya-sher.org/2016/05/11/most-jq-you-will-ever-need/)\n- [cloudadvantage.com.au/new-aws-command-line-tool-and-jq](http://www.cloudadvantage.com.au/new-aws-command-line-tool-and-jq/)\n\n## Want to learn `jq`?\n\nSeems hard to learn, but it really isn't.\n\n`jq` is like `sed` for `JSON`. *Slice*, *filter*, *map* and *transform* structured data in a **simple** and **powerful** way.\n\nTake a look at [this great introduction](https://robots.thoughtbot.com/jq-is-sed-for-json) or a [jq lesson](http://programminghistorian.org/lessons/json-and-jq).\n\nYou can check out the [official manual](https://jqlang.github.io/jq/manual) and fiddle around in the online playground [jqplay.org](https://jqplay.org).\n\n## License\n\n[License](./LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanack%2Fnode-jq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanack%2Fnode-jq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanack%2Fnode-jq/lists"}