@trojs/openapi-server 1.2.1 → 1.2.3

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@trojs/openapi-server",
     "description": "OpenAPI Server",
-    "version": "1.2.1",
+    "version": "1.2.3",
     "author": {
         "name": "Pieter Wigboldus",
         "url": "https://trojs.org/"
@@ -33,18 +33,24 @@
     ],
     "main": "src/server.js",
     "devDependencies": {
-        "@hckrnews/eslint-config": "^3.0.0",
+        "@hckrnews/eslint-code-quality": "^0.2.1",
+        "@hckrnews/eslint-config": "^3.1.0",
         "@types/express-serve-static-core": "^4.17.41",
         "@types/node": "^20.14.9",
         "c8": "^10.0.0",
         "eslint": "^8.23.0",
-        "eslint-config-standard": "^17.1.0",
+        "eslint-config-airbnb-base": "^15.0.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-plugin-html": "^8.1.1",
         "eslint-plugin-import": "^2.26.0",
         "eslint-plugin-jsdoc": "^48.0.0",
-        "eslint-plugin-n": "^16.0.0",
-        "eslint-plugin-promise": "^6.0.1",
+        "eslint-plugin-jsx-a11y": "^6.9.0",
+        "eslint-plugin-n": "^17.0.0",
+        "eslint-plugin-prettier": "^5.1.3",
+        "eslint-plugin-promise": "^7.0.0",
         "eslint-plugin-sonarjs": "^0.25.1",
         "jscpd": "^4.0.0",
+        "prettier": "^3.3.3",
         "supertest": "^7.0.0"
     },
     "repository": {

package/src/api.js

@@ -1,6 +1,6 @@
-import express from 'express'
-import swaggerUi from 'swagger-ui-express'
-import { setupRouter } from './router.js'
+import express from 'express';
+import swaggerUi from 'swagger-ui-express';
+import { setupRouter } from './router.js';
 
 /**
  * @typedef {import('openapi-backend').Handler} Handler
@@ -31,58 +31,78 @@ import { setupRouter } from './router.js'
 
 /**
  * Setup the server for a specific API, so every server can run multiple instances of the API, like different versions, for e.g. different clients
- * @class
  */
+
 export class Api {
-  /**
-   * @param {ApiSchema} params
-   */
-  constructor ({ version, specification, controllers, secret, apiRoot, strictSpecification, errorDetails, logger, meta, securityHandlers, swagger, apiDocs, ajvOptions }) {
-    this.version = version
-    this.specification = specification
-    this.controllers = controllers
-    this.secret = secret
-    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
+     * @constructor
+     * @param {ApiSchema} params
+     */
+    constructor({
+        version,
+        specification,
+        controllers,
+        secret,
+        apiRoot,
+        strictSpecification,
+        errorDetails,
+        logger,
+        meta,
+        securityHandlers,
+        swagger,
+        apiDocs,
+        ajvOptions,
+    }) {
+        this.version = version;
+        this.specification = specification;
+        this.controllers = controllers;
+        this.secret = secret;
+        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({
-      secret: this.secret,
-      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({
+            secret: this.secret,
+            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,17 +1,17 @@
 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,
+    },
+];
 
 /**
  * Get a http status when you send an error.
@@ -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

@@ -1,95 +1,94 @@
-import getStatusByError from './error-status.js'
-import { parseParams } from './params.js'
+import getStatusByError from './error-status.js';
+import { parseParams } from './params.js';
 
 /**
  * @typedef {import('express-serve-static-core').Request} Request
  * @typedef {import('express-serve-static-core').Response} Response
  * @typedef {import('openapi-backend').Context} Context
  * @typedef {import('./api.js').Logger} Logger
+ */
+
+/**
+ * Make an express callback for the controller
  * @param {object} params
  * @param {Function} params.controller
  * @param {object} params.specification
  * @param {boolean=} params.errorDetails
  * @param {Logger=} params.logger
  * @param {object=} params.meta
- * @returns {(context: object, request: object, response: object) => Promise<any>}
- */
-export const makeExpressCallback = ({
-  controller,
-  specification,
-  errorDetails,
-  logger,
-  meta
-}) =>
-/**
- * Handle controller
- * @async
- * @param {Context} context
- * @param {Request} request
- * @param {Response} response
- * @returns {Promise<any>}
+ * @returns {Function}
  */
-  async (context, request, response) => {
-    try {
-      const allParameters = {
-        ...(context.request?.params || {}),
-        ...(context.request?.query || {})
-      }
-      const parameters = parseParams({
-        query: allParameters,
-        spec: context.operation.parameters
-      })
-      const url = `${request.protocol}://${request.get('Host')}${request.originalUrl}`
+export const makeExpressCallback =
+    ({ controller, specification, errorDetails, logger, meta }) =>
+    /**
+     * Handle controller
+     * @async
+     * @param {Context} context
+     * @param {Request} request
+     * @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,
+            });
+            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
+            if (errorDetails) {
+                return {
+                    errors: [
+                        {
+                            message: error.message,
+                            value: error.valueOf(),
+                            type: error.constructor.name,
+                        },
+                    ],
+                    status: errorCodeStatus,
+                    timestamp: new Date(),
+                    message: error.message,
+                };
             }
-          ],
-          status: errorCodeStatus,
-          timestamp: new Date(),
-          message: error.message
-        }
-      }
 
-      return {
-        status: errorCodeStatus,
-        timestamp: new Date(),
-        message: error.message
-      }
-    }
-  }
+            return {
+                status: errorCodeStatus,
+                timestamp: new Date(),
+                message: error.message,
+            };
+        }
+    };

package/src/openapi.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises';
 
 /**
  * Get the OpenAPI specification from the file.
@@ -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

@@ -1,4 +1,4 @@
-const operations = ['get', 'put', 'patch', 'post', 'delete']
+const operations = ['get', 'put', 'patch', 'post', 'delete'];
 
 /**
  * Get all operation ID's from the specification.
@@ -6,9 +6,11 @@ const operations = ['get', 'put', 'patch', 'post', 'delete']
  * @param {object} params.specification
  * @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()
+export const operationIds = ({ specification }) =>
+    Object.values(specification.paths)
+        .map((path) =>
+            Object.entries(path).map(([operation, data]) =>
+                operations.includes(operation) ? data.operationId : null
+            )
+        )
+        .flat();

package/src/params.js

@@ -1,4 +1,4 @@
-import { types } from './types.js'
+import { types } from './types.js';
 
 /**
  * Parse params to the types defined in the spec
@@ -8,27 +8,32 @@ import { types } from './types.js'
  * @returns {object}
  */
 export const parseParams = ({ query, spec }) =>
-  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) {
-      return { name, value: defaultValue ?? exampleValue }
-    }
+            if (!paramName) {
+                return { name, value: defaultValue ?? exampleValue };
+            }
 
-    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 }
-  })
-    .reduce((acc, { name, value }) => {
-      acc[name] = value
-      return acc
-    }, {})
+            const value = new Type(paramName).valueOf();
+            return { name, value };
+        })
+        .reduce((acc, { name, value }) => {
+            acc[name] = value;
+            return acc;
+        }, {});

package/src/router.js

@@ -1,16 +1,19 @@
-import { OpenAPIBackend } from 'openapi-backend'
-import addFormats from 'ajv-formats'
-import { makeExpressCallback } from './express-callback.js'
-import { operationIds } from './operation-ids.js'
-import { notFound } from './handlers/not-found.js'
-import { requestValidation } from './handlers/request-validation.js'
-import { responseValidation } from './handlers/response-validation.js'
-import { unauthorized } from './handlers/unauthorized.js'
+import { OpenAPIBackend } from 'openapi-backend';
+import addFormats from 'ajv-formats';
+import { makeExpressCallback } from './express-callback.js';
+import { operationIds } from './operation-ids.js';
+import { notFound } from './handlers/not-found.js';
+import { requestValidation } from './handlers/request-validation.js';
+import { responseValidation } from './handlers/response-validation.js';
+import { unauthorized } from './handlers/unauthorized.js';
 
 /**
  * @typedef {import('./api.js').Logger} Logger
  * @typedef {import('./api.js').SecurityHandler} SecurityHandler
  * @typedef {import('ajv').Options} AjvOpts
+ */
+
+/**
  * Setup the router
  * @param {object} params
  * @param {string=} params.secret
@@ -23,60 +26,76 @@ import { unauthorized } from './handlers/unauthorized.js'
  * @param {object=} params.meta
  * @param {SecurityHandler[]=} params.securityHandlers
  * @param {AjvOpts=} params.ajvOptions
- * @returns {{ api, openAPISpecification: object }}
+ * @returns {{ api: OpenAPIBackend<any>, openAPISpecification: object }}
  */
-export const setupRouter = ({ secret, openAPISpecification, controllers, apiRoot, strictSpecification, errorDetails, logger, meta, securityHandlers = [], ajvOptions = {} }) => {
-  const api = new OpenAPIBackend({
-    definition: openAPISpecification,
+export const setupRouter = ({
+    secret,
+    openAPISpecification,
+    controllers,
     apiRoot,
-    strict: strictSpecification,
-    ajvOpts: ajvOptions,
-    customizeAjv: (originalAjv) => {
-      addFormats(originalAjv)
-      return originalAjv
-    }
-  })
+    strictSpecification,
+    errorDetails,
+    logger,
+    meta,
+    securityHandlers = [],
+    ajvOptions = {},
+}) => {
+    const api = new OpenAPIBackend({
+        definition: openAPISpecification,
+        apiRoot,
+        strict: strictSpecification,
+        ajvOpts: ajvOptions,
+        customizeAjv: (originalAjv) => {
+            addFormats(originalAjv);
+            return originalAjv;
+        },
+    });
 
-  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
-      })
-    )
-  })
+    operationIds({ specification: openAPISpecification }).forEach(
+        (operationId) => {
+            if (!Object.hasOwn(controllers, operationId)) {
+                return;
+            }
+            api.register(
+                operationId,
+                makeExpressCallback({
+                    controller: controllers[operationId],
+                    specification: openAPISpecification,
+                    errorDetails,
+                    logger,
+                    meta,
+                })
+            );
+        }
+    );
 
-  api.register('notImplemented', (context, request, response) => {
-    const { mock } = context.api.mockResponseForOperation(
-      context.operation.operationId
-    )
-    return mock
-  })
+    api.register('notImplemented', (context) => {
+        const { mock } = context.api.mockResponseForOperation(
+            context.operation.operationId
+        );
+        return mock;
+    });
 
-  if (secret) {
-    api.registerSecurityHandler(
-      'apiKey',
-      (context) => context.request.headers['x-api-key'] === secret
-    )
-  }
+    if (secret) {
+        api.registerSecurityHandler(
+            'apiKey',
+            (context) => context.request.headers['x-api-key'] === secret
+        );
+    }
 
-  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

@@ -1,11 +1,11 @@
-import express from 'express'
-import cors from 'cors'
-import compression from 'compression'
-import helmet from 'helmet'
-import * as Sentry from '@sentry/node'
-import bodyParser from 'body-parser'
-import { openAPI } from './openapi.js'
-import { Api } from './api.js'
+import express from 'express';
+import cors from 'cors';
+import compression from 'compression';
+import helmet from 'helmet';
+import * as Sentry from '@sentry/node';
+import bodyParser from 'body-parser';
+import { openAPI } from './openapi.js';
+import { Api } from './api.js';
 
 /**
  * Get the origin resource policy
@@ -13,14 +13,14 @@ 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'"],
+        },
+    },
+});
 
 /**
  * @typedef {import('express-serve-static-core').Request} Request
@@ -29,16 +29,23 @@ const getOriginResourcePolicy = (origin) => ({
  * @typedef {import('./api.js').ApiSchema} ApiSchema
  * @typedef {import('./api.js').Logger} Logger
  * @typedef {import('express').Express} Express
+ */
+
+/**
+ * @template {object} [T=object]
  * @typedef {object} Controller
  * @property {Context=} context
  * @property {Request=} request
  * @property {Response=} response
  * @property {object=} parameters
  * @property {object=} specification
- * @property {object=} post
+ * @property {T=} post
  * @property {string=} url
  * @property {Logger=} logger
  * @property {object=} meta
+ */
+
+/**
  * @typedef {object} SentryConfig
  * @property {string=} dsn
  * @property {number=} tracesSampleRate
@@ -59,55 +66,63 @@ const getOriginResourcePolicy = (origin) => ({
  * @param {any[]=} params.middleware
  * @returns {Promise<{ app: Express }>}
  */
-export const setupServer = async ({ apis, origin = '*', staticFolder, sentry, poweredBy = 'TroJS', version = '1.0.0', middleware = [] }) => {
-  const corsOptions = {
-    origin
-  }
+export const setupServer = async ({
+    apis,
+    origin = '*',
+    staticFolder,
+    sentry,
+    poweredBy = 'TroJS',
+    version = '1.0.0',
+    middleware = [],
+}) => {
+    const corsOptions = {
+        origin,
+    };
 
-  const app = express()
+    const app = express();
 
-  if (sentry) {
-    Sentry.init({
-      dsn: sentry.dsn,
-      integrations: [
-        new Sentry.Integrations.Http({ tracing: true }),
-        new Sentry.Integrations.Express({ app })
-      ],
-      tracesSampleRate: sentry.tracesSampleRate || 1.0,
-      profilesSampleRate: sentry.profilesSampleRate || 1.0,
-      release: sentry.release
-    })
+    if (sentry) {
+        Sentry.init({
+            dsn: sentry.dsn,
+            integrations: [
+                new Sentry.Integrations.Http({ tracing: true }),
+                new Sentry.Integrations.Express({ app }),
+            ],
+            tracesSampleRate: sentry.tracesSampleRate || 1.0,
+            profilesSampleRate: sentry.profilesSampleRate || 1.0,
+            release: sentry.release,
+        });
 
-    app.use(Sentry.Handlers.requestHandler())
-  }
+        app.use(Sentry.Handlers.requestHandler());
+    }
 
-  app.use(cors(corsOptions))
-  app.use(compression())
-  app.use(helmet(getOriginResourcePolicy(origin)))
-  app.use(express.json())
-  middleware.forEach((fn) => app.use(fn))
-  app.use(bodyParser.urlencoded({ extended: false }))
-  app.use((_request, response, next) => {
-    response.setHeader('X-Powered-By', poweredBy)
-    response.setHeader('X-Version', version)
-    next()
-  })
+    app.use(cors(corsOptions));
+    app.use(compression());
+    app.use(helmet(getOriginResourcePolicy(origin)));
+    app.use(express.json());
+    middleware.forEach((fn) => app.use(fn));
+    app.use(bodyParser.urlencoded({ extended: false }));
+    app.use((_request, response, next) => {
+        response.setHeader('X-Powered-By', poweredBy);
+        response.setHeader('X-Version', version);
+        next();
+    });
 
-  if (staticFolder) {
-    app.use(express.static(staticFolder))
-  }
+    if (staticFolder) {
+        app.use(express.static(staticFolder));
+    }
 
-  apis.forEach((api) => {
-    const apiRoutes = new Api(api)
-    const routes = apiRoutes.setup()
-    app.use(`/${api.version}`, routes)
-  })
+    apis.forEach((api) => {
+        const apiRoutes = new Api(api);
+        const routes = apiRoutes.setup();
+        app.use(`/${api.version}`, routes);
+    });
 
-  if (sentry) {
-    app.use(Sentry.Handlers.errorHandler())
-  }
+    if (sentry) {
+        app.use(Sentry.Handlers.errorHandler());
+    }
 
-  return { app }
-}
+    return { app };
+};
 
-export { openAPI, Api }
+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 }
+export { types };