Added optional metadata to the dereference() method (#103)

* Created a `saveOriginalRefs` option
* Added logic to the dereference() method to save metadata for all references
* Added tests
* Documented new functionality

Author: RomanHotsiy

.eslintrc.yml

@@ -13,6 +13,7 @@ extends:
 
 globals:
   Promise: false
+  Symbol: false
 
 rules:
   # This rule erroneously flags functions that use the `arguments` object

docs/options.md

@@ -74,3 +74,6 @@ The `dereference` options control how JSON Schema $Ref Parser will dereference `
 |Option(s)             |Type                |Description
 |:---------------------|:-------------------|:------------
 |`circular`|`boolean` or `"ignore"`|Determines whether [circular `$ref` pointers](README.md#circular-refs) are handled.<br><br>If set to `false`, then a `ReferenceError` will be thrown if the schema contains any circular references.<br><br> If set to `"ignore"`, then circular references will simply be ignored.  No error will be thrown, but the [`$Refs.circular`](refs.md#circular) property will still be set to `true`.
+|`saveOriginalRefs`    | `boolean`          | If set to true `dereference` will preserve information about original
+`$ref` in the object metadata which can be later retrieved using [`$RefParser.getMetadata`](ref-parser.md#getmetadata)
+ 

docs/ref-parser.md

@@ -7,13 +7,15 @@ This is the default export of JSON Schema $Ref Parser.  You can creates instance
 - [`schema`](#schema)
 - [`$refs`](#refs)
 
+##### Static Methods
+- [`getMetadata()`](#getmetadata)
+
 ##### Methods
 - [`dereference()`](#dereferenceschema-options-callback)
 - [`bundle()`](#bundleschema-options-callback)
 - [`parse()`](#parseschema-options-callback)
 - [`resolve()`](#resolveschema-options-callback)
 
-
 ### `schema`
 The `schema` property is the parsed/bundled/dereferenced JSON Schema object.  This is the same value that is passed to the callback function (or Promise) when calling the [`parse`](#parseschema-options-callback), [`bundle`](#bundleschema-options-callback), or [`dereference`](#dereferenceschema-options-callback) methods.
 
@@ -47,6 +49,24 @@ parser.dereference("my-schema.json")
   });
 ```
 
+### `getMetadata()`
+
+Extracts metadata saved by [`dereference`](#dereferenceschema-options-callback).
+
+When using [`dereference`](#dereferenceschema-options-callback) information about original `$ref` is lost. To preserve it [`dereference.saveOriginalRefs`](options.md#dereference-options) option can be used.
+
+```js
+// var obj = dereferenced value
+var meta = $RefParser.getMetadata(obj.properties.a)
+```
+
+Metadata object contains the following information:
+
+- `$ref` - original `$ref`
+- `pathFromRoot` - path from the root of the document
+- `path` - absolute path
+
+
 
 ### `dereference(schema, [options], [callback])`
 

lib/dereference.js

@@ -3,7 +3,8 @@
 var $Ref = require('./ref'),
     Pointer = require('./pointer'),
     ono = require('ono'),
-    url = require('./util/url');
+    url = require('./util/url'),
+    setMetadata = require('./util/meta').setMetadata;
 
 module.exports = dereference;
 
@@ -125,6 +126,14 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, $refs, options) {
     dereferencedValue.$ref = pathFromRoot;
   }
 
+  if (options.dereference.saveOriginalRefs) {
+    setMetadata(dereferencedValue, {
+      $ref: $ref.$ref,
+      path: path,
+      pathFromRoot: pathFromRoot,
+    });
+  }
+
   return {
     circular: circular,
     value: dereferencedValue

lib/index.js

@@ -8,11 +8,15 @@ var Options = require('./options'),
     bundle = require('./bundle'),
     dereference = require('./dereference'),
     url = require('./util/url'),
+    getMetadata = require('./util/meta').getMetadata,
+    setMetadata = require('./util/meta').setMetadata,
     maybe = require('call-me-maybe'),
     ono = require('ono');
 
 module.exports = $RefParser;
 module.exports.YAML = require('./util/yaml');
+module.exports.getMetadata = getMetadata;
+module.exports.setMetdata = setMetadata;
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,

lib/util/meta.js

@@ -0,0 +1,28 @@
+'use strict';
+
+var META_SYMBOL = Symbol('json-schema-ref-parser meta');
+
+/**
+ * Safely sets meta property on the given object value
+ *
+ * @param  {object} obj - A object to set meta info on
+ * @param  {string} prop - Name of property
+ * @param  {string} prop - Value to set
+ */
+exports.setMetadata = function (obj, value) {
+  if (!obj) { return; }
+  // we can't create property on primitives (throws in strict mode)
+  if (typeof obj !== 'object') { return; }
+
+  obj[META_SYMBOL] = value;
+};
+
+/**
+ * Given the any object returns the associated meta-information or undefined
+ *
+ * @param  {any} value - object to get the meta from
+ * @returns {{pointer: string}}
+ */
+exports.getMetadata = function (value) {
+  return value && value[META_SYMBOL];
+};

test/specs/metadata/external.yaml

@@ -0,0 +1 @@
+type: number

test/specs/metadata/metadata.spec.js

@@ -0,0 +1,29 @@
+describe('Dereference save metadata', function () {
+  'use strict';
+
+  it('should save metadata for internal refs', function () {
+    var parser = new $RefParser();
+    return parser
+      .dereference(path.rel('specs/metadata/spec.yaml'), { dereference: { saveOriginalRefs: true }})
+      .then(function (schema) {
+        var metadata = $RefParser.getMetadata(schema.properties.a);
+        expect(metadata).to.be.an('object');
+        expect(metadata.$ref).to.eq('#/definitions/internal');
+        expect(metadata.pathFromRoot).to.eq('#/properties/a');
+        expect(metadata.path.endsWith('spec.yaml#/properties/a')).to.be.true;
+      });
+  });
+
+  it('should save metadata for external refs', function () {
+    var parser = new $RefParser();
+    return parser
+      .dereference(path.rel('specs/metadata/spec.yaml'), { dereference: { saveOriginalRefs: true }})
+      .then(function (schema) {
+        var metadata = $RefParser.getMetadata(schema.properties.b);
+        expect(metadata).to.be.an('object');
+        expect(metadata.$ref).to.eq('external.yaml');
+        expect(metadata.pathFromRoot).to.eq('#/properties/b');
+        expect(metadata.path.endsWith('spec.yaml#/properties/b')).to.be.true;
+      });
+  });
+});

test/specs/metadata/spec.yaml

@@ -0,0 +1,9 @@
+type: object
+properties:
+  a:
+    $ref: "#/definitions/internal"
+  b:
+    $ref: "external.yaml"
+definitions:
+  internal:
+    type: string