feat: isRef (#5)

also includes:

* chore: update scripts to 3.0.0
* docs: hide private classes from typedoc
* chore: use @stoplight/json
* docs: improve type names and docs
* docs(readme): add basic example

Author: Marc MacLeod

README.md

@@ -27,7 +27,42 @@ yarn add @stoplight/json-ref-resolver
 
 ### Usage
 
-All relevant types and options can be found in [src/types.ts](src/types.ts).
+All relevant types and options can be found in [src/types.ts](src/types.ts) or in the TSDoc.
+
+#### Basic Local Resolution
+
+```ts
+import { Resolver } from "@stoplight/json-ref-resolver";
+
+const resolver = new Resolver();
+const resolved = await resolver.resolve({
+  user: {
+    $ref: "#/models/user"
+  },
+  models: {
+    user: {
+      name: "john"
+    }
+  }
+});
+
+console.log(resolved.result);
+
+// ==> outputs the original object, with local refs resolved and replaced
+//
+// {
+//   user: {
+//     name: 'json'
+//   },
+//   models: {
+//     user: {
+//       name: 'john'
+//     }
+//   }
+// }
+```
+
+#### With Authority Readers
 
 ```ts
 import { Resolver } from "@stoplight/json-ref-resolver";

package.json

@@ -5,10 +5,15 @@
   "keywords": [
     "json-parser",
     "json",
+    "jsonschema",
     "json-schema",
+    "json-pointer",
+    "$ref",
     "resolver",
     "openapi",
-    "swagger"
+    "swagger",
+    "dereference",
+    "resolve"
   ],
   "main": "src/index.ts",
   "sideEffects": false,
@@ -21,15 +26,14 @@
   },
   "license": "Apache-2.0",
   "files": [
-    "**/*",
-    "!__tests__"
+    "**/*"
   ],
   "engines": {
     "node": ">=8.3.0"
   },
   "scripts": {
     "build": "sl-scripts build",
-    "build.docs": "sl-scripts build:tsdoc",
+    "build.docs": "sl-scripts build:typedoc",
     "commit": "git-cz",
     "lint": "sl-scripts lint",
     "lint.fix": "yarn lint --fix",
@@ -42,22 +46,22 @@
     "test.watch": "yarn test --watch"
   },
   "dependencies": {
-    "@stoplight/fast-safe-stringify": "2.1.x",
+    "@stoplight/json": "1.1.x",
     "dependency-graph": "0.7.x",
-    "fast-memoize": "2.5.x",
-    "immer": "1.7.x",
+    "fast-memoize": "2.x.x",
+    "immer": "1.x.x",
     "lodash": "4.x.x",
-    "urijs": "1.19.x"
+    "urijs": "1.x.x"
   },
   "devDependencies": {
-    "@stoplight/scripts": "1.1.2",
+    "@stoplight/scripts": "3.0.0",
     "@types/lodash": "4.x.x",
     "@types/urijs": "1.15.x",
     "benchmark": "2.x.x",
     "typescript": "3.1.6"
   },
   "lint-staged": {
-    "*.ts": [
+    "*.{ts,tsx}$": [
       "yarn lint.fix",
       "git add"
     ]

src/__tests__/resolver.spec.ts

@@ -1,8 +1,9 @@
 import * as fs from 'fs';
 import * as URI from 'urijs';
 
+import { Cache } from '../cache';
 import { Resolver } from '../resolver';
-import { ResolveRunner } from '../runner';
+import { defaultGetRef, ResolveRunner } from '../runner';
 import * as Types from '../types';
 import httpMocks from './fixtures/http-mocks';
 import resolvedResults from './fixtures/resolved';
@@ -134,8 +135,7 @@ describe('resolver', () => {
         word: 'world',
       };
 
-      const resolver = new Resolver();
-      resolver.resolvePointers = false;
+      const resolver = new Resolver({ resolvePointers: false });
       const resolved = await resolver.resolve(source);
       expect(resolved.result).toEqual(source);
     });
@@ -306,11 +306,11 @@ describe('resolver', () => {
       };
 
       const resolver = new Resolver({
+        resolveAuthorities: false,
         readers: {
           custom: reader,
         },
       });
-      resolver.resolveAuthorities = false;
 
       const resolved = await resolver.resolve(source);
 
@@ -791,9 +791,9 @@ describe('resolver', () => {
         readers: {
           custom: reader,
         },
-        authorityCacheOpts: {
+        authorityCache: new Cache({
           stdTTL: 1000, // 1s cache
-        },
+        }),
       });
 
       let resolved = await resolver.resolve(source);
@@ -1089,6 +1089,63 @@ describe('resolver', () => {
       expect(resolved.result.inner).toEqual('hello2');
     });
 
+    /**
+     * This allows the end user to completely customize which properties are resolved.
+     */
+    test('should support `getRef` hook', async () => {
+      const source = {
+        inner: {
+          randomProp: '#/foo',
+        },
+        foo: 'hello1',
+      };
+
+      const resolver = new Resolver({
+        getRef(_key, val) {
+          if (typeof val === 'string' && val.startsWith('#/')) return val;
+          return;
+        },
+      });
+
+      const resolved = await resolver.resolve(source);
+      expect(resolved.result.inner).toEqual({
+        randomProp: 'hello1',
+      });
+    });
+
+    /**
+     * This version preserves the original $ref handling, combined with our custom getRef logic.
+     */
+    test('should support `getRef` hook combined with defaultGetRef', async () => {
+      const source = {
+        inner: {
+          randomProp: '#/foo',
+        },
+        inner2: {
+          $ref: '#/bar',
+        },
+        foo: 'hello1',
+        bar: 'hello2',
+      };
+
+      const resolver = new Resolver({
+        getRef(key, val) {
+          if (typeof val === 'string' && val.startsWith('#/')) return val;
+          return defaultGetRef(key, val);
+        },
+      });
+
+      const resolved = await resolver.resolve(source);
+      expect(resolved.result).toEqual({
+        inner: {
+          randomProp: 'hello1',
+        },
+        inner2: 'hello2',
+        foo: 'hello1',
+        bar: 'hello2',
+      });
+    });
+
     /**
      * Allows the consumer to provide a custom parser to parse lookup results before they get
      * cached and returned.

src/__tests__/utils.spec.ts

@@ -1,5 +1,6 @@
 import * as Types from './types';
 
+/** @hidden */
 export class Cache implements Types.ICache {
   public debug = false;
 
@@ -23,7 +24,7 @@ export class Cache implements Types.ICache {
     };
   } = {};
 
-  constructor(opts: Types.ICacheOptions = {}) {
+  constructor(opts: Types.ICacheOpts = {}) {
     this._stdTTL = opts.stdTTL;
   }
 

src/cache.ts

@@ -1,10 +1,12 @@
+import { pointerToPath } from '@stoplight/json';
 import { DepGraph } from 'dependency-graph';
+import _get = require('lodash/get');
 
-import { getValue } from './json';
 import * as Types from './types';
 import * as Utils from './utils';
 
-export class ResolveCrawler implements Types.IResolveCrawler {
+/** @hidden */
+export class ResolveCrawler implements Types.ICrawler {
   public readonly authorityResolvers: Array<Promise<Types.IAuthorityLookupResult>> = [];
 
   // jsonPointer = the jsonPointer the runner was originally called with
@@ -95,7 +97,7 @@ export class ResolveCrawler implements Types.IResolveCrawler {
     if (Utils.uriIsJSONPointer(ref)) {
       if (this._runner.resolvePointers) {
         const targetPointer = Utils.uriToJSONPointer(ref);
-        const targetPath = Utils.jsonPointerToPath(targetPointer);
+        const targetPath = pointerToPath(targetPointer);
 
         /**
          * Protects against circular references back to something higher up in the tree
@@ -152,7 +154,7 @@ export class ResolveCrawler implements Types.IResolveCrawler {
           pointerStack.push(targetPointer);
 
           // if we are partially resolving
-          this.computeGraph(getValue(this._runner.source, targetPath), targetPath, targetPointer, pointerStack);
+          this.computeGraph(_get(this._runner.source, targetPath), targetPath, targetPointer, pointerStack);
 
           pointerStack.pop();
         }

src/crawler.ts

@@ -1 +1,4 @@
 export * from './resolver';
+
+import { defaultGetRef } from './runner';
+export { defaultGetRef };