# @koerber/yaml

> Simple extension to JS-YAML

Latest version **1.0.5** (published 2019-06-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @koerber/yaml
pnpm add @koerber/yaml
yarn add @koerber/yaml
bun add @koerber/yaml
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2019-06-11 |
| First published | 2019-03-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 8.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Pier Fumagalli |
| Maintainers | pfumagalli, themgoncalves |
| Keywords | yaml, parser, include |

## Links

- npm: https://www.npmjs.com/package/@koerber/yaml
- Repository: gith@github.com/KoerberDigitalDevTeam/yaml
- Homepage: https://github.com/KoerberDigitalDevTeam/yaml
- npm.io page: https://npm.io/package/@koerber/yaml

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 1.0.5 (latest) — 2019-06-11
- 1.0.4 — 2019-04-02
- 1.0.3 — 2019-03-28
- 1.0.2 — 2019-03-28

## README

Simple YAML parser wrapper with extensions
==========================================

This simply wraps the `js-yaml` package providing a `parse(...)` convenience
method to parse files *synchronously*, and adding a couple of useful tags.

Usage
-----

Very simply:

```javascript
const { parse } = require('@koerber/yaml')
let parsed = parse('my_file.yml')
```

An optional *second argument* to the `parse(...)` function allows to specify
the base schema for parsing (defaulting to `DEFAULT_SAFE_SCHEMA)`.

The module also exposes `dump(...)` as an alias to `js-yaml`'s `safeDump(...)`.


The `!include` tag
------------------

The `!include` tag will include another YAML file in the current one. For example:

```yaml
object:
  <<: !include other.yml
```

Given the contents of `other.yml` as:

```yaml
foo: bar
```

And noting the use of the `<<:` merging tag in this example, the resulting
parsed JSON will be:

```json
"object" {
  "foo": "bar"
}
```

The `!include` tag can be used also in included documents, and will resolve
file names relative to the _real path_ of the document where the tag is
specified (in other words, symlinks are followed).


The `!merge` tag
----------------

The `!merge` tag merges arrays of arrays into one single array. For example:

```yaml
array: !merge
  -
    - one
    - two
  -
    - three
    - four
  - five
  -
    - six
    - seven
```

Will be parsed as the following JSON:

```json
{
  "array": [
    "one",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven"
  ]
}
```

This is quite useful when used with references where a file like the following:

```yaml
base: &base
  - a
  - b
merged: !merge
  - *base
  - c
```

Will be parsed as the following JSON:

```json
{
  "base": [ "a", "b" ],
  "merged": [ "a", "b", "c" ]
}
```

Ultimately, this can also be used in conjunction with `!include` whereas:

```yaml
!merge
- !include other.yml
- baz
```

Given the following contents for `other.yml`:

```yaml
- foo
- bar
```

Will be parsed as the following JSON:

```json
[ "foo", "bar", "baz" ]
```

The `!join` tag
----------------

The `!join` tag joins array members into a string. For example:

```yaml
joined: !join
  - One
  - Two
  - Three
```

Will be parsed as the following JSON:

```json
{ "joined": "OneTwoThree" }
```

The same output can be expected for the following YAML syntax:

```yaml
joined: !join [ One, Two, Three ]
```

License
-------

This work is licensed under the [MIT License Agreement](LICENSE.md)

---
_Source: https://npm.io/package/@koerber/yaml · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._