YAML AST Parser for Language Servers

Common errors

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

  cause Attempting to use CommonJS `require` syntax (`const { load } = require('...')`) or incorrect destructuring when the module is primarily designed for ES Module (ESM) imports.
  fix Use ES module import syntax: `import { load } from 'yaml-language-server-parser';`. Ensure your environment supports ESM or use a bundler/transpiler like Webpack/Rollup/Babel.

• Cannot find module 'yaml-language-server-parser' or its corresponding type declarations.

  cause The package is not installed, installed incorrectly, or TypeScript cannot locate its type definitions.
  fix Run `npm install yaml-language-server-parser` or `yarn add yaml-language-server-parser`. For TypeScript, ensure `esModuleInterop` is enabled in `tsconfig.json` if encountering import issues with older module resolutions.

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

  cause Attempting to access a property specific to a derived AST node type (e.g., `YAMLScalar.value`) directly on the base `YAMLNode` type without first checking its `kind` and casting.
  fix Always check the `kind` property of a `YAMLNode` against the `Kind` enum (e.g., `if (node.kind === Kind.SCALAR)`) and then cast it to the appropriate derived type (e.g., `(node as YAMLScalar).value`) before accessing type-specific properties.

Warnings

• gotcha This package is a maintained fork specifically for the YAML Language Server. If you're looking for the original, less-maintained `YAML-AST-PARSER` or the general-purpose `JS-YAML`, ensure you're installing the correct package (`yaml-language-server-parser` for language server tooling).
  Fix: Verify your `package.json` to ensure `yaml-language-server-parser` is the intended dependency for language server related YAML parsing.
• gotcha The parser includes built-in support for the `!include` tag, often used in RAML. This is a non-standard YAML extension. Users expecting strict YAML 1.2 parsing without custom tag handling might need to be aware of this behavior, as it deviates from standard YAML specifications.
  Fix: If `!include` tag behavior is undesired or causes conflicts, custom tag resolvers may be necessary, though the package is designed to support this specific extension.
• gotcha The package version (e.g., 0.1.3) might imply an early development stage to some users. While it is a 'maintained fork' and stable for its intended use case (language servers), broader or high-traffic general-purpose YAML parsing might require evaluating its maturity for your specific requirements.
  Fix: Consult the GitHub repository for recent activity and issue trends to gauge ongoing maintenance and stability if using for critical, non-language-server applications.

Install

• npm install yaml-language-server-parser npm
• yarn add yaml-language-server-parser yarn
• pnpm add yaml-language-server-parser pnpm

Imports

• load
  wrong:

  const load = require('yaml-language-server-parser').load;

  correct:

  import { load } from 'yaml-language-server-parser';

  The library primarily uses named exports and is designed for ESM consumption, though transpilation might allow CJS. TypeScript is fully supported.
• YAMLNode
  wrong:

  import YAMLNode from 'yaml-language-server-parser/YAMLNode';

  correct:

  import { YAMLNode, Kind, YAMLScalar, YamlMap, YAMLSequence } from 'yaml-language-server-parser';

  Core AST node types (YAMLNode and its descendants like YAMLScalar, YamlMap, etc., along with the Kind enum) are named exports from the root module.
• determineScalarType
  wrong:

  import { determineScalarType } from 'yaml-language-server-parser/lib/parser';

  correct:

  import { determineScalarType, parseYamlInteger } from 'yaml-language-server-parser';

  Helper functions for scalar type inference and parsing specific primitive types are named exports from the main package entry point.

Quickstart

Parses a multi-line YAML string into an Abstract Syntax Tree (AST), demonstrating how to navigate map and scalar nodes, identify their kinds, and use helper functions to determine and parse scalar values like integers and booleans. It also showcases accessing position information for nodes.

import { load, Kind, YAMLScalar, YamlMap, YAMLMapping, determineScalarType, parseYamlInteger, parseYamlBoolean } from 'yaml-language-server-parser';

const yamlString = `
# A simple YAML document
name: My Application
version: 1.0.0
config:
  port: 8080
  debug: true
  features:
    - user_auth
    - logging
`;

// Load the YAML string into an AST
const yamlNode = load(yamlString);

console.log('--- AST Analysis ---');

if (yamlNode.kind === Kind.MAP) {
  const rootMap = yamlNode as YamlMap;
  console.log(`Root node is a Map with ${rootMap.mappings.length} mappings.`);

  for (const mapping of rootMap.mappings) {
    if (mapping.key.value === 'name' && mapping.value?.kind === Kind.SCALAR) {
      const nameScalar = mapping.value as YAMLScalar;
      console.log(`Application Name: ${nameScalar.value}`);
    }

    if (mapping.key.value === 'config' && mapping.value?.kind === Kind.MAP) {
      const configMap = mapping.value as YamlMap;
      console.log(`  Config map found with ${configMap.mappings.length} items.`);

      for (const configMapping of configMap.mappings) {
        if (configMapping.key.value === 'port' && configMapping.value?.kind === Kind.SCALAR) {
          const portScalar = configMapping.value as YAMLScalar;
          console.log(`    Port (raw): ${portScalar.value}`);
          console.log(`    Port (type determined): ${determineScalarType(portScalar)}`);
          console.log(`    Port (parsed int): ${parseYamlInteger(portScalar.value)}`);
        }
        if (configMapping.key.value === 'debug' && configMapping.value?.kind === Kind.SCALAR) {
          const debugScalar = configMapping.value as YAMLScalar;
          console.log(`    Debug (raw): ${debugScalar.value}`);
          console.log(`    Debug (type determined): ${determineScalarType(debugScalar)}`);
          console.log(`    Debug (parsed bool): ${parseYamlBoolean(debugScalar.value)}`);
        }
      }
    }
  }
}

console.log(`\n'name' node starts at: ${yamlNode.mappings.find(m => m.key.value === 'name')?.key.startPosition}`);
console.log(`'name' node ends at: ${yamlNode.mappings.find(m => m.key.value === 'name')?.key.endPosition}`);