joi-to-json 1.5.0 → 2.2.0

package/README.md

@@ -8,10 +8,23 @@ It's **The most powerful schema description language and data validator for Java
 Many times, we need to utilize this schema description to produce other output, such as Swagger OpenAPI doc.
 That is why I build [joi-route-to-swagger](https://github.com/kenspirit/joi-route-to-swagger) in the first place.
 
-At the beginning, `joi-route-to-swagger` relies on [joi-to-json-schema](https://github.com/lightsofapollo/joi-to-json-schema/) which utilizes many joi internal api or properties.  I believed there was reason.  Maybe joi did not provide the `describe` api way before.  But I always feel not comfortable and think it's time to move on.
+At the beginning, `joi-route-to-swagger` relies on [joi-to-json-schema](https://github.com/lightsofapollo/joi-to-json-schema/) which utilizes many joi internal api or properties.  I believed there was reason.  Maybe joi did not provide the `describe` api way before.  But I always feel uncomfortable and think it's time to move on.
 
-The intention of `joi-to-json` is to support converting different version's joi schema to [JSON Schema (draft-04)](https://json-schema.org/specification-links.html#draft-4) using `describe` api.
+The intention of `joi-to-json` is to support converting different version's joi schema to [JSON Schema](https://json-schema.org) using `describe` api.
 
+## 2.0.0 is out
+
+It's a breaking change.
+
+* Functionally, output format supports OpenAPI Schema other than purely JSON Schema.  
+
+* Technically, implementation theory has a big change:
+  - In v1.0.0, it directly converts `joi.describe()` to JSON schema using different parser implementations.
+  - In v2.0.0, `joi.describe()` of different versions are first converted to one base format, the latest version of `joi.describe()` output.  Then different parsers (JSON, OpenAPI) all refer to this base format.
+
+* The benefits of the change are:
+  - Easier to retire old version of joi.
+  - Easier to support more output formats.
 
 ## Installation
 
@@ -28,21 +41,30 @@ The intention of `joi-to-json` is to support converting different version's joi
 * @hapi/joi
   * 15.1.1
   * 16.1.8
-  * 17.1.0
+* joi
+  * 17.4.2
 
-For all above version, I have tested one complex joi object [fixtures](./fixtures) which covers most of the JSON schema attributes that can be described in joi schema.
+For all above versions, I have tested one complex joi object [fixtures](./fixtures) which covers most of the JSON schema attributes that can be described in joi schema.
 
 Although the versions chosen are the latest one for each major version, I believe it should be supporting other minor version as well.
 
 
 ## Usage
 
-Only one API `convert` is available.
+Only one API `parse` is available.  It's signature is `parse(joiObj, type = 'json')`
 
-You can optionally provide debug flag `true` as the second argument to check which version of the parser is chosen and the joi schema describe output
+Currently supported output types:  
+* `json` - Default.  Stands for JSON Schema Draft 07
+* `open-api` - Stands for OpenAPI Schema
+* `json-draft-04` - Stands for JSON Schema Draft 04
+* `json-draft-2019-09` - Stands for JSON Schema Draft 2019-09
+
+The output schema format are in [outputs](./outputs) under specific folders for different types.
+
+Sample code is as below:  
 
 ```javascript
-const convert = require('joi-to-json')
+const parse = require('joi-to-json')
 
 const joiSchema = joi.object().keys({
   nickName: joi.string().required().min(3).max(20).example('鹄思乱想').description('Hero Nickname')
@@ -64,14 +86,15 @@ const joiSchema = joi.object().keys({
   ).required()).min(1).max(3).unique().description('Skills'),
   tags: joi.array().items(joi.string().required()).length(2),
   retired: joi.boolean().truthy('yes').falsy('no').insensitive(false),
-  certificate: joi.binary().encoding('base64')
+  certificate: joi.binary().encoding('base64'),
+  notes: joi.any().meta({ 'x-supported-lang': ['zh-CN', 'en-US'], deprecated: true })
 })
 
-const jsonSchema = convert(joiSchema, true)
+const jsonSchema = parse(joiSchema)
+// Or parsing to OpenAPI schema through:
+// const openApiSchema = parse(joiSchema, 'open-api')
 ```
 
-The output json format is [here](./output.json)
-
 ## Test
 
 >npm run test
@@ -79,8 +102,6 @@ The output json format is [here](./output.json)
 You can optionally set below environment variables:
 
 * `CASE_PATTERN=joi-obj-12` to control which version of joi obj to test
-* `DEBUG=true` to check which version of the parser is chosen and the joi schema describe output
-
 
 ## License
 

package/index.js

@@ -1,23 +1,41 @@
 const cmp = require('semver-compare')
-const DEFAULT_PARSER = require('./lib/parser_base')
+const fs = require('fs')
+const path = require('path')
 
-const parsers = [
-  require('./lib/parser_v16'),
-  require('./lib/parser_v14'),
-  DEFAULT_PARSER
-]
+const convertorsDir = path.resolve(__dirname, './lib/convertors')
+const parsersDir = path.resolve(__dirname, './lib/parsers')
+const convertors = []
+const parsers = {}
 
-function convert(joiObj, debug) {
-  let parser
+fs.readdirSync(convertorsDir).sort().reverse().forEach(file => {
+  if (file.endsWith('.js')) {
+    const convertor = require(`${convertorsDir}/${file}`)
+    convertors.push(convertor)
+  }
+})
+
+fs.readdirSync(parsersDir).forEach(file => {
+  if (file.endsWith('.js')) {
+    const parser = require(`${parsersDir}/${file}`)
+    parsers[file.split('.')[0]] = parser
+  }
+})
+
+function parse(joiObj, type = 'json') {
+  if (typeof joiObj.describe !== 'function') {
+    throw new Error('Not an joi object.')
+  }
 
-  for (let i = 0; i < parsers.length; i++) {
-    const tmpParser = parsers[i]
+  let convertor
+
+  for (let i = 0; i < convertors.length; i++) {
+    const tmpConvertor = convertors[i]
     try {
-      let version = tmpParser.getVersion(joiObj)
-      let result = cmp(tmpParser.getSupportVersion(), version)
+      let version = tmpConvertor.getVersion(joiObj)
+      let result = cmp(tmpConvertor.getSupportVersion(), version)
       if (result <= 0) {
         // The first parser has smaller or equal version
-        parser = tmpParser
+        convertor = tmpConvertor
         break
       }
     } catch (e) {
@@ -27,17 +45,18 @@ function convert(joiObj, debug) {
     }
   }
 
-  if (!parser) {
-    console.warn('No parser available, using the default one')
-    parser = DEFAULT_PARSER
+  if (!convertor) {
+    console.warn('No matched joi version convertor found, using the latest version')
+    convertor = convertors[0]
   }
 
-  const parserObj = new parser(joiObj)
-  if (debug) {
-    console.debug(`Parser of verison ${parser.getSupportVersion()} is chosen.\n`)
-    console.debug(`Joi Object Describe Result as below:\n${JSON.stringify(parserObj.joiDescribe, null, 2)}\n`)
+  const joiBaseSpec = new convertor().toBaseSpec(joiObj.describe())
+  const parser = parsers[type]
+  if (!parser) {
+    throw new Error(`No parser is registered for ${type}`)
   }
-  return parserObj.jsonSchema
+
+  return new parser().parse(joiBaseSpec)
 }
 
-module.exports = convert
+module.exports = parse

package/lib/convertors/v12.js

@@ -0,0 +1,241 @@
+const _ = require('lodash')
+
+class JoiSpecConvertor {
+  constructor() {}
+
+  static getVersion(joiObj) {
+    return joiObj._currentJoi.version
+  }
+
+  static getSupportVersion() {
+    return '12'
+  }
+
+  _convertObject(joiObj) {
+    if (joiObj.children) {
+      joiObj.keys = joiObj.children
+      delete joiObj.children
+    }
+
+    _.each(joiObj.keys, (value, _key) => {
+      this.toBaseSpec(value)
+    })
+
+    _.each(joiObj.patterns, (pattern, _idx) => {
+      this.toBaseSpec(pattern.rule)
+    })
+  }
+
+  _convertDate(joiObj) {
+    if (joiObj.flags.timestamp) {
+      joiObj.flags.format = joiObj.flags.timestamp
+      delete joiObj.flags.timestamp
+      delete joiObj.flags.multiplier
+    } else if (joiObj.flags.format = {}) {
+      joiObj.flags.format = 'iso'
+    }
+  }
+
+  _convertAlternatives(joiObj) {
+    if (joiObj.base && joiObj.base.type === 'any') {
+      // when case
+      joiObj.type = 'any'
+      joiObj.whens = joiObj.alternatives
+
+      if (joiObj.flags.presence === 'ignore') {
+        // FIXME: Not sure when this flag is set.
+        delete joiObj.flags.presence
+      }
+      if (joiObj.whens.peek) {
+        joiObj.whens.is = joiObj.whens.peek
+        delete joiObj.whens.peek
+      }
+
+      joiObj.whens[0] = _.mapValues(joiObj.whens[0], (value, condition) => {
+        switch (condition) {
+          case 'is':
+            this.toBaseSpec(value)
+            value.type = 'any'
+            // FIXME: Not sure when this is set.
+            value.allow.splice(0, 0, { 'override': true })
+            break
+          case 'otherwise':
+            this.toBaseSpec(value)
+            break
+          case 'then':
+            this.toBaseSpec(value)
+            break
+          case 'ref':
+            if (value.indexOf('ref:') === 0) {
+              value = {
+                path: value.replace('ref:', '').split('.')
+              }
+            }
+            break
+        }
+        return value
+      })
+
+      delete joiObj.alternatives
+      delete joiObj.base
+    } else {
+      joiObj.matches = _.map(joiObj.alternatives, (alternative) => {
+        return {
+          schema: this.toBaseSpec(alternative)
+        }
+      })
+      delete joiObj.alternatives
+    }
+  }
+
+  _convertString(joiObj) {
+    delete joiObj.options
+
+    _.each(joiObj.rules, (rule, _idx) => {
+      const name = rule.name
+      if (['min', 'max'].includes(name)) {
+        rule.args = {
+          limit: rule.arg
+        }
+      } else if (['lowercase', 'uppercase'].includes(name)) {
+        rule.name = 'case'
+        rule.args = {
+          direction: name.replace('case', '')
+        }
+        delete joiObj.flags.case
+      } else if (rule.arg) {
+        rule.args = {
+          options: rule.arg
+        }
+      }
+      if (name === 'regex') {
+        rule.name = 'pattern'
+        rule.args.regex = rule.arg.pattern.toString()
+        delete rule.args.options.pattern
+      }
+      delete rule.arg
+    })
+  }
+
+  _convertNumber(joiObj) {
+    _.each(joiObj.rules, (rule, _idx) => {
+      const name = rule.name
+      if (['positive', 'negative'].includes(name)) {
+        rule.args = {
+          sign: name
+        }
+        rule.name = 'sign'
+      }
+      if (['greater', 'less', 'min', 'max', 'precision'].includes(name)) {
+        rule.args = {
+          limit: rule.arg
+        }
+      }
+      if (name === 'multiple') {
+        rule.args = {
+          base: rule.arg
+        }
+      }
+      delete rule.arg
+    })
+
+    if (joiObj.flags.precision) {
+      delete joiObj.flags.precision
+    }
+  }
+
+  _convertBoolean(joiObj) {
+    if (joiObj.flags.insensitive === false) {
+      joiObj.flags.sensitive = true
+    }
+    delete joiObj.flags.insensitive
+  }
+
+  _convertArray(joiObj) {
+    if (joiObj.flags.sparse === false) {
+      delete joiObj.flags.sparse
+    }
+
+    _.each(joiObj.rules, (rule, _idx) => {
+      const name = rule.name
+      if (['min', 'max', 'length'].includes(name)) {
+        rule.args = {
+          limit: rule.arg
+        }
+      }
+      delete rule.arg
+    })
+
+    _.each(joiObj.items, (item, _idx) => {
+      this.toBaseSpec(item)
+    })
+  }
+
+  _convertExamples(_joiObj) {
+  }
+
+  toBaseSpec(joiObj) {
+    joiObj.flags = joiObj.flags || {}
+
+    if (joiObj.flags.allowOnly) {
+      joiObj.flags.only = joiObj.flags.allowOnly
+      delete joiObj.flags.allowOnly
+    }
+    if (joiObj.flags.allowUnknown) {
+      joiObj.flags.unknown = joiObj.flags.allowUnknown
+      delete joiObj.flags.allowUnknown
+    }
+    if (joiObj.description) {
+      joiObj.flags.description = joiObj.description
+      delete joiObj.description
+    }
+    if (joiObj.options) {
+      joiObj.preferences = joiObj.options
+      delete joiObj.options
+    }
+    if (joiObj.valids) {
+      joiObj.allow = joiObj.valids
+      delete joiObj.valids
+    }
+    if (joiObj.meta) {
+      joiObj.metas = joiObj.meta
+      delete joiObj.meta
+    }
+    delete joiObj.invalids
+
+    this._convertExamples(joiObj)
+
+    switch (joiObj.type) {
+      case 'object':
+        this._convertObject(joiObj)
+        break
+      case 'date':
+        this._convertDate(joiObj)
+        break
+      case 'alternatives':
+        this._convertAlternatives(joiObj)
+        break
+      case 'string':
+        this._convertString(joiObj)
+        break
+      case 'number':
+        this._convertNumber(joiObj)
+        break
+      case 'boolean':
+        this._convertBoolean(joiObj)
+        break
+      case 'array':
+        this._convertArray(joiObj)
+        break
+      default:
+        break
+    }
+    if (_.isEmpty(joiObj.flags)) {
+      delete joiObj.flags
+    }
+
+    return joiObj
+  }
+}
+
+module.exports = JoiSpecConvertor

package/lib/convertors/v13.js

@@ -0,0 +1,9 @@
+const BaseConverter = require('./v12')
+
+class JoiSpecConvertor extends BaseConverter {
+  static getSupportVersion() {
+    return '13'
+  }
+}
+
+module.exports = JoiSpecConvertor

package/lib/convertors/v14.js

@@ -0,0 +1,24 @@
+const BaseConverter = require('./v13')
+
+class JoiSpecConvertor extends BaseConverter {
+  static getSupportVersion() {
+    return '14'
+  }
+
+  _convertExamples(joiObj) {
+    if (joiObj.examples && joiObj.examples.length === 1) {
+      const example = joiObj.examples[0]
+      joiObj.examples = [example.value]
+    }
+  }
+
+  _convertNumber(joiObj) {
+    super._convertNumber(joiObj)
+
+    if (joiObj.flags) {
+      delete joiObj.flags.unsafe
+    }
+  }
+}
+
+module.exports = JoiSpecConvertor

package/lib/convertors/v15.js

@@ -0,0 +1,9 @@
+const BaseConverter = require('./v14')
+
+class JoiSpecConvertor extends BaseConverter {
+  static getSupportVersion() {
+    return '15'
+  }
+}
+
+module.exports = JoiSpecConvertor

package/lib/convertors/v16.js

@@ -0,0 +1,30 @@
+const BaseConverter = require('./v15')
+
+class JoiSpecConvertor extends BaseConverter {
+  static getVersion(joiObj) {
+    return joiObj.$_root.version
+  }
+
+  static getSupportVersion() {
+    return '16'
+  }
+
+  // All methods are overridden because the Joi v16.1.8 spec is closed to the latest version
+  _convertExamples(_joiObj) { }
+
+  _convertObject(_joiObj) { }
+
+  _convertDate(_joiObj) { }
+
+  _convertAlternatives(_joiObj) { }
+
+  _convertString(_joiObj) { }
+
+  _convertNumber(_joiObj) { }
+
+  _convertBoolean(_joiObj) { }
+
+  _convertArray(_joiObj) {}
+}
+
+module.exports = JoiSpecConvertor

package/lib/convertors/v17.js

@@ -0,0 +1,9 @@
+const BaseConverter = require('./v16')
+
+class JoiSpecConvertor extends BaseConverter {
+  static getSupportVersion() {
+    return '17'
+  }
+}
+
+module.exports = JoiSpecConvertor

package/lib/parsers/json-draft-04.js

@@ -0,0 +1,17 @@
+const _ = require('lodash')
+const JoiJsonSchemaParser = require('./json')
+
+class JoiOpenApiSchemaParser extends JoiJsonSchemaParser {
+  _setNumberFieldProperties(fieldSchema, fieldDefn) {
+    super._setNumberFieldProperties(fieldSchema, fieldDefn)
+
+    if (typeof fieldSchema.minimum !== 'undefined' && fieldSchema.minimum === fieldSchema.exclusiveMinimum) {
+      fieldSchema.exclusiveMinimum = true
+    }
+    if (typeof fieldSchema.maximum !== 'undefined' && fieldSchema.maximum === fieldSchema.exclusiveMaximum) {
+      fieldSchema.exclusiveMaximum = true
+    }
+  }
+}
+
+module.exports = JoiOpenApiSchemaParser

package/lib/parsers/json-draft-2019-09.js

@@ -0,0 +1,22 @@
+const _ = require('lodash')
+const JoiJsonSchemaParser = require('./json')
+
+class JoiOpenApiSchemaParser extends JoiJsonSchemaParser {
+  parse(joiSpec) {
+    const schema = super.parse(joiSpec)
+
+    if (!_.isEmpty(joiSpec.metas)) {
+      _.each(joiSpec.metas, meta => {
+        _.each(meta, (value, key) => {
+          if (key === 'deprecated') {
+            schema[key] = value
+          }
+        })
+      })
+    }
+
+    return schema
+  }
+}
+
+module.exports = JoiOpenApiSchemaParser