BREAKING(front-matter/unstable): move unstable overload of yaml extract to unstable-yaml (#5968)

_tools/check_docs.ts

@@ -57,6 +57,7 @@ const ENTRY_POINTS = [
   "../fmt/duration.ts",
   "../fmt/printf.ts",
   "../front_matter/mod.ts",
+  "../front_matter/unstable_yaml.ts",
   "../fs/mod.ts",
   "../html/mod.ts",
   "../html/unstable_is_valid_custom_element_name.ts",

front_matter/deno.json

@@ -8,6 +8,7 @@
     "./test": "./test.ts",
     "./toml": "./toml.ts",
     "./yaml": "./yaml.ts",
+    "./unstable-yaml": "./unstable_yaml.ts",
     "./types": "./types.ts"
   }
 }

front_matter/unstable_yaml.ts

@@ -0,0 +1,45 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+import { extractAndParse, type Parser } from "./_shared.ts";
+import { parse, type ParseOptions } from "@std/yaml/parse";
+import type { Extract } from "./types.ts";
+import { EXTRACT_YAML_REGEXP } from "./_formats.ts";
+
+export type { Extract };
+
+/**
+ * Extracts and parses {@link https://yaml.org | YAML} from the metadata of
+ * front matter content.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Extract YAML front matter
+ * ```ts
+ * import { extract } from "@std/front-matter/unstable-yaml";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const output = `---yaml
+ * date: 2022-01-01
+ * ---
+ * Hello, world!`;
+ * const result = extract(output, { schema: "json" });
+ *
+ * assertEquals(result, {
+ *   frontMatter: "date: 2022-01-01",
+ *   body: "Hello, world!",
+ *   attrs: { date: "2022-01-01" },
+ * });
+ * ```
+ *
+ * @typeParam T The type of the parsed front matter.
+ * @param text The text to extract YAML front matter from.
+ * @param options The options to pass to `@std/yaml/parse`.
+ * @returns The extracted YAML front matter and body content.
+ */
+export function extract<T>(text: string, options?: ParseOptions): Extract<T> {
+  return extractAndParse(
+    text,
+    EXTRACT_YAML_REGEXP,
+    ((s) => parse(s, options)) as Parser,
+  );
+}

front_matter/yaml.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { extractAndParse, type Parser } from "./_shared.ts";
-import { parse, type ParseOptions } from "@std/yaml/parse";
+import { parse } from "@std/yaml/parse";
 import type { Extract } from "./types.ts";
 import { EXTRACT_YAML_REGEXP } from "./_formats.ts";
 
@@ -29,45 +29,17 @@ export type { Extract };
  * });
  * ```
  *
+ * Note: If you need to pass the options to the yaml parse,
+ * use the new version of this API from `@std/yaml/unstable-yaml`.
+ *
  * @typeParam T The type of the parsed front matter.
  * @param text The text to extract YAML front matter from.
  * @returns The extracted YAML front matter and body content.
  */
-export function extract<T>(text: string): Extract<T>;
-/**
- * Extracts and parses {@link https://yaml.org | YAML} from the metadata of
- * front matter content.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Extract YAML front matter
- * ```ts
- * import { extract } from "@std/front-matter/yaml";
- * import { assertEquals } from "@std/assert";
- *
- * const output = `---yaml
- * date: 2022-01-01
- * ---
- * Hello, world!`;
- * const result = extract(output, { schema: "json" });
- *
- * assertEquals(result, {
- *   frontMatter: "date: 2022-01-01",
- *   body: "Hello, world!",
- *   attrs: { date: "2022-01-01" },
- * });
- * ```
- *
- * @typeParam T The type of the parsed front matter.
- * @param text The text to extract YAML front matter from.
- * @param options The options to pass to `@std/yaml/parse`.
- * @returns The extracted YAML front matter and body content.
- */
-export function extract<T>(text: string, options?: ParseOptions): Extract<T>;
-export function extract<T>(text: string, options?: ParseOptions): Extract<T> {
+export function extract<T>(text: string): Extract<T> {
   return extractAndParse(
     text,
     EXTRACT_YAML_REGEXP,
-    ((s) => parse(s, options)) as Parser,
+    ((s) => parse(s)) as Parser,
   );
 }

front_matter/yaml_test.ts

@@ -1,6 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { extract } from "./yaml.ts";
+import { extract as unstableExtract } from "./unstable_yaml.ts";
 import {
   runExtractTypeErrorTests,
   runExtractYamlTests1,
@@ -26,9 +27,9 @@ Deno.test("extractYaml() allows whitespaces after the header", () => {
   assertEquals(extract("= yaml =  \nfoo: 0\n---\n").attrs, { foo: 0 });
 });
 
-Deno.test("extractYaml() parses with schema options", () => {
+Deno.test("(unstable)extractYaml() parses with schema options", () => {
   assertEquals(
-    extract("---\ndate: 2024-08-20\n---\n", { schema: "json" }).attrs,
+    unstableExtract("---\ndate: 2024-08-20\n---\n", { schema: "json" }).attrs,
     {
       date: "2024-08-20",
     },