feat: uses can overwrite def-0 logic (#5)

Eomm · web-flow · commit 7f20b570a53b · 2021-08-30T17:00:50.000+02:00
* feat: customize def definition

* more test

* upgrade tap 15

* more tests
diff --git a/README.md b/README.md
@@ -4,12 +4,10 @@
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)
 
 Resolve all `$refs` in your [JSON schema](https://json-schema.org/specification.html)!  
-This module will resolve the `$ref` keyword against the `externalSchemas` you will provide.
+This module will resolve the `$ref` keyword against the `externalSchemas` you will provide.  
+By resolving the `$ref` keyword, means that you get back a single BIG inlined JSON schema that does not rely on any external schema.
 If a reference is missing, it will not throw any error.
 
-The `$ref` will be modified to point to a local reference `#/definitions/<generated key>`.
-Moreover, the `definitions` keyword will be decorated with the external schemas to get only
-one JSON schema resolved as output.
 
 ## Install
 
@@ -21,11 +19,24 @@ This plugin support Node.js >= 10
 
 ## Usage: resolve one schema against external schemas
 
+The `$ref` string is going to be modified to point to a local reference URI: `#/definitions/<generated key>`.
+Moreover, the `definitions` keyword will be decorated with the external schemas to get only one JSON schema resolved as output.
+
+By default the `<generated key>` has the `def-${index}` format.
+You can customize it by passing a `buildLocalReference` function as follows:
+
 ```js
 const RefResolver = require('json-schema-resolver')
 
 const ref = RefResolver({
-  clone: true // Clone the input schema without changing it. Default: false
+  clone: true, // Clone the input schema without changing it. Default: false,
+  buildLocalReference (json, baseUri, fragment, i) {
+    // the `json` that is being resolved
+    // the `baseUri` object of the schema. Its values is the parse result from https://www.npmjs.com/package/uri-js
+    // the `fragment` is the `$ref` string when the `$ref` is a relative reference
+    // the `i` is a local counter to generate a unique key
+    return `def-${i}` // default value
+  }
 })
 
 const inputSchema = {
@@ -48,7 +59,7 @@ const addresSchema = {
 }
 
 const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema] })
-// mySchema is untouched thanks to clone:true
+// inputSchema is untouched thanks to clone:true
 ```
 
 `singleSchema` will be like:
@@ -115,7 +126,7 @@ const inputSchema = {
 
 // the resolved schema DOES NOT have definitions added
 const singleSchema = ref.resolve(inputSchema)
-const anotherResolvedSchema = ref.resolve(input_2_Schema)
+const anotherResolvedSchema = ref.resolve(input_2_Schema) // resolve schemas within the same externalSchemas
 
 // to get the definition you need only to call:
 const sharedDefinitions = ref.definitions()
diff --git a/package.json b/package.json
@@ -6,7 +6,7 @@
   "scripts": {
     "lint": "standard",
     "lint:fix": "standard --fix",
-    "test": "npm run lint && tap test/**/*.test.js --cov"
+    "test": "npm run lint && tap test/**/*.test.js"
   },
   "engines": {
     "node": ">=10"
@@ -22,8 +22,8 @@
   },
   "homepage": "https://github.com/Eomm/json-schema-resolver#readme",
   "devDependencies": {
-    "standard": "^14.3.3",
-    "tap": "^12.7.0"
+    "standard": "^16.0.3",
+    "tap": "^15.0.9"
   },
   "dependencies": {
     "debug": "^4.1.1",
diff --git a/ref-resolver.js b/ref-resolver.js
@@ -17,7 +17,10 @@ const kConsumed = Symbol('json-schema-resolver.consumed') // when an external js
 
 const defaultOpts = {
   target: 'draft-07',
-  clone: false
+  clone: false,
+  buildLocalReference (json, baseUri, fragment, i) {
+    return `def-${i}`
+  }
 }
 
 const targetSupported = ['draft-07'] // TODO , 'draft-08'
@@ -33,7 +36,13 @@ const targetCfg = {
 // logic: https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.appendix.B.1
 function jsonSchemaResolver (options) {
   const ee = new EventEmitter()
-  const { clone, target, applicationUri, externalSchemas: rootExternalSchemas } = Object.assign({}, defaultOpts, options)
+  const {
+    clone,
+    target,
+    applicationUri,
+    externalSchemas: rootExternalSchemas,
+    buildLocalReference
+  } = Object.assign({}, defaultOpts, options)
 
   const allIds = new Map()
   let rolling = 0
@@ -130,14 +139,14 @@ function jsonSchemaResolver (options) {
     return rootSchema
   }
 
-  function collectIds (json, baseUri, relative) {
+  function collectIds (json, baseUri, fragment) {
     if (json[kIgnore]) { return }
 
-    const rel = (relative && URI.serialize(relative)) || ''
+    const rel = (fragment && URI.serialize(fragment)) || ''
     const id = URI.serialize(baseUri) + rel
     if (!allIds.has(id)) {
       debug('Collected $id %s', id)
-      json[kRefToDef] = `def-${rolling++}`
+      json[kRefToDef] = buildLocalReference(json, baseUri, fragment, rolling++)
       allIds.set(id, json)
     } else {
       debug('WARN duplicated id %s .. IGNORED - ', id)
diff --git a/test/example.test.js b/test/example.test.js
@@ -32,7 +32,7 @@ test('readme example', t => {
 
   const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema] })
 
-  t.deepEqual(singleSchema, {
+  t.same(singleSchema, {
     $id: 'http://example.com/SimplePerson',
     type: 'object',
     properties: {
@@ -100,7 +100,7 @@ test('readme example #2', t => {
   // to get the definition you need only to call:
   const sharedDefinitions = ref.definitions()
 
-  t.deepEqual(sharedDefinitions, {
+  t.same(sharedDefinitions, {
     definitions: {
       'def-0': {
         $id: 'relativeAddress',
@@ -117,7 +117,7 @@ test('readme example #2', t => {
     }
   })
 
-  t.deepEqual(singleSchema, {
+  t.same(singleSchema, {
     $id: 'my-application.org',
     type: 'object',
     properties: {
diff --git a/test/ref-as-is.test.js b/test/ref-as-is.test.js
@@ -0,0 +1,116 @@
+
+const { test } = require('tap')
+const URI = require('uri-js')
+const RefResolver = require('../ref-resolver')
+
+test('resolving schema within the $id', t => {
+  t.plan(2)
+
+  const schema = {
+    description: 'Succesful response',
+    type: 'object',
+    properties: {
+      greetings: { $ref: 'greetings#' }
+    }
+  }
+
+  const opts = {
+    applicationUri: 'one-single-uri.to',
+    externalSchemas: [
+      {
+        $id: 'greetings',
+        type: 'object',
+        properties: {
+          hello: { type: 'string' }
+        }
+      }
+    ],
+    buildLocalReference (json, baseUri, fragment, i) {
+      return baseUri.path
+    }
+  }
+
+  const resolver = RefResolver(opts)
+  const out = resolver.resolve(schema)
+  const externalDef = resolver.definitions()
+  t.equal(out.properties.greetings.$ref, '#/definitions/greetings')
+  t.same(externalDef.definitions.greetings, opts.externalSchemas[0])
+})
+
+test('resolving schema within the $id case #2', t => {
+  t.plan(3)
+
+  const schema = {
+    $id: 'urn:schema:ref',
+    type: 'object',
+    properties: {
+      hello: { $ref: 'urn:schema:base#/definitions/hello' }
+    }
+  }
+
+  const opts = {
+    applicationUri: schema.$id,
+    externalSchemas: [
+      {
+        $id: 'urn:schema:base',
+        definitions: { hello: { type: 'string' } },
+        type: 'object',
+        properties: { hello: { $ref: '#/definitions/hello' } }
+      },
+      schema
+    ],
+    buildLocalReference (json, baseUri, fragment, i) {
+      return escape(json.$id)
+    }
+  }
+
+  const resolver = RefResolver(opts)
+  const out = resolver.resolve(schema)
+  t.equal(out.properties.hello.$ref, '#/definitions/urn%3Aschema%3Abase/definitions/hello')
+
+  const externalDef = resolver.definitions()
+  t.ok(externalDef.definitions['urn%3Aschema%3Abase'], 'buildLocalReference result')
+  t.ok(externalDef.definitions['urn%3Aschema%3Aref'], 'buildLocalReference result')
+})
+
+test('resolving schema within the $id relative', t => {
+  t.plan(4)
+
+  const schema = {
+    type: 'object',
+    properties: {
+      user: { $ref: 'http://hello.absolute/user.json#/definitions/name' },
+      address: { $ref: 'adr#/definitions/street' }
+    }
+  }
+
+  const opts = {
+    applicationUri: 'http://hello.relative',
+    externalSchemas: [
+      {
+        $id: 'http://hello.absolute/user.json',
+        type: 'object',
+        definitions: { name: { type: 'string' } }
+      },
+      {
+        $id: 'adr',
+        type: 'object',
+        definitions: { street: { type: 'string' } }
+      }
+    ],
+    buildLocalReference (json, baseUri, fragment, i) {
+      t.equal(URI.serialize(baseUri), baseUriCheck.shift())
+      return escape(json.$id)
+    }
+  }
+
+  const baseUriCheck = [
+    opts.externalSchemas[0].$id,
+    `${opts.applicationUri}/${opts.externalSchemas[1].$id}`
+  ]
+
+  const resolver = RefResolver(opts)
+  const out = resolver.resolve(schema)
+  t.equal(out.properties.user.$ref, '#/definitions/http%3A//hello.absolute/user.json/definitions/name')
+  t.equal(out.properties.address.$ref, '#/definitions/adr/definitions/street')
+})
diff --git a/test/ref-fragment.test.js b/test/ref-fragment.test.js
@@ -30,7 +30,7 @@ test('Preserve $ref fragment', t => {
     }
   }, opts)
 
-  t.deepEqual(out, {
+  t.same(out, {
     $id: 'my-schema',
     type: 'object',
     properties: {
diff --git a/test/ref-resolver.test.js b/test/ref-resolver.test.js
diff --git a/test/ref-root.test.js b/test/ref-root.test.js

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ test('Preserve $ref fragment', t => {`
`30`	`30`	`}`
`31`	`31`	`}, opts)`
`32`	`32`
`33`		`- t.deepEqual(out, {`
	`33`	`+ t.same(out, {`
`34`	`34`	`$id: 'my-schema',`
`35`	`35`	`type: 'object',`
`36`	`36`	`properties: {`