4.0.4 (breaking, but ok): assign: special copying rules according to argument keys, related to #26

Author: kaelzhang

README.md

@@ -413,7 +413,8 @@ console.log(stringify(result, null, 2)) // is the same as `code`
 This method is used to copy the enumerable own properties and their corresponding comment symbol properties to the target object.
 
 ```js
-const parsed = parse(`{
+const parsed = parse(`// before all
+{
   // This is a comment
   "foo": "bar"
 }`)
@@ -423,13 +424,53 @@ const obj = assign({
 }, parsed)
 
 stringify(obj, null, 2)
+// // before all
 // {
 //   "bar": "baz",
 //   // This is a comment
 //   "foo": "bar"
 // }
 ```
 
+### Special cases about `keys`
+
+But if argument `keys` is specified and is not empty, then comment ` before all`, which belongs to no properties, will **NOT** be copied.
+
+```js
+const obj = assign({
+  bar: 'baz'
+}, parsed, ['foo'])
+
+stringify(obj, null, 2)
+// {
+//   "bar": "baz",
+//   // This is a comment
+//   "foo": "bar"
+// }
+```
+
+Specifying the argument `keys` as an empty array indicates that it will only copy non-property symbols of comments
+
+```js
+const obj = assign({
+  bar: 'baz'
+}, parsed, [])
+
+stringify(obj, null, 2)
+// // before all
+// {
+//   "bar": "baz",
+// }
+```
+
+Non-property symbols includes:
+
+```js
+Symbol.for('before-all')
+Symbol.for('before')
+Symbol.for('after-all')
+```
+
 ## `CommentArray`
 
 > Advanced Section

package.json

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

src/common.js

@@ -131,10 +131,14 @@ module.exports = {
 
     if (keys === UNDEFINED) {
       keys = Object.keys(source)
-      // We only assign non-property comments if there `keys` are not specified
+      // We assign non-property comments
+      // if argument `keys` is not specified
       assign_non_prop_comments(target, source)
     } else if (!isArray(keys)) {
       throw new TypeError('keys must be array or undefined')
+    } else if (keys.length === 0) {
+      // Or argument `keys` is an empty array
+      assign_non_prop_comments(target, source)
     }
 
     return assign(target, source, keys)

test/others.test.js

@@ -114,6 +114,25 @@ test('#26: non-property comments', t => {
     'should assign non-property comments if no keys'
   )
 
+  t.is(
+    stringify(
+      assign(
+        {
+          a: 1
+        },
+        parsed,
+        []
+      ),
+      null, 2
+    ),
+    `// before all
+{
+  "a": 1
+}
+// after all`,
+    'should assign non-property comments if keys is an empty array'
+  )
+
   t.is(
     stringify(
       assign(