@vida-global/core 2.0.11 → 2.1.0

package/lib/server/doc/requestDetails.md

@@ -0,0 +1,52 @@
+# Request details
+
+How a controller reads inbound request state, works with cookies, and coerces parameters.
+
+
+## Request Properties
+
+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
+```

package/lib/server/doc/validations.md

@@ -0,0 +1,40 @@
+# 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';
+    }
+}
+```
+
+## Supported validators
+
+- `{ optional: true }` — skip validation when the value is `undefined`.
+- `{ presence: true }`
+- `{ isInteger: true }` or `{ isInteger: { gte: 0, lte: 100 } }`
+- `{ isNumber: true }` or `{ isNumber: { gte: 0, lte: 9.99 } }` — accepts integers and decimals.
+- `{ 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' } }`
+- `{ isArray: true }` or `{ isArray: { of: { isInteger: { gte: 1 } }, length: { gte: 1, lte: 50 } } }` — `of` validates every element against the nested definition; `length` bounds the item count.
+- `{ isObject: true }` or `{ isObject: { properties: { city: { isString: true }, zip: { isString: true, optional: true } } } }` — `properties` validates each declared field against its nested definition.
+- `{ function: someFn }` — return a string to flag an error.
+
+`of` and `properties` take the same validator-definition shape as a top-level parameter, so arrays and objects can nest arbitrarily.

package/lib/server/index.js

@@ -1,7 +1,7 @@
 const { VidaServer }           = require('./server');
 const { VidaServerController } = require('./serverController');
 const   Errors                 = require('./errors');
-const { ApiDocsGenerator }    = require('./apiDocsGenerator');
+const { ApiDocsGenerator }    = require('./openApi/apiDocsGenerator');
 
 
 module.exports = {

package/lib/server/openApi/apiDocGenerator.js

@@ -0,0 +1,426 @@
+const { Schemas }        = require('./schemas');
+const { SchemaRegistry } = require('./schemaRegistry');
+const { YamlLoader }     = require('../../utils/yamlLoader');
+const { statusTextFor }  = require('../statusTexts');
+
+
+const ERROR_MESSAGE_SCHEMA = { type: 'string', nullable: true };
+const ERROR_FIELDS_SCHEMA  = { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } };
+
+const BODY_MARKER_KEY = '__vidaApiDocBodyMarker__';
+const BODY_MARKER     = { [BODY_MARKER_KEY]: true };
+const MESSAGE_MARKER  = { __vidaApiDocMessageMarker__: true };
+const FIELDS_MARKER   = { __vidaApiDocFieldsMarker__: true };
+
+
+class ApiDocGenerator {
+    #action;
+    #_allRequestInputs;
+    #controllerClass;
+    #details;
+    #documentation;
+    #_requestInputsByName;
+    #_pathParamNames;
+    #schemaRegistry;
+
+
+    constructor(action, controllerClass, schemaRegistry = new SchemaRegistry()) {
+        this.#action          = action;
+        this.#controllerClass = controllerClass;
+        this.#schemaRegistry  = schemaRegistry;
+        this.#details         = this.#loadActionDocumentation();
+    }
+
+
+    #loadActionDocumentation() {
+        if (!YamlLoader.fileExists(this.#actionDocumentationPath)) return {};
+        return YamlLoader.loadFile(this.#actionDocumentationPath);
+    }
+
+
+    get #actionDocumentationPath() {
+        return `${this.#controllerClass.documentationDirectory}/${this.#action.action}.yaml`;
+    }
+
+
+    get schemaRegistry() {
+        return this.#schemaRegistry;
+    }
+
+
+    get hasDocumentation() {
+        if (this.skip) return false;
+        return Boolean(this.#details.description);
+    }
+
+
+    get skip() {
+        return this.#details.skip === true;
+    }
+
+
+    get documentation() {
+        if (!this.#documentation) {
+            this.#documentation = this.#generateDocumentation();
+        }
+        return structuredClone(this.#documentation);
+    }
+
+
+    #generateDocumentation() {
+        const documentation = {
+            operationId: this.operationId,
+            summary:     this.summary,
+            description: this.description,
+            parameters:  this.parameters,
+            responses:   this.responses,
+        };
+
+        const requestBody = this.requestBody;
+        if (requestBody) documentation.requestBody = requestBody;
+
+        const security = this.security;
+        if (security) documentation.security = security;
+
+        const tags = this.tags;
+        if (tags && tags.length) documentation.tags = tags;
+
+        return documentation;
+    }
+
+
+    get security() {
+        return this.#controllerClass._authenticationDocumentation(this.#action.action);
+    }
+
+
+    get tags() {
+        return this.#controllerClass._tagsDocumentation(this.#action.action);
+    }
+
+
+    get responses() {
+        const responses = this.#details.responses;
+        if (!responses) return { '200': { description: 'Successful response' } };
+        return this.#formatResponses(responses);
+    }
+
+
+    #formatResponses(responses) {
+        const formatted = {};
+        for (const [status, def] of Object.entries(responses)) {
+            formatted[status] = this.#formatResponse(status, def);
+        }
+        return formatted;
+    }
+
+
+    #formatResponse(status, def) {
+        const response = { description: def.description || '' };
+        if (def.body === undefined) return response;
+
+        const dataSchema = this.#responseSchema(def.body);
+        const envelope   = this.#envelopeSchema(status);
+        const schema     = this.#schematizeNode(envelope, dataSchema);
+        response.content = { 'application/json': { schema } };
+        return response;
+    }
+
+
+    #envelopeSchema(status) {
+        const code   = Number(status);
+        const errors = code >= 400 ? this.#controllerClass.formatErrors(MESSAGE_MARKER, FIELDS_MARKER) : null;
+        return this.#controllerClass.formatResponseBody(BODY_MARKER, errors, {
+            statusCode: code,
+            statusText: statusTextFor(code),
+        });
+    }
+
+
+    #schematizeNode(node, dataSchema) {
+        if (node === BODY_MARKER)    return dataSchema;
+        if (node === MESSAGE_MARKER) return structuredClone(ERROR_MESSAGE_SCHEMA);
+        if (node === FIELDS_MARKER)  return structuredClone(ERROR_FIELDS_SCHEMA);
+        if (Array.isArray(node))     return node.map(item => this.#schematizeNode(item, dataSchema));
+        if (node !== null && typeof node === 'object') return this.#schematizeObject(node, dataSchema);
+        return this.#schematizeScalar(node);
+    }
+
+
+    #schematizeObject(node, dataSchema) {
+        if (this.#isBodySpread(node)) return this.#schematizeSpread(node, dataSchema);
+        const properties = {};
+        for (const [key, value] of Object.entries(node)) {
+            properties[key] = this.#schematizeNode(value, dataSchema);
+        }
+        return { type: 'object', properties };
+    }
+
+
+    #schematizeSpread(node, dataSchema) {
+        const properties = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key === BODY_MARKER_KEY) continue;
+            properties[key] = this.#schematizeNode(value, dataSchema);
+        }
+        return this.#mergeBodyProperties(properties, dataSchema);
+    }
+
+
+    #mergeBodyProperties(properties, dataSchema) {
+        if (!this.#isObjectSchema(dataSchema)) {
+            return { type: 'object', properties, allOf: [dataSchema] };
+        }
+        Object.assign(properties, dataSchema.properties);
+        const schema = { type: 'object', properties };
+        if (dataSchema.required) schema.required = dataSchema.required;
+        return schema;
+    }
+
+
+    #schematizeScalar(value) {
+        return { type: typeof value, example: value };
+    }
+
+
+    #isBodySpread(node) {
+        return Object.prototype.hasOwnProperty.call(node, BODY_MARKER_KEY);
+    }
+
+
+    #isObjectSchema(schema) {
+        return Boolean(schema && schema.type === 'object' && schema.properties);
+    }
+
+
+    #responseSchema(node) {
+        if (Array.isArray(node))                       return this.#responseSchemaArray(node);
+        if (node !== null && typeof node === 'object') return this.#responseSchemaObject(node);
+        return node;
+    }
+
+
+    #responseSchemaArray(nodes) {
+        return nodes.map(node => this.#responseSchema(node));
+    }
+
+
+    #responseSchemaObject(node) {
+        if (node.ref !== undefined) return this.#refSchema(node.ref);
+        const schema = {};
+        for (const [key, value] of Object.entries(node)) {
+            schema[key] = this.#responseSchema(value);
+        }
+        return schema;
+    }
+
+
+    get endpoint() {
+        return this.#action.path.replace(/:([^/]+)/g, '{$1}');
+    }
+
+
+    get method() {
+        return this.#action.method.toLowerCase();
+    }
+
+
+    get operationId() {
+        const action = this.#action.action;
+        const prefix = this.#controllerPrefix;
+        if (!prefix) return action;
+        return `${prefix}${action.charAt(0).toUpperCase()}${action.slice(1)}`;
+    }
+
+
+    get #controllerPrefix() {
+        const name = this.#controllerClass.name;
+        if (!name) return '';
+        const base = name.replace(/Controller$/, '');
+        return base.charAt(0).toLowerCase() + base.slice(1);
+    }
+
+
+    get description() {
+        return this.#details.description || null;
+    }
+
+
+    get summary() {
+        return this.#details.summary || null;
+    }
+
+
+    /***********************************************************************************************
+    * INPUTS
+    ***********************************************************************************************/
+    get parameters() {
+        return [
+            ...Object.values(this.pathParams),
+            ...Object.values(this.queryParams),
+        ];
+    }
+
+
+    get requestBody() {
+        const properties = this.bodyProperties;
+        if (!Object.keys(properties).length) return undefined;
+
+        const required = Object.keys(properties).filter(name => this.#isRequired(this.#requestInputsByName[name]));
+        const schema   = { type: 'object', properties };
+        if (required.length) schema.required = required;
+
+        return {
+            required: required.length > 0,
+            content:  { [this.#requestMediaType]: { schema } },
+        };
+    }
+
+
+    get #requestMediaType() {
+        if (this.#hasBinaryBodyProperty) return 'multipart/form-data';
+        return 'application/json';
+    }
+
+
+    get #hasBinaryBodyProperty() {
+        return Object.values(this.bodyProperties).some(property => property.format === 'binary');
+    }
+
+
+    get pathParams() {
+        const params = this.#allRequestInputs.filter(([name, _]) => this.#pathParamNames.includes(name));
+        return this.#formatInputs(Object.fromEntries(params), 'path');
+    }
+
+
+    get queryParams() {
+        const params = this.#allRequestInputs.filter(([name, details]) => {
+            if (this.#pathParamNames.includes(name)) return false;
+            if (details?.queryParameter === true)         return true;
+            return this.method == 'get' || this.method == 'delete';
+        });
+        return this.#formatInputs(Object.fromEntries(params), 'query');
+    }
+
+
+    get bodyProperties() {
+        const inputs = this.#allRequestInputs.filter(([name, _]) => {
+            if (this.#pathParamNames.includes(name)) return false;
+            return this.method == 'post' || this.method == 'put';
+        });
+        return this.#formatInputs(Object.fromEntries(inputs), 'body');
+    }
+
+
+    #formatInputs(inputs, type) {
+        const formatted = {};
+        for (const [name, details] of Object.entries(inputs || {})) {
+            formatted[name] = this.#formatInput(name, details, type);
+        }
+        return formatted;
+    }
+
+
+    #formatInput(name, details, type) {
+        if (type == 'body') {
+            return this.#formatBodyProperty(name, details);
+        } else {
+            return this.#formatParam(name, details, type);
+        }
+    }
+
+
+    #formatParam(name, details, type) {
+        const schema = this.#schemaFor(details);
+        const param  = {
+            name,
+            in:          type,
+            required:    type == 'path' || this.#isRequired(details),
+            description: details.description || '',
+            schema,
+        };
+        if (details.example !== undefined) {
+            param.example = details.example;
+            delete schema.example;
+        }
+        return param;
+    }
+
+
+    #formatBodyProperty(name, details) {
+        return {
+            ...this.#schemaFor(details),
+            description: details.description || '',
+        };
+    }
+
+
+    get #pathParamNames() {
+        if (!this.#_pathParamNames) {
+            const names = this.endpoint.match(/{[^}]+}/g) || [];
+            this.#_pathParamNames = names.map(p => {
+                return p.replace(/[{}]/g, '')
+            });
+        }
+        return this.#_pathParamNames;
+    }
+
+
+    get #allRequestInputs() {
+        if (!this.#_allRequestInputs) {
+            const inputs            = this.#controllerClass.parametersForAction(this.#action.action) || {};
+            this.#_allRequestInputs = Object.entries(inputs);
+        }
+        return this.#_allRequestInputs;
+    }
+
+
+    get #requestInputsByName() {
+        if (!this.#_requestInputsByName) {
+            this.#_requestInputsByName = Object.fromEntries(this.#allRequestInputs);
+        }
+        return this.#_requestInputsByName;
+    }
+
+
+    #isRequired(details) {
+        return details.optional !== true;
+    }
+
+
+    /***********************************************************************************************
+    * SCHEMA
+    ***********************************************************************************************/
+    #schemaFor(details) {
+        if (details.ref !== undefined) return this.#refSchema(details.ref);
+        const schema = Schemas.for(details, ref => this.#refSchema(ref));
+        if (details.example  !== undefined) schema.example  = details.example;
+        if (details.default  !== undefined) schema.default  = details.default;
+        if (details.format   !== undefined) schema.format   = details.format;
+        if (details.nullable !== undefined) schema.nullable = details.nullable;
+        return schema;
+    }
+
+
+    #refSchema(ref) {
+        const cls = (typeof ref === 'string') ? this.#schemaRegistry.resolve(ref) : ref;
+        if (!cls || typeof cls.documentationSchema !== 'function') {
+            throw new Error('A ref target must expose a static documentationSchema() method');
+        }
+        const name = this.#schemaName(cls);
+        if (!this.#schemaRegistry.has(name)) {
+            this.#schemaRegistry.reserve(name);
+            this.#schemaRegistry.set(name, { type: 'object', properties: cls.documentationSchema() });
+        }
+        return { $ref: `#/components/schemas/${name}` };
+    }
+
+
+    #schemaName(cls) {
+        return cls.documentationSchemaName || cls.name;
+    }
+}
+
+
+module.exports = { ApiDocGenerator };

package/lib/server/openApi/apiDocsGenerator.js

@@ -0,0 +1,147 @@
+const { ApiDocGenerator }    = require('./apiDocGenerator');
+const { ControllerImporter } = require('../controllerImporter');
+const { SchemaRegistry }     = require('./schemaRegistry');
+const { TagRegistry }        = require('./tagRegistry');
+
+
+class ApiDocsGenerator {
+    #_controllerClasses;
+    #title;
+    #version;
+    #_paths;
+    #_packageInfo;
+    #schemaRegistry;
+    #tagRegistry;
+    #server;
+
+    constructor(server, { title, version } = {}) {
+        this.#server                = server;
+        this.#title                 = title   || '';
+        this.#version               = version || '';
+        this.#schemaRegistry        = new SchemaRegistry(server);
+        this.#tagRegistry           = new TagRegistry();
+    }
+
+
+    /***********************************************************************************************
+    * OPENAPI DOCUMENT
+    ***********************************************************************************************/
+    get specification() {
+        const paths         = this.paths;
+        const tags          = this.tags;
+        const specification = {
+            openapi: '3.0.0',
+            info:    this.info,
+            servers: this.servers,
+        };
+        if (tags.length) specification.tags = tags;
+        specification.paths      = paths;
+        specification.components = this.components;
+        return specification;
+    }
+
+
+    get tags() {
+        if (!this.#_paths) this.#collectPaths();
+        return this.#tagRegistry.tags;
+    }
+
+
+    get info() {
+        return {
+            title:       this.#title   || this.#packageInfo.name        || '',
+            version:     this.#version || this.#packageInfo.version     || '',
+            description: this.#packageInfo.description                  || '',
+        };
+    }
+
+
+    get servers() {
+        return [{ url: this.#server.origin }];
+    }
+
+
+    get paths() {
+        if (!this.#_paths) this.#collectPaths();
+        return this.#_paths;
+    }
+
+
+    get components() {
+        const components = {
+            securitySchemes: this.#server.securitySchemes
+        };
+        const schemas = this.#schemaRegistry.schemas;
+        if (Object.keys(schemas).length) components.schemas = schemas;
+        return components;
+    }
+
+
+    /***********************************************************************************************
+    * DOC GENERATION
+    ***********************************************************************************************/
+    #collectPaths() {
+        this.#_paths = {};
+        this.#controllerClasses.forEach(controllerClass => {
+            controllerClass.actions.forEach(action => {
+                this.#generateDocsForAction(action, controllerClass);
+            });
+        });
+    }
+
+
+    #generateDocsForAction(action, controllerClass) {
+        const generator = new ApiDocGenerator(action, controllerClass, this.#schemaRegistry);
+        if (!generator.hasDocumentation) return;
+
+        const endpoint                 = generator.endpoint;
+        const method                   = generator.method;
+        this.#_paths[endpoint]         = this.#_paths[endpoint] || {};
+        this.#_paths[endpoint][method] = generator.documentation;
+        this.#registerTags(generator, controllerClass);
+    }
+
+
+    #registerTags(generator, controllerClass) {
+        const usedNames = generator.tags || [];
+        if (!usedNames.length) return;
+
+        const definitions  = controllerClass.documentationTagDefinitions();
+        const descriptions = new Map(definitions.map(({ name, description }) => [name, description]));
+        for (const name of usedNames) {
+            this.#tagRegistry.register(name, descriptions.get(name) || '');
+        }
+    }
+
+
+    get #controllerClasses() {
+        if (!this.#_controllerClasses) {
+            const controllerImporter  = new ControllerImporter(this.#server.controllerDirectories);
+            this.#_controllerClasses  = controllerImporter.controllerClasses;
+        }
+        return [...this.#_controllerClasses];
+    }
+
+
+    /***********************************************************************************************
+    * PACKAGE INFO
+    ***********************************************************************************************/
+    get #packageInfo() {
+        if (!this.#_packageInfo) this.#_packageInfo = this.#loadPackageInfo();
+        return this.#_packageInfo;
+    }
+
+
+    #loadPackageInfo() {
+        try {
+            return require(`${process.cwd()}/package.json`);
+        } catch {
+            return {};
+        }
+    }
+}
+
+
+module.exports = {
+    ApiDocsGenerator
+}