Foundation for error handling

Author: P0lip

docs/options.md

@@ -27,6 +27,7 @@ $RefParser.dereference("my-schema.yaml", {
       withCredentials: true,        // Include auth credentials when resolving HTTP references
     }
   },
+  failFast: true,                   // Abort upon first exception
   dereference: {
     circular: false                 // Don't allow circular $refs
   }

lib/index.js

@@ -8,11 +8,16 @@ const resolveExternal = require("./resolve-external");
 const bundle = require("./bundle");
 const dereference = require("./dereference");
 const url = require("./util/url");
+const { GenericError, MissingPointerError, ResolverError, ParserError, isHandledError } = require("./util/errors");
 const maybe = require("call-me-maybe");
 const { ono } = require("ono");
 
 module.exports = $RefParser;
 module.exports.YAML = require("./util/yaml");
+module.exports.GenericError = GenericError;
+module.exports.MissingPointerError = MissingPointerError;
+module.exports.ResolverError = ResolverError;
+module.exports.ParserError = ParserError;
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
@@ -38,6 +43,25 @@ function $RefParser () {
   this.$refs = new $Refs();
 }
 
+/**
+ * List of all errors
+ * @type {Array<GenericError | ResolverError | ParserError | MissingPointerError>}
+ */
+Object.defineProperty($RefParser.prototype, "errors", {
+  get () {
+    const errors = [];
+
+    for (const $ref of Object.values(this.$refs._$refs)) {
+      if ($ref.errors) {
+        errors.push(...$ref.errors);
+      }
+    }
+
+    return errors;
+  },
+  enumerable: true,
+});
+
 /**
  * Parses the given JSON schema.
  * This method does not resolve any JSON references.
@@ -119,8 +143,16 @@ $RefParser.prototype.parse = async function (path, schema, options, callback) {
       return maybe(args.callback, Promise.resolve(me.schema));
     }
   }
-  catch (e) {
-    return maybe(args.callback, Promise.reject(e));
+  catch (err) {
+    if (args.options.failFast || !isHandledError(err)) {
+      return maybe(args.callback, Promise.reject(err));
+    }
+
+    if (this.$refs._$refs[url.stripHash(args.path)]) {
+      this.$refs._$refs[url.stripHash(args.path)].addError(err);
+    }
+
+    return maybe(args.callback, Promise.resolve(null));
   }
 };
 

lib/options.js

@@ -26,7 +26,7 @@ $RefParserOptions.defaults = {
    * Determines how different types of files will be parsed.
    *
    * You can add additional parsers of your own, replace an existing one with
-   * your own implemenation, or disable any parser by setting it to false.
+   * your own implementation, or disable any parser by setting it to false.
    */
   parse: {
     json: jsonParser,
@@ -39,7 +39,7 @@ $RefParserOptions.defaults = {
    * Determines how JSON References will be resolved.
    *
    * You can add additional resolvers of your own, replace an existing one with
-   * your own implemenation, or disable any resolver by setting it to false.
+   * your own implementation, or disable any resolver by setting it to false.
    */
   resolve: {
     file: fileResolver,
@@ -55,6 +55,12 @@ $RefParserOptions.defaults = {
     external: true,
   },
 
+  /**
+   * Determines how lenient the processing should be.
+   * If this option is enable, the processing will be performed in a bail mode - will abort upon the first exception.
+  */
+  failFast: true,
+
   /**
    * Determines the types of JSON references that are allowed.
    */

lib/parse.js

@@ -3,6 +3,7 @@
 const { ono } = require("ono");
 const url = require("./util/url");
 const plugins = require("./util/plugins");
+const { StoplightParserError, ResolverError, ParserError } = require("./util/errors");
 
 module.exports = parse;
 

lib/ref.js

@@ -3,6 +3,7 @@
 module.exports = $Ref;
 
 const Pointer = require("./pointer");
+const { GenericError, GenericErrorGroup, ParserError, MissingPointerError, ResolverError } = require("./util/errors");
 
 /**
  * This class represents a single JSON reference and its resolved value.
@@ -40,8 +41,34 @@ function $Ref () {
    * @type {?string}
    */
   this.pathType = undefined;
+
+  /**
+   * List of all errors. Undefined if no errors.
+   * @type {Array<GenericError | ResolverError | ParserError | MissingPointerError>}
+   */
+  this.errors = undefined;
 }
 
+/**
+ * Pushes an error to errors array.
+ *
+ * @param {Array<GenericError | GenericErrorGroup>} error - The error to be pushed
+ * @returns {void}
+ */
+$Ref.prototype.addError = function (err) {
+  if (this.errors === undefined) {
+    this.errors = [];
+  }
+
+  if (Array.isArray(err.errors)) {
+    this.errors.push(...err.errors);
+  }
+  else {
+    this.errors.push(err);
+  }
+};
+
+
 /**
  * Determines whether the given JSON reference exists within this {@link $Ref#value}.
  *

lib/resolve-external.js

@@ -4,6 +4,7 @@ const $Ref = require("./ref");
 const Pointer = require("./pointer");
 const parse = require("./parse");
 const url = require("./util/url");
+const { isHandledError } = require("./util/errors");
 
 module.exports = resolveExternal;
 
@@ -101,11 +102,24 @@ async function resolve$Ref ($ref, path, $refs, options) {
   }
 
   // Parse the $referenced file/url
-  const result = await parse(resolvedPath, $refs, options);
+  try {
+    const result = await parse(resolvedPath, $refs, options);
+
+    // Crawl the parsed value
+    // console.log('Resolving $ref pointers in %s', withoutHash);
+    let promises = crawl(result, withoutHash + "#", $refs, options);
+
+    return Promise.all(promises);
+  }
+  catch (err) {
+    if (options.failFast || !isHandledError(err)) {
+      throw err;
+    }
 
-  // Crawl the parsed value
-  // console.log('Resolving $ref pointers in %s', withoutHash);
-  let promises = crawl(result, withoutHash + "#", $refs, options);
+    if ($refs._$refs[withoutHash]) {
+      err.source = url.stripHash(path);
+    }
 
-  return Promise.all(promises);
+    return [];
+  }
 }

lib/util/errors.js

@@ -0,0 +1,78 @@
+"use strict";
+
+const { stripHash } = require("./url");
+
+const GenericError = exports.GenericError = class GenericError extends Error {
+  constructor (message, source) {
+    super();
+
+    this.message = message;
+    this.source = source;
+    this.path = [];
+  }
+};
+
+setErrorName(GenericError);
+
+const GenericErrorGroup = exports.GenericErrorGroup = class GenericErrorGroup extends Error {
+  constructor (errors, source) {
+    super();
+
+    this.source = source;
+    this.errors = errors;
+  }
+};
+
+exports.StoplightParserError = class StoplightParserError extends GenericErrorGroup {
+  constructor (errors, source) {
+    super(errors.filter(error => error.severity === 0).map(error => {
+      const parsingError = new ParserError(error.message, source);
+      parsingError.message = error.message;
+      if (error.path) {
+        parsingError.path = error.path;
+      }
+
+      return parsingError;
+    }));
+
+    this.message = `Error parsing ${source}`;
+  }
+};
+
+const ParserError = exports.ParserError = class ParserError extends GenericError {
+  constructor (message, source) {
+    super(`Error parsing ${source}: ${message}`, source);
+  }
+};
+
+setErrorName(ParserError);
+
+const ResolverError = exports.ResolverError = class ResolverError extends GenericError {
+  constructor (ex, source) {
+    super(ex.message || `Error reading file ${source}`, source);
+    if ("code" in ex) {
+      this.code = String(ex.code);
+    }
+  }
+};
+
+setErrorName(ResolverError);
+
+const MissingPointerError = exports.MissingPointerError = class MissingPointerError extends GenericError {
+  constructor (token, path) {
+    super(`Token "${token}" does not exist.`, stripHash(path));
+  }
+};
+
+setErrorName(MissingPointerError);
+
+function setErrorName (err) {
+  Object.defineProperty(err.prototype, "name", {
+    value: err.name,
+    enumerable: true,
+  });
+}
+
+exports.isHandledError = function (err) {
+  return err instanceof GenericError || err instanceof GenericErrorGroup;
+};