joi-to-json 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+### 3.1.0
+
+- Add support for relation operator `with` and `without`.
+
 ### 3.0.0
 
 - [BREAKING] Default enable feature: relation operator `and`, `or`, `nand`, `xor`, `oxor`.

package/docs/logical_rel_support.md

@@ -0,0 +1,241 @@
+## Logical Relation
+
+There are some logical relation operators in Joi:
+
+* `and`
+* `nand`
+* `or`
+* `xor`
+* `oxor` (After Joi v14)
+* `with`
+* `without`
+
+For different operator, I have managed to describe them in JSON schema as below for different cases.
+Some named as `xxxGeneral` means it should be supported since JSON Draft 4.
+Some named as `xxxDraft7` means it is using some features until JSON Draft 7.
+
+Hence, if you are converting the Joi to Draft 4 or OpenAPI, the `xor` will be ignored.
+
+### Usage
+
+By default, this feature is enabled.
+It can be disabled completely by passing option `{ logicalOpParser: false }` to `parse` API:
+
+`parse(joiObj, 'json', {}, { logicalOpParser: false })`
+
+It's also possible to disable one particular operator or use your own convertor if you come up with a more suitable JSON schema representation by passing options like `{ logicalOpParser: { xor: convertorFun, oxor: null } }`.
+
+The signature of the `convertorFun` is `function (schema, dependency)`.  For example, the built-in `or` convertor function is:
+
+```javascript
+function (schema, dependency) {
+  schema.anyOf = _.map(dependency.peers, (peer) => {
+    return { required: [peer] }
+  })
+}
+```
+
+### OR
+
+```javascript
+// At least one of a or b or c exists.
+// Failed on { d: 1 }
+const orJoi = joi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).or('a', 'b', 'c');
+
+const orSchemaGeneral = {
+  type: 'object',
+  anyOf: [
+    { required: ['a'] }, { required: ['b'] }, { required: ['c'] }
+  ],
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+}
+```
+
+### AND
+
+```javascript
+// Either a, b, and c All NOT exists, or all of them exists
+// Failed on { a: 'hi', b: 1 }
+const andJoi = joi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).and('a', 'b', 'c');
+
+const andSchemaGeneral = {
+  type: 'object',
+  oneOf: [
+    {
+      allOf: [
+        {
+          not: { required: ['a'] }
+        },
+        {
+          not: { required: ['b'] }
+        },
+        {
+          not: { required: ['c'] }
+        }
+      ]
+    },
+    { required: ['a', 'b', 'c'] }
+  ],
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```
+
+### NAND
+
+```javascript
+// a, b, and c cannot all exist at the same time
+// Failed on { a: 'hi', b: 1, c: true }
+const nandJoi = joi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).nand('a', 'b', 'c');
+
+const nandSchemaGeneral = {
+  type: 'object',
+  not: { required: ['a', 'b', 'c'] },
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```
+
+### XOR
+
+```javascript
+// Only one of a, b and c can and must exist
+// Failed on { d: 1 } or { a: 'hi', b: 1 }
+const xorJoi = joi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).xor('a', 'b', 'c');
+
+const xorSchemaDraft7 = {
+  type: 'object',
+  if: { propertyNames: { enum: ['a', 'b', 'c'] }, minProperties: 2 },
+  then: false,
+  else: {
+    oneOf: [
+      {
+        required: ['a']
+      },
+      {
+        required: ['b']
+      },
+      {
+        required: ['c']
+      }
+    ]
+  },
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```
+
+### OXOR
+
+```javascript
+// Only one of a, b and c can exist but none is required
+// Failed on { a: 'hi', b: 1 }
+const oxorJoi = joi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).oxor('a', 'b', 'c');
+
+const oxorSchemaGeneral = {
+  type: 'object',
+  oneOf: [
+    { required: ['a'] },
+    { required: ['b'] },
+    { required: ['c'] },
+    {
+      not: {
+        oneOf: [
+          { required: ['a'] },
+          { required: ['b'] },
+          { required: ['c'] },
+          { required: ['a', 'b'] },
+          { required: ['a', 'c'] },
+          { required: ['b', 'c'] } // Combination up to 2 elements
+        ]
+      }
+    }
+  ],
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```
+
+### WITH
+
+```javascript
+// With d exists, both a and b must exist
+// Failed on { d: 1, a: '' }
+const withJoi = jjoi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).with('c', ['a']).with('d', ['a', 'b']);
+
+const withSchemaBeforeBefore2019 = {
+  type: 'object',
+  dependencies: {
+    c: ['a'],
+    d: ['a', 'b']
+  },
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+
+const withSchemaBeforeDraft2019 = {
+  type: 'object',
+  dependentRequired: {
+    c: ['a'],
+    d: ['a', 'b']
+  },
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```
+
+### WITHOUT
+
+```javascript
+// With a exists, either b or c must not exist
+// Failed on { a: '', b: 1 }
+const withoutJoi = jjoi.object({
+  a: joi.string(),
+  b: joi.number(),
+  c: joi.boolean(),
+  d: joi.number()
+}).without('a', ['b', 'c']);
+
+const withoutSchemaDraft7 = {
+  type: 'object',
+  if: { required: ['a'] },
+  then: {
+    not: {
+      anyOf: [{ required: ['b'] }, { required: ['c'] }]
+    }
+  },
+  properties: { a: { type: 'string' }, b: { type: 'number' }, c: { type: 'boolean' }, d: { type: 'number' } },
+  additionalProperties: false
+};
+```

package/index.js

@@ -1,65 +1,65 @@
-const cmp = require('semver-compare')
-
-const c17 = require('./lib/convertors/v17')
-const c16 = require('./lib/convertors/v16')
-const c15 = require('./lib/convertors/v15')
-const c14 = require('./lib/convertors/v14')
-const c13 = require('./lib/convertors/v13')
-const c12 = require('./lib/convertors/v12')
-
-const JoiJsonSchemaParser = require('./lib/parsers/json')
-const JoiOpenApiSchemaParser = require('./lib/parsers/open-api')
-const JoiJsonDraftSchemaParser19 = require('./lib/parsers/json-draft-2019-09')
-const JoiJsonDraftSchemaParser = require('./lib/parsers/json-draft-04')
-
-const convertors = [
-  c17, c16, c15, c14, c13, c12
-]
-const parsers = {
-  'json-draft-2019-09': JoiJsonDraftSchemaParser19,
-  'json-draft-04': JoiJsonDraftSchemaParser,
-  json: JoiJsonSchemaParser,
-  'open-api': JoiOpenApiSchemaParser
-}
-
-function parse(joiObj, type = 'json', definitions = {}, parserOptions = {}) {
-  if (typeof joiObj.describe !== 'function') {
-    throw new Error('Not an joi object.')
-  }
-
-  let convertor
-
-  for (let i = 0; i < convertors.length; i++) {
-    const tmpConvertor = convertors[i]
-    try {
-      let version = tmpConvertor.getVersion(joiObj)
-      let result = cmp(tmpConvertor.getSupportVersion(), version)
-      if (result <= 0) {
-        // The first parser has smaller or equal version
-        convertor = tmpConvertor
-        break
-      }
-    } catch (e) {
-      // Format does not match this parser version.
-      // Skip to check the next one
-      continue
-    }
-  }
-
-  if (!convertor) {
-    console.warn('No matched joi version convertor found, using the latest version')
-    convertor = convertors[0]
-  }
-
-  // fs.writeFileSync('./joi_spec.json', JSON.stringify(joiObj.describe(), null, 2))
-  const joiBaseSpec = new convertor().toBaseSpec(joiObj.describe())
-  // fs.writeFileSync(`./internal_${convertor.getSupportVersion()}_${type}.json`, JSON.stringify(joiBaseSpec, null, 2))
-  const parser = parsers[type]
-  if (!parser) {
-    throw new Error(`No parser is registered for ${type}`)
-  }
-
-  return new parser(parserOptions).parse(joiBaseSpec, definitions)
-}
-
-module.exports = parse
+const cmp = require('semver-compare')
+
+const c17 = require('./lib/convertors/v17')
+const c16 = require('./lib/convertors/v16')
+const c15 = require('./lib/convertors/v15')
+const c14 = require('./lib/convertors/v14')
+const c13 = require('./lib/convertors/v13')
+const c12 = require('./lib/convertors/v12')
+
+const JoiJsonSchemaParser = require('./lib/parsers/json')
+const JoiOpenApiSchemaParser = require('./lib/parsers/open-api')
+const JoiJsonDraftSchemaParser19 = require('./lib/parsers/json-draft-2019-09')
+const JoiJsonDraftSchemaParser = require('./lib/parsers/json-draft-04')
+
+const convertors = [
+  c17, c16, c15, c14, c13, c12
+]
+const parsers = {
+  'json-draft-2019-09': JoiJsonDraftSchemaParser19,
+  'json-draft-04': JoiJsonDraftSchemaParser,
+  json: JoiJsonSchemaParser,
+  'open-api': JoiOpenApiSchemaParser
+}
+
+function parse(joiObj, type = 'json', definitions = {}, parserOptions = {}) {
+  if (typeof joiObj.describe !== 'function') {
+    throw new Error('Not an joi object.')
+  }
+
+  let convertor
+
+  for (let i = 0; i < convertors.length; i++) {
+    const tmpConvertor = convertors[i]
+    try {
+      let version = tmpConvertor.getVersion(joiObj)
+      let result = cmp(tmpConvertor.getSupportVersion(), version)
+      if (result <= 0) {
+        // The first parser has smaller or equal version
+        convertor = tmpConvertor
+        break
+      }
+    } catch (e) {
+      // Format does not match this parser version.
+      // Skip to check the next one
+      continue
+    }
+  }
+
+  if (!convertor) {
+    console.warn('No matched joi version convertor found, using the latest version')
+    convertor = convertors[0]
+  }
+
+  // fs.writeFileSync('./joi_spec.json', JSON.stringify(joiObj.describe(), null, 2))
+  const joiBaseSpec = new convertor().toBaseSpec(joiObj.describe())
+  // fs.writeFileSync(`./internal_${convertor.getSupportVersion()}_${type}.json`, JSON.stringify(joiBaseSpec, null, 2))
+  const parser = parsers[type]
+  if (!parser) {
+    throw new Error(`No parser is registered for ${type}`)
+  }
+
+  return new parser(parserOptions).parse(joiBaseSpec, definitions)
+}
+
+module.exports = parse