{"id":15498,"library":"yaml-ast-parser","title":"YAML AST Parser","description":"yaml-ast-parser is a JavaScript/TypeScript library designed to parse YAML documents into an Abstract Syntax Tree (AST). It is a fork of `js-yaml` but specifically focuses on providing AST representation rather than direct deserialization into JavaScript objects. Key features include the ability to restore parsing after errors, integrate error reporting directly into AST nodes, and built-in support for the `!include` tag commonly used in RAML specifications. The library is currently at version `0.0.43` and appears to be in an abandoned state, with the last GitHub activity several years ago. Its primary differentiator is the granular AST access and specialized `!include` handling, making it suitable for tools that need to analyze or transform YAML structure rather than just consume its data. Developers should be aware of its inactive maintenance status when considering its use in new projects.","status":"abandoned","version":"0.0.43","language":"javascript","source_language":"en","source_url":"https://github.com/mulesoft-labs/yaml-ast-parser","tags":["javascript","raml","ast","yaml","typescript"],"install":[{"cmd":"npm install yaml-ast-parser","lang":"bash","label":"npm"},{"cmd":"yarn add yaml-ast-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add yaml-ast-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `load` function is the primary entry point for parsing a YAML string into an AST. While CommonJS `require` might technically work in some environments due to transpilation, it's generally discouraged for type safety and modern module practices, especially since this library ships TypeScript types.","wrong":"const { load } = require('yaml-ast-parser');","symbol":"load","correct":"import { load } from 'yaml-ast-parser';"},{"note":"The `Kind` enum defines the types of YAML nodes (e.g., `SCALAR`, `MAP`, `SEQ`). It's crucial for type-checking and safely casting `YAMLNode` instances to their specific descendant types like `YAMLScalar` or `YamlMap`. Avoid adding `YAMLNode` prefix as it's just `Kind`.","wrong":"import { YAMLNodeKind } from 'yaml-ast-parser';","symbol":"Kind","correct":"import { Kind } from 'yaml-ast-parser';"},{"note":"`YAMLNode` is the base interface for all AST nodes. To access specific properties like `value` on scalars or `mappings` on maps, you need to import and cast to the appropriate descendant type (e.g., `YAMLScalar`, `YamlMap`). It is not a default export.","wrong":"import YAMLNode from 'yaml-ast-parser';","symbol":"YAMLNode","correct":"import { YAMLNode, YAMLScalar, YamlMap, YAMLSequence, YAMLMapping } from 'yaml-ast-parser';"},{"note":"These helper functions are used to inspect and parse the string `value` of a `YAMLScalar` based on the Core Schema rules. They are named exports and useful for interpreting scalar data.","wrong":"import { determineType } from 'yaml-ast-parser';","symbol":"determineScalarType","correct":"import { determineScalarType, parseYamlBoolean, parseYamlFloat, parseYamlInteger } from 'yaml-ast-parser';"}],"quickstart":{"code":"import { load, Kind, YAMLScalar, YamlMap, YAMLSequence, YAMLMapping, YAMLNode } from 'yaml-ast-parser';\n\nconst yamlContent = `\nname: John Doe\nage: 30\naddress:\n  street: 123 Main St\n  city: Anytown\nskills:\n  - TypeScript\n  - Node.js\n  - YAML\n`;\n\nfunction traverseAST(node: YAMLNode, level: number = 0) {\n  const indent = '  '.repeat(level);\n  console.log(`${indent}Kind: ${Kind[node.kind]} (Pos: ${node.startPosition}-${node.endPosition})`);\n\n  switch (node.kind) {\n    case Kind.SCALAR:\n      const scalarNode = node as YAMLScalar;\n      console.log(`${indent}  Value: '${scalarNode.value}'`);\n      break;\n    case Kind.MAP:\n      const mapNode = node as YamlMap;\n      mapNode.mappings.forEach(mapping => {\n        console.log(`${indent}  Key: '${(mapping.key as YAMLScalar).value}'`);\n        traverseAST(mapping.value, level + 1);\n      });\n      break;\n    case Kind.SEQ:\n      const sequenceNode = node as YAMLSequence;\n      sequenceNode.items.forEach(item => {\n        traverseAST(item, level + 1);\n      });\n      break;\n    case Kind.MAPPING:\n      const mappingNode = node as YAMLMapping;\n      // Key is a scalar, Value is a general YAMLNode\n      console.log(`${indent}  Mapping Key: '${(mappingNode.key as YAMLScalar).value}'`);\n      traverseAST(mappingNode.value, level + 1);\n      break;\n    default:\n      // Handle other kinds if necessary\n      break;\n  }\n}\n\nconst ast = load(yamlContent);\n\nif (ast) {\n  console.log('YAML AST Root Node:');\n  traverseAST(ast);\n} else {\n  console.error('Failed to parse YAML content.');\n}\n","lang":"typescript","description":"This quickstart demonstrates how to parse a YAML string into an AST and then recursively traverse the resulting `YAMLNode` structure, printing the kind and value of each node. It highlights the use of `load`, `Kind` enum, and type casting for specific node types like `YAMLScalar`, `YamlMap`, and `YAMLSequence` to access their distinct properties."},"warnings":[{"fix":"For new projects, consider actively maintained YAML parsing libraries or forks that provide similar AST capabilities. For existing projects, pin the exact version to mitigate unexpected behavior, and be aware of potential vulnerabilities or unaddressed issues.","message":"The `yaml-ast-parser` project appears to be abandoned, with no significant updates or commits in several years. This means there's no ongoing maintenance, bug fixes, or security patches, which could pose risks for long-term projects.","severity":"gotcha","affected_versions":">=0.0.43"},{"fix":"Always pin exact versions (`npm install yaml-ast-parser@0.0.43`) and thoroughly test any updates, even minor ones, if a newer version were to be released. This is less critical now due to abandonment but important to note historically.","message":"The library uses `0.0.x` versioning, which typically indicates a pre-1.0.0 state where the API is not yet stable and breaking changes can occur without major version bumps. Although the project is abandoned now, this was a common risk during its active development.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Understand the specific differences between `yaml-ast-parser` and `js-yaml` relevant to your use case. If you rely on the fork's unique features, ensure they meet your requirements, and be prepared for potential incompatibilities with standard YAML parsers for complex documents.","message":"`yaml-ast-parser` is a fork of `js-yaml`. While it adds AST functionality and `!include` support, it may not keep pace with `js-yaml`'s updates, bug fixes, or new features. This could lead to diverging behavior or missing compatibility with newer YAML specifications.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using ES Module syntax: `import { load } from 'yaml-ast-parser';`. If using TypeScript, check your `tsconfig.json` for `module` and `moduleResolution` settings (e.g., `\"module\": \"commonjs\"` or `\"esnext\"`, `\"moduleResolution\": \"node\"` or `\"bundler\"`).","cause":"This error often occurs when attempting to use CommonJS `require` with a library primarily designed for ES Modules, or when trying to destructure a default export as a named export.","error":"TypeError: (0 , yaml_ast_parser_1.load) is not a function"},{"fix":"Before accessing specific properties, check the `kind` of the `YAMLNode` using the `Kind` enum and cast it to the appropriate specific type. For example: `if (node.kind === Kind.SCALAR) { const scalarNode = node as YAMLScalar; console.log(scalarNode.value); }`","cause":"The `value` property is specific to `YAMLScalar` nodes, but you are trying to access it on the generic `YAMLNode` type without proper type narrowing or casting.","error":"Property 'value' does not exist on type 'YAMLNode'."},{"fix":"Ensure that you verify the `kind` of the `YAMLNode` before attempting to access type-specific properties. For sequences: `if (node.kind === Kind.SEQ) { const sequenceNode = node as YAMLSequence; sequenceNode.items.forEach(...); }`","cause":"This typically happens when trying to access the `items` property, which belongs to `YAMLSequence` nodes, on a node that is not a sequence (e.g., a scalar or a map).","error":"Cannot read properties of undefined (reading 'items')"}],"ecosystem":"npm"}