yaml-types

library0.4.0jsnpmunverified

yaml-types is a utility library that provides a collection of JavaScript types as custom YAML tags for the `yaml` parser/stringifier library. It extends YAML's capabilities by allowing serialization and deserialization of common JavaScript primitives and objects like `RegExp`, `BigInt`, `Symbol`, `Error`, `Function`, and `Class`, as well as YAML 1.1 specific tags such as `!!binary`, `!!omap`, `!!pairs`, `!!set`, and `!!timestamp`. The current stable version is 0.4.0. The package has a relatively slow release cadence, with major features being added incrementally rather than on a strict schedule. Its key differentiator is providing pre-built tag definitions that are compatible with the `eemeli/yaml` library, simplifying the process of handling complex JavaScript types in YAML documents compared to manually defining custom tags for each type.

serialization

npm install yaml-types

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · YAML-TYPES

yaml-types

serializationjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

regexp

✓ import { regexp } from 'yaml-types'

✗ const regexp = require('yaml-types').regexp

CommonJS `require` is not officially supported or documented for individual exports; use ESM named imports. The primary `yaml` dependency is ESM-first.

parse

✓ import { parse } from 'yaml'

The `parse` function comes from the peer dependency `yaml`, not `yaml-types`. Make sure to import it from the correct package.

bigint

✓ import { bigint } from 'yaml-types'

When using `bigint`, it often needs to be explicitly prepended in `customTags` array during parsing/stringifying to override built-in `!!int` tags which might take precedence for integer-like strings.

Demonstrates parsing and stringifying various JavaScript types like RegExp, BigInt, Symbol, Error, and Date using custom YAML tags provided by `yaml-types`.

import { parse, stringify } from 'yaml'; import { regexp, bigint, sharedSymbol, error, timestamp } from 'yaml-types'; // Example 1: Parsing a RegExp const yamlRegExp = '!re /test/gi'; const parsedRegExp = parse(yamlRegExp, { customTags: [regexp] }); console.log('Parsed RegExp:', parsedRegExp); // Outputs a RegExp object console.log('RegExp match:', 'Testing123'.match(parsedRegExp)); // Example 2: Stringifying a BigInt const myBigInt = 123456789012345678901234567890n; // Note: bigint must be explicitly prioritized for accurate representation const yamlBigInt = stringify(myBigInt, { customTags: [bigint] }); console.log('Stringified BigInt:', yamlBigInt); // Example 3: Parsing a shared Symbol and a timestamp const yamlComplex = ` - !symbol/shared mySharedSymbol - !error "Something went wrong" - !!timestamp 2023-10-27T10:00:00Z `; const parsedComplex = parse(yamlComplex, { customTags: [sharedSymbol, error, timestamp] }); console.log('Parsed complex data:', parsedComplex); console.log('Is first item a shared symbol?', Symbol.for('mySharedSymbol') === parsedComplex[0]); console.log('Error message:', parsedComplex[1].message);

Debug

Known issues

breakingVersion 0.2.0 introduced a peer dependency requirement for `yaml` version `^2.3.0`. Users on older `yaml` versions will encounter peer dependency warnings or errors during installation.

fix

Upgrade your `yaml` package to version `^2.3.0` or higher (`npm install yaml@^2.3.0`).

affects: >=0.2.0

gotchaWhen using the `bigint` tag, it is crucial to ensure it is placed correctly within the `customTags` array, typically at the beginning, to prevent the default `!!int` tag from `yaml` from incorrectly parsing or stringifying BigInt values as standard integers if their string representation looks like a regular number.

fix

When using `customTags`, explicitly include `bigint` and ensure it's prioritized, e.g., `parse(data, { customTags: [bigint, ...otherTags] })` or `stringify(data, { customTags: [bigint, ...otherTags] })`.

affects: >=0.3.0

gotchaThe `!function` and `!class` tags do not replicate executable code. Instead, they produce no-op function/class values with matching names and `toString` properties. This means any methods or logic within the original function/class will not be preserved or restored.

fix

Be aware that parsing `!function` or `!class` tags results in non-functional placeholders. If you need to serialize actual code logic, this library is not suitable; consider alternative serialization strategies or explicitly documenting this limitation.

affects: >=0.2.0

gotchaThe `functionTag` can stringify `Class` values if `classTag` is not loaded ahead of it. To correctly distinguish between functions and classes in stringification, ensure `classTag` is listed before `functionTag` in your `customTags` array.

fix

Order your custom tags as `[classTag, functionTag]` when defining them for `parse` or `stringify` options to ensure correct type inference.

affects: >=0.2.0

gotchaModifying default tag identifiers requires creating a new tag object with the desired `tag` property. This is especially relevant for using YAML 1.1 tags with different local prefixes or integrating into custom tag namespaces.

fix

To change a tag's identifier, spread the original tag and override the `tag` property, e.g., `const customSymbolTag = { ...symbol, tag: 'tag:yaml.org,2002:js/symbol' };`. For named tag handles, you'll also need to configure `doc.directives.tags`.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'match')

Attempting to call `.match()` on a RegExp object that was not correctly parsed from YAML due to missing `regexp` custom tag.

fix

Ensure `regexp` is included in the `customTags` array when calling `parse` from `yaml`: `parse(yamlString, { customTags: [regexp] })`.

Error: Expected custom tag to be a plain object with tag and resolve properties, or an array of tags

Incorrectly passing a string or non-object value where a tag object is expected in the `customTags` array.

fix

Verify that all items in the `customTags` array are valid tag objects imported from `yaml-types` (e.g., `regexp`, `bigint`) or custom tag definitions that conform to the expected structure.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

yamlrequiredCore YAML parsing/stringifying library that `yaml-types` extends.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eemeli/yaml-types ↗

packagehttps://www.npmjs.com/package/yaml-types ↗

homepagehttps://eemeli.org/yaml/ ↗