@vida-global/core 2.0.10 → 2.1.0

package/lib/server/doc/renderer.md

@@ -0,0 +1,115 @@
+# 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 });
+```
+
+## 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.
+
+
+## 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,
+    );
+}
+```
+
+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.

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