{"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,"search_vec":"'0.4.0':72 '1.1':56 'ad':85 'allow':34 'bigint':46 'binari':61 'built':100 'cadenc':80 'capabl':32 'class':51 'collect':15 'common':39 'compar':121 'compat':105 'complex':115 'current':68 'custom':20,125 'defin':124 'definit':102 'deseri':37 'differenti':95 'document':120 'eemeli/yaml':108 'error':48 'extend':29 'featur':83 'function':49 'handl':114 'increment':86 'javascript':4,17,40,116,130 'key':94 'librari':11,27,109 'like':44 'major':82 'manual':123 'object':43 'omap':62 'packag':74 'pair':63 'parser/stringifier':26 'pre':99 'pre-built':98 'primit':41 'process':112 'provid':13,97 'rather':87 'regexp':45 'relat':77 'releas':79 'schedul':92 'schema':132 'serial':35 'set':64 'simplifi':110 'slow':78 'specif':57 'stabl':69 'strict':91 'symbol':47 'tag':22,58,101,126,133 'timestamp':66 'type':2,7,18,117,129 'util':10 'version':70 'well':53 'yaml':1,6,21,25,30,55,119,131 'yaml-typ':5","created_at":"2026-04-21T04:50:07.556352+00:00","updated_at":"2026-04-21T04:50:07.556352+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://eemeli.org/yaml/","github":"https://github.com/eemeli/yaml-types","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/yaml-types","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}