comment-json

All arrays within a parsed object are instances of CommentArray. These special arrays automatically handle comment symbol properties when modified using standard array methods like .unshift(), .push(), etc.

Warning: If you reassign a property that was a CommentArray to a standard JavaScript array, all associated comments will be lost. To maintain comments when creating new arrays, you must wrap the new data in a new CommentArray().

const {parse, stringify, CommentArray} = require('comment-json')

const parsed = parse(`{
  "foo": [
    // bar
    "bar",
    // baz,
    "baz"
  ]
}`)

// Correct way to reassign while preserving comments:
parsed.foo = new CommentArray('quux').concat(parsed.foo)

stringify(parsed, null, 2)
// {
//   "foo": [
//     "quux",
//     // bar
//     "bar",
//     // baz
//     "baz"
//   ]
// }

The library implements the TC39 proposal-json-parse-with-source. This allows you to use a reviver function in parse() that receives the original string source as a third argument, which is useful for parsing BigInt values.

When using stringify(), you can handle BigInt values by using JSON.rawJSON() (available in Node.js >= 21) to ensure they are written correctly to the output string.

const {parse, stringify} = require('comment-json')

// Parsing BigInts using the source argument
const parsed = parse(
  `{"foo": 9007199254740993}`,
  (key, value, {source}) =>
    /^[0-9]+$/.test(source) ? BigInt(source) : value
)

// Stringifying BigInts using JSON.rawJSON
stringify(parsed, (key, val) =>
  typeof val === 'bigint'
    ? JSON.rawJSON(String(val))
    : val
)
// {"foo": 9007199254740993}

Install the package using npm to enable parsing and stringifying JSON with comments.

$ npm i comment-json

Use parse to convert a JSON string with comments into a JavaScript object. The comments are preserved as Symbol properties on the object. Use stringify to convert the object back into a JSON string, which will include the original comments.

const { parse, stringify } = require('comment-json')
const fs = require('fs')

// Parse a file containing comments
const obj = parse(fs.readFileSync('package.json').toString())

console.log(obj.name) // Access standard properties normally

// Stringify back to a string, preserving comments
const output = stringify(obj, null, 2)

To sort the keys of a JSON file without losing comments, use parse to load the object, then use assign to copy properties into a new object following a specific key order (e.g., from Object.keys().sort()).

const { parse, assign, stringify } = require('comment-json')

const parsed = parse(`{
  // b
  "b": 2,
  // a
  "a": 1
}`)

// Copy properties including comments to a new object in sorted order
const sorted = assign(
  {},
  parsed,
  Object.keys(parsed).sort()
)

console.log(stringify(sorted, null, 2))
// {
//   // a
//   "a": 1,
//   // b
//   "b": 2
// }

The stringify() method converts an object back into a JSON string. It behaves similarly to the vanilla JSON.stringify(), but it also handles extra properties used to store comments and converts them into actual JSON comments.

Note on spacing: If the space argument is not specified or is an empty string, the resulting string will contain no comments. To preserve comments and formatting, provide a space value (e.g., 2).

stringify(object: any, replacer?, space?): string

// Preserving comments with indentation
console.log(stringify(parsed, null, 2))

// No comments if space is not specified
console.log(stringify(result)) // {"a":1}

To query comments in a TypeScript environment, use the CommentDescriptor type to define the symbol name and cast the result of Symbol.for() to CommentSymbol to enable type detection.

import {
  CommentDescriptor, 
  CommentSymbol, 
  parse, 
  CommentArray
} from 'comment-json'

const parsed = parse(`{ /* test */ "foo": "bar" }`)
// Use CommentDescriptor to ensure properly formatted symbol names
const symbolName: CommentDescriptor = 'before:foo'

// Casting to CommentSymbol is mandatory for TS to detect the query
const comment = (parsed as CommentArray<string>)[Symbol.for(symbolName) as CommentSymbol][0].value

The removeComments() method removes comments from a specific location within an object.

Parameters:

• target: The object to remove comments from.
• location: An object specifying where (a CommentPrefix) and optionally key (for property-specific comments).

const {parse, stringify, removeComments} = require('comment-json')

const obj = parse(`{
  // comment before foo
  "foo": 1, // comment after foo
  "bar": 2
}`)

// Remove comment before 'foo'
removeComments(obj, { where: 'before', key: 'foo' })

console.log(stringify(obj, null, 2))
// {
//   "foo": 1, // comment after foo
//   "bar": 2
// }