$ npm install node-jq
node-jq is a Node.js wrapper for jq - a lightweight and flexible command-line JSON processor
$ npm install node-jq --save
# or
$ yarn add node-jq
By default, node-jq
downloads jq
during the installation process with a post-install script. Depending on your SO downloads from [https://github.com/stedolan/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.
If 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
.
export NODE_JQ_SKIP_INSTALL_BINARY=true
npm install node-jq
npm install node-jq --ignore-scripts
Usually in your CLI using jq
:
jq ".abilities[].moves" bulbasaur.json
and you get
{
"name": "heartgold-soulsilver",
"power": "10"
}
{
"name": "platinum",
"power": "50"
}
{
"name": "diamond-pearl",
"power": "99"
}
With node-jq
you could run it programmatically and interact with the output as a JavaScript Object:
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.
const jq = require('node-jq')
const filter = '.abilities[].moves'
const jsonPath = '/path/to/bulbasaur.json'
const options = {}
jq.run(filter, jsonPath, options)
.then((output) => {
console.log(output)
/*
{
"name": "heartgold-soulsilver",
"power": "10"
},
{
"name": "platinum",
"power": "50"
},
{
"name": "diamond-pearl",
"power": "99"
}
*/
})
.catch((err) => {
console.error(err)
// Something went wrong...
})
By default, the jq
binary installed with the package is used. If you have special needs or want to use another binary in a different
path you can set the environment variable JQ_PATH
to override the binary path.
Description | Type | Values | Default |
---|---|---|---|
Type of input | string | 'file' , 'json' , 'string' |
'file' |
input: 'file'
Run the jq query against a JSON file.
jq.run('.', '/path/to/file.json').then(console.log)
// { "foo": "bar" }
input: 'file'
with multiple filesRun jq query against multiple JSON files.
jq.run('.', ['/path/to/file.json','path/to/other_file.json']).then(console.log)
// { "foo": "bar" }
// { "otherFoo": "andBar" }
input: 'json'
Run the jq
query against an Object.
jq.run('.', { foo: 'bar' }, { input: 'json' }).then(console.log)
// { "foo": "bar" }
input: 'string'
Run the jq query against a String.
jq.run('.', '{ foo: "bar" }', { input: 'string' }).then(console.log)
// { "foo": "bar" }
Description | Values | Default |
---|---|---|
Type of output | 'pretty' , 'json' , 'compact' , 'string' |
'pretty' |
output: 'pretty'
Return the output as a String.
jq.run('.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {
// "foo": "bar"
// }
output: 'json'
Return the output as an Object.
jq.run('.', '/path/to/file.json', { output: 'json' }).then(console.log)
// { foo: 'bar' }
output: 'compact'|'string'
Return the output as a String.
jq.run('.', '/path/to/file.json', { output: 'compact' }).then(console.log)
// {"foo":"bar"}
jq.run('.', '/path/to/file.json', { output: 'string' }).then(console.log)
// {"foo":"bar"}
Description | Values | Default |
---|---|---|
Read input stream into array | true , false |
false |
slurp: true
Read input stream into array.
jq.run('.', ['/path/to/file.json','/path/to/other_file.json'], { output: 'json', slurp: true }).then(console.log)
// [
// {
// "foo": "bar"
// },
// {
// "otherFoo": "andBar"
// }
// ]
Description | Values | Default |
---|---|---|
Sort object keys in alphabetical order | true , false |
false |
sort: true
Sorts object keys alphabetically.
jq.run('.', ['/path/to/file.json'], { output: 'json', sort: true }).then(console.log)
// {
// "a": 2,
// "b": 1
// },
Why would you want to manipulate JavaScript Objects with jq
inside a nodejs app, when there are tools like ramda or lodash?
The 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.
Our primary goal was to make jq
syntax available inside an Atom extension: atom-jq.
Other than that, jq
is an interesting CLI tool to quickly parse and manipulate the response of an API, such as:
curl 'https://jsonplaceholder.typicode.com/comments' | jq '.[].postId'
There are also people dealing with complex use-cases, and some of them want to port their bash scripts to node:
jq
?Seems hard to learn, but it really isn't.
jq
is like sed
for JSON
. Slice, filter, map and transform structured data in a simple and powerful way.
Take a look at this great introduction or a jq lesson.
You can check out the official manual and fiddle around in the online playground jqplay.org.
© 2010 - cnpmjs.org x YWFE | Home | YWFE