@yamato-daiwa/express-extensions 1.0.1 → 1.1.0

package/Distributable/QueryParametersProcessor.d.ts

@@ -0,0 +1,29 @@
+import { HttpError } from "routing-controllers";
+import { RawObjectDataProcessor, type ReadonlyParsedJSON_Object } from "@yamato-daiwa/es-extensions";
+declare abstract class QueryParametersProcessor {
+    private static defaultDeserializer;
+    static setDefaultDeserializer(deserializer: QueryParametersProcessor.Deserializer): void;
+    static process<QueryParameters extends ReadonlyParsedJSON_Object>(propertiesSpecification: RawObjectDataProcessor.PropertiesSpecification, deserializer?: QueryParametersProcessor.Deserializer): (object: object, method: string, index: number) => void;
+}
+declare namespace QueryParametersProcessor {
+    type Deserializer = (serializedQueryParameters: string) => ReadonlyParsedJSON_Object;
+    class QueryParametersDeserializingError extends HttpError {
+        static readonly NAME: string;
+        static localization: QueryParametersDeserializingError.Localization;
+        args: Array<unknown>;
+        constructor(argumentsForInternalLogging?: Array<unknown>);
+        toJSON(): Readonly<{
+            type: string;
+            title: string;
+            message: string;
+            status: number;
+        }>;
+    }
+    namespace QueryParametersDeserializingError {
+        type Localization = Readonly<{
+            defaultTitle: string;
+            description: string;
+        }>;
+    }
+}
+export default QueryParametersProcessor;

package/Distributable/QueryParametersProcessor.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const routing_controllers_1 = require("routing-controllers");
+const es_extensions_1 = require("@yamato-daiwa/es-extensions");
+const qs_1 = __importDefault(require("qs"));
+class QueryParametersProcessor {
+    static setDefaultDeserializer(deserializer) {
+        QueryParametersProcessor.defaultDeserializer = deserializer;
+    }
+    static process(propertiesSpecification, deserializer = QueryParametersProcessor.defaultDeserializer) {
+        return (0, routing_controllers_1.createParamDecorator)({
+            required: true,
+            value(action) {
+                const request = action.request;
+                let serializedQueryParameters;
+                try {
+                    serializedQueryParameters = request.url.split("?")[1];
+                }
+                catch (error) {
+                    es_extensions_1.Logger.throwErrorAndLog({
+                        errorInstance: new QueryParametersProcessor.QueryParametersDeserializingError(),
+                        title: QueryParametersProcessor.QueryParametersDeserializingError.localization.defaultTitle,
+                        occurrenceLocation: "QueryParametersProcessor.process(propertiesSpecification, deserializer)",
+                        innerError: error
+                    });
+                }
+                const deserializedQueryParameters = deserializer(serializedQueryParameters ?? "");
+                const processingResult = es_extensions_1.RawObjectDataProcessor.process(deserializedQueryParameters, {
+                    nameForLogging: "DeserializedQueryParameters",
+                    subtype: es_extensions_1.RawObjectDataProcessor.ObjectSubtypes.fixedKeyAndValuePairsObject,
+                    properties: propertiesSpecification
+                });
+                if (processingResult.rawDataIsInvalid) {
+                    throw new routing_controllers_1.BadRequestError(processingResult.validationErrorsMessages.join("\n"));
+                }
+                return processingResult.processedData;
+            }
+        });
+    }
+}
+QueryParametersProcessor.defaultDeserializer = qs_1.default.parse;
+(function (QueryParametersProcessor) {
+    class QueryParametersDeserializingError extends routing_controllers_1.HttpError {
+        constructor(argumentsForInternalLogging = []) {
+            super(es_extensions_1.HTTP_StatusCodes.internalServerError);
+            Object.setPrototypeOf(this, QueryParametersDeserializingError.prototype);
+            this.name = QueryParametersDeserializingError.NAME;
+            this.message = QueryParametersDeserializingError.localization.description;
+            this.args = argumentsForInternalLogging;
+        }
+        toJSON() {
+            return {
+                type: QueryParametersDeserializingError.NAME,
+                title: QueryParametersDeserializingError.localization.defaultTitle,
+                message: this.message,
+                status: this.httpCode
+            };
+        }
+    }
+    QueryParametersDeserializingError.NAME = "QueryParametersDeserializingError";
+    QueryParametersDeserializingError.localization = {
+        defaultTitle: "Query Parameters Deserializing Failed",
+        description: "The error has occurred during deserializing of query parameters"
+    };
+    QueryParametersProcessor.QueryParametersDeserializingError = QueryParametersDeserializingError;
+})(QueryParametersProcessor || (QueryParametersProcessor = {}));
+exports.default = QueryParametersProcessor;

package/README.md

@@ -12,16 +12,17 @@ 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
++ **body-parser**: ~2.2.0
++ **express**: ~5.1.0
 + **express-session**: ~1.18.0
-+ **routing-controllers**: ~0.10.0
++ **routing-controllers**: ~0.11.0
 
 
 ## Functionality
 
 + [`ExpressMiddleware`](#expressmiddleware)
-+ [`Route`]()
++ [`Route`](#route)
++ [`QueryParametersProcessor`](#queryparametersprocessor)
 
 + Session
 
@@ -98,6 +99,142 @@ The adapter for `Method` decorator from **routing-controllers** to `HTTP_Methods
   ["fundamental-constants"](https://www.npmjs.com/package/fundamental-constants)/["@yamato-daiwa/es-extensions"](https://www.npmjs.com/package/@yamato-daiwa/es-extensions).
 
 
+### `QueryParametersProcessor`
+
+`@QueryParametersProcessor.process` is the alternative 
+  [`@QueryParams`](https://github.com/typestack/routing-controllers?tab=readme-ov-file#inject-query-parameters) from 
+  **routing-controllers**.
+In comparison with `@QueryParams`,
+
++ Has customizable deserialization (does not use pre-deserialized `request.query`)
++ Validation without additional classes via [`RawObjectDataProcessor` API](https://github.com/TokugawaTakeshi/Yamato-Daiwa-ES-Extensions/blob/master/CoreLibrary/Package/Documentation/RawObjectDataProcessor/RawObjectDataProcessor.md);
++ Possible to modify object to which query string has been deserialized as far as `RawObjectDataProcessor` supports. 
+
+
+```typescript
+import { Controller, Get, Reader } from "routing-controllers";
+import { RawObjectDataProcessor } from "@yamato-daiwa/es-extensions";
+
+
+@Controller()
+export default class UserController {
+
+  @Get("/componets/users/edtior/new")
+  @Reader("Components/UserEditor/ForNewUser/EditorForNewUser.mvc.component.hbs")
+  protected async renderUserEditorFragmentForNewUser(
+    @QueryParametersProcessor.process({
+      userType: {
+        type: String,
+        required: true,
+        allowedAlternatives: Object.values(User.Types)
+      },
+      willBeFirstAmongOnesOfSameType: {
+        preValidationModifications: [ destringifyBooleanValue ],
+        type: Boolean,
+        required: true
+      },
+      currentContOfUsersOfSameType: {
+        preValidationModifications: [ convertPotentialStringToIntegerIfPossible ],
+        type: Number,
+        numbersSet: RawObjectDataProcessor.NumbersSets.naturalNumber,
+        required: true
+      }
+    })
+    {
+      userType,
+      willBeFirstAmongOnesOfSameType,
+      currentContOfUsersOfSameType
+    }: Readonly<{
+      
+    }>
+  ): Promise<EditorForNewUserMVC_FragmentVariables> {
+    
+    console.log(userType)
+    console.log(willBeFirstAmongOnesOfSameType)
+    console.log(currentContOfUsersOfSameType)
+  
+    // ...
+    
+  }
+
+}
+```
+
+#### Query parameters deserializing
+
+To set the default deserializer, use `setDefaultDeserializer` static method of `QueryParametersProcessor`.
+
+```
+import { QueryParametersProcessor } from "@yamato-daiwa/express-extensions"; 
+import QueryString from "qs";
+
+
+QueryParametersProcessor.setDefaultDeserializer(QueryString.parse)
+```
+
+The parameter must be the functions accepts the serialized (thus the string) query parameters and return
+  JSON-compatible type.
+
+Obvious but frequently missed out: the deserializing algorithm on backend must correspond to serializing
+  algorithm on frontend.
+Well, the `QueryString.parse()` is predefined deserializer for `QueryParametersProcessor` but even you are
+  fine with this one, add above code to your application to explicitly show that you selected this serializer
+  consciously.
+
+Additionally, you can set the custom deserializer per request what is basically not recommended but inevitably
+  if development of the client part is out your control.
+
+```typescript
+import { Controller, Get, Reader } from "routing-controllers";
+import { RawObjectDataProcessor, type ReadonlyParsedJSON_Object } from "@yamato-daiwa/es-extensions";
+
+
+@Controller()
+export default class UserController {
+
+  @Get("/componets/users/edtior/new")
+  @Reader("Components/UserEditor/ForNewUser/EditorForNewUser.mvc.component.hbs")
+  protected async renderUserEditorFragmentForNewUser(
+    @QueryParametersProcessor.process(
+      {
+        userType: {
+          type: String,
+          required: true,
+          allowedAlternatives: Object.values(User.Types)
+        },
+        // ...
+      },
+      (queryString: string): ReadonlyParsedJSON_Object => {
+        // ....
+      }
+    )
+    {
+      userType,
+      willBeFirstAmongOnesOfSameType,
+      currentContOfUsersOfSameType
+    }: Readonly<{
+      
+    }>
+  ): Promise<EditorForNewUserMVC_FragmentVariables> {
+    
+    console.log(userType)
+    console.log(willBeFirstAmongOnesOfSameType)
+    console.log(currentContOfUsersOfSameType)
+  
+    // ...
+    
+  }
+
+}
+```
+
+#### `QueryParametersDeserializingError`
+
+If error will occur during query parameters deserializing, the `QueryParametersProcessor.QueryParametersDeserializingError`
+  will be thrown. 
+You can detect it via `error instanceof QueryParametersProcessor.QueryParametersDeserializingError`
+  or `error instanceof HttpError` because `QueryParametersProcessor.QueryParametersDeserializingError`
+  extended from `HttpError` of **routing-controllers**.
 
 
 ### Session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamato-daiwa/express-extensions",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Additional functionality for Express.js and also \"routing-controllers\" aimed to reduce the routine code.",
   "keywords": [
     "nodejs",
@@ -26,7 +26,7 @@
     "Distributable"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "peerDependencies": {
     "body-parser": "~2.2.0",
@@ -35,12 +35,13 @@
     "routing-controllers": "~0.11.0"
   },
   "dependencies": {
-    "@yamato-daiwa/es-extensions": "1.7.2",
-    "fundamental-constants": "0.7.0"
+    "@yamato-daiwa/es-extensions": "1.8.0-alpha.13",
+    "fundamental-constants": "0.8.0",
+    "qs": "6.14.0"
   },
   "devDependencies": {
     "@types/express-session": "1.18.1",
-    "@yamato-daiwa/style_guides": "0.6.5",
+    "@yamato-daiwa/style_guides": "0.6.8",
     "body-parser": "2.2.0",
     "express": "5.1.0",
     "express-session": "1.18.1",