0
# js-yaml
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: js-yaml
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install js-yaml`
10

11
## Core Imports
12

13
```javascript
14
const yaml = require('js-yaml');
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as yaml from 'js-yaml';
21
import { load, dump } from 'js-yaml';
22
```
23

24
## Basic Usage
25

26
```javascript
27
const fs = require('fs');
28
const yaml = require('js-yaml');
29

30
// Parse YAML from string
31
try {
32
  const doc = yaml.load('hello: world\ncount: 42');
33
  console.log(doc); // { hello: 'world', count: 42 }
34
} catch (e) {
35
  console.log(e);
36
}
37

38
// Parse YAML from file
39
try {
40
  const doc = yaml.load(fs.readFileSync('/path/to/file.yml', 'utf8'));
41
  console.log(doc);
42
} catch (e) {
43
  console.log(e);
44
}
45

46
// Serialize object to YAML
47
const obj = { hello: 'world', count: 42 };
48
const yamlString = yaml.dump(obj);
49
console.log(yamlString);
50
```
51

52
## Architecture
53

54
js-yaml is built around several key components:
55

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

62
## Capabilities
63

64
### YAML Loading and Parsing
65

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

68
```javascript { .api }
69
function load(input, options);
70
function loadAll(input, iterator, options);
71
```
72

73
[YAML Loading](./loading.md)
74

75
### YAML Dumping and Serialization
76

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

79
```javascript { .api }
80
function dump(input, options);
81
```
82

83
[YAML Dumping](./dumping.md)
84

85
### Schema and Type System
86

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

89
```javascript { .api }
90
class Schema extends Function;
91
class Type extends Function;
92
const FAILSAFE_SCHEMA, JSON_SCHEMA, CORE_SCHEMA, DEFAULT_SCHEMA;
93
const types: {
94
  binary: Type, float: Type, map: Type, null: Type, pairs: Type,
95
  set: Type, timestamp: Type, bool: Type, int: Type, merge: Type,
96
  omap: Type, seq: Type, str: Type
97
};
98
```
99

100
[Schema System](./schemas.md)
101

102
### Error Handling
103

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

106
```javascript { .api }
107
class YAMLException extends Error;
108
```
109

110
[Error Handling](./errors.md)
111

112
### Command Line Interface
113

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

116
```bash { .api }
117
js-yaml [-h] [-v] [-c] [-t] file
118
```
119

120
### Deprecated Functions (v3 Compatibility)
121

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

124
```javascript { .api }
125
function safeLoad(input, options);     // Use load() instead
126
function safeLoadAll(input, options);  // Use loadAll() instead  
127
function safeDump(input, options);     // Use dump() instead
128
```
129

130
## Types
131

132
```javascript { .api }
133
// Load options
134
interface LoadOptions {
135
  filename?: string;
136
  onWarning?: (warning: YAMLException) => void;
137
  schema?: Schema;
138
  json?: boolean;
139
}
140

141
// Dump options  
142
interface DumpOptions {
143
  indent?: number;
144
  noArrayIndent?: boolean;
145
  skipInvalid?: boolean;
146
  flowLevel?: number;
147
  styles?: object;
148
  schema?: Schema;
149
  sortKeys?: boolean | ((a: string, b: string) => number);
150
  lineWidth?: number;
151
  noRefs?: boolean;
152
  noCompatMode?: boolean;
153
  condenseFlow?: boolean;
154
  quotingType?: '"' | "'";
155
  forceQuotes?: boolean;
156
  replacer?: (key: string, value: any) => any;
157
}
158
```