comment-json

What is comment-json?

The comment-json npm package allows you to parse, modify, and stringify JSON files while preserving comments. This is particularly useful for configuration files where comments are often used to provide context or instructions.

What are comment-json's main functionalities?

Parsing JSON with comments

This feature allows you to parse JSON strings that include comments. The comments are ignored in the resulting JavaScript object.

const commentJson = require('comment-json');
const jsonWithComments = `{
  // This is a comment
  "key": "value"
}`;
const parsed = commentJson.parse(jsonWithComments);
console.log(parsed); // { key: 'value' }

Stringifying JSON with comments

This feature allows you to convert a JavaScript object back into a JSON string, optionally including comments.

const commentJson = require('comment-json');
const obj = { key: 'value' };
const jsonString = commentJson.stringify(obj, null, 2);
console.log(jsonString); // {
// This is a comment
  "key": "value"
}

Modifying JSON while preserving comments

This feature allows you to modify a parsed JSON object and then convert it back to a JSON string, preserving the original comments.

const commentJson = require('comment-json');
const jsonWithComments = `{
  // This is a comment
  "key": "value"
}`;
let parsed = commentJson.parse(jsonWithComments);
parsed.newKey = 'newValue';
const modifiedJsonString = commentJson.stringify(parsed, null, 2);
console.log(modifiedJsonString); // {
// This is a comment
  "key": "value",
  "newKey": "newValue"
}

Other packages similar to comment-json

json5

JSON5 is a JSON extension that aims to make JSON more human-friendly. It allows comments, trailing commas, and more. However, unlike comment-json, JSON5 does not preserve comments when parsing and stringifying.

hjson

Hjson is a user interface for JSON. It allows comments and is designed to be easy to read and write. Similar to JSON5, Hjson does not preserve comments when converting between JSON and JavaScript objects.

jsonc-parser

The jsonc-parser package is used by Visual Studio Code to handle JSON with comments. It can parse JSON with comments and provide a syntax tree, but it is more complex to use compared to comment-json.

README

comment-json

• Parse JSON strings with comments into JavaScript objects.
• stringify the objects into JSON strings with comments if there are.

The usage of comment-json is exactly the same as the vanilla JSON object.

Install

$ npm install comment-json --save

Usage

package.json:

{
  // package name
  "name": "comment-json"
}

var json = require('comment-json');
var obj = json.parse(fs.readFileSync('package.json').toString());
console.log(obj);
// ->
// {
//   "// name": [["// package name"]],
//   name: "comment-json"
// }

json.stringify(obj, null, 2); // Will be the same as package.json

json.parse(string, [reviver])

The arguments are the same as the vanilla JSON.parse.

Above all, json.parse() is not a parser with 100% accuracy to output an AST which describes every detail of the commented json, including the locations of every comments, whitespaces, etc.

But it DOES work, and could meet most of our requirements to record important informations as fast as possible without making everything too complicated.

Let's jump into a much more integrated case:

code:

/**
 block comment at the top
 */
// comment at the top
{
  // comment for a
  // comment line 2 for a
  /* block comment */
  "a": 1 // comment at right
}
// comment at the bottom

var result = json.parse(code);

Then the result will be:

{
  // Comments at the top of the file
  '//^': [
    '/**\n block comment at the top\n */', 
    '// comment at the top'
  ],

  // Comments at the bottom of the file
  '//$': ['// comment at the bottom'],

  // Comment for a property is the value of `'// <prop>'`
  '// a': [
    // Comments above property `a`
    [
      '// comment for a',
      '// comment line 2 for a',
      '/* block comment */'
    ],
    ['// comment at right']
  ],

  // The real value
  a: 1
}

TL;NR

There are two types of comments:

• single line comment which starts with //
• block comment which is wrapped by /* and */

//^, is the array which contains comments at the top. If there are two lines of comments which start with //, they will be considered as two comment items in the array.

//$, similar to //^, is the comments at the bottom.

// <key>, is a two-dimensional array contains the comments for a certain property key.

• the first item of the array is an array of the comments above the key
• the second item is the comments at the right side of the key

json.stringify(object, [replacer], [space])

The arguments are the same as the vanilla JSON.stringify.

And it does the similar thing as the vanilla one, but also deal with extra properties and convert them into comments.

space

If space is not specified, or the space is an empty string, the result of json.stringify() will be no comments.

For the case above:

console.log( json.stringify(result) ); // {"a":1}
console.log( json.stringify(result, null, 2) ); // is the same as `code`

License

MIT