jq-wasm

jq-wasm

jq-wasm is a WebAssembly-powered version of the powerful jq JSON processor, built using Emscripten. It brings the versatility of jq to Node.js, modern browsers, and edge runtimes like Cloudflare Workers without any native dependencies.

Features

• Cross-Platform: One import runs jq in Node.js (ESM + CommonJS), browsers/bundlers, and Cloudflare Workers / Vercel Edge — the right build is auto-selected via package exports.
• No Native Dependencies: Everything runs in WebAssembly.
• Fully Typed: Comes with TypeScript definitions for a great developer experience.
• Familiar jq Syntax: Use standard jq queries and command-line flags.

Installation

Install via npm:

npm install jq-wasm

or with Yarn:

yarn add jq-wasm

Usage

const jq = require("jq-wasm");
// or, with ES modules:
// import * as jq from "jq-wasm";

(async () => {
  try {
    // Example JSON input
    const json = { foo: "bar", list: [1, 2, 3] };

    // Using jq.raw for raw output.
    // It returns an object with stdout, stderr, and exitCode.
    const rawResult = await jq.raw(json, ".list | .[]", ["-c"]);
    console.log("STDOUT:", rawResult.stdout);
    console.log("STDERR:", rawResult.stderr);
    console.log("Exit Code:", rawResult.exitCode);

    // Using jq.json for parsed output.
    // It automatically throws if there is any stderr output.
    const result = await jq.json(json, ".foo");
    console.log("Parsed Output:", result);
  } catch (err) {
    console.error("Error:", err.message);
  }
})();

Platform support

The same import works everywhere — the correct build is selected automatically via package.json export conditions, so there's no platform-specific entry point to remember:

Environment	Notes
Node.js (ESM & CommonJS), Bun	Works out of the box; jq.wasm is read from the installed package.
Vite, webpack, Rollup	jq.wasm is emitted automatically via new URL(..., import.meta.url).
Cloudflare Workers, Vercel Edge	Auto-selected via the workerd / edge-light conditions — no /edge import path needed.
Browsers via CDN / native ESM	jq.wasm is fetched from the package, alongside the module.
Single-file bundles (jq-wasm/inline)	A Node server bundled with esbuild/webpack/ncc, a browser app bundled with esbuild, or no bundler at all — the wasm is embedded, so there's no separate asset to resolve or serve (larger payload, no streaming compilation).

Note: the default Node and browser builds load jq.wasm as a separate file — via fs on Node, new URL(..., import.meta.url) in browsers. If you bundle your app into a single self-contained file, that asset isn't emitted or found: esbuild doesn't copy new URL(...) assets (evanw/esbuild#795), and a bundled Node server loses the package-relative jq.wasm path. Import the embedded entry instead:

import { json } from "jq-wasm/inline";

API

jq.raw(json, query, [flags])

Executes a jq query and returns the raw output along with error and exit code information.

Parameters

• json: A JSON object, array, or string. Non-string values are automatically stringified.
• query: A jq query string (e.g., .foo, .[]).
• flags (optional): An array of jq command-line flags (e.g., ["-c"] for compact output).

Returns

A Promise that resolves to an object with:

• stdout: The raw output string from jq.
• stderr: Any error messages generated by jq.
• exitCode: The exit code returned by jq.

⸻

jq.json(json, query, [flags])

Executes a jq query and returns the parsed JSON result.

Parameters

• json: A JSON object, array, or string. Non-string values are automatically stringified.
• query: A jq query string.
• flags (optional): An array of jq flags (e.g., ["-c"] for compact output).

Returns

A Promise that resolves to:

• A single parsed JSON object or array if jq produces one result.
• An array of parsed JSON objects or arrays if jq produces multiple newline-separated results.
• null if no output is produced.

Note: If jq produces any stderr output, jq.json will throw an error.

jq.version()

Returns the underlying jq version string.

Returns

A Promise that resolves to the jq version string (e.g., "jq-1.7.1").

License

This project is licensed under the MIT License.

Contributions

Contributions, issues, and feature requests are welcome! Feel free to check out the issues page.