Refactoring

Author: JamesMessinger

dist/ref-parser.js

@@ -1,51 +1,54 @@
 'use strict';
 
-var PathOrUrl = require('./path-or-url'),
-    $Ref      = require('./ref'),
+var $Ref      = require('./ref'),
     util      = require('./util'),
+    url       = require('url'),
     _forEach  = require('lodash/collection/forEach'),
     _isArray  = require('lodash/lang/isArray'),
     _isObject = require('lodash/lang/isObject');
 
 module.exports = dereference;
 
 /**
+ * Crawls the JSON schema, finds all JSON references, and dereferences them.
+ * This method mutates the JSON schema object, replacing JSON references with their resolved value.
+ *
  * @param {$RefParser} parser
- * @param {Options} options
+ * @param {ParserOptions} options
  */
 function dereference(parser, options) {
-  util.debug('Dereferencing $ref pointers in %s', parser._base);
-  crawl(parser.schema, parser._base, [], parser.$refs, options);
+  util.debug('Dereferencing $ref pointers in %s', parser._basePath);
+  crawl(parser.schema, parser._basePath + '#', [], parser.$refs, options);
 }
 
 /**
- * @param {object} obj
- * @param {PathOrUrl} pathOrUrl
- * @param {object[]} parents
- * @param {$Refs} $refs
- * @param {Options} options
+ * Recursively crawls the given value, and dereferences any JSON references.
+ *
+ * @param {*} obj - The value to crawl. If it's not an object or array, it will be ignored.
+ * @param {string} path - The path to use for resolving relative JSON references
+ * @param {object[]} parents - An array of the parent objects that have already been dereferenced
+ * @param {$Refs} $refs - The resolved JSON references
+ * @param {ParserOptions} options
  */
-function crawl(obj, pathOrUrl, parents, $refs, options) {
+function crawl(obj, path, parents, $refs, options) {
   if (_isObject(obj) || _isArray(obj)) {
     parents.push(obj);
 
     _forEach(obj, function(value, key) {
-      var keyPath = new PathOrUrl(pathOrUrl);
-      keyPath.hash += '/' + key;
+      var keyPath = path + '/' + key;
 
       if ($Ref.isAllowed(value, options)) {
-        // We found a $ref pointer.
+        // We found a $ref, so resolve it
         util.debug('Dereferencing $ref pointer "%s" at %s', value.$ref, keyPath);
-        var $refString = pathOrUrl.resolve(value.$ref, {allowFileHash: true});
-        var $refPathOrUrl = new PathOrUrl($refString, {allowFileHash: true});
+        var $refPath = url.resolve(path, value.$ref);
+        var resolved$Ref = $refs._resolve($refPath, options);
 
-        // Dereference the $ref pointer
-        var resolved$Ref = $refs._resolve($refPathOrUrl, options);
+        // Dereference the JSON reference
         obj[key] = value = resolved$Ref.value;
 
         // Crawl the dereferenced value (unless it's circular)
         if (parents.indexOf(value) === -1) {
-          crawl(resolved$Ref.value, resolved$Ref.pathOrUrl, parents, $refs, options);
+          crawl(resolved$Ref.value, resolved$Ref.path + '#', parents, $refs, options);
         }
       }
       else if (parents.indexOf(value) === -1) {

dist/ref-parser.js.map

@@ -8,12 +8,13 @@
 
 var Promise        = require('./promise'),
     Options        = require('./options'),
-    PathOrUrl      = require('./path-or-url'),
     $Refs          = require('./refs'),
     read           = require('./read'),
     resolve        = require('./resolve'),
     dereference    = require('./dereference'),
     util           = require('./util'),
+    url            = require('url'),
+    ono            = require('ono'),
     _cloneDeep     = require('lodash/lang/cloneDeep'),
     _isFunction    = require('lodash/lang/isFunction'),
     _isObject      = require('lodash/lang/isObject'),
@@ -22,6 +23,12 @@ var Promise        = require('./promise'),
 
 module.exports = $RefParser;
 
+/**
+ * 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
@@ -32,23 +39,43 @@ function $RefParser() {
   this.schema = null;
 
   /**
-   * The resolved $ref pointers
+   * The resolved JSON references
    *
    * @type {$Refs}
    */
   this.$refs = new $Refs();
 
   /**
-   * @type {PathOrUrl}
+   * @type {string}
    * @protected
    */
-  this._base = null;
+  this._basePath = '';
 }
 
+/**
+ * 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|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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(schema, options, callback) {
   return new $RefParser().parse(schema, options, callback);
 };
 
+/**
+ * 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|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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 = function(schema, options, callback) {
   if (_isFunction(options)) {
     callback = options;
@@ -58,26 +85,27 @@ $RefParser.prototype.parse = function(schema, options, callback) {
   if (schema && _isObject(schema)) {
     // The schema is an object, not a path/url
     this.schema = _cloneDeep(schema);
-    this._base = PathOrUrl.cwd();
+    this._basePath = '';
 
     util.doCallback(callback, null, this.schema);
     return Promise.resolve(this.schema);
   }
 
   if (!schema || !_isString(schema)) {
-    var err = util.newError('Expected a file path, URL, or object. Got %s', schema);
+    var err = ono('Expected a file path, URL, or object. Got %s', schema);
     util.doCallback(callback, err, schema);
     return Promise.reject(err);
   }
 
   options = new Options(options);
   var me = this;
 
-  // Resolve the full URL of the schema
-  this._base = new PathOrUrl(schema, {allowFileHash: true});
+  // Resolve the absolute path of the schema
+  schema = url.resolve(util.cwd(), schema);
+  this._basePath = util.stripHash(schema);
 
   // Read the schema file/url
-  return read(this._base, this, options)
+  return read(schema, this, options)
     .then(function($ref) {
       // Make sure the file was a POJO (in JSON or YAML format), NOT a Buffer or string
       if ($ref.value && _isPlainObject($ref.value)) {
@@ -86,7 +114,7 @@ $RefParser.prototype.parse = function(schema, options, callback) {
         return me.schema;
       }
       else {
-        throw util.newError(SyntaxError, '"%s" is not a valid JSON Schema', me._base);
+        throw ono.syntax('"%s" is not a valid JSON Schema', me._basePath);
       }
     })
     .catch(function(err) {
@@ -95,10 +123,34 @@ $RefParser.prototype.parse = function(schema, options, callback) {
     });
 };
 
+/**
+ * Parses the given JSON schema and resolves any JSON references, including references in
+ * externally-referenced files.
+ *
+ * @param {string|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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(schema, options, callback) {
   return new $RefParser().resolve(schema, options, callback);
 };
 
+/**
+ * Parses the given JSON schema and resolves any JSON references, including references in
+ * externally-referenced files.
+ *
+ * @param {string|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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 = function(schema, options, callback) {
   if (_isFunction(options)) {
     callback = options;
@@ -122,10 +174,28 @@ $RefParser.prototype.resolve = function(schema, options, callback) {
     });
 };
 
+/**
+ * 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|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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(schema, options, callback) {
   return new $RefParser().dereference(schema, options, callback);
 };
 
+/**
+ * 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|object} schema - The file path or URL of the JSON schema. Or a JSON schema object.
+ * @param {ParserOptions} [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 = function(schema, options, callback) {
   if (_isFunction(options)) {
     callback = options;

dist/ref-parser.min.js

@@ -2,25 +2,84 @@
 
 var _merge = require('lodash/object/merge');
 
-module.exports = Options;
+module.exports = ParserOptions;
 
-function Options(options) {
+/**
+ * Options that determine how JSON schemas are parsed, dereferenced, and cached.
+ *
+ * @param {object|ParserOptions} [options] - Overridden options
+ * @constructor
+ */
+function ParserOptions(options) {
+  /**
+   * Determines what types of files can be parsed
+   */
   this.allow = {
+    /**
+     * Are JSON files allowed? If false, then all schemas must be in YAML format.
+     * @type {boolean}
+     */
     json: true,
+
+    /**
+     * Are YAML files allowed? If false, then all schemas must be in JSON format.
+     * @type {boolean}
+     */
     yaml: true,
+
+    /**
+     * Are zero-byte files allowed? If false, then an error will be thrown if a file is empty.
+     * @type {boolean}
+     */
     empty: true,
+
+    /**
+     * Can unknown file types be $referenced?
+     * If true, then they will be parsed as Buffers (byte arrays).
+     * If false, then an error will be thrown.
+     * @type {boolean}
+     */
     unknown: true
   };
 
+  /**
+   * Determines the types of JSON references that are allowed.
+   */
   this.$refs = {
+    /**
+     * Allow JSON references to other parts of the same file?
+     * @type {boolean}
+     */
     internal: true,
+
+    /**
+     * Allow JSON references to external files/URLs?
+     * @type {boolean}
+     */
     external: true
   };
 
+  /**
+   * How long to cache files (in seconds).
+   */
   this.cache = {
-    fs: 60,
-    http: 5 * 60,
-    https: 5 * 60
+    /**
+     * How long to cache local files, in seconds.
+     * @type {number}
+     */
+    fs: 60, // 1 minute
+
+    /**
+     * How long to cache files downloaded via HTTP, in seconds.
+     * @type {number}
+     */
+    http: 5 * 60, // 5 minutes
+
+    /**
+     * How long to cache files downloaded via HTTPS, in seconds.
+     * @type {number}
+     */
+    https: 5 * 60 // 5 minutes
   };
 
   _merge(this, options);