{"id":14386,"library":"yaml-unist-parser","title":"YAML Unist Parser","description":"yaml-unist-parser is a JavaScript library designed to parse YAML strings and produce an Abstract Syntax Tree (AST) that is compatible with the unist specification. This makes it a suitable tool for applications that process YAML content using a unified syntax tree, such as linters, formatters, and compilers within the unist ecosystem. The current stable version is 3.1.0, with a recent major release (v3.0.0) indicating active development, though a precise release cadence isn't published. Key differentiators include its focus on generating a unist-compatible AST, enhanced node positioning within the AST, and improved comment attaching, which are crucial for tools like Prettier that rely on precise AST details for formatting.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/prettier/yaml-unist-parser","tags":["javascript","unist","yaml"],"install":[{"cmd":"npm install yaml-unist-parser","lang":"bash","label":"npm"},{"cmd":"yarn add yaml-unist-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add yaml-unist-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core YAML parsing logic. Updated to v2 in `yaml-unist-parser` v3.0.0.","package":"yaml","optional":false}],"imports":[{"note":"The library primarily uses ES modules. While CommonJS might work with transpilation, direct ESM import is preferred. `parse` is the main function for converting YAML strings to a unist AST.","wrong":"const parse = require('yaml-unist-parser').parse;","symbol":"parse","correct":"import { parse } from 'yaml-unist-parser';"},{"note":"Introduced in v3.1.0, this custom error class allows for specific error handling when parsing invalid YAML. It's a named export.","wrong":"import { SyntaxError as YAMLSyntaxError } from 'yaml-unist-parser';","symbol":"YAMLSyntaxError","correct":"import { YAMLSyntaxError } from 'yaml-unist-parser';"},{"note":"For TypeScript users, specific AST node types (like `Root`, `Scalar`, `Pair`, `YAMLMapping`, `YAMLSequence`) can be imported directly from the `src/types` path for stricter type checking and AST manipulation.","wrong":"import { Root, Scalar, Pair } from 'yaml-unist-parser';","symbol":"Node types","correct":"import type { Root, Scalar, Pair } from 'yaml-unist-parser/src/types';"}],"quickstart":{"code":"import { parse } from 'yaml-unist-parser';\n\n// Example YAML content including various structures and comments\nconst yamlContent = `\n# This is a simple YAML document\nmetadata:\n  name: my-app\n  version: 1.0.0\n  tags: [backend, service]\n\nenvironment: production\n\n# A list of features\nfeatures:\n  - login\n  - dashboard\n  - reports: { enabled: true, level: 'admin' }\n\nserver:\n  port: 8080\n  host: 0.0.0.0\n`;\n\ntry {\n  // Parse the YAML content into a unist-compatible AST\n  const ast = parse(yamlContent, { uniqueKeys: true });\n  console.log('Successfully parsed YAML. Root node type:', ast.type);\n  console.log('AST Structure (first few nodes):', JSON.stringify(ast, null, 2).substring(0, 500) + '...');\n\n  // You can traverse the AST using unist-utils or other AST manipulation libraries\n  // For example, to find all scalar nodes:\n  // visit(ast, 'scalar', (node) => { console.log('Scalar value:', node.value); });\n\n} catch (error) {\n  if (error instanceof Error) {\n    console.error('YAML Parsing Error:', error.message);\n  } else {\n    console.error('An unexpected error occurred during parsing.');\n  }\n}","lang":"typescript","description":"This quickstart demonstrates how to parse a complex YAML string into a unist AST, handling potential errors."},"warnings":[{"fix":"Replace `allowDuplicateKeysInMap: true` with `uniqueKeys: false` (to allow duplicates) or simply remove the option if you desire the default unique key behavior (`uniqueKeys: true`).","message":"The `allowDuplicateKeysInMap` option was removed in v3.0.0. Its functionality has been replaced by the `uniqueKeys` option with inverted logic.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Thoroughly test existing YAML parsing logic when upgrading to v3.0.0 to ensure no unexpected changes in AST output or error conditions, particularly for complex or unconventional YAML structures.","message":"Version 3.0.0 updated its internal `yaml` dependency to v2. While `yaml-unist-parser` aims to abstract this, it's possible that subtle changes in parsing behavior or edge case handling from the underlying `yaml` library could manifest.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To allow duplicate keys in maps, pass `{ uniqueKeys: false }` as an option to the `parse` function. Example: `parse(yamlString, { uniqueKeys: false });`","message":"By default, `yaml-unist-parser` enforces unique keys in maps, meaning duplicate keys will throw a `YAMLSyntaxError`. This strict behavior might not be desired in all use cases.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3.1.0':63 'abstract':20 'activ':71 'applic':38 'ast':23,92,98,114 'attach':102 'cadenc':77 'comment':101 'compat':26,91 'compil':53 'content':42 'crucial':105 'current':59 'design':12 'detail':115 'develop':72 'differenti':82 'ecosystem':57 'enhanc':93 'focus':85 'format':117 'formatt':51 'generat':87 'improv':100 'includ':83 'indic':70 'isn':78 'javascript':10,118 'key':81 'librari':11 'like':108 'linter':50 'major':67 'make':32 'node':94 'pars':14 'parser':3,7 'posit':95 'precis':75,113 'prettier':109 'process':40 'produc':18 'publish':80 'recent':66 'releas':68,76 'reli':111 'specif':30 'stabl':60 'string':16 'suitabl':35 'syntax':21,46 'though':73 'tool':36,107 'tree':22,47 'unifi':45 'unist':2,6,29,56,90,119 'unist-compat':89 'use':43 'v3.0.0':69 'version':61 'within':54,96 'yaml':1,5,15,41,120 'yaml-unist-pars':4","created_at":"2026-04-20T01:59:26.527648+00:00","updated_at":"2026-04-20T01:59:26.527648+00:00","problems":[{"fix":"Either ensure all map keys in your YAML are unique, or allow duplicate keys by calling `parse(yamlString, { uniqueKeys: false });`","cause":"Attempting to parse YAML content that contains duplicate keys within a map, while the `uniqueKeys` option is set to its default value of `true`.","error":"Uncaught SyntaxError [YAMLSyntaxError]: Map keys must be unique"},{"fix":"Use a named ESM import: `import { parse } from 'yaml-unist-parser';`","cause":"Incorrect import method used for `parse` function, often seen when trying to use CommonJS `require` syntax or when a default import is attempted for a named export.","error":"TypeError: parse is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/prettier/yaml-unist-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/yaml-unist-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}