feat(yaml/unstable): allow to add custom types for parse and stringify (#6841)

Author: oscarotero

yaml/_schema.ts

@@ -46,8 +46,12 @@ import { undefinedType } from "./_type/undefined.ts";
  */
 export type SchemaType = "failsafe" | "json" | "core" | "default" | "extended";
 
-type ImplicitType = Type<"scalar">;
-type ExplicitType = Type<KindType>;
+/**
+ * A type that can be implicitly resolved (i.e. without using a tag) when
+ * loading a YAML document.
+ */
+export type ImplicitType = Type<"scalar">;
+export type ExplicitType = Type<KindType>;
 
 export type TypeMap = Record<
   KindType | "fallback",
@@ -161,3 +165,19 @@ export const SCHEMA_MAP = new Map<SchemaType, Schema>([
   ["json", JSON_SCHEMA],
   ["extended", EXTENDED_SCHEMA],
 ]);
+
+export function getSchema(
+  schema: SchemaType = "default",
+  types?: ImplicitType[],
+): Schema {
+  const schemaObj = SCHEMA_MAP.get(schema)!;
+
+  if (!types) {
+    return schemaObj;
+  }
+
+  return createSchema({
+    implicitTypes: [...types, ...schemaObj.implicitTypes],
+    explicitTypes: [...schemaObj.explicitTypes],
+  });
+}

yaml/_type.ts

@@ -4,6 +4,9 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 // This module is browser compatible.
 
+/**
+ * The kind of YAML node.
+ */
 export type KindType = "sequence" | "scalar" | "mapping";
 /**
  * The style variation for `styles` option of {@linkcode stringify}
@@ -17,17 +20,30 @@ export type StyleVariant =
   | "octal"
   | "hexadecimal";
 
+/**
+ * Function to convert data to a string for YAML serialization.
+ */
 export type RepresentFn<D> = (data: D, style?: StyleVariant) => string;
 
+/**
+ * A type definition for a YAML node.
+ */
 // deno-lint-ignore no-explicit-any
 export interface Type<K extends KindType, D = any> {
+  /** Tag to identify the type */
   tag: string;
+  /** Kind of type */
   kind: K;
+  /** Cast the type. Used to stringify */
   predicate?: (data: unknown) => data is D;
+  /** Function to represent data. Used to stringify */
   represent?: RepresentFn<D> | Record<string, RepresentFn<D>>;
+  /** Default style for the type. Used to stringify */
   defaultStyle?: StyleVariant;
+  /** Function to test whether data can be resolved by this type. Used to parse */
   // deno-lint-ignore no-explicit-any
   resolve: (data: any) => boolean;
+  /** Function to construct data from string. Used to parse */
   // deno-lint-ignore no-explicit-any
   construct: (data: any) => D;
 }

yaml/deno.json

@@ -5,6 +5,7 @@
     ".": "./mod.ts",
     "./parse": "./parse.ts",
     "./stringify": "./stringify.ts",
-    "./unstable-stringify": "./unstable_stringify.ts"
+    "./unstable-stringify": "./unstable_stringify.ts",
+    "./unstable-parse": "./unstable_parse.ts"
   }
 }

yaml/parse_test.ts

@@ -4,6 +4,7 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 
 import { parse, parseAll } from "./parse.ts";
+import { type ImplicitType, parse as unstableParse } from "./unstable_parse.ts";
 import {
   assert,
   assertEquals,
@@ -492,6 +493,36 @@ Deno.test({
   },
 });
 
+Deno.test({
+  name: "unstableParse() handles custom types",
+  fn() {
+    const foo: ImplicitType = {
+      tag: "tag:custom:smile",
+      resolve: (data: string): boolean => data === "=)",
+      construct: (): string => "🙂",
+      predicate: (data: unknown): data is string => data === "🙂",
+      kind: "scalar",
+      represent: (): string => "=)",
+    };
+
+    assertEquals(
+      unstableParse(
+        `
+title: =)
+tags:
+  - =)
+  - bar
+`,
+        { extraTypes: [foo] },
+      ),
+      {
+        title: "🙂",
+        tags: ["🙂", "bar"],
+      },
+    );
+  },
+});
+
 Deno.test("parse() handles !!pairs type", () => {
   assertEquals(
     parse(`!!pairs

yaml/stringify_test.ts

@@ -5,7 +5,10 @@
 
 import { assertEquals, assertThrows } from "@std/assert";
 import { stringify } from "./stringify.ts";
-import { stringify as unstableStringify } from "./unstable_stringify.ts";
+import {
+  type ImplicitType,
+  stringify as unstableStringify,
+} from "./unstable_stringify.ts";
 import { compare, parse } from "@std/semver";
 
 Deno.test({
@@ -867,3 +870,29 @@ Deno.test({
     );
   },
 });
+
+Deno.test({
+  name: "unstableStringify() handles custom types",
+  fn() {
+    const foo: ImplicitType = {
+      tag: "tag:custom:smile",
+      resolve: (data: string): boolean => data === "=)",
+      construct: (): string => "🙂",
+      predicate: (data: unknown): data is string => data === "🙂",
+      kind: "scalar",
+      represent: (): string => "=)",
+    };
+
+    assertEquals(
+      unstableStringify({
+        title: "🙂",
+        tags: ["🙂", "bar"],
+      }, { extraTypes: [foo] }),
+      `title: =)
+tags:
+  - =)
+  - bar
+`,
+    );
+  },
+});

yaml/unstable_parse.ts

@@ -0,0 +1,116 @@
+// Ported from js-yaml v3.13.1:
+// https://github.com/nodeca/js-yaml/commit/665aadda42349dcae869f12040d9b10ef18d12da
+// Copyright 2011-2015 by Vitaly Puzrin. All rights reserved. MIT license.
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+
+import { isEOL } from "./_chars.ts";
+import { LoaderState } from "./_loader_state.ts";
+import type { ParseOptions as StableParseOptions } from "./parse.ts";
+import { getSchema, type ImplicitType, type SchemaType } from "./_schema.ts";
+import type { KindType, RepresentFn, Type } from "./_type.ts";
+
+export type { ImplicitType, KindType, RepresentFn, SchemaType, Type };
+
+/** Options for {@linkcode parse}. */
+export type ParseOptions = StableParseOptions & {
+  /**
+   * Extra types to be added to the schema.
+   */
+  extraTypes?: ImplicitType[];
+};
+
+function sanitizeInput(input: string) {
+  input = String(input);
+
+  if (input.length > 0) {
+    // Add trailing `\n` if not exists
+    if (!isEOL(input.charCodeAt(input.length - 1))) input += "\n";
+
+    // Strip BOM
+    if (input.charCodeAt(0) === 0xfeff) input = input.slice(1);
+  }
+
+  // Use 0 as string terminator. That significantly simplifies bounds check.
+  input += "\0";
+
+  return input;
+}
+
+/**
+ * Parse and return a YAML string as a parsed YAML document object.
+ *
+ * Note: This does not support functions. Untrusted data is safe to parse.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse } from "@std/yaml/parse";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const data = parse(`
+ * id: 1
+ * name: Alice
+ * `);
+ *
+ * assertEquals(data, { id: 1, name: "Alice" });
+ * ```
+ *
+ * @throws {SyntaxError} Throws error on invalid YAML.
+ * @param content YAML string to parse.
+ * @param options Parsing options.
+ * @returns Parsed document.
+ */
+export function parse(
+  content: string,
+  options: ParseOptions = {},
+): unknown {
+  content = sanitizeInput(content);
+  const state = new LoaderState(content, {
+    ...options,
+    schema: getSchema(options.schema, options.extraTypes),
+  });
+  const documentGenerator = state.readDocuments();
+  const document = documentGenerator.next().value;
+  if (!documentGenerator.next().done) {
+    throw new SyntaxError(
+      "Found more than 1 document in the stream: expected a single document",
+    );
+  }
+  return document ?? null;
+}
+
+/**
+ * Same as {@linkcode parse}, but understands multi-document YAML sources, and
+ * returns multiple parsed YAML document objects.
+ *
+ * @example Usage
+ * ```ts
+ * import { parseAll } from "@std/yaml/parse";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const data = parseAll(`
+ * ---
+ * id: 1
+ * name: Alice
+ * ---
+ * id: 2
+ * name: Bob
+ * ---
+ * id: 3
+ * name: Eve
+ * `);
+ * assertEquals(data, [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" }]);
+ * ```
+ *
+ * @param content YAML string to parse.
+ * @param options Parsing options.
+ * @returns Array of parsed documents.
+ */
+export function parseAll(content: string, options: ParseOptions = {}): unknown {
+  content = sanitizeInput(content);
+  const state = new LoaderState(content, {
+    ...options,
+    schema: getSchema(options.schema, options.extraTypes),
+  });
+  return [...state.readDocuments()];
+}

yaml/unstable_stringify.ts

@@ -5,8 +5,11 @@
 // This module is browser compatible.
 
 import { DumperState } from "./_dumper_state.ts";
-import { SCHEMA_MAP } from "./_schema.ts";
+import { getSchema, type ImplicitType, type SchemaType } from "./_schema.ts";
 import type { StringifyOptions as StableStringifyOptions } from "./stringify.ts";
+import type { KindType, RepresentFn, Type } from "./_type.ts";
+
+export type { ImplicitType, KindType, RepresentFn, SchemaType, Type };
 
 /** Options for {@linkcode stringify}. */
 export type StringifyOptions = StableStringifyOptions & {
@@ -18,6 +21,11 @@ export type StringifyOptions = StableStringifyOptions & {
    * @default {`'`}
    */
   quoteStyle?: "'" | '"';
+
+  /**
+   * Extra types to be added to the schema.
+   */
+  extraTypes?: ImplicitType[];
 };
 
 /**
@@ -45,7 +53,7 @@ export function stringify(
 ): string {
   const state = new DumperState({
     ...options,
-    schema: SCHEMA_MAP.get(options.schema!)!,
+    schema: getSchema(options.schema, options.extraTypes),
   });
   return state.stringify(data);
 }