@stoplight/yaml

What is @stoplight/yaml?

@stoplight/yaml is a versatile npm package that provides utilities for parsing, stringifying, and processing YAML data. It is particularly useful for developers working with YAML configurations, API specifications, and other structured data formats.

What are @stoplight/yaml's main functionalities?

Parsing YAML to JavaScript Object

This feature allows you to convert a YAML string into a JavaScript object. The `parse` function takes a YAML string as input and returns the corresponding JavaScript object.

const { parse } = require('@stoplight/yaml');
const yamlString = 'key: value\nlist:\n  - item1\n  - item2';
const jsObject = parse(yamlString);
console.log(jsObject);

Stringifying JavaScript Object to YAML

This feature allows you to convert a JavaScript object into a YAML string. The `stringify` function takes a JavaScript object as input and returns the corresponding YAML string.

const { stringify } = require('@stoplight/yaml');
const jsObject = { key: 'value', list: ['item1', 'item2'] };
const yamlString = stringify(jsObject);
console.log(yamlString);

Handling YAML Errors

This feature demonstrates how to handle errors that may occur during YAML parsing. The `parse` function will throw an error if the input YAML string is invalid, which can be caught and handled appropriately.

const { parse } = require('@stoplight/yaml');
try {
  const jsObject = parse('invalid: yaml: string');
} catch (error) {
  console.error('YAML parsing error:', error.message);
}

Other packages similar to @stoplight/yaml

js-yaml

js-yaml is a popular YAML parser and dumper for JavaScript. It provides similar functionalities to @stoplight/yaml, such as parsing YAML strings to JavaScript objects and stringifying JavaScript objects to YAML. It is widely used and well-documented, making it a strong alternative.

yaml

yaml is another robust YAML parser and stringifier for JavaScript. It offers a comprehensive set of features, including support for custom tags and schema definitions. It is known for its performance and flexibility, making it a good choice for complex YAML processing tasks.

yamljs

yamljs is a lightweight YAML parser and stringifier for JavaScript. It provides basic functionalities for converting between YAML strings and JavaScript objects. While it may not have as many features as some other packages, it is easy to use and suitable for simple YAML processing needs.

README

@stoplight/yaml

Useful functions when working with YAML.

• Explore the interfaces: TSDoc
• View the changelog: Releases

Installation

Supported in modern browsers and node.

# latest stable
yarn add @stoplight/yaml

Usage

• getJsonPathForPosition: Computes JSON path for given position.
• getLocationForJsonPath: Retrieves location of node matching given JSON path.
• parseWithPointers: Parses YAML into JSON and also returns diagnostics as well as full ast with line information.

// basic example of parseWithPointers
import { parseWithPointers } from "@stoplight/yaml";

const result = parseWithPointers("foo: bar");

console.log(result.data); // => the {foo: "bar"} JS object

// basic example of getJsonPathForPosition and getLocationForJsonPath
import { getJsonPathForPosition, getLocationForJsonPath, parseWithPointers } from "@stoplight/yaml";

const result = parseWithPointers(`hello: world
address:
    street: 123`
);

const path = getJsonPathForPosition(result, { line: 2, character: 7 }); // line and character are 0-based
console.log(path); // -> ["address", "street"];

const position = getLocationForJsonPath(result, ['address']);
console.log(position.range.start); // { line: 1, character: 8 } line and character are 0-based
console.log(position.range.end); // { line: 2, character: 15 } line and character are 0-based

Contributing

1. Clone repo.
2. Create / checkout feature/{name}, chore/{name}, or fix/{name} branch.
3. Install deps: yarn.
4. Make your changes.
5. Run tests: yarn test.prod.
6. Stage relevant files to git.
7. Commit: yarn commit. NOTE: Commits that don't follow the conventional format will be rejected. yarn commit creates this format for you, or you can put it together manually and then do a regular git commit.
8. Push: git push.
9. Open PR targeting the next branch.