What is yaml?
The 'yaml' npm package is a JavaScript library for parsing and serializing YAML, a human-friendly data serialization standard. It can be used to convert YAML to JSON and vice versa, and to work with YAML content programmatically in JavaScript.
What are yaml's main functionalities?
Parsing YAML to JSON
This feature allows you to parse a string of YAML content and convert it into a JavaScript object.
const yaml = require('yaml');
const yamlText = 'key: value\nnumber: 123';
const jsonObject = yaml.parse(yamlText);
console.log(jsonObject);
Stringifying JSON to YAML
This feature enables you to take a JavaScript object and serialize it into a YAML formatted string.
const yaml = require('yaml');
const jsonObject = { key: 'value', number: 123 };
const yamlText = yaml.stringify(jsonObject);
console.log(yamlText);
Custom Tags
This feature allows you to define custom tags for specialized YAML types, enabling the parsing of YAML content with custom data structures.
const yaml = require('yaml');
const customType = { identify: value => value instanceof Set, tag: 'tag:yaml.org,2002:set', resolve: (doc, cst) => new Set(cst.strValue.split(', ')) };
yaml.defaultOptions.customTags = [customType];
const yamlText = '!!set a, b, c';
const data = yaml.parse(yamlText);
console.log(data);
Other packages similar to yaml
js-yaml
js-yaml is another popular YAML parser and serializer for JavaScript. It offers similar functionality to the 'yaml' package, including parsing and stringifying, and it also provides a safe loading option to prevent executing arbitrary code during parsing.
yamljs
yamljs is a YAML parser and dumper written in JavaScript. It provides functionality similar to 'yaml' and 'js-yaml' but has a different API design and may have different performance characteristics.
YAML
JavaScript parser and stringifier for YAML 1.2
Note: yaml
0.x and 1.x are rather different implementations. For the earlier yaml
, see tj/js-yaml.
Usage
npm install yaml@next
import YAML from 'yaml'
const yaml =
`YAML:
- A human-readable data serialization language
- https://en.wikipedia.org/wiki/YAML
yaml:
- A complete JavaScript implementation
- https://www.npmjs.com/package/yaml
`
YAML.parse(yaml)
const docs = YAML.parseDocuments(yaml)
docs[0].toString() === yaml
Beta Progress
The reason why this project exists is to have a tool that's capable of properly generating and handling YAML files with comments, specifically to provide context for translation strings that have been lifted out of JS source code. We're not there quite yet, as the prerequisite for that is having a complete and functioning YAML library.
What Works So Far
Parsing
- Support for all YAML node types, including alias nodes and multi-document streams
- Complete support for the Fallback, JSON, and Core Schemas, as well as an "extended" schema that covers all of the YAML 1.1 scalar types except for
!!yaml
. YAML.parse
converts string input to native JavaScript values- Comments are parsed and included in the outputs of
YAML.parseAST
(lower-level AST of the input) and YAML.parseDocuments
(array of Document
objects with Map
/Seq
/Scalar
contents). These functions should never throw, but include arrays of errors
and warnings
. - Support for
<<
merge keys (default-disabled, enable with merge: true
option) - Complete match between the parsed
in.yaml
, in.json
, out.yaml
, and error
files across all of the yaml-test-suite test cases (note: A few of the tests are not in agreement with the spec, so this requires the use of a custom branch until the relevant pull requests and issues are resolved) - "Native"
Map
and Seq
collections have toJSON()
methods for bare JavaScript Object
and Array
output - Any string input should be accepted, and produce some output. Errors (if any) are not thrown, but included in the document's
errors
array
Creating
new YAML.Document()
does not need any arguments to create new documents, which may then have their #contents
set to any typeDocument#resolveValue(value)
wraps values in yaml
objects, deeply mapping arrays to Seq
, objects to Map
, and everything else to Scalar
- Comments can be attached on or before any
Seq
, Map
and Scalar
Stringifying
Document#toString()
produces idempotent YAML from all non-error spec examples and test suite cases- Comments and non-default tags are explicitly included in the output
- String output is folded when possible to fit to a max width of 80 characters (customisable)
AST#toString()
works completely, but is clumsy to use
Still Needs Work
- Alias nodes are resolved too early, and can't be created
- Need to consider handling stream input
- Better documentation