@pnpm/yaml.document-sync 1100.0.1 → 1100.0.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @pnpm/yaml.document-sync
 
+## 1100.0.2
+
+### Patch Changes
+
+- pnpm now preserves scalar YAML anchors and aliases when editing `pnpm-workspace.yaml`. Removing the entry that defines an anchor keeps surviving aliases valid. Entries updated to different values are written separately [#8245](https://github.com/pnpm/pnpm/issues/8245).
+
+- pnpm now preserves comments and existing key order when updating `package.yaml`. New keys are appended to their mapping [pnpm/pnpm#2008](https://github.com/pnpm/pnpm/issues/2008).
+
 ## 1100.0.1
 
 ### Patch Changes

package/README.md

@@ -60,6 +60,20 @@ qux:
   - 3
 ```
 
+For package manifests, retain null values and empty maps and keep existing keys in their original order:
+
+```ts
+patchDocument(document, target, {
+  preserveKeyOrder: true,
+  preserveScalarAliases: true,
+  pruneEmptyValues: false,
+})
+```
+
+New keys are appended to their mapping. By default, keys follow the target object's order, and null values and empty maps are pruned from existing nodes.
+
+Consumers that use a different conversion for scalar mapping keys can pass `stringifyKey`. For example, `stringifyKey: String` matches `js-yaml`, which exposes a null mapping key as the property name `"null"`. The default follows `yaml` and uses an empty string.
+
 ## Purpose
 
 This package is useful when your codebase:
@@ -164,6 +178,16 @@ bar:
   - 3
 ```
 
+Set `preserveScalarAliases: true` to retain scalar aliases whose final values
+agree. If an anchor's defining entry is removed, the first surviving entry
+defines it. An entry whose value differs from the defining entry is written
+as a scalar. This option does not coordinate dependency updates; it preserves
+YAML representation while applying the supplied target values.
+
+```ts
+patchDocument(document, target, { preserveScalarAliases: true })
+```
+
 ## License
 
 MIT

package/lib/patchDocument.d.ts

@@ -1,5 +1,11 @@
 import yaml from 'yaml';
 export interface PatchDocumentOptions {
+    /** Convert scalar keys to target property names. Defaults to YAML's null-to-empty-string conversion. */
+    readonly stringifyKey?: (key: unknown) => string;
+    /** Keep existing map keys in their original order and append new keys. */
+    readonly preserveKeyOrder?: boolean;
+    /** Remove null values and empty maps. Defaults to true for configuration files. */
+    readonly pruneEmptyValues?: boolean;
     /**
      * Updating aliases is inherently ambiguous since they're not a concept in
      * JSON. The default is to unwrap and remove aliases since that's the most
@@ -12,6 +18,13 @@ export interface PatchDocumentOptions {
      * @default 'unwrap'
      */
     readonly aliases?: 'unwrap' | 'follow';
+    /**
+     * Keep scalar aliases whose final values agree, moving removed anchors to a
+     * surviving entry. Divergent values become independent scalars. When enabled,
+     * this takes precedence over `aliases` for scalar nodes only.
+     * @default false
+     */
+    readonly preserveScalarAliases?: boolean;
 }
 /**
  * Recursively update a YAML document (in-place) to match the contents of a

package/lib/patchDocument.js

@@ -1,4 +1,5 @@
 import yaml from 'yaml';
+import { preserveScalarAliases } from './preserveScalarAliases.js';
 /**
  * Recursively update a YAML document (in-place) to match the contents of a
  * target value.
@@ -11,17 +12,22 @@ export function patchDocument(document, target, options) {
     if (document.errors.length > 0) {
         throw new Error('Document with errors cannot be patched');
     }
+    const restoreAliases = options?.preserveScalarAliases ? preserveScalarAliases(document) : undefined;
     document.contents = patchNode(document.contents, target, {
+        ...options,
         document,
         aliases: options?.aliases ?? 'unwrap',
     });
+    restoreAliases?.();
 }
 function patchNode(node, target, ctx) {
     if (node == null) {
         return ctx.document.createNode(target);
     }
     if (target == null) {
-        return null;
+        if (ctx.pruneEmptyValues !== false)
+            return null;
+        return yaml.isScalar(node) && node.value === target ? node : ctx.document.createNode(target);
     }
     if (yaml.isAlias(node)) {
         return patchAlias(node, target, ctx);
@@ -56,8 +62,7 @@ function patchAlias(alias, target, ctx) {
         case 'unwrap': {
             const copy = resolved.clone();
             copy.anchor = undefined;
-            patchNode(copy, target, ctx);
-            return copy;
+            return patchNode(copy, target, ctx);
         }
     }
 }
@@ -65,37 +70,42 @@ function patchScalar(scalar, target, ctx) {
     if (scalar.value === target) {
         return scalar;
     }
-    if (typeof target === 'boolean' || typeof target === 'string' || typeof target === 'number') {
-        scalar.value = target;
+    const replacement = ctx.document.createNode(target);
+    if (yaml.isScalar(replacement)) {
+        scalar.value = replacement.value;
+        scalar.tag = replacement.tag;
         return scalar;
     }
-    return ctx.document.createNode(target);
+    return replacement;
 }
 function patchMap(map, target, ctx) {
     if (!isRecord(target)) {
         return ctx.document.createNode(target);
     }
-    // Intentionally return null on empty maps as well. This recursively clears
-    // empty maps in the final document.
-    if (target == null || Object.keys(target).length === 0) {
+    if (ctx.pruneEmptyValues !== false && Object.keys(target).length === 0) {
         return null;
     }
     const mapKeyToExistingPair = new Map();
     for (const pair of map.items) {
         // We can't update non-node types. Pairs should only contain values that are
         // non-nodes if the yaml document was modified manually after parsing.
-        if (!yaml.isScalar(pair.key) || typeof pair.key.value !== 'string') {
+        if (!yaml.isScalar(pair.key)) {
             throw new Error('Encountered unexpected non-node value: ' + String(pair.key));
         }
-        mapKeyToExistingPair.set(pair.key.value, pair);
-    }
-    map.items = Object.entries(target)
-        .map(([key, value]) => {
+        mapKeyToExistingPair.set(ctx.stringifyKey?.(pair.key.value) ?? String(pair.key.value ?? ''), pair);
+    }
+    const keys = ctx.preserveKeyOrder
+        ? [...mapKeyToExistingPair.keys()].filter(key => Object.hasOwn(target, key))
+            .concat(Object.keys(target).filter(key => !mapKeyToExistingPair.has(key)))
+        : Object.keys(target);
+    map.items = keys
+        .map(key => {
+        const value = target[key];
         const existingPair = mapKeyToExistingPair.get(key);
         if (existingPair == null) {
             return ctx.document.createPair(key, value);
         }
-        if (!yaml.isNode(existingPair.value)) {
+        if (existingPair.value != null && !yaml.isNode(existingPair.value)) {
             throw new Error('Encountered unexpected non-node value: ' + String(existingPair.value));
         }
         existingPair.value = patchNode(existingPair.value, value, ctx);
@@ -118,10 +128,10 @@ function patchSeq(seq, target, ctx) {
     // problem becomes important in the future, it may be worth making callers to
     // pass in a getKeyForNode() function.
     return isPrimitiveList(target)
-        ? patchSeqPrimitive(seq, target)
+        ? patchSeqPrimitive(seq, target, ctx)
         : patchSeqComplex(seq, target, ctx);
 }
-function patchSeqPrimitive(seq, target) {
+function patchSeqPrimitive(seq, target, ctx) {
     // Keep track of existing nodes to reuse when building up the final list from
     // the target list. These nodes will have comments attached to them, so it's
     // important to reuse them when possible.
@@ -133,14 +143,14 @@ function patchSeqPrimitive(seq, target) {
         // We know all items in the target list are scalars. If there's a non-scalar
         // in the source list, it needs to be removed. Skip over this item so it's
         // not added to the final list.
-        if (!yaml.isScalar(item) || !isPrimitive(item.value) || item.value == null) {
+        if (!yaml.isScalar(item) || !isPrimitive(item.value) || (item.value == null && ctx.pruneEmptyValues !== false)) {
             continue;
         }
         const nodeList = valueToNodesMap.get(item.value) ?? [];
         nodeList.push(item);
         valueToNodesMap.set(item.value, nodeList);
     }
-    seq.items = target.filter(item => item != null).map((item) => {
+    seq.items = target.filter(item => item != null || ctx.pruneEmptyValues === false).map((item) => {
         const existingNodesList = valueToNodesMap.get(item);
         const firstExistingItem = existingNodesList?.shift();
         // If the list is now empty as a result of removing the first item, clean up
@@ -154,7 +164,7 @@ function patchSeqPrimitive(seq, target) {
 }
 function patchSeqComplex(seq, target, ctx) {
     const nextItems = [];
-    for (let i = 0; i < Math.max(seq.items.length, target.length); i++) {
+    for (let i = 0; i < target.length; i++) {
         const existingItem = seq.items[i];
         const targetItem = target[i];
         if (existingItem != null && !yaml.isNode(existingItem)) {

package/lib/preserveScalarAliases.d.ts

@@ -0,0 +1,2 @@
+import yaml from 'yaml';
+export declare function preserveScalarAliases(document: yaml.Document): () => void;

package/lib/preserveScalarAliases.js

@@ -0,0 +1,83 @@
+import yaml from 'yaml';
+export function preserveScalarAliases(document) {
+    const groups = new Map();
+    const replacements = new Map();
+    yaml.visit(document, {
+        Scalar(_, node) {
+            if (node.anchor)
+                groups.set(node, node);
+        },
+        Alias(_, node) {
+            const source = node.resolve(document);
+            if (!yaml.isScalar(source))
+                return;
+            const copy = source.clone();
+            copy.anchor = undefined;
+            copy.comment = node.comment;
+            copy.commentBefore = node.commentBefore;
+            copy.spaceBefore = node.spaceBefore;
+            groups.set(copy, source);
+            replacements.set(node, copy);
+        },
+    });
+    yaml.visit(document, {
+        Alias(_, node) {
+            return replacements.get(node);
+        },
+    });
+    return () => {
+        assignUniqueNames(document, new Set(groups.values()));
+        const anchors = new Map();
+        yaml.visit(document, {
+            Scalar(_, node) {
+                const source = groups.get(node);
+                if (!source)
+                    return;
+                const anchor = anchors.get(source);
+                if (!anchor) {
+                    node.anchor = source.anchor;
+                    anchors.set(source, node);
+                }
+                else if (Object.is(anchor.value, node.value)) {
+                    const alias = new yaml.Alias(anchor.anchor);
+                    alias.comment = node.comment;
+                    alias.commentBefore = node.commentBefore;
+                    alias.spaceBefore = node.spaceBefore;
+                    return alias;
+                }
+                else {
+                    node.anchor = undefined;
+                }
+                return undefined;
+            },
+        });
+    };
+}
+function assignUniqueNames(document, sources) {
+    const names = new Map();
+    yaml.visit(document, {
+        Node(_, node) {
+            if (yaml.isAlias(node) || !node.anchor)
+                return;
+            const nodes = names.get(node.anchor) ?? new Set();
+            nodes.add(node);
+            names.set(node.anchor, nodes);
+        },
+    });
+    const nextSuffix = new Map();
+    for (const source of sources) {
+        const name = source.anchor;
+        const nodes = names.get(name);
+        if (!nodes || (nodes.size === 1 && nodes.has(source))) {
+            names.set(name, new Set([source]));
+            continue;
+        }
+        let suffix = nextSuffix.get(name) ?? 1;
+        while (names.has(`${name}_${suffix}`))
+            suffix++;
+        nextSuffix.set(name, suffix + 1);
+        source.anchor = `${name}_${suffix}`;
+        names.set(source.anchor, new Set([source]));
+    }
+}
+//# sourceMappingURL=preserveScalarAliases.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/yaml.document-sync",
-  "version": "1100.0.1",
+  "version": "1100.0.2",
   "description": "Update a YAML document to match the contents of an in-memory object.",
   "keywords": [
     "pnpm",
@@ -29,11 +29,11 @@
     "!*.map"
   ],
   "dependencies": {
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@jest/globals": "30.4.1",
-    "@pnpm/yaml.document-sync": "1100.0.1"
+    "@pnpm/yaml.document-sync": "1100.0.2"
   },
   "engines": {
     "node": ">=22.13"