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 and modern browsers without any native dependencies.

🚀 Features

• Cross-Platform: Run jq seamlessly in Node.js and browsers.
• 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);
  }
})();

📖 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.