add type definitions (#72)

* add type definitions

* add types

Author: cdimascio

package-lock.json

@@ -38,6 +38,7 @@
     "@types/express": "^4.17.0",
     "@types/mocha": "^5.2.7",
     "@types/morgan": "^1.7.36",
+    "@types/multer": "^1.3.10",
     "@types/node": "^11.13.18",
     "@types/supertest": "^2.0.8",
     "body-parser": "^1.19.0",
@@ -55,6 +56,6 @@
     "supertest": "^4.0.2",
     "ts-node": "^8.3.0",
     "tsc": "^1.20150623.0",
-    "typescript": "^3.5.3"
+    "typescript": "^3.6.4"
   }
 }

package.json

@@ -1,13 +1,15 @@
 import { OpenApiSpecLoader } from './openapi.spec.loader';
 import { OpenAPIFrameworkArgs } from './index';
+import { OpenAPIV3 } from './types';
 
 export class OpenApiContext {
   // TODO cleanup structure (group related functionality)
-  expressRouteMap = {};
-  openApiRouteMap = {};
-  routes = [];
-  apiDoc;
+  public readonly expressRouteMap = {};
+  public readonly openApiRouteMap = {};
+  public readonly routes = [];
+  public readonly apiDoc: OpenAPIV3.Document;
   private basePaths: Set<string>;
+
   constructor(opts: OpenAPIFrameworkArgs) {
     const openApiRouteDiscovery = new OpenApiSpecLoader(opts);
     const { apiDoc, basePaths, routes } = openApiRouteDiscovery.load();

src/framework/openapi.context.ts

@@ -1,4 +1,4 @@
-import { Request } from 'express';
+import { Request, Response, NextFunction } from 'express';
 import { Logger } from 'ts-log';
 import BasePath from './base.path';
 export {
@@ -381,6 +381,12 @@ export interface OpenApiRequest extends Request {
   openapi;
 }
 
+export type OpenApiRequestHandler = (
+  req: OpenApiRequest,
+  res: Response,
+  next: NextFunction,
+) => any;
+
 export interface IJsonSchema {
   id?: string;
   $schema?: string;
@@ -423,6 +429,17 @@ export interface IJsonSchema {
   not?: IJsonSchema;
 }
 
+export interface ValidationError {
+  message?: string;
+  status: number;
+  errors: ValidationErrorItem[];
+}
+
+export interface ValidationErrorItem {
+  path: string;
+  message: string;
+  error_code?: string;
+}
 /* istanbul ignore next */
 export class ConsoleDebugAdapterLogger implements Logger {
   /**

src/framework/types.ts

@@ -4,22 +4,18 @@ import * as fs from 'fs';
 import * as jsYaml from 'js-yaml';
 import * as path from 'path';
 
-export function assertRegExpAndSecurity(framework, tuple) {
+export function assertRegExpAndSecurity(framework, tuple): void {
   if (!Array.isArray(tuple)) {
     throw new Error(
       `${framework.name}args.pathSecurity expects an array of tuples`,
     );
   } else if (!(tuple[0] instanceof RegExp)) {
     throw new Error(
-      `${
-        framework.name
-      }args.pathSecurity tuples expect the first argument to be a RegExp`,
+      `${framework.name}args.pathSecurity tuples expect the first argument to be a RegExp`,
     );
   } else if (!Array.isArray(tuple[1])) {
     throw new Error(
-      `${
-        framework.name
-      }args.pathSecurity tuples expect the second argument to be a security Array`,
+      `${framework.name}args.pathSecurity tuples expect the second argument to be a security Array`,
     );
   }
 }

src/framework/util.ts

@@ -1,8 +1,18 @@
 import ono from 'ono';
 import * as _ from 'lodash';
-import { Application, Request } from 'express';
+import {
+  Application,
+  Request,
+  Response,
+  NextFunction,
+  RequestHandler,
+} from 'express';
 import { OpenApiContext } from './framework/openapi.context';
-import { OpenAPIV3, OpenApiRequest } from './framework/types';
+import {
+  OpenAPIV3,
+  OpenApiRequest,
+  OpenApiRequestHandler,
+} from './framework/types';
 import * as middlewares from './middlewares';
 
 export type SecurityHandlers = {
@@ -52,13 +62,22 @@ export class OpenApiValidator {
 
     // install param on routes with paths
     for (const p of _.uniq(pathParams)) {
-      app.param(p, (req: OpenApiRequest, res, next, value, name) => {
-        if (req.openapi.pathParams) {
-          // override path params
-          req.params[name] = req.openapi.pathParams[name] || req.params[name];
-        }
-        next();
-      });
+      app.param(
+        p,
+        (
+          req: OpenApiRequest,
+          res: Response,
+          next: NextFunction,
+          value: any,
+          name: string,
+        ) => {
+          if (req.openapi.pathParams) {
+            // override path params
+            req.params[name] = req.openapi.pathParams[name] || req.params[name];
+          }
+          next();
+        },
+      );
     }
 
     const { coerceTypes, unknownFormats } = this.options;
@@ -73,9 +92,8 @@ export class OpenApiValidator {
       },
     );
 
-    const requestValidatorMw = (req, res, next) => {
-      return requestValidator.validate(req, res, next);
-    };
+    const requestValidatorMw: OpenApiRequestHandler = (req, res, next) =>
+      requestValidator.validate(req, res, next);
 
     const responseValidator = new middlewares.ResponseValidator(
       this.context.apiDoc,

src/index.ts

@@ -1,16 +1,29 @@
 import * as Ajv from 'ajv';
 import * as draftSchema from 'ajv/lib/refs/json-schema-draft-04.json';
 import { formats } from './formats';
+import { OpenAPIV3 } from '../../framework/types';
 
 const TYPE_JSON = 'application/json';
 
-export function createRequestAjv(openApiSpec, options: any = {}) {
+export function createRequestAjv(
+  openApiSpec: OpenAPIV3.Document,
+  options: any = {},
+): Ajv.Ajv {
   return createAjv(openApiSpec, options);
 }
-export function createResponseAjv(openApiSpec, options: any = {}) {
+
+export function createResponseAjv(
+  openApiSpec: OpenAPIV3.Document,
+  options: any = {},
+): Ajv.Ajv {
   return createAjv(openApiSpec, options, false);
 }
-function createAjv(openApiSpec, options: any = {}, request: boolean = true) {
+
+function createAjv(
+  openApiSpec: OpenAPIV3.Document,
+  options: any = {},
+  request = true,
+): Ajv.Ajv {
   const ajv = new Ajv({
     ...options,
     schemaId: 'auto',

src/middlewares/ajv/index.ts

@@ -1,9 +1,12 @@
 import * as pathToRegexp from 'path-to-regexp';
 import * as _ from 'lodash';
 import { OpenApiContext } from '../framework/openapi.context';
+import { OpenApiRequest, OpenApiRequestHandler } from '../framework/types';
 
-export function applyOpenApiMetadata(openApiContext: OpenApiContext) {
-  return (req, res, next) => {
+export function applyOpenApiMetadata(
+  openApiContext: OpenApiContext,
+): OpenApiRequestHandler {
+  return (req, res, next): any => {
     const matched = lookupRoute(req);
 
     if (matched) {
@@ -20,7 +23,7 @@ export function applyOpenApiMetadata(openApiContext: OpenApiContext) {
     -next();
   };
 
-  function lookupRoute(req) {
+  function lookupRoute(req: OpenApiRequest) {
     const path = req.path;
     const method = req.method;
     const routeEntries = Object.entries(openApiContext.expressRouteMap);

src/middlewares/openapi.metadata.ts

@@ -1,8 +1,13 @@
 import { OpenApiContext } from '../framework/openapi.context';
 import { validationError } from './util';
-import * as multer from 'multer';
+import { Request } from 'express';
+import { OpenApiRequest, OpenApiRequestHandler } from '../framework/types';
+const multer = require('multer');
 
-export function multipart(openApiContext: OpenApiContext, multerOpts: {} = {}) {
+export function multipart(
+  OpenApiContext: OpenApiContext,
+  multerOpts: {} = {},
+): OpenApiRequestHandler {
   const mult = multer(multerOpts);
   return (req, res, next) => {
     if (isMultipart(req) && isValidContentType(req)) {
@@ -13,20 +18,22 @@ export function multipart(openApiContext: OpenApiContext, multerOpts: {} = {}) {
           // TODO:
           // If a form parameter 'file' is defined to take file value, but the user provides a string value instead
           // req.files will be empty and req.body.file will be populated with a string
-          // This will incorrectly PASS validation. 
+          // This will incorrectly PASS validation.
           // Instead, we should return a 400 with an invalid type e.g. file expects a file, but found string.
-          // 
-          // In order to support this, we likely need to inspect the schema directly to find the type. 
+          //
+          // In order to support this, we likely need to inspect the schema directly to find the type.
           // For example, if param with type: 'string', format: 'binary' is defined, we expect to see it in
           // req.files. If it's not present we should throw a 400
-          // 
+          //
           // This is a bit complex because the schema may be defined inline (easy) or via a $ref (complex) in which
           // case we must follow the $ref to check the type.
           if (req.files) {
             // add files to body
-            req.files.forEach(f => {
-              req.body[f.fieldname] = '';
-            });
+            (<Express.Multer.File[]>req.files).forEach(
+              (f: Express.Multer.File) => {
+                req.body[f.fieldname] = '';
+              },
+            );
           }
           next();
         }
@@ -37,12 +44,12 @@ export function multipart(openApiContext: OpenApiContext, multerOpts: {} = {}) {
   };
 }
 
-function isValidContentType(req) {
+function isValidContentType(req: Request): boolean {
   const contentType = req.headers['content-type'];
   return !contentType || contentType.includes('multipart/form-data');
 }
 
-function isMultipart(req) {
+function isMultipart(req: OpenApiRequest): boolean {
   return (
     req.openapi &&
     req.openapi.schema &&
@@ -52,10 +59,9 @@ function isMultipart(req) {
   );
 }
 
-function error(req, err) {
+function error(req: OpenApiRequest, err: Error) {
   if (err instanceof multer.MulterError) {
     // TODO is special handling for MulterErrors needed
-    console.error(err);
     return validationError(500, req.path, err.message);
   } else {
     // HACK
@@ -66,7 +72,6 @@ function error(req, err) {
     if (missingField) {
       return validationError(400, req.path, 'multipart file(s) required');
     } else {
-      console.error(err);
       return validationError(500, req.path, err.message);
     }
   }

src/middlewares/openapi.multipart.ts

@@ -5,21 +5,24 @@ import {
   ajvErrorsToValidatorError,
 } from './util';
 import ono from 'ono';
+import { NextFunction, Response } from 'express';
+import { OpenAPIV3, OpenApiRequest } from '../framework/types';
+import { Ajv } from 'ajv';
 
 const TYPE_JSON = 'application/json';
 
 export class RequestValidator {
   private _middlewareCache;
-  private _apiDocs;
-  private ajv;
+  private _apiDocs: OpenAPIV3.Document;
+  private ajv: Ajv;
 
-  constructor(apiDocs, options = {}) {
+  constructor(apiDocs: OpenAPIV3.Document, options = {}) {
     this._middlewareCache = {};
     this._apiDocs = apiDocs;
     this.ajv = createRequestAjv(apiDocs, options);
   }
 
-  validate(req, res, next) {
+  public validate(req: OpenApiRequest, res: Response, next: NextFunction): void {
     if (!req.openapi) {
       // this path was not found in open api and
       // this path is not defined under an openapi base path