Consider replacing js-yaml fork with yaml for consistent spec compliance

[outslept]

Currently, pnpm uses js-yaml which inconsistently mixes YAML 1.1 and 1.2 specifications. This is particularly relevant for workspace configurations where anchors and merge keys are commonly used.

Here's a simple test showing the differences:

import * as jsYaml from 'js-yaml';
import { parse } from 'yaml';

const workspaceConfig = `
packages:
  - packages/*
  - apps/*

catalog: &base_catalog
  "react": "19.0.0"
  "react-dom": "19.0.0"

catalogs:
  web:
    <<: *base_catalog
    "next": "15.0.0"
`;

console.log('js-yaml result:');
console.dir(jsYaml.load(workspaceConfig), { depth: null });

console.log('yaml result:');
console.dir(parse(workspaceConfig), { depth: null });

Output

js-yaml result:
{
  packages: [ "packages/*", "apps/*" ],
  catalog: {
    react: "19.0.0",
    "react-dom": "19.0.0",
  },
  catalogs: {
    web: {
      react: "19.0.0",
      "react-dom": "19.0.0",
      next: "15.0.0",
    },
  },
}
yaml result:
{
  packages: [ "packages/*", "apps/*" ],
  catalog: {
    react: "19.0.0",
    "react-dom": "19.0.0",
  },
  catalogs: {
    web: {
      "<<": {
        react: "19.0.0",
        "react-dom": "19.0.0",
      },
      next: "15.0.0",
    },
  },
}

As shown:

• js-yaml expands the merge key (<<), treating it as a valid YAML 1.1 feature.
• yaml preserves << as a plain key, because YAML 1.2 does not define merge semantics.

This inconsistency can lead to surprises for users who expect their anchors/aliases to “just work,” or who assume that pnpm-workspace.yaml is parsed according to one YAML spec.

Why consider yaml?

The yaml package:

• Follows YAML 1.2 spec strictly by default
• Can optionally support YAML 1.1 with { version: '1.1' }
• Has better TypeScript definitions
• Provides an AST API for preserving comments and formatting
• Several projects have already switched, including the unified ecosystem and yaml-language-server.

I’ve been experimenting locally with pnpm-workspace.yaml and found a few inconsistencies due to this YAML parsing behavior. I wasn’t sure if this warranted a formal issue — but I’m happy to open one and provide more examples if helpful.

Also open to discussing further on Twitter or wherever is convenient!

If there's any plan to migrate from js-yaml to the yaml package in the future (or continuing efforts with #8326), I’d be more than happy to help with that effort as well.

[lishaduck]

This would also be nice for me. I migrated typesync to yaml a week or two ago, but it does mean that it's parsed differently from actual pnpm.

[danielbayley]

any plan to migrate from js-yaml to the yaml package…
continuing efforts with #8326

@outslept I certainly want to find the time to get #8326 over the line!

[danielbayley]

Let me know if there’s anything I could help with to get #8326 moving forward faster 😊

The first hurdle is replicating the changes between the pnpm fork of js-yaml, and the pnpm fork of yaml, as mentioned in #8326 (comment). This might be low-hanging fruit, not sure—I haven’t had a proper look at it yet—if you want to take a stab at it @outslept?

[outslept]

Okay, I'm on it! (https://github.com/outslept/yaml-playground/tree/sandbox). Hopefully will be back with details by the end of the week, cause I have some initial progress in replicating

[outslept]

Sooo.. Initial progress suggests replicating the formatting differences isn't the biggest blocker. Locally, I'm able to get very close structurally. The main visible difference often boils down to quoting styles, but the resulting YAML syntax should generally be valid and semantically equivalent.

The more significant challenge appears to be the computational cost (performance), as yaml is currently considerably slower than js-yaml (this problem is already mentioned in #8641).

The good news is that I've been experimenting locally with patches to optimize the eemeli/yaml library. On the pnpm-lock.yaml benchmark file (~8k lines / 266.46KB), these patches have already shown a performance improvement, reducing the average execution time from ~171 ms down to ~146 ms.

I'll see what else I can achieve in my free time regarding further optimizations and will share my findings here afterward.

[outslept]

After all the micro-optimizations, I've only managed to save a couple of tens of ms on operations and haven't achieved a substantial perf boost (as that would require introducing breaking changes to the library), so if performance is a major concern (which it should be), I believe we're not ready to replace js-yaml with yaml, although I'm now experimenting with Rust parsers to benchmark them against js-yaml and possibly use as a WASM package. We'll see how it goes

[danielbayley]

achieved a substantial perf boost (as that would require introducing breaking changes to the library)

@outslept Since we are, necessarily, already working with a fork of yaml anyway, would said breaking changes not be a concern?