@vida-global/core 1.4.6 → 2.0.1

package/lib/server/controllerImporter.js

@@ -1,61 +1,23 @@
-const   fs                     = require('fs');
+const { AbstractAutoImporter } = require('../utils/abstractAutoImporter');
 const { VidaServerController } = require('./serverController');
 
 
-class ControllerImporter {
-    #controllerDirectories;
-    #controllerClasses;
-
-
-    constructor(controllerDirectories) {
-        if (!Array.isArray(controllerDirectories)) {
-            controllerDirectories = [controllerDirectories];
-        }
-        this.#controllerDirectories = controllerDirectories;
-    }
-
-
+class ControllerImporter extends AbstractAutoImporter {
     get controllerClasses() {
-        if (!this.#controllerClasses) {
-            this.#importControllerClasses();
-        }
-        return this.#controllerClasses;
+        return this.imports;
     }
 
 
-    #importControllerClasses() {
-        this.#controllerClasses = [];
-        this.#controllerDirectories.forEach(dir => {
-            this.#importDirectory(dir, dir);
-        });
+    shouldImport(obj) {
+        return obj.prototype instanceof VidaServerController;
     }
 
 
-    #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));
+    processImport(obj, directoryPrefix) {
+        obj.directoryPrefix = directoryPrefix;
+        obj.autoLoadHelpers();
+        obj.autoLoadDocumentation();
     }
-
-
-    #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;
-                _export.autoLoadHelpers();
-                _export.autoLoadDocumentation();
-                this.#controllerClasses.push(_export);
-            }
-        });
-    }
-
 }
 
 

package/lib/server/server.js

@@ -1,3 +1,4 @@
+const   APM                    = require('../apm');
 const { ControllerImporter }   = require('./controllerImporter');
 const   express                = require('express');
 const { logger }               = require('../logger');
@@ -10,6 +11,9 @@ const { SystemController }     = require('./systemController');
 const   requestID              = require( 'express-request-id');
 
 
+logger.addScope('server');
+
+
 class VidaServer {
     #controllerClasses;
     #_expressServer;
@@ -31,7 +35,7 @@ class VidaServer {
         await this.registerControllers();
 
         this.#httpServer.listen(this.#port, this.#host, () => {
-            logger.info(`Server is running on port ${this.#port}`);
+            this.logger.info(`${this.constructor.name} running on port ${this.#port}`);
             if (callback) callback();
         });
     }
@@ -39,7 +43,7 @@ class VidaServer {
 
     get host()   { return this.#host; }
     get port()   { return this.#port; }
-    get logger() { return logger.http; }
+    get logger() { return logger.server; }
 
 
     /***********************************************************************************************
@@ -106,7 +110,7 @@ class VidaServer {
 
 
     get loggingMiddleware() {
-      return loggingMiddleware.middleware
+        return loggingMiddleware.middleware(this.logger);
     }
 
 
@@ -116,7 +120,7 @@ class VidaServer {
 
 
     get connectionAbortedMiddleware() {
-        return async function (err, req, res, next) {
+        return async function connectionAborted(err, req, res, next) {
             if (err && err.code === 'ECONNABORTED') {
                 return res.status(400).end(); // Don't process this error any further to avoid its logging
             }
@@ -180,7 +184,7 @@ class VidaServer {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
         if (process.env.NODE_ENV != 'test') {
-            logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+            this.logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
         }
         this['_'+method](action.path, requestHandler);
     }
@@ -195,24 +199,29 @@ class VidaServer {
 
 
     requestHandler(action, controllerCls) {
-        return async function(request, response) {
-            const controllerInstance = this.buildController(controllerCls, request, response);
-            request.controller       = controllerInstance;
-            request.action           = action;
-            await controllerInstance.performRequest(action);
-        }.bind(this);
+      // Implemented with this object access for APM segment tracking
+      const server  = this;
+      const handler = {
+          async requestHandler(request, response) {
+              const controllerInstance = server.buildController(controllerCls, request, response);
+              request.controller       = controllerInstance;
+              request.action           = action;
+              await controllerInstance.performRequest(action);
+          }
+      }.requestHandler;
+      return handler;
     }
 
 
     buildController(controllerCls, request, response) {
-        return new controllerCls(request, response);
+        return new controllerCls(request, response, this.logger);
     }
 
 
     get controllerClasses() {
         if (!this.#controllerClasses) {
             const controllerImporter = new ControllerImporter(this.controllerDirectories);
-            this.#controllerClasses  = controllerImporter.controllerClasses;
+            this.#controllerClasses  = controllerImporter.controllerClasses.filter(cls => !cls.name.startsWith('Abstract'));
         }
 
         return this.#controllerClasses;
@@ -236,6 +245,14 @@ class VidaServer {
     }
 
 
+    /***********************************************************************************************
+    * APM
+    ***********************************************************************************************/
+    startApmSegment(name, record, handler) {
+        APM.startSegment(name, record, handler);
+    }
+
+
     /***********************************************************************************************
     * DEPRECATED PASS THROUGH METHODS
     ***********************************************************************************************/

package/lib/server/serverController.js

@@ -1,10 +1,12 @@
-const { logger }                 = require('../logger');
+const   APM                      = require('../apm');
 const { camelize, singularize }  = require('inflection');
 const   Errors                   = require('./errors');
+const { logger }                 = require('../logger');
 const   nodeUtil                 = require('util');
 
 
 const AUTH_CALLBACK_NAME = 'authenticateRequest';
+const actionStore        = new WeakMap();
 
 
 class VidaServerController {
@@ -22,12 +24,13 @@ class VidaServerController {
     #streamAbortController;
 
 
-    constructor(request, response) {
+    constructor(request, response, serverLogger) {
         if (this.constructor == VidaServerController) {
             throw new Error("ServerControllers must be subclasses of VidaServerController");
         }
         this.#request  = request;
         this.#response = response;
+        this.#logger   = (serverLogger || logger).child(this.requestId);
 
         this.#applyCallbacks();
         this.#setupStatusRenderers();
@@ -59,11 +62,8 @@ class VidaServerController {
     set statusCode(_status) { this._response.statusCode = _status; }
 
 
-    get logger() { 
-      if (!this.#logger) {
-          this.#logger = logger.http.createChild(this.requestId);
-      }
-      return this.#logger;
+    get logger() {
+        return this.#logger;
     }
 
 
@@ -104,6 +104,7 @@ class VidaServerController {
     ***********************************************************************************************/
     async performRequest(action) {
         try {
+            APM.setControllerName(this.constructor.name, action);
             await this.#performRequest(action)
         } catch(err) {
             await this.#handleError(err);
@@ -112,7 +113,7 @@ class VidaServerController {
 
 
     async #performRequest(action) {
-        await this.setupRequestState();
+        await APM.startSegment('setupRequestState', true, () => this.setupRequestState());
 
         if (this.rendered) {
             this.#response.end();
@@ -122,7 +123,7 @@ class VidaServerController {
         const responseBody = await this.#performAction(action);
 
         if (!this.rendered) {
-            await this.render(responseBody || {});
+            await APM.startSegment('render', true, () => this.render(responseBody || {}));
         }
 
         this.#response.end();
@@ -130,13 +131,14 @@ class VidaServerController {
 
 
     async #performAction(action) {
-        if (await this.runBeforeCallbacks(action) === false) return false;
+        if (await APM.startSegment('beforeCallbacks', true, () => this.runBeforeCallbacks(action)) === false) return false;
 
         const parameters = this.constructor.parametersForAction(action);
-        if (parameters) await this.validateParameters(parameters);
+        if (parameters) await APM.startSegment('validateParameters', true, () => this.validateParameters(parameters));
 
-        const responseBody = await this[action]();
-        if (await this.runAfterCallbacks(action) === false)  return false;
+        const responseBody = await APM.startSegment(`action:${action}`, true, () => this[action]());
+
+        if (await APM.startSegment('afterCallbacks', true, () => this.runAfterCallbacks(action)) === false) return false;
 
         return responseBody;
     }
@@ -164,10 +166,17 @@ class VidaServerController {
                 message = err.message;
             }
             await this.renderServerError(message);
+
+            this.reportError(err);
         }
     }
 
 
+    reportError(err) {
+        APM.reportError(err);
+    }
+
+
     /***********************************************************************************************
     * RESPONSE RENDERING
     ***********************************************************************************************/
@@ -223,29 +232,29 @@ class VidaServerController {
         if (body === undefined)               return null;
         if (!body || typeof body != 'object') return body;
 
-        if (nodeUtil.types.isProxy(body)) body = {...body};
-
-        body = structuredClone(body);
+        let processedBody;
 
         if (body.toApiResponse) {
             const formattedBody = await body.toApiResponse(options);
             return await this.processJSONBody(formattedBody, options);
 
         } else if (Array.isArray(body)) {
+            const processed = [];
             for (const idx in body) {
-                body[idx] = await this.processJSONBody(body[idx], options);
+                processed.push(await this.processJSONBody(body[idx], options));
             }
+            return processed;
 
         } else if (body.constructor == Date) {
             return body.getTime();
 
         } else {
+            const processed = {};
             for (let [key, val] of Object.entries(body)) {
-                body[key] = await this.processJSONBody(val, options);
+                processed[key] = await this.processJSONBody(val, options);
             }
+            return processed;
         }
-
-        return body;
     }
 
 
@@ -428,6 +437,7 @@ class VidaServerController {
     * HELPERS
     ***********************************************************************************************/
     static autoLoadHelpers() {
+        this.actions; // make sure that actions are cached before loading helpers
         const { StaticMethods, InstanceMethods, Accessors } = this._autoLoadModule(this.autoLoadHelperPath);
 
         if (StaticMethods)   Object.assign(this, StaticMethods);
@@ -460,12 +470,12 @@ class VidaServerController {
 
 
     static get autoLoadHelperPath() {
-        return `${process.cwd()}/lib/controllers${this.routePrefix}Controller.js`;
+        return `${process.cwd()}/lib/controllers${this.routePrefix}Controller`;
     }
 
 
     static get autoLoadDocumentationPath() {
-        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller.js`;
+        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller`;
     }
 
 
@@ -556,6 +566,51 @@ class VidaServerController {
     }
 
 
+    /***********************************************************************************************
+    * REQUEST PARAMETERS
+    ***********************************************************************************************/
+    hasParam(name) {
+        return Object.prototype.hasOwnProperty.call(this.params, name);
+    }
+
+
+    coerceString(value, { fallback = '' } = {}) {
+        if (typeof value !== 'string') return fallback;
+        const trimmed = value.trim();
+        return trimmed || fallback;
+    }
+
+
+    coerceBoolean(value, { fallback } = {}) {
+        if (typeof value === 'boolean') return value;
+        if (typeof value !== 'string')  return fallback;
+        const normalized = value.trim().toLowerCase();
+        if (!normalized) return fallback;
+        if (normalized === 'true'  || normalized === '1' || normalized === 'yes' || normalized === 'on')  return true;
+        if (normalized === 'false' || normalized === '0' || normalized === 'no'  || normalized === 'off') return false;
+        return fallback;
+    }
+
+
+    coerceInteger(value, { min, max, fallback, nonNegative } = {}) {
+        if (value === null || value === undefined) return fallback;
+        if (typeof value === 'string' && value.trim() === '') return fallback;
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) return fallback;
+        let next = Math.floor(parsed);
+        if (nonNegative && next < 0) return fallback;
+        if (Number.isFinite(min)) next = Math.max(min, next);
+        if (Number.isFinite(max)) next = Math.min(max, next);
+        return next;
+    }
+
+
+    coerceObject(value, { fallback = {} } = {}) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+        return fallback;
+    }
+
+
     /***********************************************************************************************
     * VALIDATIONS
     ***********************************************************************************************/
@@ -657,10 +712,14 @@ class VidaServerController {
     * {getFooBar: '/ban/:accountIdd/foo/:userId/bar'}`
     ***********************************************************************************************/
     static get actions() {
+        if (actionStore.has(this)) return actionStore.get(this);
         const actionNames = this.actionNames;
-        return actionNames.map((actionName => {
+        const actions = actionNames.map((actionName => {
             return this._constructAction(actionName);
         }).bind(this));
+
+        actionStore.set(this, actions);
+        return actions;
     }
 
 
@@ -787,6 +846,24 @@ class VidaServerController {
         if (aBuf.length !== bBuf.length) return false;
         return crypto.timingSafeEqual(aBuf, bBuf);
     }
+
+
+    /***********************************************************************************************
+    * APM
+    ***********************************************************************************************/
+    addApmAttribute(key, value) {
+        APM.addCustomAttribute(key, value)
+    }
+
+
+    setApmUserId(id) {
+        APM.setUserId(id)
+    }
+
+
+    startApmSegment(name, record, handler) {
+        return APM.startSegment(name, record, handler);
+    }
 }
 
 

package/lib/utils/abstractAutoImporter.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+
+
+class AbstractAutoImporter {
+    #directories;
+    #imports;
+
+
+    constructor(directories) {
+        if (!Array.isArray(directories)) {
+            directories = [directories];
+        }
+        this.#directories = directories;
+    }
+
+
+    get imports() {
+        if (!this.#imports) {
+            this.#runImport();
+        }
+        return this.#imports;
+    }
+
+
+    #runImport() {
+        this.#imports = [];
+        this.#directories.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(obj => {
+            if (this.shouldImport(obj)) {
+                const directoryPrefix = dir.replace(topLevelDirectory, '');
+                this.processImport(obj, directoryPrefix);
+                this.#imports.push(obj);
+            }
+        });
+    }
+
+
+    shouldImport(obj)  {}
+    processImport(obj) {}
+}
+
+
+module.exports = {
+    AbstractAutoImporter
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "1.4.6",
+    "version": "2.0.1",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -18,13 +18,15 @@
         "setupFilesAfterEnv": ["jest-extended/all"]
     },
     "dependencies": {
+        "bullmq": "^5.0.0",
         "commander": "^13.1.0",
         "express": "^4.21.2",
         "express-request-id": "1.4.1",
         "express-winston": "^4.0.0",
         "mustache-express": "^1.2.8",
+        "newrelic": "^13.0.0",
         "pg": "^8.16.3",
-        "redis": "^5.0.0",
+        "redis": "^4.0.0",
         "response-time": "^2.3.3",
         "sequelize": "^6.37.7",
         "sequelize-cli": "^6.6.3",

package/test/activeRecord/baseRecord.test.js

@@ -126,6 +126,135 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('BaseRecord.configureVirtualAccessors', () => {
+        it ('adds a VIRTUAL column when a _virtualGet method is defined on the subclass', () => {
+            const getter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, get: getter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('adds a VIRTUAL column when a _virtualSet method is defined on the subclass', () => {
+            const setter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualSetFullName = setter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, set: setter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('merges _virtualGet and _virtualSet into the same VIRTUAL column', () => {
+            const getter = jest.fn();
+            const setter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.prototype._virtualSetFullName = setter;
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    fullName: { type: Sequelize.DataTypes.VIRTUAL, get: getter, set: setter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('picks up virtual accessors defined on a parent class', () => {
+            const getter = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = getter;
+            class Employee extends Person {}
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: getter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('lets a subclass override a virtual accessor defined on a parent class', () => {
+            const parentGetter = jest.fn();
+            const childGetter  = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = parentGetter;
+            class Employee extends Person {}
+            Employee.prototype._virtualGetDisplayName = childGetter;
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: childGetter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('merges a parent _virtualGet with a child _virtualSet on the same property', () => {
+            const parentGetter = jest.fn();
+            const childSetter  = jest.fn();
+            class Person extends BaseRecord {}
+            Person.prototype._virtualGetDisplayName = parentGetter;
+            class Employee extends Person {}
+            Employee.prototype._virtualSetDisplayName = childSetter;
+            Employee.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    displayName: { type: Sequelize.DataTypes.VIRTUAL, get: parentGetter, set: childSetter }
+                }),
+                expect.anything()
+            );
+        });
+
+        it ('does not pull in non-virtual methods from any ancestor', () => {
+            class Person extends BaseRecord {
+                someOtherMethod() {}
+            }
+            class Employee extends Person {}
+            Employee.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg).not.toHaveProperty('someOtherMethod');
+        });
+
+        it ('does not walk past Model.prototype when collecting accessors', () => {
+            class User extends BaseRecord {}
+            Model.prototype._virtualGetShouldBeIgnored = jest.fn();
+            User.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg).not.toHaveProperty('shouldBeIgnored');
+
+            delete Model.prototype._virtualGetShouldBeIgnored;
+        });
+
+        it ('leaves existing schema columns untouched while adding the virtual entry', () => {
+            const getter = jest.fn();
+            class User extends BaseRecord {}
+            User.prototype._virtualGetFullName = getter;
+            User.initialize();
+
+            const [schemaArg] = Model.init.mock.calls[0];
+            expect(schemaArg[Helpers.colName]).toEqual({ type: Sequelize.DataTypes[Helpers.dataTypeKey2] });
+            expect(schemaArg.fullName).toEqual({ type: Sequelize.DataTypes.VIRTUAL, get: getter });
+        });
+    });
+
+
     describe('BaseRecord.tableName', () => {
         it ('defaults to the puralized version of the class name', () => {
             class User extends BaseRecord {}

package/test/activeRecord/db/connection.test.js

@@ -1,9 +1,11 @@
 const { Connection }              = require('../../../lib/activeRecord/db/connection');
 const { ConnectionConfiguration } = require('../../../lib/activeRecord/db/connectionConfiguration');
 const   Helpers                   = require('../helpers/connection');
+const { snapshotEnv }             = require('../../helpers/env');
 
 
 let fetchConfigsSpy;
+let restoreEnv;
 
 jest.mock('sequelize', () => {
     const { MockSequelize } = require('../helpers/fixtures');
@@ -11,6 +13,7 @@ jest.mock('sequelize', () => {
 });
 
 beforeEach(() => {
+    restoreEnv = snapshotEnv(['NODE_ENV']);
     fetchConfigsSpy = jest.spyOn(ConnectionConfiguration, '_fetchAllConfigs');
     fetchConfigsSpy.mockImplementation(Helpers.buildConfigs);
 });
@@ -18,7 +21,7 @@ beforeEach(() => {
 afterEach(() => {
     fetchConfigsSpy.mockRestore();
     Connection.clearConnectionsCache();
-    process.env.NODE_ENV = Helpers.originalNodeEnv;
+    restoreEnv();
 });