feat: new public method, moveComments

kaelzhang · kaelzhang · commit b78f84ccd91a · 2025-12-11T12:39:15.000+08:00
diff --git a/README.md b/README.md
@@ -461,7 +461,7 @@ stringify(obj, null, 2)
 
 ### 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.
+But if argument `keys` is specified and is not empty, then comment ` before all`, which belongs to non-properties, will **NOT** be copied.
 
 ```js
 const obj = assign({
@@ -495,6 +495,7 @@ Non-property symbols include:
 ```js
 Symbol.for('before-all')
 Symbol.for('before')
+Symbol.for('after')      // only for stringify
 Symbol.for('after-all')
 ```
 
diff --git a/index.d.ts b/index.d.ts
@@ -111,3 +111,16 @@ export function assign<TTarget, TSource>(
   // we set the type of `keys` stricter
   keys?: readonly (number | string)[]
 ): TTarget
+
+export function moveComments(
+  source: CommentJSONValue,
+  target: CommentJSONValue,
+  from: {
+    kind: string,
+    key?: string
+  },
+  to: {
+    kind: string,
+    key?: string
+  }, override?: boolean
+): void
diff --git a/src/common.js b/src/common.js
@@ -41,6 +41,9 @@ const COLON = ':'
 const UNDEFINED = undefined
 
 const symbol = (prefix, key) => Symbol.for(prefix + COLON + key)
+const symbol_checked = (prefix, key) => key
+  ? symbol(prefix, key)
+  : prefix
 
 const define = (target, key, value) => Object.defineProperty(target, key, {
   value,
@@ -164,6 +167,7 @@ module.exports = {
 
   is_raw_json,
 
+  // TODO: js doc and usage examples
   assign (target, source, keys) {
     if (!isObject(target)) {
       throw new TypeError('Cannot convert undefined or null to object')
@@ -174,17 +178,68 @@ module.exports = {
     }
 
     if (keys === UNDEFINED) {
+      // Copy all comments from source to target, including:
+      // - non-property comments
+      // - property comments
+
       keys = Object.keys(source)
       // 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) {
+      // Copy all non-property comments from source to target
+
       // Or argument `keys` is an empty array
       assign_non_prop_comments(target, source)
     }
 
+    // Copy specified property comments from source to target
     return assign(target, source, keys)
+  },
+
+  // TODO: js doc and usage examples
+  moveComments (source, target, {
+    kind: from_kind,
+    key: from_key
+  }, {
+    kind: to_kind,
+    key: to_key
+  }, override = false) {
+    if (!isObject(source)) {
+      throw new TypeError('source must be an object')
+    }
+
+    if (!target) {
+      target = source
+    }
+
+    if (!isObject(target)) {
+      // No target to move to
+      return
+    }
+
+    const from_prop = symbol_checked(from_kind, from_key)
+    const to_prop = symbol_checked(to_kind, to_key)
+
+    if (!Object.hasOwn(source, from_prop)) {
+      return
+    }
+
+    const source_comments = source[from_prop]
+    delete source[from_prop]
+
+    if (override || !Object.hasOwn(target, to_prop)) {
+      // Override
+      // or the target has no existing comments
+      define(target, to_prop, source_comments)
+      return
+    }
+
+    const target_comments = target[to_prop]
+    if (target_comments) {
+      target_comments.push(...source_comments)
+    }
   }
 }
diff --git a/src/index.js b/src/index.js
@@ -11,7 +11,8 @@ const {
   PREFIX_BEFORE_ALL,
   PREFIX_AFTER_ALL,
 
-  assign
+  assign,
+  moveComments
 } = require('./common')
 
 module.exports = {
@@ -29,5 +30,6 @@ module.exports = {
   tokenize,
 
   CommentArray,
-  assign
+  assign,
+  moveComments
 }
diff --git a/src/parse.js b/src/parse.js
@@ -417,6 +417,7 @@ function walk () {
 
 const isObject = subject => Object(subject) === subject
 
+// TODO: js doc and usage examples
 const parse = (code, rev, no_comments) => {
   // Clean variables in closure
   clean()
diff --git a/src/stringify.js b/src/stringify.js
@@ -332,6 +332,8 @@ const is_primitive_object = subject => {
   return PRIMITIVE_OBJECT_TYPES.includes(str)
 }
 
+// TODO: js doc and usage examples
+
 // @param {function()|Array} replacer
 // @param {string|number} space
 module.exports = (value, replacer_, space) => {

Original file line number	Diff line number	Diff line change
`@@ -332,6 +332,8 @@ const is_primitive_object = subject => {`
`332`	`332`	`return PRIMITIVE_OBJECT_TYPES.includes(str)`
`333`	`333`	`}`
`334`	`334`
	`335`	`+// TODO: js doc and usage examples`
	`336`	`+`
`335`	`337`	`// @param {function()\|Array} replacer`
`336`	`338`	`// @param {string\|number} space`
`337`	`339`	`module.exports = (value, replacer_, space) => {`