@trojs/openapi-server 3.0.0 → 3.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@trojs/openapi-server",
     "description": "OpenAPI Server",
-    "version": "3.0.0",
+    "version": "3.1.3",
     "author": {
         "name": "Pieter Wigboldus",
         "url": "https://trojs.org/"
@@ -11,7 +11,7 @@
         "lint": "eslint",
         "lint:report": "eslint src/*.js -f json -o report.json",
         "lint:fix": "eslint --fix",
-        "test": "c8 node --test src/*.test.js",
+        "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=./coverage/lcov.info",
         "cpd": "node_modules/jscpd/bin/jscpd src",
         "vulnerabilities": "npm audit --omit=dev"
     },
@@ -33,22 +33,12 @@
     ],
     "main": "src/server.js",
     "devDependencies": {
-        "@eslint/js": "^9.15.0",
-        "@stylistic/eslint-plugin": "^2.11.0",
-        "@stylistic/eslint-plugin-js": "^2.11.0",
-        "@types/express-serve-static-core": "^4.17.41",
+        "@trojs/lint": "^0.2.9",
         "@types/node": "^22.0.0",
-        "c8": "^10.0.0",
+        "@types/express-serve-static-core": "^5.0.0",
         "eslint": "^9.15.0",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint-plugin-import": "^2.31.0",
-        "eslint-plugin-jsdoc": "^50.5.0",
-        "eslint-plugin-n": "^17.14.0",
-        "eslint-plugin-prettier": "^5.2.1",
-        "eslint-plugin-promise": "^7.1.0",
-        "eslint-plugin-sonarjs": "^2.0.4",
-        "globals": "^15.12.0",
-        "jscpd": "^4.0.0",
+        "globals": "^16.0.0",
+        "jscpd": "^4.0.5",
         "prettier": "^3.3.3",
         "supertest": "^7.0.0"
     },
@@ -65,12 +55,12 @@
         "express"
     ],
     "dependencies": {
-        "@sentry/node": "^8.0.0",
+        "@sentry/node": "^9.0.0",
         "ajv-formats": "^3.0.0",
         "body-parser": "^2.0.0",
         "compression": "^1.7.4",
         "cors": "^2.8.5",
-        "express": "^4.19.2",
+        "express": "^5.0.0",
         "helmet": "^8.0.0",
         "openapi-backend": "^5.9.2",
         "swagger-ui-express": "^5.0.0"
@@ -80,15 +70,8 @@
         "url": "https://github.com/sponsors/w3nl"
     },
     "overrides": {
-        "semver": "^7.5.3",
+        "semver@<=7.5.3": "^7.5.3",
         "send@<=0.19.0": "^0.19.0",
-        "cookie@<=0.7.0": "0.7.0",
-        "eslint-plugin-sonarjs": {
-            "eslint": "^9.15.0",
-            "@typescript-eslint/eslint-plugin": "^8.0.0",
-            "@typescript-eslint/utils": "^8.0.0",
-            "eslint-plugin-import": "^2.31.0",
-            "eslint-plugin-react-hooks": "^5.0.0"
-        }
+        "cookie@<=0.7.0": "0.7.0"
     }
-}
+}

package/src/api.js

@@ -34,72 +34,72 @@ import { setupRouter } from './router.js'
  */
 
 export class Api {
-    /**
-     * Create a new instance of the API
-     * @class
-     * @param {ApiSchema} params
-     */
-    constructor({
-        version,
-        specification,
-        controllers,
-        apiRoot,
-        strictSpecification,
-        errorDetails,
-        logger,
-        meta,
-        securityHandlers,
-        swagger,
-        apiDocs,
-        ajvOptions
-    }) {
-        this.version = version
-        this.specification = specification
-        this.controllers = controllers
-        this.apiRoot = apiRoot
-        this.strictSpecification = strictSpecification
-        this.errorDetails = errorDetails || false
-        this.logger = logger || console
-        this.meta = meta || {}
-        this.securityHandlers = securityHandlers || []
-        this.swagger = swagger ?? true
-        this.apiDocs = apiDocs ?? true
-        this.ajvOptions = ajvOptions ?? { allErrors: false }
-    }
+  /**
+   * Create a new instance of the API
+   * @class
+   * @param {ApiSchema} params
+   */
+  constructor ({
+    version,
+    specification,
+    controllers,
+    apiRoot,
+    strictSpecification,
+    errorDetails,
+    logger,
+    meta,
+    securityHandlers,
+    swagger,
+    apiDocs,
+    ajvOptions
+  }) {
+    this.version = version
+    this.specification = specification
+    this.controllers = controllers
+    this.apiRoot = apiRoot
+    this.strictSpecification = strictSpecification
+    this.errorDetails = errorDetails || false
+    this.logger = logger || console
+    this.meta = meta || {}
+    this.securityHandlers = securityHandlers || []
+    this.swagger = swagger ?? true
+    this.apiDocs = apiDocs ?? true
+    this.ajvOptions = ajvOptions ?? { allErrors: false }
+  }
 
-    setup() {
-        const router = express.Router()
+  setup () {
+    const router = express.Router()
 
-        if (this.swagger) {
-            router.use(
-                '/swagger',
-                swaggerUi.serveFiles(this.specification, {}),
-                swaggerUi.setup(this.specification)
-            )
-        }
-        if (this.apiDocs) {
-            router.get('/api-docs', (_request, response) =>
-                response.json(this.specification)
-            )
-        }
+    if (this.swagger) {
+      router.use(
+        '/swagger',
+        swaggerUi.serveFiles(this.specification, {}),
+        swaggerUi.setup(this.specification)
+      )
+    }
+    if (this.apiDocs) {
+      router.get('/api-docs', (_request, response) =>
+        response.json(this.specification)
+      )
+    }
 
-        const { api } = setupRouter({
-            openAPISpecification: this.specification,
-            controllers: this.controllers,
-            apiRoot: this.apiRoot,
-            strictSpecification: this.strictSpecification,
-            errorDetails: this.errorDetails,
-            logger: this.logger,
-            meta: this.meta,
-            securityHandlers: this.securityHandlers,
-            ajvOptions: this.ajvOptions
-        })
-        api.init()
+    const { api } = setupRouter({
+      openAPISpecification: this.specification,
+      controllers: this.controllers,
+      apiRoot: this.apiRoot,
+      strictSpecification: this.strictSpecification,
+      errorDetails: this.errorDetails,
+      logger: this.logger,
+      meta: this.meta,
+      securityHandlers: this.securityHandlers,
+      ajvOptions: this.ajvOptions
+    })
+    api.init()
 
-        router.use((request, response) =>
-            api.handleRequest(request, request, response)
-        )
+    router.use((request, response) =>
+      api.handleRequest(request, request, response)
+    )
 
-        return router
-    }
+    return router
+  }
 }

package/src/error-status.js

@@ -1,16 +1,16 @@
 const errorCodesStatus = [
-    {
-        type: TypeError,
-        status: 422
-    },
-    {
-        type: RangeError,
-        status: 404
-    },
-    {
-        type: Error,
-        status: 500
-    }
+  {
+    type: TypeError,
+    status: 422
+  },
+  {
+    type: RangeError,
+    status: 404
+  },
+  {
+    type: Error,
+    status: 500
+  }
 ]
 
 /**
@@ -20,5 +20,5 @@ const errorCodesStatus = [
  * @returns {number}
  */
 export default (error) =>
-    errorCodesStatus.find((errorCode) => error instanceof errorCode.type)
-        .status
+  errorCodesStatus.find((errorCode) => error instanceof errorCode.type)
+    .status

package/src/express-callback.js

@@ -19,8 +19,8 @@ import { parseParams } from './params.js'
  * @param {boolean=} params.mock
  * @returns {Function}
  */
-export const makeExpressCallback =
-    ({ controller, specification, errorDetails, logger, meta, mock }) =>
+export const makeExpressCallback
+    = ({ controller, specification, errorDetails, logger, meta, mock }) =>
     /**
      * Handle controller
      * @async
@@ -29,68 +29,68 @@ export const makeExpressCallback =
      * @param {Response} response
      * @returns {Promise<any>}
      */
-        async (context, request, response) => {
-            try {
-                const allParameters = {
-                    ...(context.request?.params || {}),
-                    ...(context.request?.query || {})
-                }
-                const parameters = parseParams({
-                    query: allParameters,
-                    spec: context.operation.parameters,
-                    mock
-                })
-                const url = `${request.protocol}://${request.get('Host')}${request.originalUrl}`
+      async (context, request, response) => {
+        try {
+          const allParameters = {
+            ...(context.request?.params || {}),
+            ...(context.request?.query || {})
+          }
+          const parameters = parseParams({
+            query: allParameters,
+            spec: context.operation.parameters,
+            mock
+          })
+          const url = `${request.protocol}://${request.get('Host')}${request.originalUrl}`
 
-                const responseBody = await controller({
-                    context,
-                    request,
-                    response,
-                    parameters,
-                    specification,
-                    post: request.body,
-                    url,
-                    logger,
-                    meta
-                })
-                logger.debug({
-                    url,
-                    parameters,
-                    post: request.body,
-                    response: responseBody
-                })
+          const responseBody = await controller({
+            context,
+            request,
+            response,
+            parameters,
+            specification,
+            post: request.body,
+            url,
+            logger,
+            meta
+          })
+          logger.debug({
+            url,
+            parameters,
+            post: request.body,
+            response: responseBody
+          })
 
-                return responseBody
-            } catch (error) {
-                const errorCodeStatus = getStatusByError(error)
+          return responseBody
+        } catch (error) {
+          const errorCodeStatus = getStatusByError(error)
 
-                if (errorCodeStatus >= 500) {
-                    logger.error(error)
-                } else {
-                    logger.warn(error)
-                }
+          if (errorCodeStatus >= 500) {
+            logger.error(error)
+          } else {
+            logger.warn(error)
+          }
 
-                response.status(errorCodeStatus)
+          response.status(errorCodeStatus)
 
-                if (errorDetails) {
-                    return {
-                        errors: [
-                            {
-                                message: error.message,
-                                value: error.valueOf(),
-                                type: error.constructor.name
-                            }
-                        ],
-                        status: errorCodeStatus,
-                        timestamp: new Date(),
-                        message: error.message
-                    }
-                }
-
-                return {
-                    status: errorCodeStatus,
-                    timestamp: new Date(),
-                    message: error.message
+          if (errorDetails) {
+            return {
+              errors: [
+                {
+                  message: error.message,
+                  value: error.valueOf(),
+                  type: error.constructor.name
                 }
+              ],
+              status: errorCodeStatus,
+              timestamp: new Date(),
+              message: error.message
             }
+          }
+
+          return {
+            status: errorCodeStatus,
+            timestamp: new Date(),
+            message: error.message
+          }
         }
+      }

package/src/handlers/not-found.js

@@ -1,8 +1,8 @@
 export const notFound = (_context, request, response) => {
-    response.status(404)
-    return {
-        status: 404,
-        timestamp: new Date(),
-        message: 'Not found'
-    }
+  response.status(404)
+  return {
+    status: 404,
+    timestamp: new Date(),
+    message: 'Not found'
+  }
 }

package/src/handlers/request-validation.js

@@ -1,9 +1,9 @@
 export const requestValidation = (context, request, response) => {
-    response.status(400)
-    return {
-        errors: context.validation.errors,
-        status: 400,
-        timestamp: new Date(),
-        message: 'Bad Request'
-    }
+  response.status(400)
+  return {
+    errors: context.validation.errors,
+    status: 400,
+    timestamp: new Date(),
+    message: 'Bad Request'
+  }
 }

package/src/handlers/response-validation.js

@@ -1,30 +1,30 @@
 export const responseValidation = (context, request, response) => {
-    const responseDoesntNeedValidation = response.statusCode >= 400
-    if (responseDoesntNeedValidation) {
-        return response.json(context.response)
-    }
+  const responseDoesntNeedValidation = response.statusCode >= 400
+  if (responseDoesntNeedValidation) {
+    return response.json(context.response)
+  }
 
-    const valid = context.api.validateResponse(
-        context.response,
-        context.operation
-    )
-    if (valid?.errors) {
-        return response.status(502).json({
-            errors: valid.errors,
-            status: 502,
-            timestamp: new Date(),
-            message: 'Bad response'
-        })
-    }
+  const valid = context.api.validateResponse(
+    context.response,
+    context.operation
+  )
+  if (valid?.errors) {
+    return response.status(502).json({
+      errors: valid.errors,
+      status: 502,
+      timestamp: new Date(),
+      message: 'Bad response'
+    })
+  }
 
-    if (!context.response) {
-        return response.end()
-    }
+  if (!context.response) {
+    return response.end()
+  }
 
-    const contentType = request?.headers?.accept ?? 'application/json'
-    if (contentType === 'application/json') {
-        return response.json(context.response)
-    }
+  const contentType = request?.headers?.accept ?? 'application/json'
+  if (contentType === 'application/json') {
+    return response.json(context.response)
+  }
 
-    return response.send(context.response)
+  return response.send(context.response)
 }

package/src/handlers/unauthorized.js

@@ -1,8 +1,8 @@
 export const unauthorized = async (context, request, response) => {
-    response.status(401)
-    return {
-        status: 401,
-        timestamp: new Date(),
-        message: 'Unauthorized'
-    }
+  response.status(401)
+  return {
+    status: 401,
+    timestamp: new Date(),
+    message: 'Unauthorized'
+  }
 }

package/src/openapi.js

@@ -9,7 +9,7 @@ import { readFile } from 'node:fs/promises'
  * @returns {Promise<{ openAPISpecification: object; }>}
  */
 export const openAPI = async ({ file, base = import.meta.url }) => {
-    const fileUrl = new URL(file, base)
-    const openAPISpecification = JSON.parse(await readFile(fileUrl, 'utf8'))
-    return { openAPISpecification }
+  const fileUrl = new URL(file, base)
+  const openAPISpecification = JSON.parse(await readFile(fileUrl, 'utf8'))
+  return { openAPISpecification }
 }

package/src/operation-ids.js

@@ -7,10 +7,10 @@ const operations = ['get', 'put', 'patch', 'post', 'delete']
  * @returns {string[]}
  */
 export const operationIds = ({ specification }) =>
-    Object.values(specification.paths)
-        .map((path) =>
-            Object.entries(path).map(([operation, data]) =>
-                operations.includes(operation) ? data.operationId : null
-            )
-        )
-        .flat()
+  Object.values(specification.paths)
+    .map((path) =>
+      Object.entries(path).map(([operation, data]) =>
+        operations.includes(operation) ? data.operationId : null
+      )
+    )
+    .flat()

package/src/params.js

@@ -9,41 +9,41 @@ import { types } from './types.js'
  * @returns {object}
  */
 export const parseParams = ({ query, spec, mock = false }) =>
-    spec
-        .map((parameter) => {
-            const { name, schema } = parameter
-            const {
-                type,
-                default: defaultValue,
-                example: exampleValue
-            } = schema
-            const Type = types[type]
-            const paramName = query?.[name]
+  spec
+    .map((parameter) => {
+      const { name, schema } = parameter
+      const {
+        type,
+        default: defaultValue,
+        example: exampleValue
+      } = schema
+      const Type = types[type]
+      const paramName = query?.[name]
 
-            if (!paramName && defaultValue !== undefined) {
-                return { name, value: defaultValue }
-            }
+      if (!paramName && defaultValue !== undefined) {
+        return { name, value: defaultValue }
+      }
 
-            if (!paramName && mock && exampleValue !== undefined) {
-                return { name, value: exampleValue }
-            }
+      if (!paramName && mock && exampleValue !== undefined) {
+        return { name, value: exampleValue }
+      }
 
-            if (!paramName) {
-                return undefined
-            }
+      if (!paramName) {
+        return undefined
+      }
 
-            if (Type === Boolean) {
-                return {
-                    name,
-                    value: JSON.parse(paramName.toLowerCase())
-                }
-            }
+      if (Type === Boolean) {
+        return {
+          name,
+          value: JSON.parse(paramName.toLowerCase())
+        }
+      }
 
-            const value = new Type(paramName).valueOf()
-            return { name, value }
-        })
-        .filter(Boolean)
-        .reduce((acc, { name, value }) => {
-            acc[name] = value
-            return acc
-        }, {})
+      const value = new Type(paramName).valueOf()
+      return { name, value }
+    })
+    .filter(Boolean)
+    .reduce((acc, { name, value }) => {
+      acc[name] = value
+      return acc
+    }, {})

package/src/router.js

@@ -11,6 +11,7 @@ import { unauthorized } from './handlers/unauthorized.js'
  * @typedef {import('./api.js').Logger} Logger
  * @typedef {import('./api.js').SecurityHandler} SecurityHandler
  * @typedef {import('ajv').Options} AjvOpts
+ * @typedef {import('openapi-backend').AjvCustomizer} AjvCustomizer
  */
 
 /**
@@ -25,70 +26,73 @@ import { unauthorized } from './handlers/unauthorized.js'
  * @param {object=} params.meta
  * @param {SecurityHandler[]=} params.securityHandlers
  * @param {AjvOpts=} params.ajvOptions
+ * @param {AjvCustomizer=} params.customizeAjv
  * @param {boolean=} params.mock
  * @returns {{ api: OpenAPIBackend<any>, openAPISpecification: object }}
  */
 export const setupRouter = ({
-    openAPISpecification,
-    controllers,
-    apiRoot,
-    strictSpecification,
-    errorDetails,
-    logger,
-    meta,
-    securityHandlers = [],
-    ajvOptions = {},
-    mock
+  openAPISpecification,
+  controllers,
+  apiRoot,
+  strictSpecification,
+  errorDetails,
+  logger,
+  meta,
+  securityHandlers = [],
+  ajvOptions = {},
+  customizeAjv,
+  mock
 }) => {
-    const api = new OpenAPIBackend({
-        definition: openAPISpecification,
-        apiRoot,
-        strict: strictSpecification,
-        ajvOpts: ajvOptions,
-        customizeAjv: (originalAjv) => {
-            addFormats(originalAjv)
-            return originalAjv
-        }
-    })
+  const ajvWithExtraFormats = (originalAjv) => {
+    addFormats(originalAjv)
+    return originalAjv
+  }
+  const api = new OpenAPIBackend({
+    definition: openAPISpecification,
+    apiRoot,
+    strict: strictSpecification,
+    ajvOpts: ajvOptions,
+    customizeAjv: customizeAjv || ajvWithExtraFormats
+  })
 
-    api.register({
-        unauthorizedHandler: unauthorized,
-        validationFail: requestValidation,
-        notFound,
-        postResponseHandler: responseValidation
-    })
+  api.register({
+    unauthorizedHandler: unauthorized,
+    validationFail: requestValidation,
+    notFound,
+    postResponseHandler: responseValidation
+  })
 
-    operationIds({ specification: openAPISpecification }).forEach(
-        (operationId) => {
-            if (!Object.hasOwn(controllers, operationId)) {
-                return
-            }
-            api.register(
-                operationId,
-                makeExpressCallback({
-                    controller: controllers[operationId],
-                    specification: openAPISpecification,
-                    errorDetails,
-                    logger,
-                    meta,
-                    mock
-                })
-            )
-        }
-    )
+  operationIds({ specification: openAPISpecification }).forEach(
+    (operationId) => {
+      if (!Object.hasOwn(controllers, operationId)) {
+        return
+      }
+      api.register(
+        operationId,
+        makeExpressCallback({
+          controller: controllers[operationId],
+          specification: openAPISpecification,
+          errorDetails,
+          logger,
+          meta,
+          mock
+        })
+      )
+    }
+  )
 
-    api.register('notImplemented', (context) => {
-        const { mock: mockImplementation } =
-            context.api.mockResponseForOperation(context.operation.operationId)
-        return mockImplementation
-    })
+  api.register('notImplemented', (context) => {
+    const { mock: mockImplementation }
+            = context.api.mockResponseForOperation(context.operation.operationId)
+    return mockImplementation
+  })
 
-    securityHandlers.forEach((securityHandler) => {
-        api.registerSecurityHandler(
-            securityHandler.name,
-            securityHandler.handler
-        )
-    })
+  securityHandlers.forEach((securityHandler) => {
+    api.registerSecurityHandler(
+      securityHandler.name,
+      securityHandler.handler
+    )
+  })
 
-    return { api, openAPISpecification }
+  return { api, openAPISpecification }
 }

package/src/server.js

@@ -15,13 +15,13 @@ import { Api } from './api.js'
  * @returns {{ crossOriginResourcePolicy: { policy: string, directives: object } }}
  */
 const getOriginResourcePolicy = (origin) => ({
-    crossOriginResourcePolicy: {
-        policy: origin === '*' ? 'cross-origin' : 'same-origin',
-        directives: {
-            // ...
-            'require-trusted-types-for': ["'script'"]
-        }
+  crossOriginResourcePolicy: {
+    policy: origin === '*' ? 'cross-origin' : 'same-origin',
+    directives: {
+      // ...
+      'require-trusted-types-for': ['\'script\'']
     }
+  }
 })
 
 /**
@@ -72,58 +72,58 @@ const getOriginResourcePolicy = (origin) => ({
  * @returns {Promise<{ app: Express }>}
  */
 export const setupServer = async ({
-    apis,
-    origin = '*',
-    staticFolder,
-    sentry,
-    poweredBy = 'TroJS',
-    version = '1.0.0',
-    middleware = [],
-    maximumBodySize = undefined
+  apis,
+  origin = '*',
+  staticFolder,
+  sentry,
+  poweredBy = 'TroJS',
+  version = '1.0.0',
+  middleware = [],
+  maximumBodySize = undefined
 }) => {
-    const corsOptions = {
-        origin
-    }
-
-    const app = express()
+  const corsOptions = {
+    origin
+  }
 
-    if (sentry) {
-        Sentry.init({
-            dsn: sentry.dsn,
-            tracesSampleRate: sentry.tracesSampleRate || 1.0,
-            profilesSampleRate: sentry.profilesSampleRate || 1.0,
-            integrations: sentry.integrations || [],
-            release: sentry.release
-        })
-    }
+  const app = express()
 
-    app.use(cors(corsOptions))
-    app.use(compression())
-    app.use(helmet(getOriginResourcePolicy(origin)))
-    app.use(express.json({ limit: maximumBodySize }))
-    middleware.forEach((fn) => app.use(fn))
-    app.use(bodyParser.urlencoded({ extended: false, limit: maximumBodySize }))
-    app.use((_request, response, next) => {
-        response.setHeader('X-Powered-By', poweredBy)
-        response.setHeader('X-Version', version)
-        next()
+  if (sentry) {
+    Sentry.init({
+      dsn: sentry.dsn,
+      tracesSampleRate: sentry.tracesSampleRate || 1.0,
+      profilesSampleRate: sentry.profilesSampleRate || 1.0,
+      integrations: sentry.integrations || [],
+      release: sentry.release
     })
+  }
 
-    if (staticFolder) {
-        app.use(express.static(staticFolder))
-    }
+  app.use(cors(corsOptions))
+  app.use(compression())
+  app.use(helmet(getOriginResourcePolicy(origin)))
+  app.use(express.json({ limit: maximumBodySize }))
+  middleware.forEach((fn) => app.use(fn))
+  app.use(bodyParser.urlencoded({ extended: false, limit: maximumBodySize }))
+  app.use((_request, response, next) => {
+    response.setHeader('X-Powered-By', poweredBy)
+    response.setHeader('X-Version', version)
+    next()
+  })
 
-    apis.forEach((api) => {
-        const apiRoutes = new Api(api)
-        const routes = apiRoutes.setup()
-        app.use(`/${api.version}`, routes)
-    })
+  if (staticFolder) {
+    app.use(express.static(staticFolder))
+  }
 
-    if (sentry) {
-        Sentry.setupExpressErrorHandler(app)
-    }
+  apis.forEach((api) => {
+    const apiRoutes = new Api(api)
+    const routes = apiRoutes.setup()
+    app.use(`/${api.version}`, routes)
+  })
+
+  if (sentry) {
+    Sentry.setupExpressErrorHandler(app)
+  }
 
-    return { app }
+  return { app }
 }
 
 export { openAPI, Api }

package/src/types.js

@@ -1,12 +1,12 @@
 const types = {
-    string: String,
-    array: Array,
-    object: Object,
-    number: Number,
-    integer: Number,
-    boolean: Boolean,
-    url: URL,
-    date: Date
+  string: String,
+  array: Array,
+  object: Object,
+  number: Number,
+  integer: Number,
+  boolean: Boolean,
+  url: URL,
+  date: Date
 }
 
 export { types }