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

package/lib/index.js

@@ -1,290 +0,0 @@
-/* eslint-disable no-unused-vars */
-import $Refs from "./refs.js";
-import _parse from "./parse.js";
-import normalizeArgs from "./normalize-args.js";
-import resolveExternal from "./resolve-external.js";
-import _bundle from "./bundle.js";
-import _dereference from "./dereference.js";
-import * as url from "./util/url.js";
-import { JSONParserError, InvalidPointerError, MissingPointerError, ResolverError, ParserError, UnmatchedParserError, UnmatchedResolverError, isHandledError, JSONParserErrorGroup } from "./util/errors.js";
-import maybe from "call-me-maybe";
-import { ono } from "@jsdevtools/ono";
-
-export default $RefParser;
-export { JSONParserError };
-export { InvalidPointerError };
-export { MissingPointerError };
-export { ResolverError };
-export { ParserError };
-export { UnmatchedParserError };
-export { UnmatchedResolverError };
-
-/**
- * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
- * and provides methods for traversing, manipulating, and dereferencing those references.
- *
- * @constructor
- */
-function $RefParser () {
-  /**
-   * The parsed (and possibly dereferenced) JSON schema object
-   *
-   * @type {object}
-   * @readonly
-   */
-  this.schema = null;
-
-  /**
-   * The resolved JSON references
-   *
-   * @type {$Refs}
-   * @readonly
-   */
-  this.$refs = new $Refs();
-}
-
-/**
- * Parses the given JSON schema.
- * This method does not resolve any JSON references.
- * It just reads a single file in JSON or YAML format, and parse it as a JavaScript object.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed
- * @param {function} [callback] - An error-first callback. The second parameter is the parsed JSON schema object.
- * @returns {Promise} - The returned promise resolves with the parsed JSON schema object.
- */
-$RefParser.parse = function parse (path, schema, options, callback) {
-  let Class = this; // eslint-disable-line consistent-this
-  let instance = new Class();
-  return instance.parse.apply(instance, arguments);
-};
-
-/**
- * Parses the given JSON schema.
- * This method does not resolve any JSON references.
- * It just reads a single file in JSON or YAML format, and parse it as a JavaScript object.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed
- * @param {function} [callback] - An error-first callback. The second parameter is the parsed JSON schema object.
- * @returns {Promise} - The returned promise resolves with the parsed JSON schema object.
- */
-$RefParser.prototype.parse = async function parse (path, schema, options, callback) {
-  let args = normalizeArgs(arguments);
-  let promise;
-
-  if (!args.path && !args.schema) {
-    let err = ono(`Expected a file path, URL, or object. Got ${args.path || args.schema}`);
-    return maybe(args.callback, Promise.reject(err));
-  }
-
-  // Reset everything
-  this.schema = null;
-  this.$refs = new $Refs();
-
-  // If the path is a filesystem path, then convert it to a URL.
-  // NOTE: According to the JSON Reference spec, these should already be URLs,
-  // but, in practice, many people use local filesystem paths instead.
-  // So we're being generous here and doing the conversion automatically.
-  // This is not intended to be a 100% bulletproof solution.
-  // If it doesn't work for your use-case, then use a URL instead.
-  let pathType = "http";
-  if (url.isFileSystemPath(args.path)) {
-    args.path = url.fromFileSystemPath(args.path);
-    pathType = "file";
-  }
-
-  // Resolve the absolute path of the schema
-  args.path = url.resolve(url.cwd(), args.path);
-
-  if (args.schema && typeof args.schema === "object") {
-    // A schema object was passed-in.
-    // So immediately add a new $Ref with the schema object as its value
-    let $ref = this.$refs._add(args.path);
-    $ref.value = args.schema;
-    $ref.pathType = pathType;
-    promise = Promise.resolve(args.schema);
-  }
-  else {
-    // Parse the schema file/url
-    promise = _parse(args.path, this.$refs, args.options);
-  }
-
-  let me = this;
-  try {
-    let result = await promise;
-
-    if (result !== null && typeof result === "object" && !Buffer.isBuffer(result)) {
-      me.schema = result;
-      return maybe(args.callback, Promise.resolve(me.schema));
-    }
-    else if (args.options.continueOnError) {
-      me.schema = null; // it's already set to null at line 79, but let's set it again for the sake of readability
-      return maybe(args.callback, Promise.resolve(me.schema));
-    }
-    else {
-      throw ono.syntax(`"${me.$refs._root$Ref.path || result}" is not a valid JSON Schema`);
-    }
-  }
-  catch (err) {
-    if (!args.options.continueOnError || !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));
-  }
-};
-
-/**
- * Parses the given JSON schema and resolves any JSON references, including references in
- * externally-referenced files.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed and resolved
- * @param {function} [callback]
- * - An error-first callback. The second parameter is a {@link $Refs} object containing the resolved JSON references
- *
- * @returns {Promise}
- * The returned promise resolves with a {@link $Refs} object containing the resolved JSON references
- */
-$RefParser.resolve = function resolve (path, schema, options, callback) {
-  let Class = this; // eslint-disable-line consistent-this
-  let instance = new Class();
-  return instance.resolve.apply(instance, arguments);
-};
-
-/**
- * Parses the given JSON schema and resolves any JSON references, including references in
- * externally-referenced files.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed and resolved
- * @param {function} [callback]
- * - An error-first callback. The second parameter is a {@link $Refs} object containing the resolved JSON references
- *
- * @returns {Promise}
- * The returned promise resolves with a {@link $Refs} object containing the resolved JSON references
- */
-$RefParser.prototype.resolve = async function resolve (path, schema, options, callback) {
-  let me = this;
-  let args = normalizeArgs(arguments);
-
-  try {
-    await this.parse(args.path, args.schema, args.options);
-    await resolveExternal(me, args.options);
-    finalize(me);
-    return maybe(args.callback, Promise.resolve(me.$refs));
-  }
-  catch (err) {
-    return maybe(args.callback, Promise.reject(err));
-  }
-};
-
-/**
- * Parses the given JSON schema, resolves any JSON references, and bundles all external references
- * into the main JSON schema. This produces a JSON schema that only has *internal* references,
- * not any *external* references.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed, resolved, and dereferenced
- * @param {function} [callback] - An error-first callback. The second parameter is the bundled JSON schema object
- * @returns {Promise} - The returned promise resolves with the bundled JSON schema object.
- */
-$RefParser.bundle = function bundle (path, schema, options, callback) {
-  let Class = this; // eslint-disable-line consistent-this
-  let instance = new Class();
-  return instance.bundle.apply(instance, arguments);
-};
-
-/**
- * Parses the given JSON schema, resolves any JSON references, and bundles all external references
- * into the main JSON schema. This produces a JSON schema that only has *internal* references,
- * not any *external* references.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed, resolved, and dereferenced
- * @param {function} [callback] - An error-first callback. The second parameter is the bundled JSON schema object
- * @returns {Promise} - The returned promise resolves with the bundled JSON schema object.
- */
-$RefParser.prototype.bundle = async function bundle (path, schema, options, callback) {
-  let me = this;
-  let args = normalizeArgs(arguments);
-
-  try {
-    await this.resolve(args.path, args.schema, args.options);
-    _bundle(me, args.options);
-    finalize(me);
-    return maybe(args.callback, Promise.resolve(me.schema));
-  }
-  catch (err) {
-    return maybe(args.callback, Promise.reject(err));
-  }
-};
-
-/**
- * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
- * That is, all JSON references are replaced with their resolved values.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed, resolved, and dereferenced
- * @param {function} [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
- * @returns {Promise} - The returned promise resolves with the dereferenced JSON schema object.
- */
-$RefParser.dereference = function dereference (path, schema, options, callback) {
-  let Class = this; // eslint-disable-line consistent-this
-  let instance = new Class();
-  return instance.dereference.apply(instance, arguments);
-};
-
-/**
- * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
- * That is, all JSON references are replaced with their resolved values.
- *
- * @param {string} [path] - The file path or URL of the JSON schema
- * @param {object} [schema] - A JSON schema object. This object will be used instead of reading from `path`.
- * @param {$RefParserOptions} [options] - Options that determine how the schema is parsed, resolved, and dereferenced
- * @param {function} [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
- * @returns {Promise} - The returned promise resolves with the dereferenced JSON schema object.
- */
-$RefParser.prototype.dereference = async function dereference (path, schema, options, callback) {
-  let me = this;
-  let args = normalizeArgs(arguments);
-
-  try {
-    await this.resolve(args.path, args.schema, args.options);
-    _dereference(me, args.options);
-    finalize(me);
-    return maybe(args.callback, Promise.resolve(me.schema));
-  }
-  catch (err) {
-    return maybe(args.callback, Promise.reject(err));
-  }
-};
-
-function finalize (parser) {
-  const errors = JSONParserErrorGroup.getParserErrors(parser);
-  if (errors.length > 0) {
-    throw new JSONParserErrorGroup(parser);
-  }
-}
-
-export const parse = $RefParser.parse.bind($RefParser);
-export const resolve = $RefParser.resolve.bind($RefParser);
-export const bundle = $RefParser.bundle.bind($RefParser);
-export const dereference = $RefParser.dereference.bind($RefParser);
-
-// CommonJS default export hack
-if (typeof module === "object" && typeof module.exports === "object") {
-  module.exports = Object.assign(module.exports.default, module.exports);
-}

package/lib/options.js

@@ -1,128 +0,0 @@
-/* eslint lines-around-comment: [2, {beforeBlockComment: false}] */
-import jsonParser from "./parsers/json.js";
-import yamlParser from "./parsers/yaml.js";
-import textParser from "./parsers/text.js";
-import binaryParser from "./parsers/binary.js";
-import fileResolver from "./resolvers/file.js";
-import httpResolver from "./resolvers/http.js";
-
-export default $RefParserOptions;
-
-/**
- * Options that determine how JSON schemas are parsed, resolved, and dereferenced.
- *
- * @param {object|$RefParserOptions} [options] - Overridden options
- * @constructor
- */
-function $RefParserOptions (options) {
-  merge(this, $RefParserOptions.defaults);
-  merge(this, options);
-}
-
-$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 implementation, or disable any parser by setting it to false.
-   */
-  parse: {
-    json: jsonParser,
-    yaml: yamlParser,
-    text: textParser,
-    binary: binaryParser,
-  },
-
-  /**
-   * Determines how JSON References will be resolved.
-   *
-   * You can add additional resolvers of your own, replace an existing one with
-   * your own implementation, or disable any resolver by setting it to false.
-   */
-  resolve: {
-    file: fileResolver,
-    http: httpResolver,
-
-    /**
-     * Determines whether external $ref pointers will be resolved.
-     * If this option is disabled, then none of above resolvers will be called.
-     * Instead, external $ref pointers will simply be ignored.
-     *
-     * @type {boolean}
-     */
-    external: true,
-  },
-
-  /**
-   * By default, JSON Schema $Ref Parser throws the first error it encounters. Setting `continueOnError` to `true`
-   * causes it to keep processing as much as possible and then throw a single error that contains all errors
-   * that were encountered.
-  */
-  continueOnError: false,
-
-  /**
-   * Determines the types of JSON references that are allowed.
-   */
-  dereference: {
-    /**
-     * Dereference circular (recursive) JSON references?
-     * If false, then a {@link ReferenceError} will be thrown if a circular reference is found.
-     * If "ignore", then circular references will not be dereferenced.
-     *
-     * @type {boolean|string}
-     */
-    circular: true,
-
-    /**
-     * A function, called for each path, which can return true to stop this path and all
-     * subpaths from being dereferenced further. This is useful in schemas where some
-     * subpaths contain literal $ref keys that should not be dereferenced.
-     *
-     * @type {function}
-     */
-    excludedPathMatcher: () => false
-  },
-};
-
-/**
- * Merges the properties of the source object into the target object.
- *
- * @param {object} target - The object that we're populating
- * @param {?object} source - The options that are being merged
- * @returns {object}
- */
-function merge (target, source) {
-  if (isMergeable(source)) {
-    let keys = Object.keys(source);
-    for (let i = 0; i < keys.length; i++) {
-      let key = keys[i];
-      let sourceSetting = source[key];
-      let targetSetting = target[key];
-
-      if (isMergeable(sourceSetting)) {
-        // It's a nested object, so merge it recursively
-        target[key] = merge(targetSetting || {}, sourceSetting);
-      }
-      else if (sourceSetting !== undefined) {
-        // It's a scalar value, function, or array. No merging necessary. Just overwrite the target value.
-        target[key] = sourceSetting;
-      }
-    }
-  }
-  return target;
-}
-
-/**
- * Determines whether the given value can be merged,
- * or if it is a scalar value that should just override the target value.
- *
- * @param   {*}  val
- * @returns {Boolean}
- */
-function isMergeable (val) {
-  return val &&
-    (typeof val === "object") &&
-    !Array.isArray(val) &&
-    !(val instanceof RegExp) &&
-    !(val instanceof Date);
-}

package/lib/parse.js

@@ -1,162 +0,0 @@
-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";
-
-export default parse;
-
-/**
- * Reads and parses the specified file path or URL.
- *
- * @param {string} path - This path MUST already be resolved, since `read` doesn't know the resolution context
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
- *
- * @returns {Promise}
- * The promise resolves with the parsed file contents, NOT the raw (Buffer) contents.
- */
-async function parse (path, $refs, 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
-  let $ref = $refs._add(path);
-
-  // This "file object" will be passed to all resolvers and parsers.
-  let file = {
-    url: path,
-    extension: url.getExtension(path),
-  };
-
-  // 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 {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 {$RefParserOptions} options
- *
- * @returns {Promise}
- * The promise resolves with the raw file contents and the resolver that was used.
- */
-function readFile (file, options, $refs) {
-  return new Promise(((resolve, reject) => {
-    // 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);
-    plugins.run(resolvers, "read", file, $refs)
-      .then(resolve, onError);
-
-    function onError (err) {
-      if (!err && options.continueOnError) {
-        // No resolver could be matched
-        reject(new UnmatchedResolverError(file.url));
-      }
-      else if (!err || !("error" in err)) {
-        // Throw a generic, friendly error.
-        reject(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) {
-        reject(err.error);
-      }
-      else {
-        reject(new ResolverError(err, file.url));
-      }
-    }
-  }));
-}
-
-/**
- * Parses the given file's contents, using the configured parser plugins.
- *
- * @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
- * @param {$RefParserOptions} options
- *
- * @returns {Promise}
- * The promise resolves with the parsed file contents and the parser that was used.
- */
-function parseFile (file, options, $refs) {
-  return new Promise(((resolve, reject) => {
-    // 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.
-    let allParsers = plugins.all(options.parse);
-    let filteredParsers = plugins.filter(allParsers, "canParse", file);
-    let parsers = filteredParsers.length > 0 ? filteredParsers : allParsers;
-
-    // Run the parsers, in order, until one of them succeeds
-    plugins.sort(parsers);
-    plugins.run(parsers, "parse", file, $refs)
-      .then(onParsed, onError);
-
-    function onParsed (parser) {
-      if (!parser.plugin.allowEmpty && isEmpty(parser.result)) {
-        reject(ono.syntax(`Error parsing "${file.url}" as ${parser.plugin.name}. \nParsed value is empty`));
-      }
-      else {
-        resolve(parser);
-      }
-    }
-
-    function onError (err) {
-      if (!err && options.continueOnError) {
-        // No resolver could be matched
-        reject(new UnmatchedParserError(file.url));
-      }
-      else if (!err || !("error" in err)) {
-        reject(ono.syntax(`Unable to parse ${file.url}`));
-      }
-      else if (err.error instanceof ParserError) {
-        reject(err.error);
-      }
-      else {
-        reject(new ParserError(err.error.message, file.url));
-      }
-    }
-  }));
-}
-
-/**
- * Determines whether the parsed value is "empty".
- *
- * @param {*} value
- * @returns {boolean}
- */
-function isEmpty (value) {
-  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.js

@@ -1,53 +0,0 @@
-let BINARY_REGEXP = /\.(jpeg|jpg|gif|png|bmp|ico)$/i;
-
-export default {
-  /**
-   * The order that this parser will run, in relation to other parsers.
-   *
-   * @type {number}
-   */
-  order: 400,
-
-  /**
-   * Whether to allow "empty" files (zero bytes).
-   *
-   * @type {boolean}
-   */
-  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.
-   *
-   * @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 {boolean}
-   */
-  canParse (file) {
-    // 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).
-   *
-   * @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 {Buffer}
-   */
-  parse (file) {
-    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);
-    }
-  }
-};

package/lib/parsers/text.js

@@ -1,64 +0,0 @@
-import { ParserError } from "../util/errors.js";
-
-let 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.
-   *
-   * @type {number}
-   */
-  order: 300,
-
-  /**
-   * Whether to allow "empty" files (zero bytes).
-   *
-   * @type {boolean}
-   */
-  allowEmpty: true,
-
-  /**
-   * The encoding that the text is expected to be in.
-   *
-   * @type {string}
-   */
-  encoding: "utf8",
-
-  /**
-   * 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.
-   *
-   * @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 {boolean}
-   */
-  canParse (file) {
-    // 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
-   *
-   * @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 {string}
-   */
-  parse (file) {
-    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);
-    }
-  }
-};