@yamato-daiwa/express-extensions v0.3.0

Yamato Daiwa Express Extensions

Additional functions for express and its plugins, and also for routing-controllers.

Installation

npm i @yamato-daiwa/express-extensions -E

Also, install the following peer dependencies if not installed yet.

• body-parser: ~1.20.0
• express: ~4.21.0
• express-session: ~1.18.0
• routing-controllers: ~0.10.0

Functionality

• ExpressMiddleware

• Route

• Session

  • saveExpressSession
  • disposeExpressSession

• Request Body

  • parseAndValidateJSON_RequestBody
  • validateAndProcessJSON_RequestBody

ExpressMiddleware

The abstract class intended to be extended for the creating of Express middleware and using with @UseBefore and @UseAfter decorators. Unlike MiddlewareInterface and @Middleware() decorator of routing-controllers, has safely typed parameters.

classDiagram
  class ExpressMiddleware {
    <<abstract>>
    #handleRequest(request: Express.Request, response: Express.Response, toNextMiddleware: ToNextMiddlewareTransfer) Promise<void>
  }

The only method need to be implemented is handleRequest:

(
  request: Express.Request,
  response: Express.Response,
  toNextMiddleware: ExpressMiddleware.ToNextMiddlewareTransfer
): Promise<void>

Example

import type Express from "express";
import ExpressMiddleware from "@Incubators/routing-controllers-polyfills/ExpressMiddleware";
import { Logger } from "@yamato-daiwa/es-extensions";


export default class DebuggerMiddleware extends ExpressMiddleware {

  protected override async handleRequest(
      request: Express.Request,
      response: Express.Response,
      toNextMiddleware: ExpressMiddleware.ToNextMiddlewareTransfer
  ): Promise<void> {

    Logger.logInfo({
      title: "DebuggerMiddleware",
      description: "",
      additionalData: {
        request,
        response
      }
    });

    toNextMiddleware();
    return Promise.resolve();

  }

}

Route

The adapter for Method decorator from routing-controllers to HTTP_Methods enumeration from "fundamental-constants"/"@yamato-daiwa/es-extensions".

Session

saveExpressSession

saveExpressSession(session: Session): Promise<void>

The promisfied version of session.save(callback). The promise will reject if the callback of session.save will receive neither undefined nor null parameter.

disposeExpressSession

# === [ Overload 1 ] Must wait until completion
(session: Session, options: Readonly<{ mustWaitUntilCompletion: true; }>): Promise<void>;

# === [ Overload 2 ] Do not wait until completion
(session: Session, options: Readonly<{ mustWaitUntilCompletion: false; }>): void;

The wrapper for session.destroy(callback).

• If the second parameter has been set to { mustWaitUntilCompletion: true }, this function will return the promise which will be resolved when the disposal will successfully complete. In this case, the disposeExpressSession is the promisfied version of session.destroy(callback).

• If there is no need to wait the ending of disposal, set the second parameter to { mustWaitUntilCompletion: false } and this function will return nothing.

Request Body

parseAndValidateJSON_RequestBody

<RequestData extends ReadonlyParsedJSON>(
  settings: Readonly<{
    requestBodySizeLimit__bytesPackageFormat: string | number;
    validationAndProcessing: RawObjectDataProcessor.ObjectDataSpecification;
    mustLogDataAfterParsing?: boolean;
  }>
): ExpressMiddleware

Parses expected to be the JSON-type request body, validates it by RawObjectDataProcessor and, if demanded, modifying it by same util. The alternative to class-transformer which is transforming the request body to the instances of classes for the cases when there is no need to turn the objects to the instances of the classes.

• Requirements
  1. body-parser has not been applied neither globally nor locally, by other words, the request body has not been parsed yet.
  2. The class-transformer is disabled by useExpressServer({ classTransformer: false }) where the useExpressServer is the function from routing-controllers
• Intended to be used as one of parameters of routing-controllers middleware.

validateAndProcessJSON_RequestBody

<RequestData extends ReadonlyParsedJSON>(
  validationAndProcessing: RawObjectDataProcessor.ObjectDataSpecification,
  { mustLogDataAfterParsing = false }: Readonly<{ mustLogDataAfterParsing?: boolean; }> = { mustLogDataAfterParsing: false }
): ExpressMiddleware

Validates the pre-parsed JSON body by RawObjectDataProcessor and, if demanded, modifying it by same util. The alternative to class-transformer which is transforming the request body to the instances of classes for the cases when there is no need to turn the objects to the instances of the classes.

• Requirements
  1. The JSON-type request body has been preliminary parsed by body-parser.
  2. The class-transformer is disabled by useExpressServer({ classTransformer: false }) where the useExpressServer is the function from routing-controllers
• Intended to be used as one of parameters of routing-controllers middleware.