2.1.0: CommentArray

Author: kaelzhang

README.md

@@ -32,6 +32,12 @@ Imagine that if the user settings are saved in `${library}.json`， and the user
 
 So, **if you want to parse a JSON string with comments, modify it, then save it back**, `comment-json` is your must choice!
 
+## How?
+
+`comment-json` parse JSON strings with comments and save comment tokens into [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) properties.
+
+For JSON array with comments, `comment-json` extends the vanilla `Array` object into [`CommentArray`](#commentarray) whose instances could handle comments changes even after a comment array is modified.
+
 ## Install
 
 ```sh
@@ -338,6 +344,80 @@ stringify(obj, null, 2)
 // }
 ```
 
+## `CommentArray`
+
+> Advanced Section
+
+All arrays of the parsed object are `CommentArray`s.
+
+The constructor of `CommentArray` could be accessed by:
+
+```js
+const {CommentArray} = require('comment-json')
+```
+
+If we modify a comment array, its comment symbol properties could be handled automatically.
+
+```js
+const parsed = parse(`{
+  "foo": [
+    // bar
+    "bar",
+    // baz,
+    "baz"
+  ]
+}`)
+
+parsed.foo.unshift('qux')
+
+stringify(parsed, null, 2)
+// {
+//   "foo": [
+//     "qux",
+//     // bar
+//     "bar",
+//     // baz
+//     "baz"
+//   ]
+// }
+```
+
+Oh yeah! 😆
+
+But pay attention, if you reassign the property of a comment array with a normal array, all comments will be gone:
+
+```js
+parsed.foo = ['quux'].concat(parsed.foo)
+stringify(parsed, null, 2)
+// {
+//   "foo": [
+//     "quux",
+//     "qux",
+//     "bar",
+//     "baz"
+//   ]
+// }
+
+// Whoooops!! 😩 Comments are gone
+```
+
+Instead, we should:
+
+```js
+parsed.foo = new CommentArray('quux').concat(parsed.foo)
+stringify(parsed, null, 2)
+// {
+//   "foo": [
+//     "quux",
+//     "qux",
+//     // bar
+//     "bar",
+//     // baz
+//     "baz"
+//   ]
+// }
+```
+
 ## License
 
 [MIT](LICENSE)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-json",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "description": "Parse and stringify JSON with comments. It will retain comments even after saved!",
   "main": "src/index.js",
   "scripts": {

src/array.js

@@ -251,6 +251,30 @@ class CommentArray extends Array {
 
     return ret
   }
+
+  concat (...items) {
+    let {length} = this
+    const ret = super.concat(...items)
+
+    if (!items.length) {
+      return ret
+    }
+
+    items.forEach(item => {
+      const prev = length
+      length += isArray(item)
+        ? item.length
+        : 1
+
+      if (!(item instanceof CommentArray)) {
+        return
+      }
+
+      move_comments(ret, item, 0, item.length, prev)
+    })
+
+    return ret
+  }
 }
 
 module.exports = {

test/array.test.js

@@ -2,7 +2,9 @@ const test = require('ava')
 const {
   isFunction, isObject, isString, isArray
 } = require('core-util-is')
-const {parse, stringify, assign} = require('../src')
+const {
+  parse, stringify, assign, CommentArray
+} = require('../src')
 
 const st = o => stringify(o, null, 2)
 
@@ -217,3 +219,28 @@ test('assign', t => {
   t.throws(() => assign({}, parsed, false), /keys/)
   t.throws(() => assign(), /convert/)
 })
+
+test('concat', t => {
+  const parsed = parse(`[
+  // bar
+  "bar",
+  // baz,
+  "baz"
+]`)
+
+  const concated = new CommentArray('quux').concat(
+    'qux',
+    parsed
+  )
+
+  t.is(stringify(concated, null, 2), `[
+  "quux",
+  "qux",
+  // bar
+  "bar",
+  // baz,
+  "baz"
+]`)
+
+  t.is(stringify(new CommentArray().concat()), '[]')
+})