{"_id":"@visulima/yaml","_rev":"3-530ee0b739bc9eaa074b02c026f47b21","name":"@visulima/yaml","dist-tags":{"latest":"2.0.0"},"versions":{"0.0.0":{"name":"@visulima/yaml","version":"0.0.0","keywords":["oidc","trusted-publishing","setup"],"_id":"@visulima/yaml@0.0.0","maintainers":[{"name":"prisis","email":"d.bannert@anolilab.de"}],"dist":{"shasum":"837ea5d08fa04ff483c52f8975672bb4cccc3e74","tarball":"https://registry.npmjs.org/@visulima/yaml/-/yaml-0.0.0.tgz","fileCount":2,"integrity":"sha512-euL7wrCRLFOmpCXlgY+zP4NQQuAkgWXqsrNrJ57QRlX+ZbHsQOIFl3iY9/TfrCGlobhmSQnNhnhWVJBsAefNsQ==","signatures":[{"sig":"MEQCIB10iI55P4Vy17fqjsg0muv0Tccx6OefGpLpuox8935uAiBj4kPJLZBrn/UdfHi2kw5vI3y6kYxwBFnpvUr9dBgtqg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2019},"_npmUser":{"name":"prisis","email":"d.bannert@anolilab.de"},"_npmVersion":"11.3.0","description":"OIDC trusted publishing setup package for @visulima/yaml","directories":{},"_nodeVersion":"22.14.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/yaml_0.0.0_1786111112248_0.5559824278599725","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@visulima/yaml","version":"1.0.0","keywords":["yaml","yml","yaml-parser","yaml1.2","parser","serializer","stringify","parse","load","dump","js-yaml","data","config","typescript","visulima"],"author":{"name":"Daniel Bannert","email":"d.bannert@anolilab.de"},"license":"MIT","_id":"@visulima/yaml@1.0.0","maintainers":[{"name":"prisis","email":"d.bannert@anolilab.de"}],"homepage":"https://visulima.com/packages/yaml","bugs":"https://github.com/visulima/visulima/issues","dist":{"shasum":"bce7ebabf4ccf10779a06d032867d24571eae3c9","tarball":"https://registry.npmjs.org/@visulima/yaml/-/yaml-1.0.0.tgz","fileCount":12,"integrity":"sha512-06obI/5zlKRjScekXqHTtF06S5peqHE9J3AmEthJ5b40a4FuJAysbOJ9EVyznTpOVmy3IvL8cZu3QiNpgF/cbg==","signatures":[{"sig":"MEUCIAPUIt7GDZKsEmON8Wvs9mAobv56WbNZsIYc3V9GDUHoAiEA/ad5Y2RVvQ/S2H/gTzEyhKwutJM9mw6kw6X+lBD+yyM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@visulima%2fyaml@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":88386},"type":"module","engines":{"node":"^22.14.0 || >=24.10.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"funding":[{"url":"https://github.com/sponsors/prisis","type":"github"},{"url":"https://anolilab.com/support","type":"consulting"}],"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:69102f88-fd63-4431-99f7-e40244b3e7d3"}},"repository":{"url":"git+https://github.com/visulima/visulima.git","type":"git","directory":"packages/data-manipulation/yaml"},"description":"A fast, zero-dependency YAML 1.2 parser and serializer with a drop-in API for both `yaml` and `js-yaml`.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.1","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/yaml_1.0.0_1786191843698_0.6245166891797578","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"_id":"@visulima/yaml@2.0.0","bugs":"https://github.com/visulima/visulima/issues","dist":{"shasum":"50796433b5dcadff2d6c58c7dffa46f3cc4a1879","tarball":"https://registry.npmjs.org/@visulima/yaml/-/yaml-2.0.0.tgz","fileCount":12,"integrity":"sha512-4/JYuxyzAhHmoI49qBqQ60WkX7mjUiNYv2Z4WvIaV6iVdNjLwq2Xq8MmF/bWagb4aDo4oQg6Uhenv4woItkmAg==","signatures":[{"sig":"MEYCIQC2VUwRDwnmAdbC0rQg05PN795LAIucebvX31DihBWRnwIhAPTjIa+JtFzcIfdoSO1RI38yCS5rUZySwA77ZZU2fMFs","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIE6yxMhYRDhVke+dUyLdPh/Hbh3GBiJCJKnzLsSPo2lOAiBX8V6uBf++9T3PNBgEGZRV0N0qK8BRv9GeBvgOo5nnAg=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@visulima%2fyaml@2.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":93014},"name":"@visulima/yaml","type":"module","author":{"name":"Daniel Bannert","email":"d.bannert@anolilab.de"},"engines":{"node":"^22.14.0 || >=24.10.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./package.json":"./package.json"},"funding":[{"url":"https://github.com/sponsors/prisis","type":"github"},{"url":"https://anolilab.com/support","type":"consulting"}],"license":"MIT","version":"2.0.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"69102f88-fd63-4431-99f7-e40244b3e7d3"}},"homepage":"https://visulima.com/packages/yaml","keywords":["yaml","yml","yaml-parser","yaml1.2","parser","serializer","stringify","parse","load","dump","js-yaml","data","config","typescript","visulima"],"repository":{"url":"git+https://github.com/visulima/visulima.git","type":"git","directory":"packages/data-manipulation/yaml"},"description":"A fast, zero-dependency YAML 1.2 parser and serializer with a drop-in API for both `yaml` and `js-yaml`.","directories":{},"maintainers":[{"name":"prisis","email":"d.bannert@anolilab.de"}],"sideEffects":false,"_nodeVersion":"24.21.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/yaml_2.0.0_1792081651314_0.6653006097931629"}}},"time":{"created":"2026-08-07T13:58:32.062Z","modified":"2026-10-15T16:27:31.888Z","0.0.0":"2026-08-07T13:58:32.391Z","1.0.0":"2026-08-08T12:24:03.841Z","2.0.0":"2026-10-15T16:27:31.406Z"},"bugs":"https://github.com/visulima/visulima/issues","author":{"name":"Daniel Bannert","email":"d.bannert@anolilab.de"},"license":"MIT","homepage":"https://visulima.com/packages/yaml","keywords":["yaml","yml","yaml-parser","yaml1.2","parser","serializer","stringify","parse","load","dump","js-yaml","data","config","typescript","visulima"],"repository":{"url":"git+https://github.com/visulima/visulima.git","type":"git","directory":"packages/data-manipulation/yaml"},"description":"A fast, zero-dependency YAML 1.2 parser and serializer with a drop-in API for both `yaml` and `js-yaml`.","maintainers":[{"name":"prisis","email":"d.bannert@anolilab.de"}],"readme":"\n\n\n\n \n\n\n\n
A fast, zero-dependency YAML 1.2 parser and serializer with a drop-in API for both `yaml` and `js-yaml`.
\n \n Daniel Bannert's open source work is supported by the community on GitHub Sponsors\n \n
\n
\n\n---\n\n## Features\n\n- **100% spec conformance** — passes all 402 cases of the official [yaml-test-suite](https://github.com/yaml/yaml-test-suite) in the default (strict) mode.\n- **YAML 1.2 core schema** — strict, spec-compliant scalar resolution (`null`, `bool`, `int` in dec/hex/oct, `float`, `.inf`/`.nan`). `yes`/`no`/`on`/`off` are strings, as YAML 1.2 mandates.\n- **Full block & flow grammar** — block/flow mappings and sequences, all five scalar styles (plain, single-quoted, double-quoted, literal `|`, folded `>`) with chomping and indentation indicators.\n- **Anchors, aliases & merge keys** — `&anchor` / `*alias` with shared references, plus `<<` merge keys.\n- **Multi-document streams** — `---` / `...` document markers and `%YAML` / `%TAG` directives.\n- **Two compatible APIs** — the `yaml`-style `parse` / `stringify` and the `js-yaml`-style `load` / `loadAll` / `dump`.\n- **Safe by default** — prototype-pollution guard, duplicate-key detection, and an alias-expansion (billion-laughs) limit.\n- **Zero runtime dependencies** and fully typed.\n\n## Install\n\n```sh\nnpm install @visulima/yaml\n```\n\n```sh\nyarn add @visulima/yaml\n```\n\n```sh\npnpm add @visulima/yaml\n```\n\n## Usage\n\n### parse\n\n```ts\nimport { parse } from \"@visulima/yaml\";\n\nparse(`\nname: my-app\nversion: 1.0.0\nscripts:\n build: packem build\n test: vitest run\ntags: [cli, tooling]\n`);\n// => {\n// name: \"my-app\",\n// version: \"1.0.0\",\n// scripts: { build: \"packem build\", test: \"vitest run\" },\n// tags: [\"cli\", \"tooling\"],\n// }\n```\n\n### stringify\n\n```ts\nimport { stringify } from \"@visulima/yaml\";\n\nstringify({ name: \"my-app\", tags: [\"cli\", \"tooling\"], nested: { a: 1 } });\n// name: my-app\n// tags:\n// - cli\n// - tooling\n// nested:\n// a: 1\n```\n\n### Multiple documents\n\n```ts\nimport { parseAll } from \"@visulima/yaml\";\n\nparseAll(\"---\\na: 1\\n---\\nb: 2\"); // => [{ a: 1 }, { b: 2 }]\n```\n\n### Anchors, aliases and merge keys\n\n```ts\nimport { parse } from \"@visulima/yaml\";\n\nparse(`\ndefaults: &defaults\n adapter: postgres\n host: localhost\ndevelopment:\n <<: *defaults\n database: dev\n`);\n// => {\n// defaults: { adapter: \"postgres\", host: \"localhost\" },\n// development: { adapter: \"postgres\", host: \"localhost\", database: \"dev\" },\n// }\n```\n\n### js-yaml-compatible API\n\nAlready using `js-yaml`? Swap the import — `load`, `loadAll` and `dump` are exported with the same shape.\n\n```ts\nimport { load, loadAll, dump } from \"@visulima/yaml\";\n\nload(\"foo: bar\"); // => { foo: \"bar\" }\ndump({ foo: \"bar\" }); // => \"foo: bar\\n\"\n\nloadAll(\"---\\n- 1\\n---\\n- 2\", (doc) => console.log(doc)); // logs [1] then [2]\n```\n\n## API\n\n### `parse(source, options?)` / `load(source, options?)`\n\nParse the first document of a YAML string into a native JavaScript value.\n\n`options`:\n\n| Option | Type | Default | Description |\n| ----------------------- | ---------------------------------------------- | --------- | ---------------------------------------------------------------------------------------- |\n| `duplicateKeys` | `\"error\" \\| \"overwrite\" \\| \"ignore\"` | `\"error\"` | How repeated keys within a mapping are handled. |\n| `schema` | `\"core\" \\| \"failsafe\" \\| \"json\" \\| \"yaml-1.1\"` | `\"core\"` | Scalar-resolution rules (see below). |\n| `version` | `\"1.1\" \\| \"1.2\"` | `\"1.2\"` | YAML version assumed without a `%YAML` directive. `\"1.1\"` selects the `yaml-1.1` schema. |\n| `customTags` | `ScalarTag[] \\| (tags) => ScalarTag[]` | — | Extra scalar types (see below). |\n| `reviver` | `(key, value) => unknown` | — | Applied to every pair after parsing, like `JSON.parse`. Return `undefined` to drop. |\n| `merge` | `boolean` | `true` | Resolve `<<` merge keys. |\n| `mapAsMap` | `boolean` | `false` | Build mappings as `Map`, keeping complex keys native. |\n| `intAsBigInt` | `boolean` | `false` | Resolve integers as `BigInt`. |\n| `stringKeys` | `boolean` | `false` | Keep every mapping key a string. |\n| `maxDepth` | `number` | `1000` | Maximum collection nesting depth (guards against stack exhaustion). |\n| `maxAliasCount` | `number` | `100` | Upper bound on resolved alias nodes (guards against expansion attacks). |\n| `preventProtoPollution` | `boolean` | `true` | Make a `__proto__` key an own property instead of touching the prototype. |\n| `strict` | `boolean` | `true`\\* | Full YAML 1.2 strictness (see below). Set `false` for js-yaml-style leniency. |\n| `onWarning` | `(warning: YAMLWarning) => void` | — | Callback for non-fatal notices. |\n\n#### Custom tags\n\nA tag teaches the parser one extra scalar type. Give it a `test` and\n`default: true` to resolve implicitly as well as via an explicit `!!tag`:\n\n```ts\nclass Hex {\n constructor(readonly value: number) {}\n}\n\nconst hex = {\n tag: \"!!hex\",\n test: /^0h[\\da-f]+$/i,\n default: true,\n resolve: (raw) => new Hex(Number.parseInt(raw.slice(2), 16)),\n identify: (value) => value instanceof Hex,\n stringify: (value) => `0h${value.value.toString(16)}`,\n};\n\nparse(\"a: 0hff\", { customTags: [hex] }); // => { a: Hex(255) }\nparse(\"a: !!hex 0hff\", { customTags: [hex] }); // => { a: Hex(255) }\nstringify({ a: new Hex(255) }, { customTags: [hex] }); // => \"a: !!hex 0hff\\n\"\n```\n\n`resolve` receives the raw text and `stringify` the value — this parser builds\nnative values directly, so there are no node wrappers to unpack. Collection tags\nare not supported for the same reason.\n\n#### Schemas\n\nA schema decides which unquoted scalars stop being strings. `core` (the default)\nis YAML 1.2 core. `failsafe` resolves nothing. `json` resolves only the JSON\ngrammar and rejects anything else. `yaml-1.1` is the older, wider set:\n\n```ts\nparse(\"a: off\"); // => { a: \"off\" } — core: not a boolean\nparse(\"a: off\", { schema: \"yaml-1.1\" }); // => { a: false }\nparse(\"a: 010\", { schema: \"yaml-1.1\" }); // => { a: 8 } — octal\nparse(\"a: 1_000\", { schema: \"yaml-1.1\" }); // => { a: 1000 } — underscores\nparse(\"a: 1:30\", { schema: \"yaml-1.1\" }); // => { a: 90 } — sexagesimal\nparse(\"a: 2001-12-15\", { schema: \"yaml-1.1\" }); // => { a: Date }\n\nparse(\"a: 1\", { schema: \"failsafe\" }); // => { a: \"1\" }\nparse(\"a: ~\", { schema: \"json\" }); // throws — not JSON\n```\n\n`version: \"1.1\"` selects the `yaml-1.1` schema unless `schema` says otherwise.\nNote that under 1.1 a bare `y` or `n` key is a boolean, which is why\n`x: true\\ny: off` parses as `{ x: true, true: false }` — the same result `yaml`\nproduces.\n\n#### Strict mode (default)\n\nThe parser always rejects the unambiguous YAML 1.2 violations (tabs used as indentation,\nmalformed `%YAML`/`%TAG` directives, deficient indentation, comments not separated from\nother tokens by white space). On top of that, strict mode — **on by default** — rejects\nthe corner cases that both reference parsers accept but the spec does not: a node property\nindented no deeper than its parent key (`key: &a\\n!!map\\n a: b`), and a block collection\nwhose first entry sits on the `---` line (`--- a: b`). Pass `strict: false` to relax only\nthese checks (closer to `js-yaml`); it never changes the value of an accepted document.\n\n```ts\nparse(\"--- a: b\"); // throws YAMLParseError (block mapping on the --- line)\nparse(\"--- a: b\", { strict: false }); // => { a: \"b\" }\n```\n\n\\* `strict` defaults to `true` for `parse` / `parseAll`, but the `js-yaml`-style\n`load` / `loadAll` aliases default to `strict: false` so they stay drop-in\nreplacements for `js-yaml`. Pass `{ strict: true }` to opt in.\n\n### `parseDocument(source, options?)` / `parseAllDocuments(source, options?)`\n\nParse **without throwing**. Each returns a `YAMLDocument` carrying its own\n`errors` and `warnings`, so a caller can report problems in its own words —\nand `parseAllDocuments` keeps going after a malformed document instead of\nlosing the whole stream.\n\nDocuments also support **comment-preserving edits**: `setIn` splices the\noriginal source rather than re-serializing it, so comments, blank lines and key\norder elsewhere in the file are untouched.\n\n```ts\nimport { parseDocument } from \"@visulima/yaml\";\n\nconst document = parseDocument(\"packages:\\n - 'a/*'\\n\\n# keep me\\n\");\n\ndocument.setIn([\"overrides\", \"some-pkg\"], \"npm:other@1.2.3\");\ndocument.toString();\n// packages:\n// - 'a/*'\n//\n// # keep me\n// overrides:\n// some-pkg: npm:other@1.2.3\n```\n\n| Member | Description |\n| -------------------------------- | --------------------------------------------- |\n| `errors` / `warnings` | Diagnostics from reading the document. |\n| `toJS()` / `toJSON()` | The parsed value. |\n| `get(key)` / `getIn(path)` | Read a value by key or path. |\n| `has(key)` / `hasIn(path)` | Whether a key or path is present. |\n| `set(key, v)` / `setIn(path, v)` | Edit, creating missing intermediate mappings. |\n| `toString()` | The source with every pending edit applied. |\n\nError recovery is per document — within one document the first error ends it.\n`setIn` edits block mappings only; a path through a flow collection or a\nsequence throws.\n\n### `parseAll(source, options?)` / `loadAll(source, iterator?, options?)`\n\nParse every document of a multi-document stream. `parseAll` returns an array; the\n`js-yaml`-style `loadAll` optionally accepts a per-document iterator.\n\n### `stringify(value, options?)` / `dump(value, options?)`\n\nSerialize a JavaScript value to a YAML document string.\n\n`options`:\n\n| Option | Type | Default | Description |\n| ----------------------- | ---------------------------------- | --------- | ------------------------------------------------------------------ |\n| `indent` | `number` | `2` | Spaces per indentation level (minimum 2). |\n| `flowLevel` | `number` | `-1` | Use flow style at or beyond this nesting level (`-1` disables it). |\n| `sortKeys` | `boolean \\| ((a, b) => number)` | `false` | Sort mapping keys. |\n| `lineWidth` | `number` | `80` | Preferred wrap width for folded scalars. |\n| `forceQuotes` | `boolean` | `false` | Escape non-ASCII characters in double-quoted scalars. |\n| `skipInvalid` | `boolean` | `false` | Skip `undefined` members instead of emitting `null`. |\n| `directives` | `boolean` | `false` | Emit a leading `---` document marker. |\n| `nullStr` | `string` | `\"null\"` | String written for `null`. |\n| `trueStr` | `string` | `\"true\"` | String written for `true`. |\n| `falseStr` | `string` | `\"false\"` | String written for `false`. |\n| `singleQuote` | `boolean` | `false` | Prefer single quotes when a string must be quoted. |\n| `blockQuote` | `boolean \\| \"literal\" \\| \"folded\"` | `true` | How to render multi-line strings. |\n| `collectionStyle` | `\"any\" \\| \"block\" \\| \"flow\"` | `\"any\"` | Force one collection style. |\n| `flowCollectionPadding` | `boolean` | `true` | Pad flow collections: `{ a: 1 }` vs `{a: 1}`. |\n| `indentSeq` | `boolean` | `true` | Indent block sequences under their key. |\n| `keepUndefined` | `boolean` | `false` | Keep `undefined` values instead of dropping them. |\n| `replacer` | `(key, value) => unknown` | — | `JSON.stringify`-style value replacer. |\n\n> `dump` (the `js-yaml` alias) defaults `singleQuote` to `true`, and `load` returns `undefined` for an empty stream where `parse` returns `null` — each alias follows the package it stands in for.\n\n\n### Errors\n\n`YAMLParseError`, `YAMLStringifyError`, `YAMLWarning` and the shared base `YAMLError`\nare exported. Parse errors carry a `mark` with `{ line, column, position }` and a\nsource snippet.\n\n## Benchmarks\n\n`@visulima/yaml` is benchmarked against `yaml` and `js-yaml` across small, medium,\nlarge, anchor-heavy and stringify workloads. See [`__bench__`](./__bench__) and run:\n\n```sh\npnpm --filter yaml-bench run test:bench\n```\n\n## Related\n\n- [yaml](https://github.com/eemeli/yaml) — feature-rich YAML parser with CST support.\n- [js-yaml](https://github.com/nodeca/js-yaml) — the long-standing JavaScript YAML implementation.\n\n## Supported Node.js Versions\n\nLibraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).\nHere’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).\n\n## Contributing\n\nIf you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md) guidelines.\n\n> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.\n\n## Credits\n\n- [Daniel Bannert](https://github.com/prisis)\n- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)\n\n## Made with ❤️ at Anolilab\n\nThis is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!\n\n## License\n\nThe visulima yaml is open-sourced software licensed under the [MIT][license]\n\n\n\n[license-badge]: https://img.shields.io/npm/l/@visulima/yaml?style=for-the-badge\n[license]: https://github.com/visulima/visulima/blob/main/LICENSE\n[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/yaml?style=for-the-badge\n[npm-downloads]: https://www.npmjs.com/package/@visulima/yaml\n[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge\n[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md\n[chat-badge]: https://img.shields.io/discord/902465130518949899.svg?style=for-the-badge\n[chat]: https://discord.gg/eajEZvk2PG\n[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript\n[typescript-url]: https://www.typescriptlang.org/\n","readmeFilename":""}
![\"yaml\"](\"__assets__/package-og.svg\")
\n\n