johan / format-json

A JSON formatter module for various text/plain serialization styles

format-json

A JSON formatter module for various text/plain serialization styles

> var json = require('format-json');
> var data = {test: "for example", some: [{nested:0, things: []}, {}]};
> console.log(json.diffy(data));
{ "test": "for example"
, "some":
  [ { "nested": 0
    , "things": []
    }
  , {}
  ]
}
> console.log(json.plain(data));
{
  "test": "for example",
  "some": [
    {
      "nested": 0,
      "things": []
    },
    {}
  ]
}
> console.log(json.terse(data));
{"test":"for example","some":[{"nested":0,"things":[]},{}]}
> console.log(json.space(data));
{ "test": "for example", "some": [ { "nested": 0, "things": [] }, {} ] }
> console.log(json.lines(data));
{ "test": "for example"
, "some": [ { "nested": 0, "things": [] }, {} ]
}

CLI

We ship a command-line binary format-json. To keep dependencies minimal it comes without an argument processor, so it's very simplistic.

By defaults it works over stdin/stdout, producing diffy output:

$ format-json < path/to/file.json
$ some_pipe_chain | format-json

If you want to specify a formatter, you can use the file-processing variant:

$ format-json [format <terse|plain|space|lines|diffy>] path/to/file.json

Why?

For short: diffs in version controlled JSON is what prompted json.diffy.

The comma-first style may look wonky at first, but it's a compromise that helps produce diffs where a change (addition, change or deletion) of one property has no affect on surrounding lines to reduce the amount of diff noise.

Having used this format for a while now, I also appreciate how you get straight left margins for Objects and Arrays alike.

Not convinced? Then please don't use it! :-)

format-json's Issues

CLI format parameter working?

Hello. I can't pass the "format" option to the CLI format-json. Looks like the code is not ready to handle this:

format-json [format <terse|plain|space|lines|diffy>] path/to/file.json

i.e.

$ ./node_modules/.bin/format-json plain package.json
fs.js:438
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);

Keep empty lines?

JSON is lame enough that it doesn't support comments. The only thing that makes for a bit better readability are empty lines. So I often group properties in my configuration files – like this:

{ "name": "..."
, "version": "..."

, "devDependencies":
  { "cli": "..."
  , "dependencies": "..."

  , "build": "..."
  , "dependencies": "..."
  }
}

format-json swallows these empty lines. Is it possible/reasonable to keep them?

Document CLI

Hi, thanks for this great library. Keeps sanity for JSON files :)

I see you provide a CLI as well as a programmatic API, but I can't find docs for it anywhere. Also running format-json -h or --help is of no help. Have I missed something?