https://github.com/jliocsar/jstr
ð Simple JavaScript CLI tool to read and parse JSON files.
https://github.com/jliocsar/jstr
cli javascript json manipulation object parsing terminal ts-belt typescript
Last synced: 4 months ago
JSON representation
ð Simple JavaScript CLI tool to read and parse JSON files.
- Host: GitHub
- URL: https://github.com/jliocsar/jstr
- Owner: jliocsar
- License: mit
- Created: 2023-08-23T00:58:39.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-12-26T22:09:11.000Z (6 months ago)
- Last Synced: 2026-02-18T10:40:22.867Z (4 months ago)
- Topics: cli, javascript, json, manipulation, object, parsing, terminal, ts-belt, typescript
- Language: JavaScript
- Homepage:
- Size: 621 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.md
Awesome Lists containing this project
README
# jstr
[](https://jliocsar.gitbook.io/jstr)
[](#)
[](https://www.npmjs.com/package/@jliocsar/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`](https://mobily.github.io/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
**JS**ON S**tr**ingifier (`jstr`, pronounced as _jester_) is a CLI tool built with JavaScript & [`ts-belt`](https://mobily.github.io/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.
[](https://www.buymeacoffee.com/jliocsar)
## Requirements
To run `jstr`, you must have either [Node.js](https://nodejs.org/en/blog/release/v18.0.0) or [Bun](https://bun.sh/blog/bun-v1.0) ^v1.0.0 installed.
## Installation
```sh
npm i -g @jliocsar/jstr
```
To make sure it installed successfully:
```sh
jstr --version
```
### Bun version
`jstr` also exposes a version to run with [`Bun`](https://github.com/oven-sh/bun):
```sh
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](https://jliocsar.gitbook.io/jstr/)
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](https://www.npmjs.com/package/notation))
**Example:**
Input (`./package.json` file):
```json
{ "name": "Test", "devDependencies": { "pkg": "1.0.0" } }
```
```sh
jstr -s 2 -m '{"devDependencies.pkg":"devDependencies.foo"}' --prefix "bar:" package.json
```
Output:
```json
{
"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`):
```json
{
"coordinates": {
"latitude": 20,
"longitude": 20
}
}
```
```sh
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`:
```js
({ coordinates: { latitude, longitude } }) => [latitude, longitude]
```
**Output:**
```json
[20, 20]
```
### Evolve JSON files
You can also use `jstr` to remake JSON files:
**Example:**
Input (`./package.json` file):
```json
{ "name": "Test", "devDependencies": { "pkg": "1.0.0" } }
```
```sh
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):
```json
{
"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):
```json
[
{
"name": "Tiny",
"age": 27,
"friends": [{ "name": "Other" }]
},
{
"name": "Tim",
"age": 28,
"friends": [
{ "name": "Some" },
{ "name": "Friend" }
]
}
]
```
```sh
jstr users.json --csv "flow(A.map(D.get('friends')), A.flat)" > users.csv
```
Output (`./users.csv` file):
```csv
name
Other
Some
Friend
```
### API Usage
You can call `jstr` from your Node.js script through its API:
**Example:**
```js
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](https://www.freepik.com/)