deprecation(yaml): cleanup schema exports (#4566)

Author: iuioiua

yaml/schema/core.ts

@@ -5,10 +5,22 @@
 // This module is browser compatible.
 
 import { Schema } from "../schema.ts";
-import { json } from "./json.ts";
+import { JSON_SCHEMA } from "./json.ts";
 
-// Standard YAML's Core schema.
-// http://www.yaml.org/spec/1.2/spec.html#id2804923
-export const core: Schema = new Schema({
-  include: [json],
+/**
+ * Standard YAML's core schema.
+ *
+ * @see {@link http://www.yaml.org/spec/1.2/spec.html#id2804923}
+ */
+export const CORE_SCHEMA: Schema = new Schema({
+  include: [JSON_SCHEMA],
 });
+
+/**
+ * Standard YAML's core schema.
+ *
+ * @see {@link http://www.yaml.org/spec/1.2/spec.html#id2804923}
+ *
+ * @deprecated (will be removed in 1.0.0) Use {@link CORE_SCHEMA} instead.
+ */
+export const core = CORE_SCHEMA;

yaml/schema/default.ts

@@ -6,12 +6,20 @@
 
 import { Schema } from "../schema.ts";
 import { binary, merge, omap, pairs, set, timestamp } from "../_type/mod.ts";
-import { core } from "./core.ts";
+import { CORE_SCHEMA } from "./core.ts";
 
-// JS-YAML's default schema for `safeLoad` function.
-// It is not described in the YAML specification.
-export const def: Schema = new Schema({
+/**
+ * Default YAML schema. It is not described in the YAML specification.
+ */
+export const DEFAULT_SCHEMA: Schema = new Schema({
   explicit: [binary, omap, pairs, set],
   implicit: [timestamp, merge],
-  include: [core],
+  include: [CORE_SCHEMA],
 });
+
+/**
+ * Default YAML schema. It is not described in the YAML specification.
+ *
+ * @deprecated (will be removed in 1.0.0) Use {@link DEFAULT_SCHEMA} instead.
+ */
+export const def = DEFAULT_SCHEMA;

yaml/schema/extended.ts

@@ -3,7 +3,7 @@
 
 import { Schema } from "../schema.ts";
 import { regexp, undefinedType } from "../_type/mod.ts";
-import { def } from "./default.ts";
+import { DEFAULT_SCHEMA } from "./default.ts";
 
 /***
  * Extends JS-YAML default schema with additional JavaScript types
@@ -33,7 +33,39 @@ import { def } from "./default.ts";
  * );
  * ```
  */
-export const extended: Schema = new Schema({
+export const EXTENDED_SCHEMA: Schema = new Schema({
   explicit: [regexp, undefinedType],
-  include: [def],
+  include: [DEFAULT_SCHEMA],
 });
+
+/***
+ * Extends JS-YAML default schema with additional JavaScript types
+ * It is not described in the YAML specification.
+ * Functions are no longer supported for security reasons.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   EXTENDED_SCHEMA,
+ *   parse,
+ * } from "https://deno.land/std@$STD_VERSION/yaml/mod.ts";
+ *
+ * const data = parse(
+ *   `
+ *   regexp:
+ *     simple: !!js/regexp foobar
+ *     modifiers: !!js/regexp /foobar/mi
+ *   undefined: !!js/undefined ~
+ * # Disabled, see: https://github.com/denoland/deno_std/pull/1275
+ * #  function: !!js/function >
+ * #    function foobar() {
+ * #      return 'hello world!';
+ * #    }
+ * `,
+ *   { schema: EXTENDED_SCHEMA },
+ * );
+ * ```
+ *
+ * @deprecated (will be removed in 1.0.0) Use {@link EXTENDED_SCHEMA} instead.
+ */
+export const extended = EXTENDED_SCHEMA;

yaml/schema/failsafe.ts

@@ -7,8 +7,20 @@
 import { Schema } from "../schema.ts";
 import { map, seq, str } from "../_type/mod.ts";
 
-// Standard YAML's Failsafe schema.
-// http://www.yaml.org/spec/1.2/spec.html#id2802346
-export const failsafe: Schema = new Schema({
+/**
+ * Standard YAML's failsafe schema.
+ *
+ * @see {@link http://www.yaml.org/spec/1.2/spec.html#id2802346}
+ */
+export const FAILSAFE_SCHEMA: Schema = new Schema({
   explicit: [str, seq, map],
 });
+
+/**
+ * Standard YAML's failsafe schema.
+ *
+ * @see {@link http://www.yaml.org/spec/1.2/spec.html#id2802346}
+ *
+ * @deprecated (will be removed in 1.0.0) Use {@link FAILSAFE_SCHEMA} instead.
+ */
+export const failsafe = FAILSAFE_SCHEMA;

yaml/schema/json.ts

@@ -6,11 +6,16 @@
 
 import { Schema } from "../schema.ts";
 import { bool, float, int, nil } from "../_type/mod.ts";
-import { failsafe } from "./failsafe.ts";
+import { FAILSAFE_SCHEMA } from "./failsafe.ts";
 
-// Standard YAML's JSON schema.
-// http://www.yaml.org/spec/1.2/spec.html#id2803231
-export const json: Schema = new Schema({
+/**
+ * Standard YAML's JSON schema.
+ *
+ * @see {@link http://www.yaml.org/spec/1.2/spec.html#id2803231}
+ *
+ * @deprecated (will be removed in 1.0.0) Use {@link JSON_SCHEMA} instead.
+ */
+export const JSON_SCHEMA: Schema = new Schema({
   implicit: [nil, bool, int, float],
-  include: [failsafe],
+  include: [FAILSAFE_SCHEMA],
 });

yaml/schema/mod.ts

@@ -4,8 +4,8 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-export { core as CORE_SCHEMA } from "./core.ts";
-export { def as DEFAULT_SCHEMA } from "./default.ts";
-export { extended as EXTENDED_SCHEMA } from "./extended.ts";
-export { failsafe as FAILSAFE_SCHEMA } from "./failsafe.ts";
-export { json as JSON_SCHEMA } from "./json.ts";
+export { CORE_SCHEMA } from "./core.ts";
+export { DEFAULT_SCHEMA } from "./default.ts";
+export { EXTENDED_SCHEMA } from "./extended.ts";
+export { FAILSAFE_SCHEMA } from "./failsafe.ts";
+export { JSON_SCHEMA } from "./json.ts";