@vida-global/core 1.2.5 → 1.3.0

package/.github/workflows/npm-test.yml

@@ -0,0 +1,24 @@
+name: npm test
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/index.js

@@ -3,7 +3,7 @@ const { AuthorizationError,
         VidaServer,
         VidaServerController }  = require('./lib/server');
 const { logger }                = require('./lib/logger');
-const   ActiveRecord            = require('./lib/active_record');
+const   ActiveRecord            = require('./lib/activeRecord');
 const { redisClientFactory }    = require('./lib/redis');
 
 

package/lib/{active_record → activeRecord}/README.md

@@ -82,9 +82,9 @@ development: {
 # Migrations
 To prepare your project to run database migrations, add the following lines to the `scripts` section of your `package.json`:
 ```
-"db:create_migration": "node node_modules/@vida-global/core/scripts/active_record/migrate.js create_migration",
-"db:migrate": "node node_modules/@vida-global/core/scripts/active_record/migrate.js migrate",
-"db:rollback": "node node_modules/@vida-global/core/scripts/active_record/migrate.js rollback"
+"db:create_migration": "node node_modules/@vida-global/core/scripts/activeRecord/migrate.js create_migration",
+"db:migrate": "node node_modules/@vida-global/core/scripts/activeRecord/migrate.js migrate",
+"db:rollback": "node node_modules/@vida-global/core/scripts/activeRecord/migrate.js rollback"
 ```
 
 To generate a new migration file, run: `npm run db:create_migration createUsers`. This will automatically generate a migration file. Your migration can create tables, create indexes, and add, remove, or update columns.

package/lib/{active_record → activeRecord}/baseRecord.js

@@ -98,7 +98,8 @@ class BaseRecord extends Model {
 
     static initializeHooks() {
         if (this.isCacheable) {
-            this.addHook('afterSave', this._afterSaveCacheHook);
+            this.addHook('afterSave',    this._afterSaveCacheHook);
+            this.addHook('afterDestroy', this._afterDestroyCacheHook);
         }
     }
 
@@ -202,7 +203,9 @@ class BaseRecord extends Model {
         }
 
         const client = await this._getRedisClient();
-        await client.mSet(toCache);
+        if (Object.keys(toCache).length) {
+            await client.mSet(toCache);
+        }
         this.debugLog('Cache Set', Object.keys(fetchedData).join(', '));
     }
 
@@ -273,6 +276,12 @@ class BaseRecord extends Model {
     }
 
 
+    static async _afterDestroyCacheHook(record, options) {
+        await record.clearSelfCache();
+        await record.updateCache(options);
+    }
+
+
     /***********************************************************************************************
     * MISC
     ***********************************************************************************************/

package/lib/http/README.md

@@ -26,7 +26,7 @@ const client = new MyApiClient(true, '123abctoken');
 const requestParameters = {baz: 1, ban: 2};
 const response = await client.get("/foo/bar", {requestParameters});
 
-const requestBody = {baz: 1, ban: 2};
-const response = await client.post("/foo/bar", {requestBody});
+const body = {baz: 1, ban: 2};
+const response = await client.post("/foo/bar", { body });
 ```
 

package/lib/server/README.md

@@ -1,37 +1,198 @@
 # VidaServer
 The `VidaServer` is a general purpose wrapper around an `express` server. It initializes standard middleware that we want running on all Vida application servers and leaves hooks for adding additional middleware on subclasses for specific use cases.
-The `VidaServer` works in conjunction with the `VidaServerController`. When a `VidaServer` begins listening, it searches its directory structure (as defined in the `controllerDirectories` getter) for subclasses of `VidaServerController`. It then creates routes based on all methods of the controller that are prefixed with `get`, `post`, `put`, `patch`, or `delete`. 
+
+## Controllers
+The `VidaServer` works in conjunction with the `VidaServerController`. When a `VidaServer` begins listening, it searches its directory structure (as defined in the `controllerDirectories` getter) for subclasses of `VidaServerController` and autoloads their paths.
+
+
+## Routing
+When a controller is auto loaded, it generates routes based on all methods of the controller that are prefixed with `get`, `post`, `put`, `patch`, or `delete`. 
 The paths for these routes are defined by the directory structure of the controller, the name of the controller, and the name of the method. For example, a method `getFoo` defined on a `BarController` in the directory `/controllers/baz`, will create the route `GET /baz/bar/foo`. “Index” will yield an empty path (e.g. `getIndex` in the previously described controller generates `GET /baz/bar`). However, the default paths can be overridden by defining the `routes` getter.
 Each controller method will have direct access to request and response variables and a logger. Calling `render` will set the response body. It accepts either a string or a JSON object.
 ```
+// defined in the /api/v2 directory
 class UsersController extends ServerController {
-    // GET /users
-    getIndex() {
-        const users = getUsers(this.query.pageNumber, this.query.pageSize);
-        this.render(users.toJson());
+
+    // GET /api/v2/users
+    getIndex() {}
+
+    // POST /api/v2/user/:id
+    postRecord() {
+        const user = User.find(this.params.id);
     }
 
-    // PUT /users/foo
-    putFoo() {
-        this.logger.info("Putting Foo");
-        this.render("hello world");
+    // PUT /api/v2/users/foo
+    putFoo() {}
+
+    // Delete /foo/bar/baz
+    deleteSomething() {}
+
+    static get routes() {
+        return {deleteSomething: '/foo/bar/baz'};
     }
+}
+```
+
+
+## Helpers 🚨IMPORTANT🚨
+Controller actions should be kept slim with most of the logic in helper files. Helper files that follow the same directory structure as the controller, but in the `/lib` directory will be auto loaded and can add instance methods and custom accessors.
+```
+// ./controllers/api/v2/fooController.js
+class FooController extends ServerController {
+    async getBar() {
+        await this.validateParameters({playerNumber: {isInteger: true}});
+        return this.doTheThing();
+    }
+}
 
-    // POST /user/:id
-    postUpdateUser() {
-        const user = getUser(this.params.id);
-        if (!user) {
-            this.status = 404;
-            this.render({error: "No user found"});
-            return;
+// ./lib/controllers/api/v2/fooController.js
+const InstanceMethods = {
+    doTheThing() {
+        const user = this.getTheThing();
+        user.name  = this.playerName;
+        return user;
+    },
+
+    getTheThing() {
+        return new User();
+    }
+}
+
+const Accessors = {
+    playerName: {
+        get() {
+            return `Player ${this.params.playerNumber}`;
         }
-        user.update(this.body.user);
-        this.render({success: true});
     }
+}
 
-    static get routes() {
-        return {postUpdateUser: '/user/:id'};
+
+module.exports = {
+    InstanceMethods,
+    Accessors
+}
+```
+
+
+## Request Properties
+Within an action, the controller has access to:
+- `this.params` includes:
+  - any parameters from the route (e.g. `/foo/:bar/:baz` would provide `this.params.bar` and `this.params.baz`)
+  - any values from a JSON formatted request body
+  - any URL query parameters
+- `this.requestHeaders` the headers sent with the request
+- `this.responseHeaders` the headers to be sent with the response (can be updated)
+- `this.contentType`
+
+
+## Rendering a response
+By default, the controller will render the value returned from the action. It recursively searches the result for any objects with a `toApiResponse` and renders that. For example...
+```
+class User {
+    toApiResponse(opts) {
+        const data = {name: this.name, email: this.email}
+        if (opts.includeTitle) data.title = this.title;
+        return data;
     }
 }
+
+async getFoo() {
+    const user1    = new User("Bruce", "bwayne@wayne-enterprises.inc");
+    const user2    = new User("Babs", "bgordon@wayne-enterprises.inc");
+    const response = {bar: 1, baz: [user1, user2]};
+    return response;
+}
+```
+...will generate the response
+```
+{data: {bar: 1,
+        baz: [
+            {name: "Bruce", email: "bwayne@wayne-enterprises.inc"},
+            {name: "Babs", email: "bgordon@wayne-enterprises.inc"],
+        ]
+}, status: "ok"}
+```
+
+Additional options can be passed to `toApiResponse` by explicitly calling `render`
+```
+await this.render(response, {includeTitle: true});
+```
+
+
+## Error handling
+There is no need to set `statusCode` directly as there are helper methods for all statuses.
+HTTP 400
+```
+await this.renderErrors("Something bad happened", {password: ['must be > 8 characters', 'must include numbers']})
+// renders {data: {errors: {message: "Soemthing bad happened", fields: {password: [...]}}}, status: "bad request"}
+
+await this.renderErrors("Something bad happened"})
+// renders {data: {errors: {message: "Soemthing bad happened"}}, status: "bad request"}
+
+await this.renderErrors({password: ['must be > 8 characters', 'must include numbers']}
+// renders {data: {errors: {fields: {password: [...]}}}, status: "bad request"}
+```
+HTTP 401
+```
+await this.renderUnauthorizedResponse("Nope")
+// renders {data: {message: "Nope"}, status: "unauthorized"}
+```
+HTTP 403
+```
+await this.renderForbiddenResponse("You shall not pass")
+// renders {data: {message: "You shall not pass"}, status: "forbidden"}
+```
+HTTP 404
+```
+await this.renderNotFoundResponse("Whoops")
+// renders {data: {message: "Whoops"}, status: "not found"}
+```
+Throwing any of `this.Errors.Authorization(msg)`, `this.Errors.Forbidden(msg)`, `this.Errors.NotFound(msg)`, `this.Errors.Validation(msg, errors)` from anywhere in the code will trigger the corresponding error handler. All other errors will generate a 500 error.
+
+
+## Callbacks
+Callbacks are methods that will run before or after an action has performed. They can be used for authentication, action setup, etc. If a callback returns false, execution is stopped and no other callbacks or the action are run.
+```
+// This will run on all actions except for getIndex and will halt execution if the environment is production (e.g. development routes)
+this.beforeCallback(() => process.env.NODE_ENV != 'production', {except: 'getIndex'});
+
+// This will run an instance method, `setUpSomeStuff` before every action
+this.beforeCallback('setUpSomeStuff');
+
+// This will run an instance method, 'cleanupRequest', after `getFoo` and `getBar`
+this.afterCallback('cleanupRequest', {only: ['getFoo', 'getBar']})
+```
+
+## Validations
+The `validateParameters` method can be called to automatically validate parameters based on given criteria. If validation fails, execution is stopped and a response is sent with a 400 code and body `{data: {errors: {field1: [errorMsg]}}, status: "bad request"}`
+```
+async getFoo() {
+    // validates that the pageSize parameter is an integer greater than or equal to one
+    await this.validateParameters({pageSize: {isInteger: true, gte: 1}});
+}
+
+async postBar() {
+    await this.validateParameters(this.barValidations);
+}
+
+get barValidations() {
+    return {
+        name: {presence: true},
+        role: {isEnum: {enums: ['CEO', 'COO', 'other']}},
+        email: {regex: /\w@\w\.com/},
+        title: {function: this.titleUniqueness}
+    }
+}
+
+titleUniqueness(title) {
+    if (User.findByTitle(title)) return 'must be unique';
+}
 ```
 
+### Supported Validations
+- `{presence: true}`
+- `{isInteger: true}`, `{isInteger: {gte: 0, lte: 100}}`
+- `{isDateTime}`
+- `{isEnum: {enums: [a, b, c]}}`
+- `{regex: /foo/}`
+- `{function: someFunction}` If the function returns a string, that is considered an error and returned as the validation message

package/lib/server/errors.js

@@ -0,0 +1,28 @@
+class ServerError extends Error {
+    #message;
+    constructor(message) {
+        super();
+        this.#message = message;
+    }
+    get message() { return this.#message; }; 
+}
+class AuthorizationError extends ServerError {}
+class ForbiddenError     extends ServerError {}
+class NotFoundError      extends ServerError {}
+class ValidationError    extends ServerError {
+    #fields;
+    constructor(message, fields) {
+        super(message);
+        this.#fields = fields;
+    }
+    get fields() { return structuredClone(this.#fields) }; 
+}
+
+
+module.exports = {
+    AuthorizationError,
+    ForbiddenError,
+    NotFoundError,
+    ServerError,
+    ValidationError
+}

package/lib/server/index.js

@@ -1,9 +1,9 @@
 const { VidaServer }           = require('./server');
-const { AuthorizationError,
-        VidaServerController } = require('./serverController');
+const { VidaServerController } = require('./serverController');
+const   ERRORS                 = require('./errors');
 
 module.exports = {
-    AuthorizationError,
+    ...ERRORS,
     VidaServer,
     VidaServerController,
 }

package/lib/server/server.js

@@ -9,6 +9,8 @@ const   IoServer               = require("socket.io")
 const { Server }               = require('http');
 const { SystemController }     = require('./systemController');
 const { AuthorizationError,
+        ForbiddenError,
+        NotFoundError,
         ValidationError,
         VidaServerController } = require('./serverController');
 
@@ -191,6 +193,7 @@ class VidaServer {
 
 
     #registerController(controllerCls) {
+        controllerCls.autoLoadHelpers();
         controllerCls.actions.forEach((action => {
             this.#registerAction(action, controllerCls)
         }).bind(this));
@@ -200,7 +203,9 @@ class VidaServer {
     #registerAction(action, controllerCls) {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
-        logger.info(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+        if (process.env.NODE_ENV != 'test') {
+            logger.info(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+        }
         this['_'+method](action.path, requestHandler);
     }
 
@@ -216,62 +221,11 @@ class VidaServer {
         return async function(request, response) {
             if (process.env.NODE_ENV != 'test') this.logger.info(`${controllerCls.name}#${action}`);
             const controllerInstance = this.buildController(controllerCls, request, response);
-            await controllerInstance.setupRequestState();
-
-            if (controllerInstance.rendered) {
-                response.end();
-                return;
-            }
-
-            controllerInstance.setupCallbacks();
-
-            const responseBody = await this.performRequest(controllerInstance, action);
-
-            if (!controllerInstance.rendered) {
-                await controllerInstance.render(responseBody || {});
-            }
-
-            response.end();
+            await controllerInstance.performRequest(action);
         }.bind(this);
     }
 
 
-    async performRequest(controllerInstance, action) {
-        try {
-            return await this._performRequest(controllerInstance, action);
-        } catch(err) {
-            await this.handleError(err, controllerInstance);
-        }
-    }
-
-
-    async handleError(err, controllerInstance) {
-        if (err.constructor == AuthorizationError) {
-            await controllerInstance.renderUnauthorizedResponse();
-            return;
-
-        } else if (err.constructor == ValidationError) {
-            await controllerInstance.renderErrors(err.errors);
-            return;
-
-        } else {
-            controllerInstance.statusCode = 500;
-            await controllerInstance.render({error: err.message});
-        }
-
-        if (process.env.NODE_ENV == 'development') console.log(err);
-    }
-
-
-    async _performRequest(controllerInstance, action) {
-        if (await controllerInstance.runBeforeCallbacks(action) === false) return false;
-        const responseBody = await controllerInstance[action]();
-        if (await controllerInstance.runAfterCallbacks(action) === false)  return false;
-
-        return responseBody;
-    }
-
-
     buildController(controllerCls, request, response) {
         return new controllerCls(request, response);
     }

package/lib/server/serverController.js

@@ -1,5 +1,10 @@
 const { logger }                 = require('../logger');
 const { camelize, singularize }  = require('inflection');
+const{ AuthorizationError,
+       ForbiddenError,
+       NotFoundError,
+       ServerError,
+       ValidationError }         = require('./errors');
 
 
 class VidaServerController {
@@ -70,6 +75,71 @@ class VidaServerController {
     }
 
 
+    /***********************************************************************************************
+    * PERFORM ACTION
+    ***********************************************************************************************/
+    async performRequest(action) {
+        try {
+            await this.#performRequest(action)
+        } catch(err) {
+            await this.#handleError(err);
+        }
+    }
+
+
+    async #performRequest(action) {
+        await this.setupRequestState();
+
+        if (this.rendered) {
+            this.#response.end();
+            return;
+        }
+
+        this.setupCallbacks();
+
+        const responseBody = await this.#performAction(action);
+
+        if (!this.rendered) {
+            await this.render(responseBody || {});
+        }
+
+        this.#response.end();
+    }
+
+
+    async #performAction(action) {
+        if (await this.runBeforeCallbacks(action) === false) return false;
+        const responseBody = await this[action]();
+        if (await this.runAfterCallbacks(action) === false)  return false;
+
+        return responseBody;
+    }
+
+
+    async #handleError(err) {
+        if (err instanceof AuthorizationError) {
+            await this.renderUnauthorizedResponse(err.message);
+
+        } else if (err instanceof ForbiddenError) {
+            await this.renderForbiddenResponse(err.message);
+
+        } else if (err instanceof NotFoundError) {
+            await this.renderNotFoundResponse(err.message);
+
+        } else if (err instanceof ValidationError) {
+            await this.renderErrors(err.message, err.errors);
+
+        } else {
+            this.statusCode = 500;
+            await this.render({error: err.message});
+            if (process.env.NODE_ENV == 'development') console.log(err);
+        }
+    }
+
+
+    /***********************************************************************************************
+    * RESPONSE RENDERING
+    ***********************************************************************************************/
     async render(body, options={}) {
         if (typeof body == 'string') {
             this._response.send(body);
@@ -81,6 +151,46 @@ class VidaServerController {
     }
 
 
+    async renderErrors(message, fields) {
+        this.statusCode = 400;
+
+        const errors = {message: null, fields: {}};
+
+        if (message && !fields && typeof message == 'object') {
+            fields  = message;
+            message = null;
+        }
+
+        if (message) errors.message = message;
+        if (fields) {
+          for (const [field, values] of Object.entries(fields)) {
+              if (!Array.isArray(values)) fields[field] = [values];
+          }
+          errors.fields = fields;
+        }
+
+        await this.render({ errors });
+    }
+
+
+    async renderNotFoundResponse(message=null) {
+        this.statusCode = 404;
+        await this.render({ message });
+    }
+
+
+    async renderUnauthorizedResponse(message=null) {
+        this.statusCode = 401;
+        await this.render({ message });
+    }
+
+
+    async renderForbiddenResponse(message=null) {
+        this.statusCode = 403;
+        await this.render({ message });
+    }
+
+
     async formatJSONBody(body, options) {
         body = await this._formatJSONBody(body, options);
         if (options.standardize === false) return body;
@@ -122,6 +232,8 @@ class VidaServerController {
                 return 'bad request'
             case 401:
                 return 'unauthorized';
+            case 403:
+                return 'forbidden';
             case 404:
                 return 'not found';
             case 500:
@@ -130,21 +242,34 @@ class VidaServerController {
     }
 
 
-    async renderErrors(errors) {
-        this.statusCode = 400;
-        await this.render({ errors });
+    /***********************************************************************************************
+    * HELPERS
+    ***********************************************************************************************/
+    static autoLoadHelpers() {
+        try {
+            this._autoLoadHelpers()
+        } catch(err) {
+            if (err.message.includes(`Cannot find module '${this.autoLoadHelperPath}'`)) return;
+            throw err;
+        }
     }
 
 
-    async renderNotFoundResponse() {
-        this.statusCode = 404;
-        await this.render();
+    static _autoLoadHelpers() {
+        const { InstanceMethods, Accessors } = require(this.autoLoadHelperPath);
+
+        if (InstanceMethods) Object.assign(this.prototype, InstanceMethods);
+
+        if (Accessors) {
+            for (const [attrName, attrAccessors] of Object.entries(Accessors)) {
+                Object.defineProperty(this.prototype, attrName, attrAccessors);
+            }
+        }
     }
 
 
-    async renderUnauthorizedResponse() {
-        this.statusCode = 401;
-        await this.render();
+    static get autoLoadHelperPath() {
+        return `${process.cwd()}/lib/controllers${this.routePrefix}Controller.js`;
     }
 
 
@@ -222,7 +347,7 @@ class VidaServerController {
             if (parameterErrors.length) errors[parameterName] = parameterErrors;
         }
 
-        if (Object.keys(errors).length) throw new ValidationError(errors);
+        if (Object.keys(errors).length) throw new ValidationError('', errors);
     }
 
 
@@ -264,6 +389,11 @@ 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;
@@ -272,6 +402,7 @@ class VidaServerController {
 
     /***********************************************************************************************
     * ACTION SETUP
+    ************************************************************************************************
     * The controller looks for any methods that fit the pattern of `{httpMethod}ActionName`
     * (e.g. getFooBar) and prepares server routes for them. By default, a method `getFooBar` on a
     * `BazController` would have an endpoint of  `GET /baz/fooBar`. The server will also prepend
@@ -356,19 +487,15 @@ class VidaServerController {
 }
 
 
-class AuthorizationError extends Error {}
-class ValidationError    extends Error {
-    #errors;
-    constructor(errors) {
-        super();
-        this.#errors = errors;
-    }
-    get errors() { return structuredClone(this.#errors) }; 
+VidaServerController.prototype.Errors = {
+    Authorization: AuthorizationError,
+    Forbidden:     ForbiddenError,
+    NotFound:      NotFoundError,
+    Server:        ServerError,
+    Validation:    ValidationError
 }
 
 
 module.exports = { 
-    AuthorizationError,
-    ValidationError,
     VidaServerController
 };