@vida-global/core 1.4.4 → 1.4.6

package/AGENTS.md

@@ -0,0 +1,13 @@
+# vida-core Guide
+
+Use this guide to understand and write code for the vida-core repo.
+
+# Style and conventions
+@agents/style.md
+@agents/server.md
+@agents/db.md
+@agents/apis.md
+@agents/testing.md
+
+
+# Helpers for common use cases

package/lib/http/README.md

@@ -30,3 +30,13 @@ const body = {baz: 1, ban: 2};
 const response = await client.post("/foo/bar", { body });
 ```
 
+## Aborting requests
+All request methods accept `timeout` (ms) and/or a caller-supplied `signal` (`AbortSignal`). When both are provided, they are composed via `AbortSignal.any` — whichever fires first aborts the request. If the request is aborted (by the timeout or the external signal), an `HttpAbortError` is thrown with `reason` set to either `'timed out'` or `'aborted'`.
+
+```
+await client.post("/foo/bar", { body, timeout: 5000 });
+
+const ctrl = new AbortController();
+await client.get("/foo/bar", { signal: ctrl.signal });
+```
+

package/lib/http/client.js

@@ -1,38 +1,67 @@
-const { logger }    = require('../logger');
-const { HttpError } = require('./error');
+const { logger }                    = require('../logger');
+const { HttpError, HttpAbortError } = require('./error');
 
 
 class HttpClient {
-    async get(endpoint, { requestParams, headers }={}) {
+    async get(endpoint, { requestParams, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "GET", arguments[1]);
     }
 
 
-    async post(endpoint, { body, headers }={}) {
+    async post(endpoint, { body, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "POST", arguments[1]);
     }
 
 
-    async put(endpoint, { body, headers }={}) {
+    async put(endpoint, { body, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "PUT", arguments[1]);
     }
 
 
-    async delete(endpoint, { requestParams, headers }={}) {
+    async delete(endpoint, { requestParams, headers, timeout, signal }={}) {
         return await this.#makeRequest(endpoint, "DELETE", arguments[1]);
     }
 
 
-    async #makeRequest(endpoint, method, { requestParams, body, headers }={}) {
+    async #makeRequest(endpoint, method, { requestParams, body, headers, timeout, signal }={}) {
         this.#logRequest(method, endpoint);
 
         endpoint            = `${this.urlRoot}${endpoint}`;
         const url           = new URL(endpoint);
         const requestData   = structuredClone(requestParams || body || {});
-        const payload       = this.#prepareRequestPayload(url, requestData, headers, method);
+        const payload       = this.#prepareRequestPayload(url, requestData, headers, method, timeout, signal);
 
-        const res  = await fetch(url.toString(), payload);
+        try {
+            const res = await fetch(url.toString(), payload);
+            return await this.#handleRequestResponse(res, payload);
+        } catch (err) {
+            this.#handleRequestError(err, payload, timeout, signal);
+        }
+    }
+
+
+    #handleRequestError(err, payload, timeout, externalSignal) {
+        if (this.#isAbortError(err)) {
+            const msg = this.#classifyAbortReason(timeout, externalSignal)
+            throw new HttpAbortError(msg, payload);
+        }
+        throw err;
+    }
+
+
+    #isAbortError(err) {
+        return err instanceof DOMException && (err.name === 'AbortError' || err.name === 'TimeoutError');
+    }
 
+
+    #classifyAbortReason(timeout, externalSignal) {
+        if (externalSignal?.aborted) return 'aborted';
+        if (timeout)                 return 'timed out';
+        return 'aborted';
+    }
+
+
+    async #handleRequestResponse(res, payload) {
         if (res.status && res.status < 300) {
             const json = await res.json();
             return {data: json, status: res.status};
@@ -42,7 +71,7 @@ class HttpClient {
     }
 
 
-    #prepareRequestPayload(url, requestData, headers, method) {
+    #prepareRequestPayload(url, requestData, headers, method, timeout, signal) {
         const payload = {};
 
         headers       ||= {};
@@ -50,10 +79,23 @@ class HttpClient {
         payload.method  = method;
         this.#addRequestData(payload, requestData, method, url, payload.headers);
 
+        const composedSignal = this.#composeSignal(signal, timeout);
+        if (composedSignal) payload.signal = composedSignal;
+
         return payload;
     }
 
 
+    #composeSignal(externalSignal, timeoutMs) {
+        const signals = [];
+        if (externalSignal) signals.push(externalSignal);
+        if (timeoutMs)      signals.push(AbortSignal.timeout(timeoutMs));
+        if (signals.length === 0) return undefined;
+        if (signals.length === 1) return signals[0];
+        return AbortSignal.any(signals);
+    }
+
+
     #addRequestData(payload, requestData, method, url, headers) {
         if (method == "POST" || method == "PUT") {
             payload.body = JSON.stringify(requestData || {});
@@ -123,7 +165,8 @@ class HttpClient {
 }
 
 
-module.exports = { 
+module.exports = {
   HttpClient,
-  HttpError
+  HttpError,
+  HttpAbortError
 }

package/lib/http/error.js

@@ -29,6 +29,24 @@ class HttpError extends Error {
 }
 
 
+class HttpAbortError extends Error {
+    #requestPayload;
+    #reason;
+
+
+    constructor(reason, requestPayload) {
+        super(`HTTP request ${reason}`);
+        this.#reason         = reason;
+        this.#requestPayload = requestPayload;
+    }
+
+
+    get reason()         { return this.#reason; }
+    get requestPayload() { return structuredClone(this.#requestPayload); }
+}
+
+
 module.exports = {
-  HttpError
+  HttpError,
+  HttpAbortError
 }

package/lib/logger/README.md

@@ -1,2 +1,33 @@
-## Logger ##
-A standard logger to be used across all Vida applications. Currently, a simple implementation of `pino`, supports the full `pino` API.
+# Logger
+A simple logger that support multiple scopes and log levels. Set the `LOG_LEVEL` environment variable to determine what log levels are output.
+
+## Scopes
+```
+logger.addScope('foo');
+logger.addScope('bar');
+
+logger.foo.debug('my log');
+// [2026-04-30 16:16:12.797 -0700][DEBUG][FOO] my log
+
+logger.bar.verbose('my log');
+// [2026-04-30 16:16:12.797 -0700][VERBOSE][BAR] my log
+
+logger.bar.info('my log');
+// [2026-04-30 16:16:12.797 -0700][INFO][BAR] my log
+
+logger.bar.warn('my log');
+// [2026-04-30 16:16:12.797 -0700][WARN][BAR] my log
+
+logger.bar.error('my log');
+// [2026-04-30 16:16:12.797 -0700][ERROR][BAR] my log
+```
+
+## IDs
+```
+logger.addScope('http');
+const requestId     = 123;
+const requestLogger = logger.http.createChild(requestId);
+
+requestLogger.debug('my log');
+// [2026-04-30 16:16:12.797 -0700][DEBUG][HTTP][123] my log
+``

package/lib/logger/index.js

@@ -1,25 +1,104 @@
-const pino = require('pino');
-
-const config = {
-    level: process.env.LOG_LEVEL || 'info',
-    customLevels: {
-      test: 1000
-    }
-};
-
-if (!process.env.ENV_VERCEL) {
-    config.transport = {
-        target: 'pino-pretty',
-        options: {
-            colorize: true,
-            ignore: 'pid,hostname',
-            translateTime: 'SYS:standard',
-            messageFormat: '{msg}',
+const   winston                           = require('winston');
+const { colorize, combine, printf, timestamp } = winston.format;
+
+
+class Logger {
+    #id;
+    #logger;
+    #scope;
+
+
+    constructor(scope, id) {
+        this.#id     = id;
+        this.#scope  = scope || 'API';
+        this.#logger = winston.createLogger(this.loggerOptions);
+    }
+
+
+    get scope() { return this.#scope; }
+    get id()    { return this.#id; }
+
+
+    get loggerOptions() {
+        const format     = combine(...this.formatters);
+        const level      = this.level;
+        const transports = this.transports;
+
+        return { format, level, transports };
+    }
+
+
+    get formatters() {
+        const colors = {
+            debug:   'magenta',
+            verbose: 'green',
+            info:    'cyan',
+            warn:    'yellow',
+            error:   'red',
+        }
+        const messageFormatter = winston.format(this.messageFormatter.bind(this));
+        return [
+            timestamp({format: 'YYYY-MM-DD HH:mm:ss.SSS ZZ'}),
+            messageFormatter(),
+            colorize({all: true, colors}),
+            printf(({ message }) => message)
+        ];
+    }
+
+
+    messageFormatter(info) {
+        const level  = info.level.toUpperCase()
+
+        let prefix = `[${info.timestamp}][${level}][${this.scope.toUpperCase()}]`;
+        if (this.id) prefix = `${prefix}[${this.id}]`;
+
+        info.message =  `${prefix} ${info.message}`;
+        return info;
+    }
+
+
+    get level() {
+        return process.env.LOG_LEVEL || 'info';
+    }
+
+
+    get transports() {
+        const transports = [ new winston.transports.Console() ];
+        return transports;
+    }
+
+
+    addScope(scope) {
+        const existing = this[scope];
+        if (existing && !existing instanceof Logger) {
+            throw `Property already exists at ${scope}`;
         }
-    };
+
+        const logger = new Logger(scope, this.id);
+        Object.defineProperty(this, scope, { get: () => logger });
+    }
+
+
+    createChild(id) {
+        return new Logger(this.scope, id);
+    }
+
+
+    debug(msg)   { this.#logger.debug(msg) }
+    error(msg)   { this.#logger.error(msg) }
+    info(msg)    { this.#logger.info(msg) }
+    silly(msg)   { this.#logger.silly(msg) }
+    verbose(msg) { this.#logger.verbose(msg) }
+    warn(msg)    { this.#logger.warn(msg) }
+
+    get _winstonLogger() { 
+        this.warn('Directly accessing the underlying winston logger should be avoided unless necessary');
+        return this.#logger
+    }
 }
 
-const logger = pino(config);
+
+const logger = new Logger();
 
 
-module.exports = { logger };
+module.exports = { logger, Logger };

package/lib/logger/serverMiddleware.js

@@ -0,0 +1,39 @@
+const { logger }     = require('./index');
+const expressWinston = require('express-winston');
+
+
+const msgFormatter = (req, res) => {
+    let msg;
+    if (req.controller) {
+        msg = `${req.controller.constructor.name}#${req.action}`;
+    } else {
+        msg = res.statusCode >= 500 ? 'request errored' : 'request completed';
+    }
+
+    const headerPcs       = res._header.split("\n").map(h => h.split(/:(.*)/));
+    const headers         = Object.fromEntries(headerPcs);
+    const responseTime    = headers['X-Response-Time'];
+
+    const requestDetails  = `req: ${req.method} ${req.url.split('?')[0]} for ${req.ip}`;
+    const responseDetails = `res: statusCode=${res.statusCode} responseTime=${responseTime}`;
+
+    msg = `${msg}\n    ${requestDetails}\n    ${responseDetails}`;
+    if (res.error) {
+        msg = `${msg}\n${res.error.stack}`;
+    }
+
+    return msg;
+};
+
+
+logger.addScope('http');
+const middleware = expressWinston.logger({
+    level:           'debug',
+    msg:             msgFormatter,
+    winstonInstance: logger.http._winstonLogger,
+});
+
+
+module.exports = {
+  middleware
+}

package/lib/server/server.js

@@ -1,13 +1,13 @@
 const { ControllerImporter }   = require('./controllerImporter');
 const   express                = require('express');
-const   httpLogger             = require('pino-http')
 const { logger }               = require('../logger');
+const   loggingMiddleware      = require('../logger/serverMiddleware');
 const   mustacheExpress        = require('mustache-express');
-const { pino }                 = require('pino');
 const   responseTime           = require('response-time');
 const   IoServer               = require("socket.io")
 const { Server }               = require('http');
 const { SystemController }     = require('./systemController');
+const   requestID              = require( 'express-request-id');
 
 
 class VidaServer {
@@ -31,7 +31,7 @@ class VidaServer {
         await this.registerControllers();
 
         this.#httpServer.listen(this.#port, this.#host, () => {
-            this.logger.info(`Server is running on port ${this.#port}`);
+            logger.info(`Server is running on port ${this.#port}`);
             if (callback) callback();
         });
     }
@@ -39,7 +39,7 @@ class VidaServer {
 
     get host()   { return this.#host; }
     get port()   { return this.#port; }
-    get logger() { return logger; }
+    get logger() { return logger.http; }
 
 
     /***********************************************************************************************
@@ -72,11 +72,12 @@ class VidaServer {
     setupMiddleware() {
         this.use(this.jsonParsingMiddleware);
         this.use(this.octetStreamParsingMiddleware);
-        this.use(responseTime())
+        this.use(responseTime({suffix: true}))
         this.use(express.static('public'))
         this.use(this.loggingMiddleware);
         this.use('/static', express.static(this.staticFilesDirectory));
         this.use(this.connectionAbortedMiddleware);
+        this.use(requestID());
 
         this.#expressServer.engine('html', mustacheExpress());
     }
@@ -105,15 +106,7 @@ class VidaServer {
 
 
     get loggingMiddleware() {
-        return httpLogger({
-            logger:               this.middlewareLogger,
-            customLogLevel:       this.requestLogLevel.bind(this),
-            customSuccessMessage: this.requestLogMessage.bind(this),
-            customErrorMessage:   this.requestLogMessage.bind(this),
-            customErrorObject:    this.requestLogDetails.bind(this),
-            customSuccessObject:  this.requestLogDetails.bind(this),
-            wrapSerializers:      false,
-        })
+      return loggingMiddleware.middleware
     }
 
 
@@ -135,53 +128,6 @@ class VidaServer {
     use() { this.#expressServer.use(...arguments); }
 
 
-    /***********************************************************************************************
-    * LOGGING
-    ***********************************************************************************************/
-    requestLogDetails(req, res, err) {
-        const details = {
-            req: `${req.method} ${req.url}`,
-            res: `statusCode=${res.statusCode}, responseTime=${res.get('X-Response-Time')}`,
-        };
-
-        if (res.statusCode >= 500 && res.error) {
-            details.error = this.requestLogErrorDetails(req, res, res.error);
-        }
-
-        return details;
-    }
-
-
-    requestLogErrorDetails(req, res, err) {
-        if (typeof err == 'string') return {message: err};
-        return {
-            type: err.constructor.name,
-            message: err.message,
-            stack: err.stack
-        }
-    }
-
-    
-    requestLogMessage(req, res) {
-        const prefix = '[VidaServer]';
-        if (req.controller) {
-            return `${prefix} ${req.controller.constructor.name}#${req.action}`;
-        }
-
-        return `${prefix} ${res.status >= 500 ? 'request errored' : 'request completed'}`;
-    }
-
-
-    requestLogLevel(req, res) {
-        return 'debug';
-    }
-
-
-    get middlewareLogger() {
-        return logger;
-    }
-
-
     /***********************************************************************************************
     * SETTINGS
     ***********************************************************************************************/
@@ -234,7 +180,7 @@ class VidaServer {
         const method         = action.method.toLowerCase();
         const requestHandler = this.requestHandler(action.action, controllerCls)
         if (process.env.NODE_ENV != 'test') {
-            logger.info(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
+            logger.verbose(`ROUTE: ${method.toUpperCase().padEnd(6)} ${action.path}`);
         }
         this['_'+method](action.path, requestHandler);
     }