YAML AST Parser

Common errors

• TypeError: (0 , yaml_ast_parser_1.load) is not a function

  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.
  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"`).

• Property 'value' does not exist on type 'YAMLNode'.

  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.
  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); }`

• Cannot read properties of undefined (reading 'items')

  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).
  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(...); }`

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha `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.
  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.

Install

• npm install yaml-ast-parser npm
• yarn add yaml-ast-parser yarn
• pnpm add yaml-ast-parser pnpm

Imports

• load
  wrong:

  const { load } = require('yaml-ast-parser');

  correct:

  import { load } from 'yaml-ast-parser';

  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.
• Kind
  wrong:

  import { YAMLNodeKind } from 'yaml-ast-parser';

  correct:

  import { Kind } from 'yaml-ast-parser';

  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`.
• YAMLNode
  wrong:

  import YAMLNode from 'yaml-ast-parser';

  correct:

  import { YAMLNode, YAMLScalar, YamlMap, YAMLSequence, YAMLMapping } from 'yaml-ast-parser';

  `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.
• determineScalarType
  wrong:

  import { determineType } from 'yaml-ast-parser';

  correct:

  import { determineScalarType, parseYamlBoolean, parseYamlFloat, parseYamlInteger } from 'yaml-ast-parser';

  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.

Quickstart

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.

import { load, Kind, YAMLScalar, YamlMap, YAMLSequence, YAMLMapping, YAMLNode } from 'yaml-ast-parser';

const yamlContent = `
name: John Doe
age: 30
address:
  street: 123 Main St
  city: Anytown
skills:
  - TypeScript
  - Node.js
  - YAML
`;

function traverseAST(node: YAMLNode, level: number = 0) {
  const indent = '  '.repeat(level);
  console.log(`${indent}Kind: ${Kind[node.kind]} (Pos: ${node.startPosition}-${node.endPosition})`);

  switch (node.kind) {
    case Kind.SCALAR:
      const scalarNode = node as YAMLScalar;
      console.log(`${indent}  Value: '${scalarNode.value}'`);
      break;
    case Kind.MAP:
      const mapNode = node as YamlMap;
      mapNode.mappings.forEach(mapping => {
        console.log(`${indent}  Key: '${(mapping.key as YAMLScalar).value}'`);
        traverseAST(mapping.value, level + 1);
      });
      break;
    case Kind.SEQ:
      const sequenceNode = node as YAMLSequence;
      sequenceNode.items.forEach(item => {
        traverseAST(item, level + 1);
      });
      break;
    case Kind.MAPPING:
      const mappingNode = node as YAMLMapping;
      // Key is a scalar, Value is a general YAMLNode
      console.log(`${indent}  Mapping Key: '${(mappingNode.key as YAMLScalar).value}'`);
      traverseAST(mappingNode.value, level + 1);
      break;
    default:
      // Handle other kinds if necessary
      break;
  }
}

const ast = load(yamlContent);

if (ast) {
  console.log('YAML AST Root Node:');
  traverseAST(ast);
} else {
  console.error('Failed to parse YAML content.');
}