feat: add Document.merge() method

Author: nathanjmcdougall

src/yamltrip/document.py

@@ -543,6 +543,50 @@ def sync(self, *keys: KeyPart, value: Any) -> Document:
             op = _core.Op.replace(value)
             return self._apply_patches([_core.Patch(route=route, operation=op)])
 
+    def merge(self, *keys: KeyPart, value: Any) -> Document:
+        """Merge a value into the mapping at path without removing extra keys.
+
+        Recursively updates matching keys and adds new keys, but never
+        removes existing keys not present in *value*. Lists are replaced
+        entirely (not merged element-wise).
+        """
+        from yamltrip.sync import _compute_patches  # noqa: PLC0415
+
+        normalized = _normalize_keys(keys) if keys else ()
+
+        # If path doesn't exist, delegate to upsert.
+        if normalized:
+            route = _make_route(normalized)
+            if not self._core_doc.query_exists(route):
+                return self.upsert(*normalized, value=value)
+
+        # Get current value and diff
+        try:
+            old_value = self._core_doc.parse_value(_make_route(normalized))
+        except (ValueError, KeyError):
+            return self.upsert(*normalized, value=value)
+
+        # Pre-convert any flow sequences that will be modified.
+        doc: Document = self
+        flow_patches = _flow_seq_replacements(
+            self._core_doc, old_value, value, normalized
+        )
+        if flow_patches:
+            doc = doc._apply_patches(flow_patches)
+            old_value = doc._core_doc.parse_value(_make_route(normalized))
+
+        patches = _compute_patches(old_value, value, normalized, remove_extra=False)
+        if not patches:
+            return doc
+        try:
+            return doc._apply_patches(patches)
+        except PatchError as e:
+            if "expected BlockSequence" not in str(e):
+                raise
+            route = _make_route(normalized)
+            op = _core.Op.replace(value)
+            return self._apply_patches([_core.Patch(route=route, operation=op)])
+
     def find_index(self, *keys: KeyPart, where: dict[str, Any]) -> int | None:
         """Return the index of the first list item matching all key/value pairs.
 

tests/test_merge.py

@@ -0,0 +1,26 @@
+from yamltrip.document import Document
+
+
+class TestMergeMapping:
+    def test_keeps_extra_keys(self):
+        doc = Document("a: 1\nb: 2\nc: 3\n")
+        doc2 = doc.merge(value={"a": 10, "d": 4})
+        assert doc2["a"] == 10
+        assert doc2["b"] == 2
+        assert doc2["c"] == 3
+        assert doc2["d"] == 4
+
+    def test_nested_merge(self):
+        doc = Document("db:\n  host: localhost\n  port: 5432\n  user: admin\n")
+        doc2 = doc.merge("db", value={"port": 3306, "ssl": True})
+        assert doc2["db", "host"] == "localhost"
+        assert doc2["db", "port"] == 3306
+        assert doc2["db", "user"] == "admin"
+        assert doc2["db", "ssl"] is True
+
+    def test_deeply_nested_merge(self):
+        doc = Document("a:\n  b:\n    c: 1\n    d: 2\n  e: 3\n")
+        doc2 = doc.merge("a", value={"b": {"c": 99}})
+        assert doc2["a", "b", "c"] == 99
+        assert doc2["a", "b", "d"] == 2
+        assert doc2["a", "e"] == 3