@vida-global/core 1.2.5 → 1.3.1

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/{active_record → activeRecord}/db/schema.js

@@ -59,7 +59,7 @@ function resolveAutoIncrementColumns(details) {
     if (!details.defaultValue) return;
 
     const regExp = /^nextval\(\w+_seq::regclass\)$/;
-    if (details.defaultValue.match(regExp)) {
+    if (regExp.test(details.defaultValue)) {
         delete details.defaultValue;
         delete details.allowNull;
         details.autoIncrement = true;

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/apiDocsGenerator.js

@@ -0,0 +1,55 @@
+const { ControllerImporter } = require('./controllerImporter');
+
+
+class ApiDocsGenerator {
+    #controllerDirectories
+    #controllers;
+    #docs = {};
+    
+    constructor(server) {
+        this.#controllerDirectories = server.controllerDirectories;
+    }
+
+
+    generateDocs() {
+console.log("\n\n");
+        this.controllers.forEach(controller => {
+            controller.actions.forEach(action => {
+                this.generateDocsForAction(action);
+            });
+        });
+console.log("\n\n");
+    }
+
+
+    generateDocsForAction(action) {
+        const endpoint       = this.formatEndpoint(action);
+        this.#docs[endpoint] = this.#docs[endpoint] || {};
+        const actionDocs     = this.#docs[endpoint][action.method.toLowerCase()] = {foo: 1};
+      console.log(actionDocs);
+    }
+
+
+    get controllers() {
+        if (!this.#controllers) {
+            const controllerImporter = new ControllerImporter(this.#controllerDirectories);
+            this.#controllers        = controllerImporter.controllers;
+        }
+        return this.#controllers;
+    }
+
+
+    /***********************************************************************************************
+    * OPENAPI COMPONENTS
+    ***********************************************************************************************/
+    formatEndpoint(action) {
+        const endpoint = action.path.replace(/:([^/]+)/g, '{$1}');
+        return endpoint;
+    }
+
+}
+
+
+module.exports = {
+    ApiDocsGenerator
+}

package/lib/server/controllerImporter.js

@@ -0,0 +1,62 @@
+const   fs                     = require('fs');
+const { VidaServerController } = require('./serverController');
+
+
+class ControllerImporter {
+    #controllerDirectories;
+    #controllers;
+
+
+    constructor(controllerDirectories) {
+        if (!Array.isArray(controllerDirectories)) {
+            controllerDirectories = [controllerDirectories];
+        }
+        this.#controllerDirectories = controllerDirectories;
+    }
+
+
+    get controllers() {
+        if (!this.#controllers) {
+            this.#importControllers();
+        }
+        return this.#controllers;
+    }
+
+
+    #importControllers() {
+        this.#controllers = [];
+        this.#controllerDirectories.forEach(dir => {
+            this.#importDirectory(dir, dir);
+        });
+    }
+
+
+    #importDirectory(dir, topLevelDirectory) {
+        fs.readdirSync(dir).forEach((f => {
+            const filePath = `${dir}/${f}`;
+            if (fs.lstatSync(filePath).isDirectory()) {
+                this.#importDirectory(filePath, topLevelDirectory);
+            } else if (f.endsWith('.js')) {
+                this.#importFromFile(filePath, dir, topLevelDirectory);
+            }
+        }).bind(this));
+    }
+
+
+    #importFromFile(filePath, dir, topLevelDirectory) {
+        const exports     = Object.values(require(filePath));
+        exports.forEach(_export => {
+            if (_export.prototype instanceof VidaServerController) {
+                const directoryPrefix   = dir.replace(topLevelDirectory, '');
+                _export.directoryPrefix = directoryPrefix;
+                this.#controllers.push(_export);
+            }
+        });
+    }
+
+}
+
+
+module.exports = {
+    ControllerImporter
+}

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);
     }