# yaml-types

> Useful JavaScript types for YAML

Latest version **0.4.0** (published 2024-07-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install yaml-types
pnpm add yaml-types
yarn add yaml-types
bun add yaml-types
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2024-07-07 |
| First published | 2023-04-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >= 16 |
| Dependencies | 0 |
| Unpacked size | 23.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Eemeli Aro |
| Maintainers | eemeli |
| Keywords | YAML, schema, tags |

## Links

- npm: https://www.npmjs.com/package/yaml-types
- Repository: https://github.com/eemeli/yaml-types
- Homepage: https://eemeli.org/yaml/
- Issues: https://github.com/eemeli/yaml-types/issues
- npm.io page: https://npm.io/package/yaml-types

## 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

- 0.4.0 (latest) — 2024-07-07
- 0.3.0 — 2023-05-31
- 0.2.0 — 2023-05-23
- 0.1.0 — 2023-04-14

## README

# yaml-types

Additional useful types for [`yaml`](https://github.com/eemeli/yaml).

## Installation and Usage

```
npm install yaml yaml-types
```

Each type (a.k.a. "tag") is available as a named export of `'yaml-types'`.
These may then be used as [custom tags](https://eemeli.org/yaml/#writing-custom-tags):

```js
import { parse } from 'yaml'
import { regexp } from 'yaml-types'

const re = parse('!re /fo./g', { customTags: [regexp] })
'foxbarfoo'.match(re) // [ 'fox', 'foo' ]
```

## Available Types

- `bigint` (`!bigint`) - JavaScript [BigInt] values.
  Note: in order to use this effectively,
  a function must be provided as `customTags` in order to prepend the `bigint` tag,
  or else the built-in `!!int` tags will take priority.
  See [bigint.test.ts](./src/bigint.test.ts) for examples.
- `binary` (`!!binary`) - JavaScript [Uint8Array], one of the YAML 1.1 tags
- `classTag` (`!class`) - JavaScript [Class] values
- `error` (`!error`) - JavaScript [Error] objects
- `functionTag` (`!function`) - JavaScript [Function] values
  (will also be used to stringify Class values,
  unless the `classTag` tag is loaded ahead of `functionTag`)
- `nullobject` (`!nullobject`) - Object with a `null` prototype
- `omap` (`!!omap`) - JavaScript [Map], one of the YAML 1.1 tags
- `pairs` (`!!pairs`) - Ordered sequence of key-value [pairs], one of the YAML 1.1 tags
- `regexp` (`!re`) - [RegExp] values,
  using their default `/foo/flags` string representation.
- `set` (`!!set`) - JavaScript [Set], one of the YAML 1.1 tags
- `sharedSymbol` (`!symbol/shared`) - [Shared Symbols],
  i.e. ones created with `Symbol.for()`
- `symbol` (`!symbol`) - [Unique Symbols]
- `timestamp` (`!!timestamp`) - JavaScript [Date], one of the YAML 1.1 tags

The function and class values created by parsing `!function` and
`!class` tags will not actually replicate running code, but
rather no-op function/class values with matching name and
`toString` properties.

[BigInt]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
[Class]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
[Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
[Error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
[Function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
[Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
[Shared Symbols]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#shared_symbols_in_the_global_symbol_registry
[Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
[Unique Symbols]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
[pairs]: https://yaml.org/type/pairs.html

## Customising Tag Names

To use one of the types with a different tag identifier, set its `tag` value accordingly.
For example, to extend the default tag namespace with `!!js/symbol`
instead of using a local `!symbol` tag for Symbol values:

```js
import { stringify } from 'yaml'
import { symbol } from 'yaml-types'

const mysymbol = { ...symbol, tag: 'tag:yaml.org,2002:js/symbol' }
stringify(Symbol('foo'), { customTags: [mysymbol] })
```

```yaml
!!js/symbol foo
```

To use a named tag handle like `!js!symbol`, a few more steps are required:

```js
import { Document } from 'yaml'
import { symbol } from 'yaml-types'

const mysymbol = { ...symbol, tag: 'tag:js:symbol' }
const doc = new Document(Symbol('foo'), { customTags: [mysymbol] })
doc.directives.tags['!js!'] = 'tag:js:'
doc.toString()
```

```yaml
%TAG !js! tag:js:
---
!js!symbol foo
```

## Contributing

Additions to this library are very welcome!
Many data types are useful beyond any single project,
and while the core `yaml` library is mostly limited to the YAML spec,
no such restriction applies here.

The source code is written in [TypeScript], and the tests use [Node-Tap].
When submitting a PR for a new type, tests and documentation are required,
as well as satisfying [Prettier].

[TypeScript]: https://www.typescriptlang.org/
[Node-Tap]: https://node-tap.org/
[Prettier]: https://prettier.io/

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