YAML Types for JavaScript

Common errors

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

  cause 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

  cause 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.

Warnings

• breaking Version 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`).
• gotcha When 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] })`.
• gotcha The `!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.
• gotcha The `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.
• gotcha Modifying 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`.

Install

• npm install yaml-types npm
• yarn add yaml-types yarn
• pnpm add yaml-types pnpm

Imports

• regexp
  wrong:

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

  correct:

  import { regexp } from 'yaml-types'

  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.

Quickstart

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);