@yamato-daiwa/express-extensions 1.1.2 → 1.2.0

package/Distributable/QueryParametersProcessor.js

@@ -21,7 +21,7 @@ class QueryParametersProcessor {
                     serializedQueryParameters = request.url.split("?")[1];
                 }
                 catch (error) {
-                    es_extensions_1.Logger.throwErrorAndLog({
+                    es_extensions_1.Logger.throwErrorWithFormattedMessage({
                         errorInstance: new QueryParametersProcessor.QueryParametersDeserializingError(),
                         title: QueryParametersProcessor.QueryParametersDeserializingError.localization.defaultTitle,
                         occurrenceLocation: "QueryParametersProcessor.process(propertiesSpecification, deserializer)",
@@ -31,10 +31,10 @@ class QueryParametersProcessor {
                 const deserializedQueryParameters = deserializer(serializedQueryParameters ?? "");
                 const processingResult = es_extensions_1.RawObjectDataProcessor.process(deserializedQueryParameters, {
                     nameForLogging: "DeserializedQueryParameters",
-                    subtype: es_extensions_1.RawObjectDataProcessor.ObjectSubtypes.fixedKeyAndValuePairsObject,
+                    subtype: es_extensions_1.RawObjectDataProcessor.ObjectSubtypes.fixedSchema,
                     properties: propertiesSpecification
                 });
-                if (processingResult.rawDataIsInvalid) {
+                if (processingResult.isRawDataInvalid) {
                     throw new routing_controllers_1.BadRequestError(processingResult.validationErrorsMessages.join("\n"));
                 }
                 return processingResult.processedData;

package/Distributable/RequestBody/parseAndValidateJSON_RequestBody.js

@@ -22,7 +22,7 @@ function parseAndValidateJSON_RequestBody({ requestBodySizeLimit__bytesPackageFo
                 mustOutputIf: mustLogDataAfterParsing
             });
             const requestBodyValidationAndProcessingResult = es_extensions_1.RawObjectDataProcessor.process(request.body, validationAndProcessing);
-            if (requestBodyValidationAndProcessingResult.rawDataIsInvalid) {
+            if (requestBodyValidationAndProcessingResult.isRawDataInvalid) {
                 response.
                     status(es_extensions_1.HTTP_StatusCodes.badRequest).
                     json(requestBodyValidationAndProcessingResult.validationErrorsMessages);

package/Distributable/RequestBody/validateAndProcessJSON_RequestBody.js

@@ -14,7 +14,7 @@ function validateAndProcessJSON_RequestBody(validationAndProcessing, { mustLogDa
         });
         const requestBodyProcessingResult = es_extensions_1.RawObjectDataProcessor.
             process(request.body, validationAndProcessing);
-        if (requestBodyProcessingResult.rawDataIsInvalid) {
+        if (requestBodyProcessingResult.isRawDataInvalid) {
             response.
                 status(es_extensions_1.HTTP_StatusCodes.badRequest).
                 json(requestBodyProcessingResult.validationErrorsMessages);

package/Distributable/Route.js

@@ -36,7 +36,7 @@ function Route(HTTP_Method, pathTemplate) {
                 HTTP_MethodInRoutingControllersFormat = "trace";
                 break;
             default:
-                es_extensions_1.Logger.throwErrorAndLog({
+                es_extensions_1.Logger.throwErrorWithFormattedMessage({
                     errorInstance: new es_extensions_1.InvalidParameterValueError({
                         parameterNumber: 1,
                         parameterName: "HTTP_Method",

package/Distributable/index.d.ts

@@ -1,5 +1,6 @@
 export { ExpressMiddleware } from "./ExpressMiddleware";
 export { QueryParametersProcessor } from "./QueryParametersProcessor";
+export { initializeRoutingControllersExpressHTTPS_Application } from "./initializeRoutingControllersExpressHTTPS_Application";
 export { Route } from "./Route";
 export { parseAndValidateJSON_RequestBody } from "./RequestBody/parseAndValidateJSON_RequestBody";
 export { validateAndProcessJSON_RequestBody } from "./RequestBody/validateAndProcessJSON_RequestBody";

package/Distributable/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.disposeExpressSession = exports.saveExpressSession = exports.validateAndProcessJSON_RequestBody = exports.parseAndValidateJSON_RequestBody = exports.Route = exports.QueryParametersProcessor = exports.ExpressMiddleware = void 0;
+exports.disposeExpressSession = exports.saveExpressSession = exports.validateAndProcessJSON_RequestBody = exports.parseAndValidateJSON_RequestBody = exports.Route = exports.initializeRoutingControllersExpressHTTPS_Application = exports.QueryParametersProcessor = exports.ExpressMiddleware = void 0;
 var ExpressMiddleware_1 = require("./ExpressMiddleware");
 Object.defineProperty(exports, "ExpressMiddleware", { enumerable: true, get: function () { return ExpressMiddleware_1.ExpressMiddleware; } });
 var QueryParametersProcessor_1 = require("./QueryParametersProcessor");
 Object.defineProperty(exports, "QueryParametersProcessor", { enumerable: true, get: function () { return QueryParametersProcessor_1.QueryParametersProcessor; } });
+var initializeRoutingControllersExpressHTTPS_Application_1 = require("./initializeRoutingControllersExpressHTTPS_Application");
+Object.defineProperty(exports, "initializeRoutingControllersExpressHTTPS_Application", { enumerable: true, get: function () { return initializeRoutingControllersExpressHTTPS_Application_1.initializeRoutingControllersExpressHTTPS_Application; } });
 var Route_1 = require("./Route");
 Object.defineProperty(exports, "Route", { enumerable: true, get: function () { return Route_1.Route; } });
 var parseAndValidateJSON_RequestBody_1 = require("./RequestBody/parseAndValidateJSON_RequestBody");

package/Distributable/initializeRoutingControllersExpressHTTPS_Application.d.ts

@@ -0,0 +1,25 @@
+import { type Express as ExpressApplication } from "express";
+import NodeHTTPS from "https";
+import { type RoutingControllersOptions } from "routing-controllers";
+export declare function initializeRoutingControllersExpressHTTPS_Application({ configuration: { HTTPS, routingControllers }, eventsHandlers: { onExpressApplicationCreated, onHTTPS_ServerCreated, onRoutingControllersSetupComplete, onApplicationStarted } }: Readonly<{
+    configuration: Readonly<{
+        HTTPS: Readonly<{
+            port: number;
+        } & (({
+            SSL_Key: string;
+        } | {
+            SSL_KeyFilePath__absoluteOrRelative: string;
+        }) & ({
+            SSL_Certificate: string;
+        } | {
+            SSL_CertificateFilePath__absoluteOrRelative: string;
+        }))>;
+        routingControllers: RoutingControllersOptions;
+    }>;
+    eventsHandlers: Readonly<{
+        onExpressApplicationCreated: (expressApplication: ExpressApplication) => Promise<void>;
+        onHTTPS_ServerCreated?: (HTTPS_Server: NodeHTTPS.Server, expressApplication: ExpressApplication) => Promise<void>;
+        onRoutingControllersSetupComplete?: (expressApplication: ExpressApplication) => Promise<void>;
+        onApplicationStarted?: () => Promise<void>;
+    }>;
+}>): Promise<void>;

package/Distributable/initializeRoutingControllersExpressHTTPS_Application.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeRoutingControllersExpressHTTPS_Application = initializeRoutingControllersExpressHTTPS_Application;
+const express_1 = __importDefault(require("express"));
+const https_1 = __importDefault(require("https"));
+const fs_1 = __importDefault(require("fs"));
+const es_extensions_1 = require("@yamato-daiwa/es-extensions");
+const routing_controllers_1 = require("routing-controllers");
+async function initializeRoutingControllersExpressHTTPS_Application({ configuration: { HTTPS, routingControllers }, eventsHandlers: { onExpressApplicationCreated, onHTTPS_ServerCreated, onRoutingControllersSetupComplete, onApplicationStarted } }) {
+    const expressApplication = (0, express_1.default)();
+    await onExpressApplicationCreated(expressApplication);
+    const HTTPS_Server = https_1.default.createServer({
+        key: "SSL_Key" in HTTPS ?
+            HTTPS.SSL_Key : fs_1.default.readFileSync(HTTPS.SSL_KeyFilePath__absoluteOrRelative, "utf8"),
+        cert: "SSL_Certificate" in HTTPS ?
+            HTTPS.SSL_Certificate : fs_1.default.readFileSync(HTTPS.SSL_CertificateFilePath__absoluteOrRelative, "utf8")
+    }, expressApplication);
+    await onHTTPS_ServerCreated?.(HTTPS_Server, expressApplication);
+    (0, routing_controllers_1.useExpressServer)(expressApplication, routingControllers);
+    await onRoutingControllersSetupComplete?.(expressApplication);
+    HTTPS_Server.listen(HTTPS.port, () => {
+        onApplicationStarted?.().catch(es_extensions_1.Logger.logPromiseError);
+    });
+}

package/Distributable/redirectOnNotFound.d.ts

@@ -0,0 +1,2 @@
+import type Express from "express";
+export default function redirectOnNotFound(targetRoute: string): (_request: Express.Request, response: Express.Response) => void;

package/Distributable/redirectOnNotFound.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = redirectOnNotFound;
+function redirectOnNotFound(targetRoute) {
+    return (_request, response) => {
+        if (!response.headersSent) {
+            response.redirect(targetRoute);
+        }
+    };
+}

package/README.md

@@ -21,6 +21,8 @@ Also, install the following peer dependencies if not installed yet.
 ## Functionality
 
 + [`ExpressMiddleware`](#expressmiddleware)
++ [`initializeRoutingControllersExpressHTTPS_Application`](#initializeroutingcontrollersexpresshttps_application)
++ [`redirectOnNotFound`](#redirectonnotfound)
 + [`Route`](#route)
 + [`QueryParametersProcessor`](#queryparametersprocessor)
 
@@ -93,6 +95,239 @@ export default class DebuggerMiddleware extends ExpressMiddleware {
 }
 ```
 
+### `initializeRoutingControllersExpressHTTPS_Application`
+
+Initializer of the application using **routing-controllers**, **Express** and **HTTPS protocol**.  
+
+```ts
+(
+  {
+    configuration: {
+      HTTPS,
+      routingControllers
+    },
+    eventsHandlers: {
+      onExpressApplicationCreated,
+      onHTTPS_ServerCreated,
+      onRoutingControllersSetupComplete,
+      onApplicationStarted
+    }
+  }: Readonly<{
+
+    configuration: Readonly<{
+      
+      HTTPS: Readonly<
+        { port: number; } &
+        (
+          (
+            { SSL_Key: string; } |
+            { SSL_KeyFilePath__absoluteOrRelative: string; }
+          ) &
+          (
+            { SSL_Certificate: string; } |
+            { SSL_CertificateFilePath__absoluteOrRelative: string; }
+          ) 
+        )
+      >;
+      routingControllers: RoutingControllersOptions;
+    }>;
+
+    eventsHandlers: Readonly<{
+      onExpressApplicationCreated: (expressApplication: ExpressApplication) => Promise<void>;
+      onHTTPS_ServerCreated?: (HTTPS_Server: NodeHTTPS.Server, expressApplication: ExpressApplication) => Promise<void>;
+      onRoutingControllersSetupComplete?: () => Promise<void>;
+      onApplicationStarted?: () => Promise<void>;
+    }>;
+
+  }>
+): Promise<void>
+```
+
+
+#### Background
+
+The initialization of **routing-controllers** + **Express** + **HTTPS** application 
+  [has not been documented well](https://github.com/typestack/routing-controllers/discussions/1243) 
+  and a little bit complicated:
+
+```ts
+import Express, { type Express as ExpressApplication } from "express";
+import createExpressApplication from "express";
+import { useExpressServer as supportClassSyntax } from "routing-controllers";
+
+import HTTPS from "https";
+import FileSystem from "fs";
+
+
+const expressApplication: ExpressApplication = createExpressApplication();
+
+expressApplication.get(
+  "/",
+  (_request: Express.Request, response: Express.Response): void => {
+    response.send("<h1>Hello, world!</h1>");
+  }
+);
+
+const HTTPS_Server: HTTPS.Server = HTTPS.createServer(
+  {
+    key: FileSystem.readFileSync("./SSL/key.pem"),
+    cert: FileSystem.readFileSync("./SSL/cert.pem")
+  },
+  expressApplication
+);
+
+supportClassSyntax(expressApplication);
+
+HTTPS_Server.listen(443, "127.0.0.1");
+```
+
+**initializeRoutingControllersExpressHTTPS_Application** encapsulates this complexity.
+
+
+#### Configuration
+
+##### `HTTPS` - The HTTPS Requirements
+
+<dl>
+
+  <dt><code>HTTPS</code></dt>
+  <dd>
+    <dl>
+      <dt>Type</dt>
+      <dd>String</dd>
+      <dt>Is Required</dt>
+      <dd>Yes</dd>
+      <dt>Description</dt>
+      <dd>
+        HTTPS port number will be listened.
+        Valid port number expected.
+      </dd>
+    </dl>
+  </dd>
+
+  <dt><code>SSL_Key</code></dt>
+  <dd>
+    <dl>
+      <dt>Type</dt>
+      <dd>String</dd>
+      <dt>Required If</dt>
+      <dd><code>SSL_KeyFilePath__absoluteOrRelative</code> not specified</dd>
+      <dt>Description</dt>
+      <dt>Description</dt>
+      <dd>The string which must represent the valid SSL key.</dd>
+    </dl>
+  </dd>
+
+  <dt><code>SSL_KeyFilePath__absoluteOrRelative</code></dt>
+  <dd>
+    <dl>
+      <dt>Type</dt>
+      <dd>String</dd>
+      <dt>Required If</dt>
+      <dd><code>SSL_Key</code> not specified</dd>
+      <dt>Description</dt>
+      <dd>Expected the valid path (absolute or relative) of the existing file contains the valid SSL key.</dd>
+    </dl>
+  </dd>
+
+  <dt><code>SSL_Certificate</code></dt>
+  <dd>
+    <dl>
+      <dt>Type</dt>
+      <dd>String</dd>
+      <dt>Required If</dt>
+      <dd><code>SSL_CertificateFilePath__absoluteOrRelative</code> not specified</dd>
+      <dt>Description</dt>
+      <dd>The string which must represent the valid SSL certificate.</dd>
+    </dl>
+  </dd>
+
+  <dt><code>SSL_CertificateFilePath__absoluteOrRelative</code></dt>
+  <dd>
+    <dl>
+      <dt>Type</dt>
+      <dd>String</dd>
+      <dt>Required If</dt>
+      <dd><code>SSL_Certificate</code> not specified</dd>
+      <dt>Description</dt>
+      <dd>Expected the valid path (absolute or relative) of the existing file contains the valid SSL certificate.</dd>
+    </dl>
+  </dd>
+
+</dl>
+
+
+##### `routingControllers` - The "routing-controllers" configuration
+
+Options of [routing-controllers](https://www.npmjs.com/package/routing-controllers/v/0.11.3).
+See the [TypeScript type definitions of `RoutingControllersOptions` type](https://app.unpkg.com/routing-controllers@0.11.3/files/types/RoutingControllersOptions.d.ts)
+  for reference.
+
+
+#### Events Handers
+##### `onExpressApplicationCreated`
+
+```
+(expressApplication: ExpressApplication) => Promise<void>
+```
+
+As it obviously from the function name, called when basic Express application created.
+Basically being used to use the Express plugins and middlewares.
+
++ **routing-controllers** library has not been involved yet.
++ The express application instance will be passed via parameter.
+
+
+##### `onHTTPS_ServerCreated`
+
+```
+(HTTPS_Server: NodeHTTPS.Server, expressApplication: ExpressApplication) => Promise<void>
+```
+
+As it obviously from the function name, called when the HTTPS server created.
+
++ **routing-controllers** library has not been involved yet.
++ The HTTPS server instance, and also the express application instance will be passed via parameters.
+
+
+
+##### `onRoutingControllersSetupComplete`
+
+```
+(expressApplication: ExpressApplication) => Promise<void>;
+```
+
+As it obviously from the function name, called when the **routing-controllers** functionality has been initialized.
+
+
+##### `onRoutingControllersSetupComplete`
+
+```
+() => Promise<void>
+```
+
+As it obviously from the function name, called when the application　actually started and ready to accept the HTTP
+  requests.
+Usually being called to log the application starting.
+
+
+### `redirectOnNotFound`
+
+```
+redirectOnNotFound(targetRoute: string): (_request: Express.Request, response: Express.Response) => void
+```
+
+Redirects to specified route when `response.headersSent` value is false.
+Intended to be used via `expressApplicationUse()` _after_ the initialization of **routing-controllers** application
+  complete to redirect to "Not found" page.
+
+Although with the plain Express the "Not found" page is being provided by other way, with **routing-controllers** the
+  [usual ways may not work](https://github.com/typestack/routing-controllers/discussions/1476) because of incorrectly
+  arranged routes.
+There is no official recommendation how to redirect to "Not found" page when no route matchings found so
+  `redirectOnNotFound` function may be used for such purposes. 
+
+
 ### `Route`
 
 The adapter for `Method` decorator from **routing-controllers** to `HTTP_Methods` enumeration from 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamato-daiwa/express-extensions",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Additional functionality for Express.js and also \"routing-controllers\" aimed to reduce the routine code.",
   "keywords": [
     "nodejs",
@@ -35,19 +35,20 @@
     "routing-controllers": "~0.11.0"
   },
   "dependencies": {
-    "@yamato-daiwa/es-extensions": "1.8.0-alpha.13",
+    "@yamato-daiwa/es-extensions": "1.8.0",
     "fundamental-constants": "0.8.0",
     "qs": "6.14.0"
   },
   "devDependencies": {
-    "@types/express-session": "1.18.1",
-    "@yamato-daiwa/style_guides": "0.6.8",
+    "@types/express": "5.0.3",
+    "@types/express-session": "1.18.2",
+    "@yamato-daiwa/style_guides": "0.9.0",
     "body-parser": "2.2.0",
     "express": "5.1.0",
-    "express-session": "1.18.1",
+    "express-session": "1.18.2",
     "rimraf": "6.0.1",
-    "routing-controllers": "0.11.2",
-    "typescript": "5.8.3"
+    "routing-controllers": "0.11.3",
+    "typescript": "5.9.2"
   },
   "scripts": {
     "Rebuild Distributable Without Preliminary Cleaning": "tsc",