Home

Awesome

jq-wasm

A revamped version of jq-web, the Javascript/WebAssembly build of jq

Quickstart

var newJQ = require('jq-wasm')
const jq = await newJQ()
const output = await jq.invoke('{"jq": {"is": "awesome"}}', ".jq.is")
// "awesome"

Installation

The easiest way is to download the build output directly from the releases page:

FileDescription
jq.wasm.jsJavascript interface for interacting with JQ
jq.wasm.min.jsSame as jq.wasm.js, but minified
jq.wasmJQ WebAssembly binary, loaded by jq.wasm.js and jq.wasm.min.js
jq.wasm.d.tsTypescript types definition

Reference

newJQ(module?): Promise<JQ>

Return a promise that resolves into a JQ instance after the WebAssembly runtime has been initialized.

It accepts an optional module object to overwrite emscripten default parameters.
Example: customize the path of the wasm file with newJQ({locateFile: () => "path/to/jq.wasm"})

For a complete list of available options, see the emscripten official documentation

jq.invoke(input, filter, options): Promise<string>

Run jq and return the content of stdout on success.
It's equivalent to echo <input> | jq <options> <filter>

Build

  1. Install Emscripten from source
  2. Clone jq-wasm and cd into it
  3. Look over the Makefile for more Emscripten instructions
  4. make (...and go grab a coffe while you wait)

Known issues

Error when loading .wasm files

By default projects compiled with Emscripten look for .wasm files in the same directory that the .js file is run from. This causes issues when using webpack because name of the .wasm file is altered with a hash and can be placed in a different directory. To fix this problem you can use the copy-webpack-plugin to copy the jq.wasm file to the same directory that the webpack bundle is placed.

Error when invoking more than once in the browser

The JQ instance in theory can be used more than once. For some yet unknown reason this is not the case when running JQ in the browser. The solution at the moment is to create a new instance each time you need it: newJQ({noExitRuntime: false})