jstr

Simple JavaScript CLI tool to read and parse JSON files

• 🪶 Lightweight: Tiny as f*ck, keeping it simple & straightforward;
• ⚡ Fast: Get parsed results or new JSON files in milliseconds;
• 🦣 Functional: Have the benefits of functional programming in your JSON parsing tool (see ts-belt);
• 🙅 No BS: Manipulate results with good ole' JavaScript, no need to learn cryptic languages/libraries -- use what fits you best.
• 🌭 Multi-platform: Runs anywhere -- Linux, macOS & Windows; Read data from your clipboard, file or I/O.

Description

JSON Stringifier (jstr, pronounced as jester) is a CLI tool built with JavaScript & ts-belt to easily parse and manipulate JSON strings or files.

It is a JSON.parse/stringify wrapper focused in CLI commands rather than JS scripts.

Requirements

To run jstr, you must have either Node.js or Bun ^v1.0.0 installed.

Installation

npm i -g @jliocsar/jstr

To make sure it installed successfully:

jstr --version

Bun version

jstr also exposes a version to run with Bun:

jstr.bun --version

Note

Currently jstr runs faster in Node v20 against jstr.bun in Bun 1.0.3.

Keep that in mind if you plan to use the Bun version.

---

Usage

Documentation

Make sure you read the docs! It has all the details about each command option and such.

Map field names

The -m/--map option will rename fields using dot notation (see Notation.js)

Example:

Input (./package.json file):

{ "name": "Test", "devDependencies": { "pkg": "1.0.0" } }

jstr -s 2 -m '{"devDependencies.pkg":"devDependencies.foo"}' --prefix "bar:" package.json

Output:

{
  "bar:name": "Test",
  "bar:devDependencies": { "foo": "1.0.0" }
}

Read from stdin (pipe commands)

The -i/--input option will read the JSON data from stdin rather than the file provided:

Example:

Input (Output from running my-fetch-script.js):

{
  "coordinates": {
    "latitude": 20,
    "longitude": 20
  }
}

node my-fetch-script.js | jstr -s 2 -i \
  -m '{"coordinates.longitude":"longitude","coordinates.latitude":"latitude"}' \
  '({ latitude, longitude }) => [latitude, longitude]'

If you don't want to mess around with the mapping of fields, you can just use pure JS instead and skip the -m option`:

({ coordinates: { latitude, longitude } }) => [latitude, longitude]

Output:

[20, 20]

Evolve JSON files

You can also use jstr to remake JSON files:

Example:

Input (./package.json file):

{ "name": "Test", "devDependencies": { "pkg": "1.0.0" } }

jstr -s 2 -m '{"devDependencies.pkg":"bar"}' --prefix "foo:" package.json \
  "x => {
    x['foo:name'] = x['foo:name'].toUpperCase()
    return x
  }" > my-new-file.json

Output (./my-new-file.json file):

{
  "foo:name": "TEST",
  "foo:bar": "1.0.0"
}

CSV Output

You can provide the --csv flag to format the output to CSV:

Example:

Input (./users.json file):

[
  {
    "name": "Tiny",
    "age": 27,
    "friends": [{ "name": "Other" }]
  },
  {
    "name": "Tim",
    "age": 28,
    "friends": [
      { "name": "Some" },
      { "name": "Friend" }
    ]
  }
]

jstr users.json --csv "flow(A.map(D.get('friends')), A.flat)" > users.csv

Output (./users.csv file):

name
Other
Some
Friend

API Usage

You can call jstr from your Node.js script through its API:

Example:

const { jstr } = require('@jliocsar/jstr/api')

;(async () => {
  console.log(await jstr(
    './my-file.json',
    "x => x['foo:name']",
    { prefix: 'foo:' }
  ))
})()

To do

• Support require of user-defined modules?;
• Get more coffee.

Credits

Logo icon from Freepik