Convert Figma logo to code with AI

nodeca logojs-yaml

JavaScript YAML parser and dumper. Very fast.

6,265
768
6,265
61
View on GitHubView on NPM

Top Related Projects

yaml's avatar

pyyaml

2,524

Canonical source repository for PyYAML

go-yaml's avatar

yaml

6,829

YAML support for the Go language.

crdoconnor's avatar

strictyaml

1,458

Type-safe YAML parser and validator.

mikefarah's avatar

yq

11,663

yq is a portable command-line YAML, JSON, XML, CSV, TOML and properties processor

Quick Overview

js-yaml is a YAML parser and dumper for JavaScript. It allows you to convert between JavaScript objects and YAML documents, making it a useful tool for working with configuration files, data serialization, and other applications that require YAML support.

Pros

  • Comprehensive YAML Support: js-yaml supports the full YAML 1.2 specification, including features like anchors, aliases, and complex data structures.
  • High Performance: The library is written in pure JavaScript and is optimized for speed, making it a efficient choice for YAML processing.
  • Flexible API: The API provides a variety of methods for loading, dumping, and manipulating YAML data, allowing for easy integration into different projects and use cases.
  • Active Development: The project is actively maintained, with regular updates and bug fixes, ensuring ongoing support and improvements.

Cons

  • Limited Error Handling: While the library does provide some error handling, the error messages can sometimes be cryptic or difficult to interpret, especially for complex YAML documents.
  • Dependency on Node.js: The library is primarily designed for use in Node.js environments, and may require additional setup or configuration when used in browser-based applications.
  • Lack of Streaming Support: The library does not currently support streaming YAML parsing or dumping, which can be a limitation for processing large YAML files.
  • Potential Security Concerns: As with any library that parses untrusted input, there is a potential risk of security vulnerabilities if the YAML data is not properly validated.

Code Examples

Loading a YAML file:

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

try {
  const doc = yaml.load(fs.readFileSync('config.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.error(e);
}

Dumping a JavaScript object to YAML:

const data = {
  name: 'John Doe',
  age: 42,
  hobbies: ['reading', 'hiking', 'photography']
};

const yamlString = yaml.dump(data);
console.log(yamlString);

Handling YAML anchors and aliases:

const yamlString = `
- &person
  name: John Doe
  age: 42
- *person
  hobbies: [reading, hiking, photography]
`;

const doc = yaml.load(yamlString);
console.log(doc);

Validating YAML input:

const yamlString = `
- name: John Doe
  age: 42
- name: Jane Doe
  age: invalid
`;

try {
  const doc = yaml.load(yamlString, { filename: 'example.yml' });
  console.log(doc);
} catch (e) {
  console.error(e);
}

Getting Started

To use js-yaml in your project, you can install it via npm:

npm install js-yaml

Then, you can import the library and start using it in your code:

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

// Load a YAML file
const doc = yaml.load(fs.readFileSync('config.yml', 'utf8'));

// Dump a JavaScript object to YAML
const yamlString = yaml.dump({ name: 'John Doe', age: 42 });

// Handle YAML anchors and aliases
const yamlWithAnchors = `
- &person
  name: John Doe
  age: 42
- *person
  hobbies: [reading, hiking, photography]
`;
const docWithAnchors = yaml.load(yamlWithAnchors);

For more advanced usage and configuration options, please refer to the js-yaml documentation.

Competitor Comparisons

yaml logo

pyyaml

2,524

Canonical source repository for PyYAML

Pros of PyYAML

  • Native Python implementation, offering seamless integration with Python projects
  • Supports both YAML 1.1 and 1.2 specifications
  • Extensive documentation and well-established in the Python ecosystem

Cons of PyYAML

  • Generally slower performance compared to js-yaml
  • Less frequent updates and maintenance
  • Limited support for custom tags and advanced YAML features

Code Comparison

PyYAML:

import yaml

data = yaml.safe_load("""
- name: John
  age: 30
""")
print(data)

js-yaml:

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

const data = yaml.load(`
- name: John
  age: 30
`);
console.log(data);

Both libraries provide similar functionality for parsing YAML, but js-yaml offers a more modern and actively maintained codebase. PyYAML is better suited for Python-specific projects, while js-yaml is ideal for JavaScript and Node.js environments. js-yaml generally provides better performance and more frequent updates, making it a preferred choice for many developers working with YAML in JavaScript projects.

go-yaml logo

yaml

6,829

YAML support for the Go language.

Pros of yaml

  • Written in Go, offering better performance and concurrency support
  • Provides a more comprehensive API for advanced YAML manipulation
  • Supports YAML 1.2 specification, including merge keys and complex mappings

Cons of yaml

  • Less widespread adoption in JavaScript/Node.js ecosystems
  • May require additional setup for use in non-Go projects
  • Documentation is less extensive compared to js-yaml

Code Comparison

js-yaml:

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

const doc = yaml.load(fs.readFileSync('file.yml', 'utf8'));
console.log(doc);

yaml:

package main

import (
    "fmt"
    "io/ioutil"
    "gopkg.in/yaml.v3"
)

func main() {
    data, err := ioutil.ReadFile("file.yml")
    if err != nil {
        panic(err)
    }

    var doc map[string]interface{}
    err = yaml.Unmarshal(data, &doc)
    if err != nil {
        panic(err)
    }

    fmt.Printf("%v\n", doc)
}

The code comparison shows that while js-yaml offers a more concise syntax for parsing YAML in JavaScript, yaml provides a more robust error handling approach in Go. Both libraries offer similar functionality for reading and parsing YAML files, but the implementation differs based on the language and ecosystem they're designed for.

crdoconnor logo

strictyaml

1,458

Type-safe YAML parser and validator.

Pros of strictyaml

  • Focuses on simplicity and safety, reducing the risk of security vulnerabilities
  • Enforces a stricter subset of YAML, preventing common pitfalls and ambiguities
  • Provides clear error messages and validation, making debugging easier

Cons of strictyaml

  • Less flexible than js-yaml, with fewer features and customization options
  • Smaller community and ecosystem compared to js-yaml
  • Limited to Python, while js-yaml is available for JavaScript/Node.js

Code Comparison

strictyaml:

from strictyaml import load, Map, Str, Int

schema = Map({"name": Str(), "age": Int()})
data = load("name: John\nage: 30", schema)

js-yaml:

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

const data = yaml.load(fs.readFileSync('file.yml', 'utf8'));

strictyaml emphasizes schema validation and type checking, while js-yaml offers a more flexible approach to parsing YAML. The strictyaml example demonstrates built-in validation, whereas js-yaml requires additional steps for schema validation. js-yaml's simplicity in parsing without a schema can be both an advantage and a potential risk, depending on the use case.

mikefarah logo

yq

11,663

yq is a portable command-line YAML, JSON, XML, CSV, TOML and properties processor

Pros of yq

  • Command-line tool for YAML/JSON processing, offering easy manipulation and querying
  • Supports multiple input formats (YAML, JSON, XML, properties)
  • Provides powerful jq-like syntax for complex data transformations

Cons of yq

  • Limited to command-line usage, not suitable for in-application YAML parsing
  • Steeper learning curve for advanced operations compared to js-yaml
  • May be overkill for simple YAML parsing tasks

Code Comparison

yq:

yq e '.users[] | select(.age > 30)' input.yaml

js-yaml:

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

const data = yaml.load(fs.readFileSync('input.yaml', 'utf8'));
const filteredUsers = data.users.filter(user => user.age > 30);

Key Differences

  • yq is primarily a command-line tool, while js-yaml is a JavaScript library
  • yq offers more advanced data manipulation features out-of-the-box
  • js-yaml is better suited for integrating YAML parsing into JavaScript applications
  • yq supports multiple input formats, whereas js-yaml focuses solely on YAML
  • js-yaml provides a more straightforward API for basic YAML parsing and dumping

Use Cases

  • Choose yq for command-line YAML/JSON processing and complex data transformations
  • Opt for js-yaml when working with YAML in JavaScript applications or for simple parsing needs

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

JS-YAML - YAML 1.2 parser / writer for JavaScript

CI NPM version

Online Demo

This is an implementation of YAML, a human-friendly data serialization language. Started as PyYAML port, it was completely rewritten from scratch. Now it's very fast, and supports 1.2 spec.

Installation

YAML module for node.js

npm install js-yaml

CLI executable

If you want to inspect your YAML files from CLI, install js-yaml globally:

npm install -g js-yaml

Usage

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

Positional arguments:
  file           File with YAML document(s)

Optional arguments:
  -h, --help     Show this help message and exit.
  -v, --version  Show program's version number and exit.
  -c, --compact  Display errors in compact mode
  -t, --trace    Show stack trace on error

API

Here we cover the most 'useful' methods. If you need advanced details (creating your own tags), see examples for more info.

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

// Get document, or throw exception on error
try {
  const doc = yaml.load(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}

load (string [ , options ])

Parses string as single YAML document. Returns either a plain object, a string, a number, null or undefined, or throws YAMLException on error. By default, does not support regexps, functions and undefined.

options:

  • filename (default: null) - string to be used as a file path in error/warning messages.
  • onWarning (default: null) - function to call on warning messages. Loader will call this function with an instance of YAMLException for each warning.
  • schema (default: DEFAULT_SCHEMA) - specifies a schema to use.
  • json (default: false) - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.

NOTE: This function does not understand multi-document sources, it throws exception on those.

NOTE: JS-YAML does not support schema-specific tag resolution restrictions. So, the JSON schema is not as strictly defined in the YAML specification. It allows numbers in any notation, use Null and NULL as null, etc. The core schema also has no such restrictions. It allows binary notation for integers.

loadAll (string [, iterator] [, options ])

Same as load(), but understands multi-document sources. Applies iterator to each document if specified, or returns array of documents.

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

yaml.loadAll(data, function (doc) {
  console.log(doc);
});

dump (object [ , options ])

Serializes object as a YAML document. Uses DEFAULT_SCHEMA, so it will throw an exception if you try to dump regexps or functions. However, you can disable exceptions by setting the skipInvalid option to true.

options:

  • indent (default: 2) - indentation width to use (in spaces).
  • noArrayIndent (default: false) - when true, will not add an indentation level to array elements
  • skipInvalid (default: false) - do not throw on invalid types (like function in the safe schema) and skip pairs and single values with such types.
  • flowLevel (default: -1) - specifies level of nesting, when to switch from block to flow style for collections. -1 means block style everwhere
  • styles - "tag" => "style" map. Each tag may have own set of styles.
  • schema (default: DEFAULT_SCHEMA) specifies a schema to use.
  • sortKeys (default: false) - if true, sort keys when dumping YAML. If a function, use the function to sort the keys.
  • lineWidth (default: 80) - set max line width. Set -1 for unlimited width.
  • noRefs (default: false) - if true, don't convert duplicate objects into references
  • noCompatMode (default: false) - if true don't try to be compatible with older yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1
  • condenseFlow (default: false) - if true flow sequences will be condensed, omitting the space between a, b. Eg. '[a,b]', and omitting the space between key: value and quoting the key. Eg. '{"a":b}' Can be useful when using yaml for pretty URL query params as spaces are %-encoded.
  • quotingType (' or ", default: ') - strings will be quoted using this quoting style. If you specify single quotes, double quotes will still be used for non-printable characters.
  • forceQuotes (default: false) - if true, all non-key strings will be quoted even if they normally don't need to.
  • replacer - callback function (key, value) called recursively on each key/value in source object (see replacer docs for JSON.stringify).

The following table show availlable styles (e.g. "canonical", "binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml output is shown on the right side after => (default setting) or ->:

!!null
  "canonical"   -> "~"
  "lowercase"   => "null"
  "uppercase"   -> "NULL"
  "camelcase"   -> "Null"
  "empty"       -> ""

!!int
  "binary"      -> "0b1", "0b101010", "0b1110001111010"
  "octal"       -> "0o1", "0o52", "0o16172"
  "decimal"     => "1", "42", "7290"
  "hexadecimal" -> "0x1", "0x2A", "0x1C7A"

!!bool
  "lowercase"   => "true", "false"
  "uppercase"   -> "TRUE", "FALSE"
  "camelcase"   -> "True", "False"

!!float
  "lowercase"   => ".nan", '.inf'
  "uppercase"   -> ".NAN", '.INF'
  "camelcase"   -> ".NaN", '.Inf'

Example:

dump(object, {
  'styles': {
    '!!null': 'canonical' // dump null as ~
  },
  'sortKeys': true        // sort object keys
});

Supported YAML types

The list of standard YAML tags and corresponding JavaScript types. See also YAML tag discussion and YAML types repository.

!!null ''                   # null
!!bool 'yes'                # bool
!!int '3...'                # number
!!float '3.14...'           # number
!!binary '...base64...'     # buffer
!!timestamp 'YYYY-...'      # date
!!omap [ ... ]              # array of key-value pairs
!!pairs [ ... ]             # array or array pairs
!!set { ... }               # array of objects with given keys and null values
!!str '...'                 # string
!!seq [ ... ]               # array
!!map { ... }               # object

JavaScript-specific tags

See js-yaml-js-types for extra types.

Caveats

Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects or arrays as keys, and stringifies (by calling toString() method) them at the moment of adding them.

---
? [ foo, bar ]
: - baz
? { foo: bar }
: - baz
  - baz

{ "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }

Also, reading of properties on implicit block mapping keys is not supported yet. So, the following YAML document cannot be loaded.

&anchor foo:
  foo: bar
  *anchor: duplicate key
  baz: bat
  *anchor: duplicate key

js-yaml for enterprise

Available as part of the Tidelift Subscription

The maintainers of js-yaml and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

NPM DownloadsLast 30 Days