Human JSON - Better JSON experience with HJSON

Dealing with JSON is not usually the first and most important bottleneck of any project. This is one reason why most people are using JSON as it is.

But making the switch from JSON to HJSON has various advantages:

Readability

This is how HJSON file looks like:

scripts: {
  test: mocha --recursive "./test/test-*.js"
  cover: istanbul cover -R spec --recursive "./test/test-*.js"
}

Notice that we don't have to write double quotes and commas, as they are inserted when compiling the HJSON file. By removing the need for quotes and commas, our HJSON file is more readable than its JSON counterpart.

Editability

As much as readability is important, changing your workflow just because of that is overengineering. More important is that when using HJSON, you will decrease your errors when editing JSON files.

Comments

I can't say that was my dream to write comments in my JSON files, but once I was able to do that, it felt just like fulfilling a dream.

// npm run colors blue 333 afafe7 3
// blue: colorName | 333: firstColor | 777: secondColor | 3: numberColors

colors: node /home/just/ils/service/colors.js

// run jsxFormat service for the latest React.js dev file

jsx: node --harmony-async-await service/jsx

How to use HJSON?

To compile HJSON to JSON we need the HJSON npm package. I will add some formatting, as I want my final JSON file to be readable. I do that with json-format npm package.

hjsonParse.js

const J = require("./common")
var R = require("ramda")
var Hjson = require("hjson")
var jsonFormat = require("./jsonFormat")

async function main(filepath) {
    try {
        let output = R.replace(".hjson", ".json", filepath)
        let beforeState = await J.readFile(filepath)
        let afterState = Hjson.parse(beforeState)
        afterState = jsonFormat.string(afterState)
        await J.writeFile(output, afterState)
        return true
    } catch (error) {
        console.error(error)
        return error
    }
}
main("package.hjson").then(console.log)

common.js

const fs = require("fs")
function readFile(filepath) {
    return new Promise((resolve, reject)=>{
        fs.readFile(filepath, "utf8", (err, data) => {
            if (err) {
                reject(err)
            }
            resolve(data)
        })
    })
}
function writeFile(filepath, data) {
    return new Promise((resolve, reject)=>{
        fs.writeFile(filepath, data, (err) => {
            if (err) {
                reject(err)
            }
            resolve(true)
        })
    })
}

jsonFormat.js

var jsonFormat = require("json-format")

function string(str) {
    try {
        return jsonFormat(str)
    } catch (error) {
        return error
    }
}

module.exports.string = string

Now we run with Node.js v7 node --harmony-async-await hjsonParse.js and the file package.hjson will be compiled and formated to package.json

My blog