feat: add JsonObjectNode merge

README.md

@@ -191,6 +191,47 @@ node.update({
 
 The `update` method reconciles the new content with the existing document, preserving comments, indentation, and spacing.
 
+To merge two documents while preserving comments, use the `merge` method:
+
+```ts
+
+const destinationCode = `{
+  // Destination pre-foo comment
+  "foo": "value",
+  // Destination post-foo comment
+  "baz": [1, 2, 3]
+}
+`;
+
+const sourceCode = `{
+  /* Source pre-bar comment */
+  "bar": 123, /* Inline comment */
+  /* Source post-bar comment */
+  "baz": true /* Another inline comment */
+}
+`;
+
+const source = JsonParser.parse(sourceCode, JsonObjectNode);
+const destination = JsonParser.parse(destinationCode, JsonObjectNode);
+
+console.log(JsonObjectNode.merge(source, destination).toString());
+```
+
+Output:
+
+```json5
+{
+  // Destination pre-foo comment
+  "foo": "value",
+  /* Source pre-bar comment */
+  "bar": 123, /* Inline comment */
+  /* Source post-bar comment */
+  "baz": true /* Another inline comment */
+}
+```
+
+The `merge` method removes any existing destination properties that clash with source, along with their leading/trailing trivia, to avoid duplicate keys.
+
 ## Contributing
 
 Contributions are welcome!

src/node/objectNode.ts

@@ -8,6 +8,8 @@ import {JsonPrimitiveNode, JsonStringNode} from './primitiveNode';
 import {JsonValueFactory} from './factory';
 import {JsonIdentifierNode} from './identifierNode';
 import {JsonError} from '../error';
+import { JsonTokenNode } from './tokenNode';
+import { JsonTokenType } from '../token';
 
 export interface JsonObjectDefinition extends JsonCompositeDefinition {
     readonly properties: readonly JsonPropertyNode[];
@@ -33,6 +35,45 @@ export class JsonObjectNode extends JsonStructureNode implements JsonCompositeDe
         });
     }
 
+    public static merge(source: JsonObjectNode, destination: JsonObjectNode): JsonObjectNode {
+        const isTrivia = (node: JsonNode): boolean => {
+            if (!(node instanceof JsonTokenNode)) {
+                return false;
+            }
+            return node.isType(JsonTokenType.LINE_COMMENT)
+                || node.isType(JsonTokenType.BLOCK_COMMENT)
+                || node.isType(JsonTokenType.NEWLINE)
+                || node.isType(JsonTokenType.WHITESPACE);
+        }
+
+        for (const property of source.properties) {
+            const key = property.key.toJSON();
+            const index = destination.children.findIndex(
+                (node) => node instanceof JsonPropertyNode && node.key.toJSON() === key,
+            );
+
+            if (index >= 0) {
+                let startIndex = index;
+                let endIndex = index;
+                while (startIndex > 0 && isTrivia(destination.children[startIndex - 1])) {
+                    startIndex--;
+                }
+                while (endIndex + 1 < destination.children.length && isTrivia(destination.children[endIndex + 1])) {
+                    endIndex++;
+                }
+                destination.children.splice(startIndex, endIndex - startIndex + 1);
+                destination.delete(key);
+            }
+        }
+
+        for (const property of source.properties) {
+            destination.set(property.key, property.value);
+        }
+
+        destination.children.push(...source.children);
+        return destination;
+    }
+
     public update(other: JsonValueNode|JsonValue): JsonValueNode {
         if (!(other instanceof JsonValueNode)) {
             if (typeof other !== 'object' || other === null || Array.isArray(other)) {

test/node/objectNode.test.ts

@@ -381,4 +381,60 @@ describe('ObjectNode', () => {
             key: value,
         });
     });
+
+    it.each([
+		{
+			sourceCode: `{
+                /* Source pre-bar comment */
+                "bar": 123, /* Inline comment */
+                /* Source post-bar comment */
+                "baz": true /* Another inline comment */ }`,
+			destinationCode: `{
+                // Destination pre-foo comment
+                "foo": "value",
+                // Destination post-foo comment
+                "baz": [1, 2, 3] }`,
+			expected: `{			
+                // Destination pre-foo comment
+                "foo": "value",
+                /* Source pre-bar comment */
+                "bar": 123, /* Inline comment */
+                /* Source post-bar comment */
+                "baz": true /* Another inline comment */ }`,
+		},
+		{
+			sourceCode: `{
+                /* Source pre-bar comment */ 
+                "bar": 123, /* Inline comment */
+                /* Source post-bar comment */
+                "baz": true /* Another inline comment */ }`,
+			destinationCode: `{           
+                // Destination pre-foo comment
+                "foo": "value",
+                // Destination post-foo comment
+                "fizz": 42 }`,
+			expected: `{
+                // Destination pre-foo comment
+                "foo": "value",
+                // Destination post-foo comment
+                "fizz": 42,
+                /* Source pre-bar comment */
+                "bar": 123, /* Inline comment */
+                /* Source post-bar comment */
+                "baz": true /* Another inline comment */ }`,
+		},
+	])(
+		'should merge two JsonObjectNode',
+		({ sourceCode, destinationCode, expected }) => {
+			const source = JsonParser.parse(sourceCode, JsonObjectNode);
+			const destination = JsonParser.parse(destinationCode, JsonObjectNode);
+
+			const node = JsonObjectNode.merge(source, destination);
+
+			const removeWhiteSpaces = (str: string) => str.replace(/\s+/g, ' ');
+			expect(removeWhiteSpaces(node.toString())).toStrictEqual(
+				removeWhiteSpaces(expected)
+			);
+		}
+	);
 });