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:

{
  "abc:name": "Test",
  "abc: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