@vida-global/core 1.3.1 → 1.3.3

package/lib/server/serverController.js

@@ -7,14 +7,16 @@ const{ AuthorizationError,
        ValidationError }         = require('./errors');
 
 
+const AUTH_CALLBACK_NAME = 'authenticateRequest';
+
+
 class VidaServerController {
     #afterCallbacks  = [];
     #beforeCallbacks = [];
+    #callbacksSetUp  = false;
     #params;
     #rendered        = false;
     #request;
-    #requestBody;
-    #requestQuery;
     #response;
 
 
@@ -24,6 +26,8 @@ class VidaServerController {
         }
         this.#request  = request;
         this.#response = response;
+
+        this.#applyCallbacks();
     }
 
 
@@ -32,15 +36,15 @@ class VidaServerController {
 
     get params()          { 
         if (!this.#params) {
-            const body   = this.#processRequestData('body');
-            const query  = this.#processRequestData('query');
-            this.#params = {...this._request.params, ...body, ...query};
+            const body   = Buffer.isBuffer(this._request.body) ? {} : this.#processRequestData('body');
+            this.#params = {...this._request.params, ...this._request.query, ...body};
         }
         return structuredClone(this.#params);
     }
 
     get requestHeaders()  { return structuredClone(this._request.headers || {}); }
     get responseHeaders() { return this._response.headers; };
+    get requestBody()     { return this._request.body; }
     get contentType()     { return this.requestHeaders['content-type']; }
     get logger()          { return logger; }
     get rendered()        { return this.#rendered }
@@ -51,23 +55,20 @@ class VidaServerController {
 
 
     #processRequestData(key) {
-        const instanceVarKey  = key.charAt(0).toUpperCase() + key.slice(1);
-        const instanceVarName = `#request${instanceVarKey}`;
-        const data            = this._request[key] || {};
-        if (this[instanceVarName] === undefined) {
-            const processedData = {};
-            this[instanceVarName] = processedData;
-            for (let [paramName, paramValue] of Object.entries(data)) {
-                processedData[paramName] = this.#processedRequestDataValue(paramValue)
-            }
+        const data          = this._request[key] || {};
+        const processedData = {};
+        for (let [paramName, paramValue] of Object.entries(data)) {
+            processedData[paramName] = this.#processedRequestDataValue(paramValue)
         }
 
-        return structuredClone(this[instanceVarName]);
+        return processedData;
     }
 
 
     #processedRequestDataValue(value) {
+      return value;
         try {
+            if (!/^\[|{/.test(value)) return value;
             return JSON.parse(value);
         } catch(err) {
             return value;
@@ -95,8 +96,6 @@ class VidaServerController {
             return;
         }
 
-        this.setupCallbacks();
-
         const responseBody = await this.#performAction(action);
 
         if (!this.rendered) {
@@ -109,6 +108,10 @@ class VidaServerController {
 
     async #performAction(action) {
         if (await this.runBeforeCallbacks(action) === false) return false;
+
+        const parameters = this.constructor.parametersForAction(action);
+        if (parameters) await this.validateParameters(parameters);
+
         const responseBody = await this[action]();
         if (await this.runAfterCallbacks(action) === false)  return false;
 
@@ -127,12 +130,17 @@ class VidaServerController {
             await this.renderNotFoundResponse(err.message);
 
         } else if (err instanceof ValidationError) {
-            await this.renderErrors(err.message, err.errors);
+            await this.renderErrors(err.message, err.fields);
 
         } else {
-            this.statusCode = 500;
-            await this.render({error: err.message});
-            if (process.env.NODE_ENV == 'development') console.log(err);
+            this._response.error = err;
+            let message;
+            if (typeof err == 'string') {
+                message = err;
+            } else {
+                message = err.message;
+            }
+            await this.renderServerErrorResponse(message);
         }
     }
 
@@ -144,7 +152,12 @@ class VidaServerController {
         if (typeof body == 'string') {
             this._response.send(body);
         } else {
-            body = await this.formatJSONBody(body, options);
+            body = await this.processJSONBody(body, options);
+
+            const  errors = body.errors || null;
+            delete body.errors;
+
+            body = this.formatJSONBody(body, errors, options);
             this._response.json(body);
         }
         this.#rendered = true;
@@ -173,42 +186,54 @@ class VidaServerController {
     }
 
 
+    async renderUnauthorizedResponse(message=null) {
+        return await this.#renderError(401, message);
+    }
+
+
+    async renderForbiddenResponse(message=null) {
+        return await this.#renderError(403, message);
+    }
+
+
     async renderNotFoundResponse(message=null) {
-        this.statusCode = 404;
-        await this.render({ message });
+        return await this.#renderError(404, message);
     }
 
 
-    async renderUnauthorizedResponse(message=null) {
-        this.statusCode = 401;
-        await this.render({ message });
+    async renderServerErrorResponse(message=null) {
+        return await this.#renderError(500, message);
     }
 
 
-    async renderForbiddenResponse(message=null) {
-        this.statusCode = 403;
-        await this.render({ message });
+    async #renderError(statusCode, message) {
+        this.statusCode = statusCode;
+        const body = {errors: {message: message || null}};
+        return await this.render(body);
     }
 
 
-    async formatJSONBody(body, options) {
-        body = await this._formatJSONBody(body, options);
+    formatJSONBody(body, errors, options) {
         if (options.standardize === false) return body;
-        return {data: body, status: this.statusText};
+
+        const response = {data: body, status: this.statusText};
+        if (errors) response.errors = errors;
+
+        return response;
     }
 
 
-    async _formatJSONBody(body, options) {
+    async processJSONBody(body, options) {
         if (body === undefined)               return null;
         if (!body || typeof body != 'object') return body;
 
         if (body.toApiResponse) {
             const formattedBody = await body.toApiResponse(options);
-            return await this._formatJSONBody(formattedBody, options);
+            return await this.processJSONBody(formattedBody, options);
 
         } else if (Array.isArray(body)) {
             for (const idx in body) {
-                body[idx] = await this._formatJSONBody(body[idx], options);
+                body[idx] = await this.processJSONBody(body[idx], options);
             }
 
         } else if (body.constructor == Date) {
@@ -216,7 +241,7 @@ class VidaServerController {
 
         } else {
             for (let [key, val] of Object.entries(body)) {
-                body[key] = await this._formatJSONBody(val, options);
+                body[key] = await this.processJSONBody(val, options);
             }
         }
 
@@ -246,17 +271,7 @@ class VidaServerController {
     * HELPERS
     ***********************************************************************************************/
     static autoLoadHelpers() {
-        try {
-            this._autoLoadHelpers()
-        } catch(err) {
-            if (err.message.includes(`Cannot find module '${this.autoLoadHelperPath}'`)) return;
-            throw err;
-        }
-    }
-
-
-    static _autoLoadHelpers() {
-        const { InstanceMethods, Accessors } = require(this.autoLoadHelperPath);
+        const { InstanceMethods, Accessors } = this._autoLoadModule(this.autoLoadHelperPath);
 
         if (InstanceMethods) Object.assign(this.prototype, InstanceMethods);
 
@@ -268,11 +283,34 @@ class VidaServerController {
     }
 
 
+    static autoLoadDocumentation() {
+        const docs = this._autoLoadModule(this.autoLoadDocumentationPath);
+        Object.assign(this, docs);
+    }
+
+
+    static _autoLoadModule(path) {
+        try {
+            return require(path);
+        } catch(err) {
+            const errorText = `Cannot find module '${path}'`;
+            if (!err.message.includes(errorText)) throw err;
+        }
+
+        return {};
+    }
+
+
     static get autoLoadHelperPath() {
         return `${process.cwd()}/lib/controllers${this.routePrefix}Controller.js`;
     }
 
 
+    static get autoLoadDocumentationPath() {
+        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller.js`;
+    }
+
+
     /***********************************************************************************************
     * CALLBACKS
     ***********************************************************************************************/
@@ -280,6 +318,13 @@ class VidaServerController {
     setupCallbacks() {}
 
 
+    #applyCallbacks() {
+        // set up the callbacks when the instance is constructed and prevent it from being called again
+        this.setupCallbacks();
+        this.setupCallbacks = undefined;
+    }
+
+
     beforeCallback(callback, options={}) {
         this.#addCallback(callback, options, this.#beforeCallbacks);
     }
@@ -340,7 +385,7 @@ class VidaServerController {
     /***********************************************************************************************
     * VALIDATIONS
     ***********************************************************************************************/
-    async validateParameters(validations) {
+    validateParameters(validations) {
         const errors = {};
         for (const [parameterName, parameterValidations] of Object.entries(validations)) {
             const parameterErrors = this.validateParameter(this.params[parameterName], parameterValidations);
@@ -353,8 +398,12 @@ class VidaServerController {
 
     validateParameter(value, parameterValidations) {
         const errors = [];
+
+        if (parameterValidations?.optional && value === undefined) return errors;
+
         for (const [validationType, validationOptions] of Object.entries(parameterValidations)) {
             const validationMethod = `validate${camelize(validationType)}`;
+            if (!this[validationMethod]) continue;
             const error = this[validationMethod](value, validationOptions);
             if (error) errors.push(error);
         }
@@ -370,10 +419,29 @@ class VidaServerController {
 
     validateIsInteger(value, options) {
         const num = parseFloat(value);
-        if (/\D/.test(value) || isNaN(num) || !Number.isInteger(num)) return 'must be an integer';
-        if (options && options.gte !== undefined) {
+        if (!/^-?\d+$/.test(value) || isNaN(num) || !Number.isInteger(num)) return 'must be an integer';
+
+        if (options?.gte !== undefined) {
             if (num < options.gte) return `must be greater than or equal to ${options.gte}`;
         }
+        if (options?.lte !== undefined) {
+            if (num > options.lte) return `must be less than or equal to ${options.lte}`;
+        }
+    }
+
+
+    validateIsString(value, options) {
+        if (typeof value !== 'string') return 'must be a string';
+
+        if (options?.length?.gte !== undefined) {
+            if (value.length < options.length.gte) return `must be greater than or equal to ${options.length.gte} characters`;
+        }
+        if (options?.length?.lte !== undefined) {
+            if (value.length > options.length.lte) return `must be fewer than or equal to ${options.length.lte} characters`;
+        }
+        if (options?.regex !== undefined) {
+            if (!options.regex.test(value)) return `must match ${options.regex}`;
+        }
     }
 
 
@@ -389,11 +457,6 @@ class VidaServerController {
     }
 
 
-    validateRegex(value, regex) {
-        if (!regex.test(value)) return `must match the pattern ${regex}`;
-    }
-
-
     validateFunction(value, fnc) {
         const error = fnc(value);
         if (error) return error;
@@ -482,7 +545,56 @@ class VidaServerController {
 
 
     static get actionRegExp() {
-        return new RegExp(/^(?<method>get|post|put|delete|patch)(?<path>[A-Z][a-zA-Z]+)$/);
+        return new RegExp(/^(?<method>get|post|put|delete|patch|head)(?<path>[A-Z][a-zA-Z]+)$/);
+    }
+
+
+    /***********************************************************************************************
+    * DOCUMENTATION
+    ***********************************************************************************************/
+    static parametersForAction(actionName) {
+        const methodName = this.parametersMethodForAction(actionName);
+        if (this[methodName]) return this[methodName]();
+        return null;
+    }
+
+
+    static parametersMethodForAction(actionName) {
+        return `parametersFor${camelize(actionName)}`;
+    }
+
+
+    static documentationForAction(actionName) {
+        const methodName = this.documentationMethodForAction(actionName);
+        if (this[methodName]) return this[methodName]();
+        return null;
+    }
+
+
+    static documentationMethodForAction(actionName) {
+        return `document${camelize(actionName)}`;
+    }
+
+
+    isAuthenticatedAction(actionName) {
+        const { options } = this.#beforeCallbacks.find(({ callback, options }) => callback == AUTH_CALLBACK_NAME)
+        return Boolean(options) && this.#shouldRunCallback(actionName, options);
+    }
+
+
+    static isAuthenticatedAction(actionName) {
+        const controller = new this();
+        return controller.isAuthenticatedAction(actionName);
+    }
+
+
+    static _authenticationDocumentation(actionName) {
+        if (!this.isAuthenticatedAction(actionName)) return undefined;
+    }
+
+
+    static authenticationDocumentation(actionName) {
+        return {apiKeyAuth: []};
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "1.3.1",
+    "version": "1.3.3",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -33,7 +33,7 @@
         "@vida-global/release": "^1.0.0"
     },
     "devDependencies": {
-        "jest": "^30.0.0",
+        "jest": "^29.0.0",
         "jest-express": "^1.12.0",
         "jest-extended": "^7.0.0",
         "@vida-global/test-helpers": "^1.0.1"

package/test/server/server.test.js

@@ -8,12 +8,14 @@ const { VidaServer }    = require('../../lib/server');
 
 
 jest.mock('express', () => {
+    const   express    = require('jest-express');
     const { Response } = require('jest-express/lib/response');
 
-    // missing functions in mock Response
-    Response.prototype.on   = jest.fn();
+    // missing functions in mock express
+    Response.prototype.on = jest.fn();
+    express.raw           = jest.fn();
 
-    return require('jest-express');
+    return express;
 });