{"id":15290,"library":"yaml-types","title":"YAML Types for JavaScript","description":"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.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/eemeli/yaml-types","tags":["javascript","YAML","schema","tags"],"install":[{"cmd":"npm install yaml-types","lang":"bash","label":"npm"},{"cmd":"yarn add yaml-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add yaml-types","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core YAML parsing/stringifying library that `yaml-types` extends.","package":"yaml","optional":false}],"imports":[{"note":"CommonJS `require` is not officially supported or documented for individual exports; use ESM named imports. The primary `yaml` dependency is ESM-first.","wrong":"const regexp = require('yaml-types').regexp","symbol":"regexp","correct":"import { regexp } from 'yaml-types'"},{"note":"The `parse` function comes from the peer dependency `yaml`, not `yaml-types`. Make sure to import it from the correct package.","symbol":"parse","correct":"import { parse } from 'yaml'"},{"note":"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.","symbol":"bigint","correct":"import { bigint } from 'yaml-types'"}],"quickstart":{"code":"import { parse, stringify } from 'yaml';\nimport { regexp, bigint, sharedSymbol, error, timestamp } from 'yaml-types';\n\n// Example 1: Parsing a RegExp\nconst yamlRegExp = '!re /test/gi';\nconst parsedRegExp = parse(yamlRegExp, { customTags: [regexp] });\nconsole.log('Parsed RegExp:', parsedRegExp); // Outputs a RegExp object\nconsole.log('RegExp match:', 'Testing123'.match(parsedRegExp));\n\n// Example 2: Stringifying a BigInt\nconst myBigInt = 123456789012345678901234567890n;\n// Note: bigint must be explicitly prioritized for accurate representation\nconst yamlBigInt = stringify(myBigInt, { customTags: [bigint] });\nconsole.log('Stringified BigInt:', yamlBigInt);\n\n// Example 3: Parsing a shared Symbol and a timestamp\nconst yamlComplex = `\n- !symbol/shared mySharedSymbol\n- !error \"Something went wrong\"\n- !!timestamp 2023-10-27T10:00:00Z\n`;\nconst parsedComplex = parse(yamlComplex, { customTags: [sharedSymbol, error, timestamp] });\nconsole.log('Parsed complex data:', parsedComplex);\nconsole.log('Is first item a shared symbol?', Symbol.for('mySharedSymbol') === parsedComplex[0]);\nconsole.log('Error message:', parsedComplex[1].message);\n","lang":"typescript","description":"Demonstrates parsing and stringifying various JavaScript types like RegExp, BigInt, Symbol, Error, and Date using custom YAML tags provided by `yaml-types`."},"warnings":[{"fix":"Upgrade your `yaml` package to version `^2.3.0` or higher (`npm install yaml@^2.3.0`).","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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] })`.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Order your custom tags as `[classTag, functionTag]` when defining them for `parse` or `stringify` options to ensure correct type inference.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `regexp` is included in the `customTags` array when calling `parse` from `yaml`: `parse(yamlString, { customTags: [regexp] })`.","cause":"Attempting to call `.match()` on a RegExp object that was not correctly parsed from YAML due to missing `regexp` custom tag.","error":"TypeError: Cannot read properties of undefined (reading 'match')"},{"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.","cause":"Incorrectly passing a string or non-object value where a tag object is expected in the `customTags` array.","error":"Error: Expected custom tag to be a plain object with tag and resolve properties, or an array of tags"}],"ecosystem":"npm"}