js-yaml

js-yaml is a comprehensive YAML 1.2 parser and serializer for JavaScript environments, implementing the complete YAML specification with high performance and compatibility. It offers both loading (parsing) and dumping (serialization) functionality for YAML documents, supporting single and multi-document parsing, various schema types, and extensive configuration options for both parsing and serialization behaviors.

Package Information

• Package Name: js-yaml
• Package Type: npm
• Language: JavaScript
• Installation: npm install js-yaml

Core Imports

const yaml = require('js-yaml');

For ES modules:

import * as yaml from 'js-yaml';
import { load, dump } from 'js-yaml';

Basic Usage

const fs = require('fs');
const yaml = require('js-yaml');

// Parse YAML from string
try {
  const doc = yaml.load('hello: world\ncount: 42');
  console.log(doc); // { hello: 'world', count: 42 }
} catch (e) {
  console.log(e);
}

// Parse YAML from file
try {
  const doc = yaml.load(fs.readFileSync('/path/to/file.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}

// Serialize object to YAML
const obj = { hello: 'world', count: 42 };
const yamlString = yaml.dump(obj);
console.log(yamlString);

Architecture

js-yaml is built around several key components:

• Parsing Engine: Complete YAML 1.2 parser supporting all specification features
• Schema System: Extensible type system with built-in schemas (FAILSAFE, JSON, CORE, DEFAULT)
• Type System: Modular type definitions for custom YAML tags and data types
• Serialization Engine: Full-featured YAML dumper with extensive formatting options
• Error Handling: Detailed error reporting with position information and code snippets

Capabilities

YAML Loading and Parsing

Core functionality for parsing YAML documents into JavaScript objects, with support for single documents, multi-document streams, and various parsing options.

function load(input, options);
function loadAll(input, iterator, options);

YAML Loading

YAML Dumping and Serialization

Converts JavaScript objects to YAML strings with extensive formatting and style options for clean, readable output.

function dump(input, options);

YAML Dumping

Schema and Type System

Extensible schema system for controlling which YAML types are supported during parsing and serialization, with built-in schemas and support for custom types.

class Schema extends Function;
class Type extends Function;
const FAILSAFE_SCHEMA, JSON_SCHEMA, CORE_SCHEMA, DEFAULT_SCHEMA;
const types: {
  binary: Type, float: Type, map: Type, null: Type, pairs: Type,
  set: Type, timestamp: Type, bool: Type, int: Type, merge: Type,
  omap: Type, seq: Type, str: Type
};

Schema System

Error Handling

Comprehensive error handling with detailed position information and helpful error messages for debugging YAML parsing issues.

class YAMLException extends Error;

Error Handling

Command Line Interface

Built-in CLI tool for inspecting and processing YAML files from the command line.

js-yaml [-h] [-v] [-c] [-t] file

Deprecated Functions (v3 Compatibility)

Legacy functions from js-yaml v3 that now throw helpful migration errors.

function safeLoad(input, options);     // Use load() instead
function safeLoadAll(input, options);  // Use loadAll() instead  
function safeDump(input, options);     // Use dump() instead

Types

// Load options
interface LoadOptions {
  filename?: string;
  onWarning?: (warning: YAMLException) => void;
  schema?: Schema;
  json?: boolean;
}

// Dump options  
interface DumpOptions {
  indent?: number;
  noArrayIndent?: boolean;
  skipInvalid?: boolean;
  flowLevel?: number;
  styles?: object;
  schema?: Schema;
  sortKeys?: boolean | ((a: string, b: string) => number);
  lineWidth?: number;
  noRefs?: boolean;
  noCompatMode?: boolean;
  condenseFlow?: boolean;
  quotingType?: '"' | "'";
  forceQuotes?: boolean;
  replacer?: (key: string, value: any) => any;
}