@apidevtools/json-schema-ref-parser 10.0.0 → 10.1.0

package/lib/parse.ts

@@ -0,0 +1,153 @@
+import { ono } from "@jsdevtools/ono";
+import * as url from "./util/url.js";
+import * as plugins from "./util/plugins.js";
+import {
+  ResolverError,
+  ParserError,
+  UnmatchedParserError,
+  UnmatchedResolverError,
+  isHandledError,
+} from "./util/errors.js";
+import type $Refs from "./refs.js";
+import type { Options } from "./options.js";
+import type { FileInfo } from "./types/index.js";
+
+export default parse;
+
+/**
+ * Reads and parses the specified file path or URL.
+ */
+async function parse(path: string, $refs: $Refs, options: Options) {
+  // Remove the URL fragment, if any
+  path = url.stripHash(path);
+
+  // Add a new $Ref for this file, even though we don't have the value yet.
+  // This ensures that we don't simultaneously read & parse the same file multiple times
+  const $ref = $refs._add(path);
+
+  // This "file object" will be passed to all resolvers and parsers.
+  const file = {
+    url: path,
+    extension: url.getExtension(path),
+  } as FileInfo;
+
+  // Read the file and then parse the data
+  try {
+    const resolver = await readFile(file, options, $refs);
+    $ref.pathType = resolver.plugin.name;
+    file.data = resolver.result;
+
+    const parser = await parseFile(file, options, $refs);
+    $ref.value = parser.result;
+
+    return parser.result;
+  } catch (err) {
+    if (isHandledError(err)) {
+      $ref.value = err;
+    }
+
+    throw err;
+  }
+}
+
+/**
+ * Reads the given file, using the configured resolver plugins
+ *
+ * @param file           - An object containing information about the referenced file
+ * @param file.url       - The full URL of the referenced file
+ * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+ * @param options
+ *
+ * @returns
+ * The promise resolves with the raw file contents and the resolver that was used.
+ */
+async function readFile(file: FileInfo, options: Options, $refs: $Refs): Promise<any> {
+  // console.log('Reading %s', file.url);
+
+  // Find the resolvers that can read this file
+  let resolvers = plugins.all(options.resolve);
+  resolvers = plugins.filter(resolvers, "canRead", file);
+
+  // Run the resolvers, in order, until one of them succeeds
+  plugins.sort(resolvers);
+  try {
+    const data = await plugins.run(resolvers, "read", file, $refs);
+    return data;
+  } catch (err: any) {
+    if (!err && options.continueOnError) {
+      // No resolver could be matched
+      throw new UnmatchedResolverError(file.url);
+    } else if (!err || !("error" in err)) {
+      // Throw a generic, friendly error.
+      throw ono.syntax(`Unable to resolve $ref pointer "${file.url}"`);
+    }
+    // Throw the original error, if it's one of our own (user-friendly) errors.
+    else if (err.error instanceof ResolverError) {
+      throw err.error;
+    } else {
+      throw new ResolverError(err, file.url);
+    }
+  }
+}
+
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ *
+ * @param file           - An object containing information about the referenced file
+ * @param file.url       - The full URL of the referenced file
+ * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+ * @param file.data      - The file contents. This will be whatever data type was returned by the resolver
+ * @param options
+ *
+ * @returns
+ * The promise resolves with the parsed file contents and the parser that was used.
+ */
+async function parseFile(file: FileInfo, options: Options, $refs: $Refs) {
+  // console.log('Parsing %s', file.url);
+
+  // Find the parsers that can read this file type.
+  // If none of the parsers are an exact match for this file, then we'll try ALL of them.
+  // This handles situations where the file IS a supported type, just with an unknown extension.
+  const allParsers = plugins.all(options.parse);
+  const filteredParsers = plugins.filter(allParsers, "canParse", file);
+  const parsers = filteredParsers.length > 0 ? filteredParsers : allParsers;
+
+  // Run the parsers, in order, until one of them succeeds
+  plugins.sort(parsers);
+  try {
+    const parser = await plugins.run(parsers, "parse", file, $refs);
+    if (!parser.plugin.allowEmpty && isEmpty(parser.result)) {
+      throw ono.syntax(`Error parsing "${file.url}" as ${parser.plugin.name}. \nParsed value is empty`);
+    } else {
+      return parser;
+    }
+  } catch (err: any) {
+    if (!err && options.continueOnError) {
+      // No resolver could be matched
+      throw new UnmatchedParserError(file.url);
+    } else if (err && err.message && err.message.startsWith("Error parsing")) {
+      throw err;
+    } else if (!err || !("error" in err)) {
+      throw ono.syntax(`Unable to parse ${file.url}`);
+    } else if (err.error instanceof ParserError) {
+      throw err.error;
+    } else {
+      throw new ParserError(err.error.message, file.url);
+    }
+  }
+}
+
+/**
+ * Determines whether the parsed value is "empty".
+ *
+ * @param value
+ * @returns
+ */
+function isEmpty(value: any) {
+  return (
+    value === undefined ||
+    (typeof value === "object" && Object.keys(value).length === 0) ||
+    (typeof value === "string" && value.trim().length === 0) ||
+    (Buffer.isBuffer(value) && value.length === 0)
+  );
+}

package/lib/parsers/binary.ts

@@ -0,0 +1,39 @@
+import type { FileInfo } from "../types/index.js";
+import type { Plugin } from "../types/index.js";
+
+const BINARY_REGEXP = /\.(jpeg|jpg|gif|png|bmp|ico)$/i;
+
+export default {
+  /**
+   * The order that this parser will run, in relation to other parsers.
+   */
+  order: 400,
+
+  /**
+   * Whether to allow "empty" files (zero bytes).
+   */
+  allowEmpty: true,
+
+  /**
+   * Determines whether this parser can parse a given file reference.
+   * Parsers that return true will be tried, in order, until one successfully parses the file.
+   * Parsers that return false will be skipped, UNLESS all parsers returned false, in which case
+   * every parser will be tried.
+   */
+  canParse(file: FileInfo) {
+    // Use this parser if the file is a Buffer, and has a known binary extension
+    return Buffer.isBuffer(file.data) && BINARY_REGEXP.test(file.url);
+  },
+
+  /**
+   * Parses the given data as a Buffer (byte array).
+   */
+  parse(file: FileInfo) {
+    if (Buffer.isBuffer(file.data)) {
+      return file.data;
+    } else {
+      // This will reject if data is anything other than a string or typed array
+      return Buffer.from(file.data);
+    }
+  },
+} as Plugin;

package/lib/parsers/{json.js → json.ts}

@@ -1,17 +1,15 @@
 import { ParserError } from "../util/errors.js";
+import type { FileInfo } from "../types/index.js";
+import type { Plugin } from "../types/index.js";
 
 export default {
   /**
    * The order that this parser will run, in relation to other parsers.
-   *
-   * @type {number}
    */
   order: 100,
 
   /**
    * Whether to allow "empty" files. This includes zero-byte files, as well as empty JSON objects.
-   *
-   * @type {boolean}
    */
   allowEmpty: true,
 
@@ -20,21 +18,13 @@ export default {
    * Parsers that match will be tried, in order, until one successfully parses the file.
    * Parsers that don't match will be skipped, UNLESS none of the parsers match, in which case
    * every parser will be tried.
-   *
-   * @type {RegExp|string|string[]|function}
    */
   canParse: ".json",
 
   /**
    * Parses the given file as JSON
-   *
-   * @param {object} file           - An object containing information about the referenced file
-   * @param {string} file.url       - The full URL of the referenced file
-   * @param {string} file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
-   * @param {*}      file.data      - The file contents. This will be whatever data type was returned by the resolver
-   * @returns {Promise}
    */
-  async parse (file) {      // eslint-disable-line require-await
+  async parse(file: FileInfo): Promise<object | undefined> {
     let data = file.data;
     if (Buffer.isBuffer(data)) {
       data = data.toString();
@@ -43,19 +33,16 @@ export default {
     if (typeof data === "string") {
       if (data.trim().length === 0) {
         return; // This mirrors the YAML behavior
-      }
-      else {
+      } else {
         try {
           return JSON.parse(data);
-        }
-        catch (e) {
+        } catch (e: any) {
           throw new ParserError(e.message, file.url);
         }
       }
-    }
-    else {
+    } else {
       // data is already a JavaScript value (object, array, number, null, NaN, etc.)
-      return data;
+      return data as object;
     }
-  }
-};
+  },
+} as Plugin;

package/lib/parsers/text.ts

@@ -0,0 +1,46 @@
+import { ParserError } from "../util/errors.js";
+import type { FileInfo } from "../types/index.js";
+import type { Plugin } from "../types/index.js";
+
+const TEXT_REGEXP = /\.(txt|htm|html|md|xml|js|min|map|css|scss|less|svg)$/i;
+
+export default {
+  /**
+   * The order that this parser will run, in relation to other parsers.
+   */
+  order: 300,
+
+  /**
+   * Whether to allow "empty" files (zero bytes).
+   */
+  allowEmpty: true,
+
+  /**
+   * The encoding that the text is expected to be in.
+   */
+  encoding: "utf8" as BufferEncoding,
+
+  /**
+   * Determines whether this parser can parse a given file reference.
+   * Parsers that return true will be tried, in order, until one successfully parses the file.
+   * Parsers that return false will be skipped, UNLESS all parsers returned false, in which case
+   * every parser will be tried.
+   */
+  canParse(file: FileInfo) {
+    // Use this parser if the file is a string or Buffer, and has a known text-based extension
+    return (typeof file.data === "string" || Buffer.isBuffer(file.data)) && TEXT_REGEXP.test(file.url);
+  },
+
+  /**
+   * Parses the given file as text
+   */
+  parse(file: FileInfo) {
+    if (typeof file.data === "string") {
+      return file.data;
+    } else if (Buffer.isBuffer(file.data)) {
+      return file.data.toString(this.encoding);
+    } else {
+      throw new ParserError("data is not text", file.url);
+    }
+  },
+} as Plugin;

package/lib/parsers/{yaml.js → yaml.ts}

@@ -1,19 +1,17 @@
 import { ParserError } from "../util/errors.js";
 import yaml from "js-yaml";
 import { JSON_SCHEMA } from "js-yaml";
+import type { FileInfo } from "../types/index.js";
+import type { Plugin } from "../types/index.js";
 
 export default {
   /**
    * The order that this parser will run, in relation to other parsers.
-   *
-   * @type {number}
    */
   order: 200,
 
   /**
    * Whether to allow "empty" files. This includes zero-byte files, as well as empty JSON objects.
-   *
-   * @type {boolean}
    */
   allowEmpty: true,
 
@@ -22,21 +20,20 @@ export default {
    * Parsers that match will be tried, in order, until one successfully parses the file.
    * Parsers that don't match will be skipped, UNLESS none of the parsers match, in which case
    * every parser will be tried.
-   *
-   * @type {RegExp|string[]|function}
    */
-  canParse: [".yaml", ".yml", ".json"],  // JSON is valid YAML
+  canParse: [".yaml", ".yml", ".json"], // JSON is valid YAML
 
   /**
    * Parses the given file as YAML
    *
-   * @param {object} file           - An object containing information about the referenced file
-   * @param {string} file.url       - The full URL of the referenced file
-   * @param {string} file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
-   * @param {*}      file.data      - The file contents. This will be whatever data type was returned by the resolver
-   * @returns {Promise}
+   * @param file           - An object containing information about the referenced file
+   * @param file.url       - The full URL of the referenced file
+   * @param file.extension - The lowercased file extension (e.g. ".txt", ".html", etc.)
+   * @param file.data      - The file contents. This will be whatever data type was returned by the resolver
+   * @returns
    */
-  async parse (file) {      // eslint-disable-line require-await
+  async parse(file: FileInfo) {
+    // eslint-disable-line require-await
     let data = file.data;
     if (Buffer.isBuffer(data)) {
       data = data.toString();
@@ -45,14 +42,13 @@ export default {
     if (typeof data === "string") {
       try {
         return yaml.load(data, { schema: JSON_SCHEMA });
-      }
-      catch (e) {
+      } catch (e) {
+        // @ts-expect-error TS(2571): Object is of type 'unknown'.
         throw new ParserError(e.message, file.url);
       }
-    }
-    else {
+    } else {
       // data is already a JavaScript value (object, array, number, null, NaN, etc.)
       return data;
     }
-  }
-};
+  },
+} as Plugin;

package/lib/pointer.ts

@@ -0,0 +1,296 @@
+import type $RefParserOptions from "./options.js";
+
+import $Ref from "./ref.js";
+import * as url from "./util/url.js";
+import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+const slashes = /\//g;
+const tildes = /~/g;
+const escapedSlash = /~1/g;
+const escapedTilde = /~0/g;
+
+/**
+ * This class represents a single JSON pointer and its resolved value.
+ *
+ * @param $ref
+ * @param path
+ * @param [friendlyPath] - The original user-specified path (used for error messages)
+ * @class
+ */
+class Pointer {
+  /**
+   * The {@link $Ref} object that contains this {@link Pointer} object.
+   */
+  $ref: $Ref;
+
+  /**
+   * The file path or URL, containing the JSON pointer in the hash.
+   * This path is relative to the path of the main JSON schema file.
+   */
+  path: string;
+
+  /**
+   * The original path or URL, used for error messages.
+   */
+  originalPath: string;
+
+  /**
+   * The value of the JSON pointer.
+   * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
+   */
+
+  value: any;
+  /**
+   * Indicates whether the pointer references itself.
+   */
+  circular: boolean;
+  /**
+   * The number of indirect references that were traversed to resolve the value.
+   * Resolving a single pointer may require resolving multiple $Refs.
+   */
+  indirections: number;
+
+  constructor($ref: any, path: any, friendlyPath: any) {
+    this.$ref = $ref;
+
+    this.path = path;
+
+    this.originalPath = friendlyPath || path;
+
+    this.value = undefined;
+
+    this.circular = false;
+
+    this.indirections = 0;
+  }
+
+  /**
+   * Resolves the value of a nested property within the given object.
+   *
+   * @param obj - The object that will be crawled
+   * @param options
+   * @param pathFromRoot - the path of place that initiated resolving
+   *
+   * @returns
+   * Returns a JSON pointer whose {@link Pointer#value} is the resolved value.
+   * If resolving this value required resolving other JSON references, then
+   * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
+   * of the resolved value.
+   */
+  resolve(obj: any, options: any, pathFromRoot: any) {
+    const tokens = Pointer.parse(this.path, this.originalPath);
+
+    // Crawl the object, one token at a time
+    this.value = unwrapOrThrow(obj);
+
+    for (let i = 0; i < tokens.length; i++) {
+      if (resolveIf$Ref(this, options)) {
+        // The $ref path has changed, so append the remaining tokens to the path
+        this.path = Pointer.join(this.path, tokens.slice(i));
+      }
+
+      if (typeof this.value === "object" && this.value !== null && "$ref" in this.value) {
+        return this;
+      }
+
+      const token = tokens[i];
+      if (this.value[token] === undefined || this.value[token] === null) {
+        this.value = null;
+        throw new MissingPointerError(token, decodeURI(this.originalPath));
+      } else {
+        this.value = this.value[token];
+      }
+    }
+
+    // Resolve the final value
+    if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
+      resolveIf$Ref(this, options);
+    }
+
+    return this;
+  }
+
+  /**
+   * Sets the value of a nested property within the given object.
+   *
+   * @param obj - The object that will be crawled
+   * @param value - the value to assign
+   * @param options
+   *
+   * @returns
+   * Returns the modified object, or an entirely new object if the entire object is overwritten.
+   */
+  set(obj: any, value: any, options?: $RefParserOptions) {
+    const tokens = Pointer.parse(this.path);
+    let token;
+
+    if (tokens.length === 0) {
+      // There are no tokens, replace the entire object with the new value
+      this.value = value;
+      return value;
+    }
+
+    // Crawl the object, one token at a time
+    this.value = unwrapOrThrow(obj);
+
+    for (let i = 0; i < tokens.length - 1; i++) {
+      resolveIf$Ref(this, options);
+
+      token = tokens[i];
+      if (this.value && this.value[token] !== undefined) {
+        // The token exists
+        this.value = this.value[token];
+      } else {
+        // The token doesn't exist, so create it
+        this.value = setValue(this, token, {});
+      }
+    }
+
+    // Set the value of the final token
+    resolveIf$Ref(this, options);
+    token = tokens[tokens.length - 1];
+    setValue(this, token, value);
+
+    // Return the updated object
+    return obj;
+  }
+
+  /**
+   * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
+   * and returns an array of the pointer's tokens.
+   * (e.g. "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
+   *
+   * The pointer is parsed according to RFC 6901
+   * {@link https://tools.ietf.org/html/rfc6901#section-3}
+   *
+   * @param path
+   * @param [originalPath]
+   * @returns
+   */
+  static parse(path: string, originalPath?: string) {
+    // Get the JSON pointer from the path's hash
+    let pointer = url.getHash(path).substr(1);
+
+    // If there's no pointer, then there are no tokens,
+    // so return an empty array
+    if (!pointer) {
+      return [];
+    }
+
+    // Split into an array
+    pointer = pointer.split("/");
+
+    // Decode each part, according to RFC 6901
+    for (let i = 0; i < pointer.length; i++) {
+      pointer[i] = decodeURIComponent(pointer[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+    }
+
+    if (pointer[0] !== "") {
+      throw new InvalidPointerError(pointer, originalPath === undefined ? path : originalPath);
+    }
+
+    return pointer.slice(1);
+  }
+
+  /**
+   * Creates a JSON pointer path, by joining one or more tokens to a base path.
+   *
+   * @param base - The base path (e.g. "schema.json#/definitions/person")
+   * @param tokens - The token(s) to append (e.g. ["name", "first"])
+   * @returns
+   */
+  static join(base: any, tokens: any) {
+    // Ensure that the base path contains a hash
+    if (base.indexOf("#") === -1) {
+      base += "#";
+    }
+
+    // Append each token to the base path
+    tokens = Array.isArray(tokens) ? tokens : [tokens];
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      // Encode the token, according to RFC 6901
+      base += "/" + encodeURIComponent(token.replace(tildes, "~0").replace(slashes, "~1"));
+    }
+
+    return base;
+  }
+}
+
+/**
+ * If the given pointer's {@link Pointer#value} is a JSON reference,
+ * then the reference is resolved and {@link Pointer#value} is replaced with the resolved value.
+ * In addition, {@link Pointer#path} and {@link Pointer#$ref} are updated to reflect the
+ * resolution path of the new value.
+ *
+ * @param pointer
+ * @param options
+ * @returns - Returns `true` if the resolution path changed
+ */
+function resolveIf$Ref(pointer: any, options: any) {
+  // Is the value a JSON reference? (and allowed?)
+
+  if ($Ref.isAllowed$Ref(pointer.value, options)) {
+    const $refPath = url.resolve(pointer.path, pointer.value.$ref);
+
+    if ($refPath === pointer.path) {
+      // The value is a reference to itself, so there's nothing to do.
+      pointer.circular = true;
+    } else {
+      const resolved = pointer.$ref.$refs._resolve($refPath, pointer.path, options);
+      if (resolved === null) {
+        return false;
+      }
+
+      pointer.indirections += resolved.indirections + 1;
+
+      if ($Ref.isExtended$Ref(pointer.value)) {
+        // This JSON reference "extends" the resolved value, rather than simply pointing to it.
+        // So the resolved path does NOT change.  Just the value does.
+        pointer.value = $Ref.dereference(pointer.value, resolved.value);
+        return false;
+      } else {
+        // Resolve the reference
+        pointer.$ref = resolved.$ref;
+        pointer.path = resolved.path;
+        pointer.value = resolved.value;
+      }
+
+      return true;
+    }
+  }
+}
+export default Pointer;
+
+/**
+ * Sets the specified token value of the {@link Pointer#value}.
+ *
+ * The token is evaluated according to RFC 6901.
+ * {@link https://tools.ietf.org/html/rfc6901#section-4}
+ *
+ * @param pointer - The JSON Pointer whose value will be modified
+ * @param token - A JSON Pointer token that indicates how to modify `obj`
+ * @param value - The value to assign
+ * @returns - Returns the assigned value
+ */
+function setValue(pointer: any, token: any, value: any) {
+  if (pointer.value && typeof pointer.value === "object") {
+    if (token === "-" && Array.isArray(pointer.value)) {
+      pointer.value.push(value);
+    } else {
+      pointer.value[token] = value;
+    }
+  } else {
+    throw new JSONParserError(
+      `Error assigning $ref pointer "${pointer.path}". \nCannot set "${token}" of a non-object.`,
+    );
+  }
+  return value;
+}
+
+function unwrapOrThrow(value: any) {
+  if (isHandledError(value)) {
+    throw value;
+  }
+
+  return value;
+}