Merge branch 'main' of github.com:agjs/fastify-enforce-schema

Author: agjs

README.md

@@ -1,12 +1,15 @@
 # Fastify Enforce Schema
 
+[![NPM version](https://img.shields.io/npm/v/fastify-enforce-schema.svg?style=flat)](https://www.npmjs.com/package/fastify-enforce-schema)
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
+
 <p align="center">
   <img width="250" src="./assets/images/badge.png">
 </p>
 
 This plugin enables you to enforce `response`, `body` and `params` schemas on your controllers. The sentiment behind this is that no endpoint should ever be left without validation, and now you can enforce this on your application level, so no endpoints are released without the validation.
 
-The plugin works by `"hooking"` into [`onRoute hook`](https://www.fastify.io/docs/latest/Reference/Hooks/#onroute) which as described in the docs, triggers when a new route is registered.
+The plugin works by "hooking" into the [`onRoute hook`](https://www.fastify.io/docs/latest/Reference/Hooks/#onroute) which as described in the docs, triggers when a new route is registered.
 
 _This plugin is built together with our [Programmer Network](https://programmer.network/) Community. You can join us on [Twitch](https://twitch.tv/programmer_network) and [Discord](https://discord.gg/ysnpXnY7ba)._
 
@@ -22,45 +25,82 @@ Using [yarn](https://yarnpkg.com/):
 
 ## Usage
 
-```js
-import fastify from "fastify";
-import enforceSchema from "fastify-enforce-schema";
+Route definitions in Fastify (4.x) are synchronous, so you must ensure that this plugin is registered before your route definitions.
 
-const options = {
-  required: ["response", "body", "params"], // available schemas that you'd want to enforce
-  exclude: [{ url: "/api/v1/foo/:bar", excludedSchemas: ["body"] }],
-  // don't enforce body schema validation for a path /api/v1/foo/:bar
-};
+```js
+// ESM
+import Fastify from 'fastify'
+import enforceSchema from 'fastify-enforce-schema'
+
+const fastify = Fastify()
+await fastify.register(enforceSchema, { 
+  // options
+})
+```
+> _Note_: top-level await requires Node.js 14.8.0 or later
 
-fastify.register(enforceSchema, options);
+```js
+// CommonJS
+const fastify = require('fastify')()
+const enforceSchema = require('fastify-enforce-schema')
+
+fastify.register(enforceSchema, { 
+  // options
+})
+fastify.register((fastify, options, done) => {
+  // your route definitions here...
+  
+  done()
+})
+
+// Plugins are loaded when fastify.listen(), fastify.inject() or fastify.ready() are called
 ```
 
 ## Options
 
-- **required**: response, body or params
+```js
+{
+  disabled: ['response', 'body', 'params'], // can also be `true`
+  exclude: [
+    {
+      url: '/foo'
+    },
+    {
+      url: '/bar',
+      excludeSchemas: ['response'] // [..., 'body', 'params']
+    }
+  ]
+}
+```
 
-  _Note_ - The body schema will only be enforced on POST, PUT and PATCH
+<!-- - **required**: response, body or params<br /> -->
+- **disabled**: Disable specific schemas (`body`, `response`, `params`) or disable the plugin by passing `true`. <br />
 
-- **exclude**: Endpoints to exclude by the _routeOptions.path_. Each exclude is an object, with a `url` and optional, `excludeSchemas` array. If the `excludeSchemas` array is not passed, validation for all 3 schemas (`body`, `respone`, `params`) is disabled.
+- **exclude**: Endpoints to exclude by the `routeOptions.path`. Each exclude is an object with a `url` and (optional) `excludeSchemas` array. If the `excludeSchemas` array is not passed, validation for all 3 schemas (`body`, `response`, `params`) is disabled.
 
-### **Excluding specific schemas**
+By default, all schemas are enforced where appropriate.
 
-To disable schema validation for all three types (response, body, and params), you can set { schema: false }. If you only want to disable the schema for a specific type, you can do so by setting the corresponding key to false. For example, to disable schema validation for the response, you can use { response: false }.
+> _Note_: The `body` schema is only enforced on POST, PUT and PATCH routes, and the `params` schema is only enforced on routes with `:params`.
 
-```js
-await fastify.register(enforceSchema, {
-  required: ["response", "body", "params"],
-});
+### Disable schema enforcement on specific routes
 
-fastify.get("/foo", { schema: false }, (req, reply) => {
-  reply.code(200);
-});
+```js
+// Exclude all schemas
+fastify.get('/foo', { schema: false }, (req, reply) => {
+  reply.code(200)
+})
 
+// Exclude response and params schemas
 fastify.get(
-  "/bar",
-  { schema: { response: false, body: false, params: false } },
+  '/bar:baz',
+  { schema: { response: false, params: false } },
   (req, reply) => {
-    reply.code(200);
+    reply.code(200)
   }
-);
+)
+
+// Exclude body schema
+fastify.post('/baz', { schema: { body: false } }, (req, reply) => {
+  reply.code(200)
+})
 ```

index.js

@@ -1,26 +1,36 @@
 const fp = require('fastify-plugin')
 const {
-  getErrrorMessage,
+  getErrorMessage,
   hasProperties,
   initialExcludes,
   isSchemaTypeExcluded,
-  SCHEMA_TYPES
+  SCHEMA_TYPES,
+  isSchemaDisabled
 } = require('./utils')
 
 function FastifyEnforceSchema (fastify, opts, done) {
-  if (!opts) {
-    opts = {}
+  if (Object.prototype.hasOwnProperty.call(opts, 'required')) {
+    process.emitWarning(
+      'The `required` option for fastify-enforce-schema will be removed soon. Since all schemas are enforced by default, consider using the `exclude` option to exclude specific schemas.',
+      'DeprecationWarning'
+    )
+  } else {
+    opts.required = []
   }
 
-  if (!Object.prototype.hasOwnProperty.call(opts, 'required')) {
-    opts.required = []
+  if (!Object.prototype.hasOwnProperty.call(opts, 'disabled')) {
+    opts.disabled = []
+  }
+  if (opts.disabled === true || (Array.isArray(opts.disabled) && isSchemaDisabled(opts.disabled))) {
+    done()
+    return
   }
 
   if (!Object.prototype.hasOwnProperty.call(opts, 'exclude')) {
     opts.exclude = []
   }
 
-  const { required, exclude } = opts
+  const { disabled, exclude } = opts
 
   fastify.addHook('onRoute', (routeOptions) => {
     if (
@@ -46,59 +56,62 @@ function FastifyEnforceSchema (fastify, opts, done) {
     }
 
     if (!routeOptions?.schema) {
-      throw new Error(
-        `schema missing at the path ${routeOptions.method}: "${routeOptions.path}"`
-      )
+      throw new Error(getErrorMessage({ schema: true }, routeOptions))
     }
 
     if (
       routeOptions?.schema?.response !== false &&
       !isSchemaTypeExcluded(excludedEntity, SCHEMA_TYPES.response) &&
-      required.indexOf(SCHEMA_TYPES.response) !== -1
+      disabled.indexOf(SCHEMA_TYPES.response) === -1
     ) {
-      const schema = Object.keys(routeOptions?.schema?.response || [])
+      const responseKeys = Object.keys(routeOptions?.schema?.response || {})
 
       if (!routeOptions?.schema?.response) {
-        throw new Error(getErrrorMessage(SCHEMA_TYPES.response, routeOptions))
+        throw new Error(getErrorMessage({ schemaType: SCHEMA_TYPES.response }, routeOptions))
       }
 
       if (
         routeOptions?.schema?.response &&
-        !Object.keys(routeOptions?.schema?.response || []).length
+        !responseKeys.length
       ) {
-        throw new Error('No HTTP status codes provided in the response schema')
+        throw new Error(getErrorMessage({ message: 'No HTTP status codes provided in the response schema' }, routeOptions))
       }
 
-      schema.forEach((value) => {
-        if (!Number.isInteger(parseInt(value, 10))) {
-          throw new Error(
-            `"${value}" is not a number. HTTP status codes from 100 - 599 supported`
-          )
+      responseKeys.forEach((value) => {
+        if (value === 'default' || ['1xx', '2xx', '3xx', '4xx', '5xx'].includes(value) || (value >= 100 && value <= 599)) {
+          if (hasProperties(routeOptions, SCHEMA_TYPES.response, value)) {
+            done()
+            return
+          }
+
+          throw new Error(getErrorMessage({ message: `${SCHEMA_TYPES.response} key "${value}" must be a non-empty object` }, routeOptions))
         }
 
-        if (value < 100 || value > 599) {
-          throw new Error('HTTP status codes from 100 - 599 supported')
+        if (Number.isInteger(parseInt(value, 10))) {
+          throw new Error(getErrorMessage({ message: 'valid HTTP status codes range from 100 - 599' }, routeOptions))
         }
+
+        throw new Error(getErrorMessage({ message: `"${value}" is not "default" or a supported HTTP status code` }, routeOptions))
       })
     }
     if (
       routeOptions?.schema?.body !== false &&
       !isSchemaTypeExcluded(excludedEntity, SCHEMA_TYPES.body) &&
       ['POST', 'PUT', 'PATCH'].includes(routeOptions.method) &&
-      required.indexOf(SCHEMA_TYPES.body) !== -1 &&
+      disabled.indexOf(SCHEMA_TYPES.body) === -1 &&
       !hasProperties(routeOptions, SCHEMA_TYPES.body)
     ) {
-      throw new Error(getErrrorMessage(SCHEMA_TYPES.body, routeOptions))
+      throw new Error(getErrorMessage({ schemaType: SCHEMA_TYPES.body }, routeOptions))
     }
 
     if (
       routeOptions?.schema?.params !== false &&
-      new RegExp(/:\w+/).test(routeOptions.url) &&
+      /:\w+/.test(routeOptions.url) &&
       !isSchemaTypeExcluded(excludedEntity, SCHEMA_TYPES.params) &&
-      required.indexOf(SCHEMA_TYPES.params) !== -1 &&
+      disabled.indexOf(SCHEMA_TYPES.params) === -1 &&
       !hasProperties(routeOptions, SCHEMA_TYPES.params)
     ) {
-      throw new Error(getErrrorMessage(SCHEMA_TYPES.params, routeOptions))
+      throw new Error(getErrorMessage({ schemaType: SCHEMA_TYPES.params }, routeOptions))
     }
   })