openapi-backend - npm Package Compare versions

Comparing version 4.2.0 to 5.0.0

backend.d.ts

 import type { Options as AjvOpts } from 'ajv';
-import { OpenAPIV3_1 } from 'openapi-types';
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { OpenAPIRouter, Request, ParsedRequest, Operation } from './router';
 import { OpenAPIValidator, ValidationResult, AjvCustomizer } from './validation';
-export declare type Document = OpenAPIV3_1.Document;
-export declare type SecurityRequirement = OpenAPIV3_1.SecurityRequirementObject;
+export declare type Document = OpenAPIV3_1.Document | OpenAPIV3.Document;
+export declare type PickVersionElement<D extends Document, V30, V31> = D extends OpenAPIV3_1.Document ? V31 : V30;
+export declare type SecurityRequirement = OpenAPIV3_1.SecurityRequirementObject | OpenAPIV3.SecurityRequirementObject;
 /**
@@ -22,6 +23,6 @@ * Security / Authorization context for requests
  */
-export interface Context {
-    api: OpenAPIBackend;
+export interface Context<D extends Document = Document> {
+    api: OpenAPIBackend<D>;
     request: ParsedRequest;
-    operation: Operation;
+    operation: Operation<D>;
     validation: ValidationResult;
@@ -50,4 +51,4 @@ security: SecurityHandlerResults;
  */
-export interface Options {
-    definition: Document | string;
+export interface Options<D extends Document = Document> {
+    definition: D | string;
     apiRoot?: string;
@@ -73,6 +74,6 @@ strict?: boolean;
  */
-export declare class OpenAPIBackend {
-    document: Document;
-    inputDocument: Document | string;
-    definition: Document;
+export declare class OpenAPIBackend<D extends Document = Document> {
+    document: D;
+    inputDocument: D | string;
+    definition: D;
     apiRoot: string;
@@ -93,4 +94,4 @@ initalized: boolean;
     };
-    router: OpenAPIRouter;
-    validator: OpenAPIValidator;
+    router: OpenAPIRouter<D>;
+    validator: OpenAPIValidator<D>;
     /**
@@ -100,3 +101,3 @@ * Creates an instance of OpenAPIBackend.
      * @param opts - constructor options
-     * @param {Document | string} opts.definition - the OpenAPI definition, file path or Document object
+     * @param {D | string} opts.definition - the OpenAPI definition, file path or Document object
      * @param {string} opts.apiRoot - the root URI of the api. all paths are matched relative to apiRoot
@@ -111,3 +112,3 @@ * @param {boolean} opts.strict - strict mode, throw errors or warn on OpenAPI spec validation errors (default: false)
      */
-    constructor(opts: Options);
+    constructor(opts: Options<D>);
     /**
@@ -133,3 +134,3 @@ * Initalizes OpenAPIBackend.
      */
-    loadDocument(): Promise<Document>;
+    loadDocument(): Promise<D>;
     /**
@@ -204,6 +205,6 @@ * Handles a request
      *
-     * @returns {Document} parsed document
+     * @returns {D} parsed document
      * @memberof OpenAPIBackend
      */
-    validateDefinition(): Document;
+    validateDefinition(): D;
     /**
@@ -214,6 +215,6 @@ * Flattens operations into a simple array of Operation objects easy to work with
      *
-     * @returns {Operation[]}
+     * @returns {Operation<D>[]}
      * @memberof OpenAPIBackend
      */
-    getOperations(): Operation[];
+    getOperations(): Operation<D>[];
     /**
@@ -225,6 +226,6 @@ * Gets a single operation based on operationId
      * @param {string} operationId
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIBackend
      */
-    getOperation(operationId: string): Operation | undefined;
+    getOperation(operationId: string): Operation<D> | undefined;
     /**
@@ -236,6 +237,6 @@ * Matches a request to an API operation (router)
      * @param {Request} req
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIBackend
      */
-    matchOperation(req: Request): Operation | undefined;
+    matchOperation(req: Request): Operation<D> | undefined;
     /**
@@ -250,7 +251,7 @@ * Validates a request and returns the result.
      * @param {Request} req - request to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @returns {ValidationStatus}
      * @memberof OpenAPIBackend
      */
-    validateRequest(req: Request, operation?: Operation | string): ValidationResult;
+    validateRequest(req: Request, operation?: Operation<D> | string): ValidationResult;
     /**
@@ -264,3 +265,3 @@ * Validates a response and returns the result.
      * @param {*} res - response to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @param {number} status
@@ -270,3 +271,3 @@ * @returns {ValidationStatus}
      */
-    validateResponse(res: any, operation: Operation | string, statusCode?: number): ValidationResult;
+    validateResponse(res: any, operation: Operation<D> | string, statusCode?: number): ValidationResult;
     /**
@@ -280,3 +281,3 @@ * Validates response headers and returns the result.
      * @param {*} headers - response to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @param {number} [opts.statusCode]
@@ -287,3 +288,3 @@ * @param {SetMatchType} [opts.setMatchType] - one of 'any', 'superset', 'subset', 'exact'
      */
-    validateResponseHeaders(headers: any, operation: Operation | string, opts?: {
+    validateResponseHeaders(headers: any, operation: Operation<D> | string, opts?: {
         statusCode?: number;
@@ -290,0 +291,0 @@ setMatchType?: SetMatchType;

backend.js

@@ -34,3 +34,3 @@ "use strict";
      * @param opts - constructor options
-     * @param {Document | string} opts.definition - the OpenAPI definition, file path or Document object
+     * @param {D | string} opts.definition - the OpenAPI definition, file path or Document object
      * @param {string} opts.apiRoot - the root URI of the api. all paths are matched relative to apiRoot
@@ -442,3 +442,3 @@ * @param {boolean} opts.strict - strict mode, throw errors or warn on OpenAPI spec validation errors (default: false)
      *
-     * @returns {Document} parsed document
+     * @returns {D} parsed document
      * @memberof OpenAPIBackend
@@ -460,3 +460,3 @@ */
      *
-     * @returns {Operation[]}
+     * @returns {Operation<D>[]}
      * @memberof OpenAPIBackend
@@ -473,3 +473,3 @@ */
      * @param {string} operationId
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIBackend
@@ -486,3 +486,3 @@ */
      * @param {Request} req
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIBackend
@@ -502,3 +502,3 @@ */
      * @param {Request} req - request to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @returns {ValidationStatus}
@@ -518,3 +518,3 @@ * @memberof OpenAPIBackend
      * @param {*} res - response to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @param {number} status
@@ -535,3 +535,3 @@ * @returns {ValidationStatus}
      * @param {*} headers - response to validate
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} [operation]
      * @param {number} [opts.statusCode]
@@ -538,0 +538,0 @@ * @param {SetMatchType} [opts.setMatchType] - one of 'any', 'superset', 'subset', 'exact'

package.json

 {
   "name": "openapi-backend",
   "description": "Build, Validate, Route, Authenticate and Mock using OpenAPI definitions. Framework-agnostic",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "author": "Viljami Kuosmanen <[e-mail]>",
@@ -44,3 +44,3 @@ "license": "MIT",
     "@apidevtools/json-schema-ref-parser": "^9.0.7",
-    "ajv": "^8.5.0",
+    "ajv": "^8.6.2",
     "bath-es5": "^3.0.3",
@@ -47,0 +47,0 @@ "cookie": "^0.4.0",

router.d.ts

@@ -1,4 +0,9 @@
-import type { OpenAPIV3_1 } from 'openapi-types';
-declare type Document = OpenAPIV3_1.Document;
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import { PickVersionElement } from './backend';
+declare type Document = OpenAPIV3_1.Document | OpenAPIV3.Document;
 /**
+ * OperationObject
+ * @typedef {(OpenAPIV3_1.OperationObject | OpenAPIV3.OperationObject)} OperationObject
+ */
+/**
  * OAS Operation Object containing the path and method so it can be placed in a flat array of operations
@@ -8,8 +13,8 @@ *
  * @interface Operation
- * @extends {OpenAPIV3_1.OperationObject}
+ * @extends {OperationObject}
  */
-export interface Operation extends OpenAPIV3_1.OperationObject {
+export declare type Operation<D extends Document = Document> = PickVersionElement<D, OpenAPIV3.OperationObject, OpenAPIV3_1.OperationObject> & {
     path: string;
     method: string;
-}
+};
 export interface Request {
@@ -44,4 +49,4 @@ method: string;
  */
-export declare class OpenAPIRouter {
-    definition: Document;
+export declare class OpenAPIRouter<D extends Document = Document> {
+    definition: D;
     apiRoot: string;
@@ -53,3 +58,3 @@ private ignoreTrailingSlashes;
      * @param opts - constructor options
-     * @param {Document} opts.definition - the OpenAPI definition, file path or Document object
+     * @param {D} opts.definition - the OpenAPI definition, file path or Document object
      * @param {string} opts.apiRoot - the root URI of the api. all paths are matched relative to apiRoot
@@ -59,3 +64,3 @@ * @memberof OpenAPIRouter
     constructor(opts: {
-        definition: Document;
+        definition: D;
         apiRoot?: string;
@@ -69,14 +74,14 @@ ignoreTrailingSlashes?: boolean;
      * @param {boolean} [strict] strict mode, throw error if operation is not found
-     * @returns {Operation }
+     * @returns {Operation<D>}
      * @memberof OpenAPIRouter
      */
-    matchOperation(req: Request): Operation | undefined;
-    matchOperation(req: Request, strict: boolean): Operation;
+    matchOperation(req: Request): Operation<D> | undefined;
+    matchOperation(req: Request, strict: boolean): Operation<D>;
     /**
      * Flattens operations into a simple array of Operation objects easy to work with
      *
-     * @returns {Operation[]}
+     * @returns {Operation<D>[]}
      * @memberof OpenAPIRouter
      */
-    getOperations(): Operation[];
+    getOperations(): Operation<D>[];
     /**
@@ -86,6 +91,6 @@ * Gets a single operation based on operationId
      * @param {string} operationId
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIRouter
      */
-    getOperation(operationId: string): Operation | undefined;
+    getOperation(operationId: string): Operation<D> | undefined;
     /**
@@ -121,7 +126,8 @@ * Normalises request:
      * @param {Request} req
+     * @param {Operation<D>} [operation]
      * @param {string} [patbh]
      * @returns {ParsedRequest}
      */
-    parseRequest(req: Request, operation?: Operation): ParsedRequest;
+    parseRequest(req: Request, operation?: Operation<D>): ParsedRequest;
 }
 export {};

router.js

@@ -19,3 +19,3 @@ "use strict";
      * @param opts - constructor options
-     * @param {Document} opts.definition - the OpenAPI definition, file path or Document object
+     * @param {D} opts.definition - the OpenAPI definition, file path or Document object
      * @param {string} opts.apiRoot - the root URI of the api. all paths are matched relative to apiRoot
@@ -86,3 +86,3 @@ * @memberof OpenAPIRouter
      *
-     * @returns {Operation[]}
+     * @returns {Operation<D>[]}
      * @memberof OpenAPIRouter
@@ -102,3 +102,4 @@ */
                     parameters: [
-                        ...(op.parameters || []),
+                        ...(op.parameters ||
+                            []),
                         ...((pathBaseObject === null || pathBaseObject === void 0 ? void 0 : pathBaseObject.parameters) || []), // path base object parameters
@@ -116,3 +117,3 @@ ],
      * @param {string} operationId
-     * @returns {Operation}
+     * @returns {Operation<D>}
      * @memberof OpenAPIRouter
@@ -176,2 +177,3 @@ */
      * @param {Request} req
+     * @param {Operation<D>} [operation]
      * @param {string} [patbh]
@@ -212,3 +214,4 @@ * @returns {ParsedRequest}
                 if (query[queryParam]) {
-                    const parameter = _.find(operation.parameters || [], {
+                    const parameter = _.find(operation.parameters ||
+                        [], {
                         name: queryParam,
@@ -215,0 +218,0 @@ in: 'query',

utils.d.ts

@@ -0,2 +1,4 @@
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { Operation } from './router';
+declare type Document = OpenAPIV3_1.Document | OpenAPIV3.Document;
 export default class OpenAPIUtils {
@@ -35,7 +37,8 @@ /**
      * @static
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {string} OperationId of the given operation
      * @memberof OpenAPIUtils
      */
-    static getOperationId(operation: Operation): string;
+    static getOperationId<D extends Document = Document>(operation: Operation<D>): string;
 }
+export {};

utils.js

@@ -72,3 +72,3 @@ "use strict";
      * @static
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {string} OperationId of the given operation
@@ -75,0 +75,0 @@ * @memberof OpenAPIUtils

validation.d.ts

 import Ajv, { Options as AjvOpts, ErrorObject, ValidateFunction } from 'ajv';
-import type { OpenAPIV3_1 } from 'openapi-types';
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { OpenAPIRouter, Request, Operation } from './router';
 import { SetMatchType } from './backend';
-declare type Document = OpenAPIV3_1.Document;
+declare type Document = OpenAPIV3_1.Document | OpenAPIV3.Document;
 /**
@@ -37,4 +37,4 @@ * The output object for validationRequest. Contains the results for validation
  */
-export declare class OpenAPIValidator {
-    definition: Document;
+export declare class OpenAPIValidator<D extends Document = Document> {
+    definition: D;
     ajvOpts: AjvOpts;
@@ -55,3 +55,3 @@ lazyCompileValidators: boolean;
     };
-    router: OpenAPIRouter;
+    router: OpenAPIRouter<D>;
     /**
@@ -68,5 +68,5 @@ * Creates an instance of OpenAPIValidation
     constructor(opts: {
-        definition: Document;
+        definition: D;
         ajvOpts?: AjvOpts;
-        router?: OpenAPIRouter;
+        router?: OpenAPIRouter<D>;
         lazyCompileValidators?: boolean;
@@ -100,7 +100,7 @@ customizeAjv?: AjvCustomizer;
      * @param {Request} req - request to validate
-     * @param {(Operation | string)} operation - operation to validate against
+     * @param {(Operation<D> | string)} operation - operation to validate against
      * @returns {ValidationResult}
      * @memberof OpenAPIRequestValidator
      */
-    validateRequest(req: Request, operation?: Operation | string): ValidationResult;
+    validateRequest(req: Request, operation?: Operation<D> | string): ValidationResult;
     /**
@@ -110,3 +110,3 @@ * Validates a response against a prebuilt Ajv validator and returns the result
      * @param {*} res
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} operation
      * @package {number} [statusCode]
@@ -116,3 +116,3 @@ * @returns {ValidationResult}
      */
-    validateResponse(res: any, operation: Operation | string, statusCode?: number): ValidationResult;
+    validateResponse(res: any, operation: Operation<D> | string, statusCode?: number): ValidationResult;
     /**
@@ -122,3 +122,3 @@ * Validates response headers against a prebuilt Ajv validator and returns the result
      * @param {*} headers
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} operation
      * @param {number} [opts.statusCode]
@@ -129,3 +129,3 @@ * @param {SetMatchType} [opts.setMatchType] - one of 'any', 'superset', 'subset', 'exact'
      */
-    validateResponseHeaders(headers: any, operation: Operation | string, opts?: {
+    validateResponseHeaders(headers: any, operation: Operation<D> | string, opts?: {
         statusCode?: number;
@@ -159,7 +159,7 @@ setMatchType?: SetMatchType;
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ValidateFunction[] | null)}
      * @memberof OpenAPIValidator
      */
-    buildRequestValidatorsForOperation(operation: Operation): ValidateFunction[] | null;
+    buildRequestValidatorsForOperation(operation: Operation<D>): ValidateFunction[] | null;
     /**
@@ -176,7 +176,7 @@ * Get response validator function for an operation by operationId
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ValidateFunction | null)}
      * @memberof OpenAPIValidator
      */
-    buildResponseValidatorForOperation(operation: Operation): ValidateFunction | null;
+    buildResponseValidatorForOperation(operation: Operation<D>): ValidateFunction | null;
     /**
@@ -193,7 +193,7 @@ * Get response validator function for an operation by operationId
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(StatusBasedResponseValidatorsFunctionMap | null)}
      * @memberof OpenAPIValidator
      */
-    buildStatusBasedResponseValidatorForOperation(operation: Operation): StatusBasedResponseValidatorsFunctionMap | null;
+    buildStatusBasedResponseValidatorForOperation(operation: Operation<D>): StatusBasedResponseValidatorsFunctionMap | null;
     /**
@@ -210,7 +210,7 @@ * Get response validator function for an operation by operationId
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ResponseHeadersValidateFunctionMap | null)}
      * @memberof OpenAPIValidator
      */
-    buildResponseHeadersValidatorForOperation(operation: Operation): ResponseHeadersValidateFunctionMap | null;
+    buildResponseHeadersValidatorForOperation(operation: Operation<D>): ResponseHeadersValidateFunctionMap | null;
     /**
@@ -217,0 +217,0 @@ * Get Ajv options

validation.js

@@ -139,3 +139,3 @@ "use strict";
      * @param {Request} req - request to validate
-     * @param {(Operation | string)} operation - operation to validate against
+     * @param {(Operation<D> | string)} operation - operation to validate against
      * @returns {ValidationResult}
@@ -168,3 +168,4 @@ * @memberof OpenAPIRequestValidator
                         const { schema } = operationParameter;
-                        if (schema && schema.type === 'array') {
+                        if (schema &&
+                            schema.type === 'array') {
                             query[name] = [value];
@@ -225,3 +226,3 @@ }
      * @param {*} res
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} operation
      * @package {number} [statusCode]
@@ -276,3 +277,3 @@ * @returns {ValidationResult}
      * @param {*} headers
-     * @param {(Operation | string)} [operation]
+     * @param {(Operation<D> | string)} operation
      * @param {number} [opts.statusCode]
@@ -405,3 +406,3 @@ * @param {SetMatchType} [opts.setMatchType] - one of 'any', 'superset', 'subset', 'exact'
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ValidateFunction[] | null)}
@@ -518,3 +519,3 @@ * @memberof OpenAPIValidator
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ValidateFunction | null)}
@@ -566,3 +567,3 @@ * @memberof OpenAPIValidator
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(StatusBasedResponseValidatorsFunctionMap | null)}
@@ -609,3 +610,3 @@ * @memberof OpenAPIValidator
      *
-     * @param {Operation} operation
+     * @param {Operation<D>} operation
      * @returns {*}  {(ResponseHeadersValidateFunctionMap | null)}
@@ -612,0 +613,0 @@ * @memberof OpenAPIValidator

No alert changes

Improved metrics

Total package byte prevSize

104312

0.99%

Lines of code

2247

0.63%

Dependency changes

• Updated

  ajv@^8.6.2