@vida-global/core 2.0.11 → 2.1.0

package/lib/activeRecord/README.md

@@ -173,7 +173,7 @@ const rows = await User.findAll({
 
 ### API serialization
 
-`record.toApiResponse()` returns a plain object containing every column with overridden getters applied. The server's response renderer calls this automatically when a record is included in an action's return value.
+`record.toApiResponse()` returns a plain object containing the columns exposed by the model's static `documentationSchema()` (which excludes `created_at`, `updated_at`, and `deleted_at`), with overridden getters applied. The server's response renderer calls this automatically when a record is included in an action's return value.
 
 ### Closing connections
 

package/lib/activeRecord/baseRecord.js

@@ -1,5 +1,6 @@
 const { Connection, DEFAULT_DATABASE_ID } = require('./db/connection');
 const { getActiveRecordSchema }           = require('./db/schema');
+const { Schemas }                         = require('../server/openApi/schemas');
 const { logger }                          = require('../logger');
 const { Model, Op, Sequelize }            = require('sequelize');
 const   nodeUtil                          = require('util');
@@ -373,11 +374,76 @@ class BaseRecord extends Model {
 
 
     toApiResponse() {
-      const obj = this.dataValues;
-      for (const attr of Object.keys(obj)) {
-        obj[attr] = this[attr]; // Use overridden getters when available
+      const response = {};
+      for (const column of this.apiResponseColumns) {
+        response[column] = this[column]; // Use overridden getters when available
       }
-      return obj
+      return response;
+    }
+
+
+    get apiResponseColumns() {
+      return Object.keys(this.constructor.documentationSchema());
+    }
+
+
+    /***********************************************************************************************
+    * DOCUMENTATION
+    ***********************************************************************************************/
+    static documentationSchema() {
+        this.initialize();
+        const schemas = {};
+        for (const [name, attribute] of Object.entries(this.getAttributes())) {
+            if (this.documentationExcludedColumns.includes(name)) continue;
+            schemas[name] = this.documentationColumnSchema(attribute);
+        }
+        return schemas;
+    }
+
+
+    static get documentationExcludedColumns() {
+        return ['created_at', 'updated_at', 'deleted_at'];
+    }
+
+
+    static documentationColumnSchema(attribute) {
+        const builder = this.documentationTypeBuilders[attribute.type?.key];
+        if (!builder) return Schemas.stringSchema();
+        return builder(attribute);
+    }
+
+
+    static get documentationTypeBuilders() {
+        return {
+            INTEGER:   () => Schemas.integerSchema(),
+            BIGINT:    () => Schemas.integerSchema(),
+            SMALLINT:  () => Schemas.integerSchema(),
+            TINYINT:   () => Schemas.integerSchema(),
+            MEDIUMINT: () => Schemas.integerSchema(),
+            FLOAT:     () => Schemas.numberSchema(),
+            DOUBLE:    () => Schemas.numberSchema(),
+            REAL:      () => Schemas.numberSchema(),
+            DECIMAL:   () => Schemas.numberSchema(),
+            NUMBER:    () => Schemas.numberSchema(),
+            BOOLEAN:   () => Schemas.booleanSchema(),
+            DATE:      () => Schemas.dateTimeSchema(),
+            DATEONLY:  () => Schemas.dateTimeSchema(),
+            TIME:      () => Schemas.dateTimeSchema(),
+            ENUM:      (attribute) => Schemas.enumSchema({ enums: attribute.type.values }),
+            JSON:      () => Schemas.objectSchema(),
+            JSONB:     () => Schemas.objectSchema(),
+            ARRAY:     () => Schemas.arraySchema(),
+            STRING:    () => Schemas.stringSchema(),
+            CHAR:      () => Schemas.stringSchema(),
+            TEXT:      () => Schemas.stringSchema(),
+            CITEXT:    () => Schemas.stringSchema(),
+            UUID:      () => Schemas.stringSchema(),
+        };
+    }
+
+
+    get apiXMLTagName() {
+        return this.constructor.name;
     }
 }
 

package/lib/server/README.md

@@ -113,240 +113,29 @@ module.exports = { InstanceMethods, Accessors };
 ```
 
 
-## Request Properties
+## Request details
 
-Within an action, the controller exposes:
-
-| Property | Description |
-|---|---|
-| `this.params` | Merged route, query, and JSON-body parameters. Returns a structured clone — mutate freely. |
-| `this.requestHeaders` | Cloned request headers. |
-| `this.responseHeaders` | Outgoing response headers (mutable). |
-| `this.contentType` | Shortcut for `requestHeaders['content-type']`. |
-| `this.userAgent` | Shortcut for `requestHeaders['user-agent']`. |
-| `this.requestId` | Unique request id (added by `express-request-id`). |
-| `this.requestBody` | Raw request body. |
-| `this.requestMethod` | HTTP method. |
-| `this.requestIp` | Client IP address. |
-| `this.url` | Original URL. |
-| `this.bearerToken` | Parsed `Authorization: Bearer <token>` value, or `null`. |
-| `this.statusCode` | Current outgoing status (settable, but prefer the render helpers below). |
-| `this.logger` | Per-request child logger. |
-
-
-## Cookies
-
-```js
-// All cookies (object)
-const all = this.cookies;
-
-// A single cookie, or null if missing
-const session = this.getCookie('session');
-
-// Set a cookie. Options are passed through to express `res.cookie`.
-this.setCookie('session', token, { httpOnly: true, secure: true, maxAge: 86400_000 });
-```
-
-
-## Parameter coercion
-
-Use these on the controller instance to normalize inbound params without throwing. Each accepts a `{ fallback }` option (and other shape-specific options) and returns the fallback for unusable input.
-
-```js
-this.hasParam('agentId');                                       // true/false
-this.coerceString(this.params.name, { fallback: 'anonymous' }); // trims; empty -> fallback
-this.coerceBoolean(this.params.enabled, { fallback: false });   // accepts true/false, "true"/"false"/"1"/"0"/"yes"/"no"/"on"/"off"
-this.coerceInteger(this.params.limit,
-                   { min: 1, max: 100, fallback: 25 });          // floors, clamps, nonNegative supported
-this.coerceObject(this.params.filters, { fallback: {} });        // arrays return fallback
-```
+See [Request details](./doc/requestDetails.md) — request properties, cookies, and parameter coercion.
 
 
 ## Validations
 
-Prefer the static `parametersFor<ActionName>` method on the controller class — the framework runs it before the action and renders a 400 response with structured field errors if anything fails.
-
-```js
-class UsersController extends VidaServerController {
-    static parametersForGetIndex() {
-        return {
-            pageSize: { isInteger: { gte: 1, lte: 100 }, optional: true },
-            email:    { presence: true, isString: { regex: /\S+@\S+\.\S+/ } },
-            role:     { isEnum: { enums: ['admin', 'member', 'guest'] } },
-            title:    { function: this.prototype.validateUniqueTitle },
-        };
-    }
-
-    async getIndex() {
-        // pageSize/email/role/title are already validated when this runs
-    }
-
-    async validateUniqueTitle(title) {
-        if (await User.findByTitle(title)) return 'must be unique';
-    }
-}
-```
-
-If you need to validate values that are constructed mid-action, call `this.validateParameters(...)` directly with the same shape.
-
-### Supported validators
-
-- `{ optional: true }` — skip validation when the value is `undefined`.
-- `{ presence: true }`
-- `{ isInteger: true }` or `{ isInteger: { gte: 0, lte: 100 } }`
-- `{ isString: true }` or `{ isString: { length: { gte: 10, lte: 100 }, regex: /foo/ } }`
-- `{ isBoolean: true }` or `{ isBoolean: false }` (asserts the exact value)
-- `{ isDateTime: true }`
-- `{ isEnum: { enums: ['a', 'b', 'c'], error: 'optional message' } }`
-- `{ function: someFn }` — return a string to flag an error.
-
-
-## Rendering responses
-
-By default the controller renders the value returned from the action. Render walks the result recursively and calls `toApiResponse(opts)` on anything that defines it, then wraps the result in a standard envelope.
-
-```js
-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');
-    return { bar: 1, baz: [user1, user2] };
-}
-```
-
-…produces:
-
-```json
-{
-  "data": {
-    "bar": 1,
-    "baz": [
-      { "name": "Bruce", "email": "bwayne@wayne-enterprises.inc" },
-      { "name": "Babs",  "email": "bgordon@wayne-enterprises.inc" }
-    ]
-  },
-  "status": "ok"
-}
-```
-
-Pass options through to `toApiResponse` by calling `render` explicitly:
-
-```js
-await this.render(response, { includeTitle: true });
-```
-
-To skip the standard envelope and emit the body verbatim (legacy clients, file-style payloads):
-
-```js
-return await this.render(response, { standardize: false });
-```
-
-### Status code helpers
-
-Don't set `this.statusCode` directly — use the helper that pairs the status with `render`:
-
-| Status | Helper |
-|---|---|
-| 201 Created | `this.renderCreationSuccessful(body)` |
-| 202 Accepted | `this.renderAccepted(body)` |
-| 204 No Content | `this.renderNoConent(body)` |
-| 301 Moved Permanently | `this.renderMovedPermanently(body)` |
-| 302 Found | `this.renderFound(body)` |
-| 304 Not Modified | `this.renderNotModified(body)` |
-| 307 Temporary Redirect | `this.renderTemporaryRedirect(body)` |
-| 308 Permanent Redirect | `this.renderPermanentRedirect(body)` |
-| 401 Unauthorized | `this.renderUnauthorized(message, body)` |
-| 402 Payment Required | `this.renderPaymentRequired(message, body)` |
-| 403 Forbidden | `this.renderForbidden(message, body)` |
-| 404 Not Found | `this.renderNotFound(message, body)` |
-| 405 Method Not Allowed | `this.renderMethodNotAllowed(message, body)` |
-| 408 Request Timeout | `this.renderRequestTimeout(message, body)` |
-| 409 Conflict | `this.renderConflict(message, body)` |
-| 410 Gone | `this.renderGone(message, body)` |
-| 413 Content Too Large | `this.renderContentTooLarge(message, body)` |
-| 415 Unsupported Media Type | `this.renderUnsupportedMediaType(message, body)` |
-| 422 Unprocessable Content | `this.renderUnprocessableContent(message, body)` |
-| 423 Locked | `this.renderLocked(message, body)` |
-| 429 Too Many Requests | `this.renderTooManyRequests(message, body)` |
-
-After a render helper runs, the action does not need to return — the response has already been sent.
-
-
-## Error handling
-
-```js
-await this.renderErrors('Something bad happened',
-                        { password: ['must be > 8 characters', 'must include numbers'] });
-// {data: {errors: {message: "Something bad happened", fields: {password: [...]}}}, status: "bad request"}
-
-await this.renderErrors('Something bad happened');
-// {data: {errors: {message: "Something bad happened"}}, status: "bad request"}
-
-await this.renderErrors({ password: ['must be > 8 characters', 'must include numbers'] });
-// {data: {errors: {fields: {password: [...]}}}, status: "bad request"}
-
-await this.renderUnauthorized('Nope');
-// {data: {message: "Nope"}, status: "unauthorized"}
-
-await this.renderForbidden('You shall not pass');
-// {data: {message: "You shall not pass"}, status: "forbidden"}
-```
-
-Throwing any of `this.Errors.Authorization(msg)`, `this.Errors.Forbidden(msg)`, `this.Errors.NotFound(msg)`, or `this.Errors.Validation(msg, fields)` from anywhere in the call chain triggers the matching render helper. Any other thrown error becomes a 500.
+See [Validations](./doc/validations.md) — `parametersFor<ActionName>` and the supported validators.
 
 
 ## Callbacks
 
-Callbacks are methods that run before or after an action. They are used for authentication, action setup, cleanup, etc. If a callback returns `false`, execution stops and no further callbacks or the action are run. Define callbacks in `setupCallbacks()` on the controller.
+See [Callbacks](./doc/callbacks.md) — before/after action callbacks and how subclasses skip them.
 
-```js
-setupCallbacks() {
-    // Runs before every action except getIndex; halts in production
-    this.beforeCallback(() => process.env.NODE_ENV != 'production', { except: 'getIndex' });
-
-    // Runs the `setUpSomeStuff` instance method before every action
-    this.beforeCallback('setUpSomeStuff');
-
-    // Runs `cleanupRequest` after getFoo and getBar
-    this.afterCallback('cleanupRequest', { only: ['getFoo', 'getBar'] });
-}
-```
-
-A subclass can suppress a callback inherited from a parent without removing it for everyone:
-
-```js
-this.skipBeforeCallback('authenticateRequest', { only: 'getHealthCheck' });
-this.skipAfterCallback('logActivity',          { except: ['getRecord'] });
-```
 
+## Rendering responses
 
-## Server-Sent Events / streaming
+See [Rendering responses](./doc/renderer.md) — the render envelope, status-code helpers, error handling, and Server-Sent Events / streaming.
 
-Use `streamSseResponse` to write a long-lived stream of events instead of a one-shot JSON response. The handler is run with `this` bound to the controller, and `writeStreamEvent(name, data)` emits SSE frames.
 
-```js
-async getEvents() {
-    const ctrl = new AbortController();
-    await this.streamSseResponse(
-        async () => {
-            for await (const evt of this.subscribeToEvents(ctrl.signal)) {
-                this.writeStreamEvent('update', JSON.stringify(evt));
-            }
-        },
-        async (err) => this.logger.error(err),
-        ctrl,
-    );
-}
-```
+## Documentation
 
-A trailing `data: [DONE]\n\n` frame is emitted automatically when the handler returns. If the client disconnects, the abort controller (when provided) is aborted.
+See [API Documentation (OpenAPI)](./doc/documentation.md) — generating an OpenAPI spec: per-action YAML, tags, schema refs, and auth.
 
 
 ## Advanced

package/lib/server/controllerImporter.js

@@ -16,7 +16,6 @@ class ControllerImporter extends AbstractAutoImporter {
     processImport(obj, directoryPrefix) {
         obj.directoryPrefix = directoryPrefix;
         obj.autoLoadMixins();
-        obj.autoLoadDocumentation();
     }
 }
 

package/lib/server/controllerMixins/callbacks.js

@@ -1,55 +1,27 @@
 const APM = require('../../apm');
+const { ClassScopedRegistry, appliesToAction } = require('./classScopedRegistry');
 
 
 const AUTH_CALLBACK_NAME = 'authenticateRequest';
 
 
-const afterCallbacks        = new Map();
-const afterCallbacksToSkip  = new Map();
-const beforeCallbacks       = new Map();
-const beforeCallbacksToSkip = new Map();
-const callbacksSetup        = new Map();
+const registry = new ClassScopedRegistry();
 
 
-function callbacksListForController(list, controller) {
-    const cls = controller.constructor;
-    if (!list.has(cls)) {
-        list.set(cls, []);
-    }
-    return list.get(cls);
-}
-
-
-function addCallback(controller, callback, options, callbacksList) {
-    const list = callbacksListForController(callbacksList, controller)
-    list.push({ callback, options });
-}
-
-
-function shouldRunCallback(actionName, options) {
-    if (options.only) {
-        if (Array.isArray(options.only)) return options.only.includes(actionName);
-        return options.only == actionName;
-    }
-
-    if (options.except) {
-        if (Array.isArray(options.except)) return !options.except.includes(actionName);
-        return options.except != actionName;
-    }
-
-    return true;
+function addCallback(controller, callback, options, listName) {
+    registry.list(listName, controller).push({ callback, options });
 }
 
 
 async function runCallbacks(callbacksList, callbacksToSkipList, actionName, controller) {
     let toSkip = callbacksToSkipList.filter(({ callback, options }) => {
-        return shouldRunCallback(actionName, options);
+        return appliesToAction(actionName, options);
     });
     toSkip = toSkip.map(({ callback }) => callback);
 
     for (const  { callback, options } of callbacksList) {
-        if (!shouldRunCallback(actionName, options)) continue;
-        if (toSkip.includes(callback))               continue;
+        if (!appliesToAction(actionName, options)) continue;
+        if (toSkip.includes(callback))             continue;
         const result = await runCallback(callback, controller)
         if (result === false) return false;
     }
@@ -69,50 +41,33 @@ const InstanceMethods = {
 
 
     _applyCallbacks() {
-        const cls = this.constructor;
-        if (!callbacksSetup.has(cls)) {
-            this.setupCallbacks();
-            callbacksSetup.set(cls, true)
-        }
-
-        // set up the callbacks when the instance is constructed and prevent it from being called again
-        this.setupCallbacks = undefined;
+        registry.applySetupOnce(this, 'setupCallbacks');
     },
 
 
     beforeCallback(callback, options={}) {
-        addCallback(this, callback, options, beforeCallbacks);
+        addCallback(this, callback, options, 'before');
     },
 
 
     afterCallback(callback, options={}) {
-        addCallback(this, callback, options, afterCallbacks);
+        addCallback(this, callback, options, 'after');
     },
 
 
     skipBeforeCallback(callback, options={}) {
-        addCallback(this, callback, options, beforeCallbacksToSkip);
+        addCallback(this, callback, options, 'beforeSkip');
     },
 
 
     skipAfterCallback(callback, options={}) {
-        addCallback(this, callback, options, afterCallbacksToSkip);
+        addCallback(this, callback, options, 'afterSkip');
     },
 
 
     async _runCallbacks(type, actionName) {
-        let callbacksList, callbacksToSkipList;
-
-        switch(type) {
-            case 'after':
-                callbacksList       = callbacksListForController(afterCallbacks, this);
-                callbacksToSkipList = callbacksListForController(afterCallbacksToSkip, this);
-                break;
-            case 'before':
-                callbacksList       = callbacksListForController(beforeCallbacks, this);
-                callbacksToSkipList = callbacksListForController(beforeCallbacksToSkip, this);
-                break;
-        }
+        const callbacksList       = registry.list(type, this);
+        const callbacksToSkipList = registry.list(`${type}Skip`, this);
 
         return await APM.startSegment(`${type}Callbacks`, true, () => {
             return runCallbacks(callbacksList, callbacksToSkipList, actionName, this);
@@ -121,10 +76,10 @@ const InstanceMethods = {
 
 
     isAuthenticatedAction(actionName) {
-        const list  = callbacksListForController(beforeCallbacks, this);
+        const list  = registry.list('before', this);
         const entry = list.find(({ callback }) => callback === AUTH_CALLBACK_NAME);
         if (!entry) return false;
-        return shouldRunCallback(actionName, entry.options);
+        return appliesToAction(actionName, entry.options);
     }
 }
 

package/lib/server/controllerMixins/classScopedRegistry.js

@@ -0,0 +1,48 @@
+function appliesToAction(actionName, options) {
+    if (options.only) {
+        if (Array.isArray(options.only)) return options.only.includes(actionName);
+        return options.only == actionName;
+    }
+
+    if (options.except) {
+        if (Array.isArray(options.except)) return !options.except.includes(actionName);
+        return options.except != actionName;
+    }
+
+    return true;
+}
+
+
+class ClassScopedRegistry {
+    #lists = new Map();
+    #setup = new Map();
+
+
+    list(name, controller) {
+        const byClass = this.#listsFor(name);
+        const cls     = controller.constructor;
+        if (!byClass.has(cls)) byClass.set(cls, []);
+        return byClass.get(cls);
+    }
+
+
+    #listsFor(name) {
+        if (!this.#lists.has(name)) this.#lists.set(name, new Map());
+        return this.#lists.get(name);
+    }
+
+
+    applySetupOnce(controller, hookName) {
+        const cls = controller.constructor;
+        if (!this.#setup.has(cls)) {
+            controller[hookName]();
+            this.#setup.set(cls, true);
+        }
+
+        // run the hook once when the instance is constructed and prevent it from being called again
+        controller[hookName] = undefined;
+    }
+}
+
+
+module.exports = { ClassScopedRegistry, appliesToAction };

package/lib/server/controllerMixins/documentation.js

@@ -1,36 +1,68 @@
-const { camelize }  = require('inflection');
+const { ClassScopedRegistry, appliesToAction } = require('./classScopedRegistry');
 
 
-const StaticMethods = {
-    documentationForAction(actionName) {
-        const methodName = this.documentationMethodForAction(actionName);
-        if (this[methodName]) return this[methodName]();
-        return null;
+const registry = new ClassScopedRegistry();
+
+
+const InstanceMethods = {
+    setupDocumentation() {},
+
+
+    _applyDocumentation() {
+        registry.applySetupOnce(this, 'setupDocumentation');
     },
 
 
-    documentationMethodForAction(actionName) {
-        return `document${camelize(actionName)}`;
+    documentationTag(name, options = {}) {
+        registry.list('tags', this).push({ name, options });
     },
 
 
+    tagsForAction(actionName) {
+        return registry.list('tags', this)
+            .filter(({ options }) => appliesToAction(actionName, options))
+            .map(({ name }) => name);
+    }
+}
+
+
+const StaticMethods = {
     isAuthenticatedAction(actionName) {
-        const controller = new this();
+        const controller = new this({}, {});
         return controller.isAuthenticatedAction(actionName);
     },
 
 
     _authenticationDocumentation(actionName) {
         if (!this.isAuthenticatedAction(actionName)) return undefined;
+        return [this.authenticationDocumentation(actionName)];
     },
 
 
     authenticationDocumentation(actionName) {
         return {apiKeyAuth: []};
+    },
+
+
+    _tagsDocumentation(actionName) {
+        const controller = new this({}, {});
+        return controller.tagsForAction(actionName);
+    },
+
+
+    documentationTagDefinitions() {
+        const controller  = new this({}, {});
+        const list        = registry.list('tags', controller);
+        const definitions = new Map();
+        for (const { name, options } of list) {
+            if (!definitions.has(name)) definitions.set(name, options.description || '');
+        }
+        return [...definitions].map(([name, description]) => ({ name, description }));
     }
 }
 
 
 module.exports = {
+    InstanceMethods,
     StaticMethods
 }