# @pnpm/yaml.document-sync

> Update a YAML document to match the contents of an in-memory object.

Latest version **1100.0.2** (published 2026-09-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @pnpm/yaml.document-sync
pnpm add @pnpm/yaml.document-sync
yarn add @pnpm/yaml.document-sync
bun add @pnpm/yaml.document-sync
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1100.0.2 |
| Published | 2026-09-20 |
| First published | 2026-01-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.13 |
| Dependencies | 1 |
| Unpacked size | 19.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 36813 |
| Maintainers | pnpmuser, zkochan |
| Keywords | pnpm, pnpm11, patch, yaml |

## Links

- npm: https://www.npmjs.com/package/@pnpm/yaml.document-sync
- Repository: https://github.com/pnpm/pnpm/tree/main/pnpm11/yaml/document-sync
- Homepage: https://github.com/pnpm/pnpm/tree/main/pnpm11/yaml/document-sync#readme
- Issues: https://github.com/pnpm/pnpm/issues
- Funding: https://opencollective.com/pnpm
- npm.io page: https://npm.io/package/@pnpm/yaml.document-sync

## Dependencies (1)

- [yaml](https://npm.io/package/yaml.md) ^2.9.1

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 1100.0.2 (latest) — 2026-09-20
- 1100.0.1 — 2026-07-23
- 1100.0.0 — 2026-04-10
- 1000.0.0 — 2026-03-07
- 1000.0.0-0 — 2026-01-13

## README

# @pnpm/yaml.document-sync

> Update a YAML document to match the contents of an in-memory object.

<!--@shields('npm')-->
[![npm version](https://img.shields.io/npm/v/@pnpm/yaml.document-sync.svg)](https://npmx.dev/package/@pnpm/yaml.document-sync)
<!--/@-->

## Installation

```sh
pnpm add @pnpm/yaml.document-sync
```

## Usage

Given a "_source_" document such as:

```yaml
foo:
  bar:
    # 25 is better than 24
    baz: 25

qux:
  # He was number 1
  - 1
```

And a "_target_" object in-memory:

```ts
import fs from 'node:fs'
import { patchDocument } from '@pnpm/yaml.document-sync'
import yaml from 'yaml'

const source = await fs.promises.readFile('source.yaml', 'utf8')
const document = yaml.parseDocument(source)

const target = {
  foo: { bar: { baz: 25 } },
  qux: [1, 2, 3]
}

patchDocument(document, target)
```

The `patchDocument` function will mutate `document` to match the `target`'s contents, retaining comments along the way. In the example above, the final rendered document will be:

```yaml
foo:
  bar:
    # 25 is better than 24
    baz: 25

qux:
  # He was number 1
  - 1
  - 2
  - 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:

1. Uses the [yaml](https://npmx.dev/package/yaml) library.
2. Calls `.toJSON()` on the parse result and performs changes to it.
3. Needs to "sync" those changes back to the source document.

Instead of this package, consider performing mutations directly on the `yaml.Document` returned from `yaml.parseDocument()` instead. Directly modifying will be faster and more accurate. This package exists as a workaround for codebases that make changes to a JSON object instead and need to reconcile changes back into the source `yaml.Document`.

## Caveats

There are several cases where comment preservation is inherently ambiguous. If the caveats outlined below are problematic, consider modifying the source `yaml.Document` before running the patch function in this package.

### Key Renames

For example, renames of a key are ambiguous. Given:

```yaml
- foo:
    # Test
    bar: 1
```

And a target object to match:

```json
{
  "baz": {
    "bar": 1
  }
}
```

The comment on `bar` won't be retained.

### List Reconciliation

For simple lists (e.g. lists with only primitives), items will be uniquely matched using their contents. However, updates to complex lists are inherently ambiguous.

For example, given a source list with objects as elements:

```yaml
- foo: 1
# Comment
- bar: 2
```

And a target:

```json
[
  { "foo": 1 },
  { "baz": 3 },
  { "bar": 2 }
]
```

The result will erase the comment:

```yaml
- foo: 1
- baz: 3
- bar: 2
```

It's not trivial to detect that the object with `bar` as a field moved down. Detecting this case would require a diffing algorithm, which would be best effort anyway.

Virtual DOM libraries such as React have the same problem. In React, list elements need to specify a `key` prop to uniquely identify each item. This library may take a similar approach in the future if needed. This is not a problem for primitive lists since their values can be compared using simple equality checks.

### Aliases

Given:

```yaml
foo: &config
  - 1
  - 2

bar: *config
```

And a target object:

```json
{
  "foo": [1, 2],
  "bar": [1, 2, 3]
}
```

For correctness, the YAML alias needs to be removed.

```yaml
foo: &config
  - 1
  - 2

bar:
  - 1
  - 2
  - 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

---
_Source: https://npm.io/package/@pnpm/yaml.document-sync · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._