@vida-global/core 2.0.11 → 2.1.0

package/lib/server/openApi/schemaImporter.js

@@ -0,0 +1,41 @@
+const { AbstractAutoImporter } = require('../../utils/abstractAutoImporter');
+
+
+class SchemaImporter extends AbstractAutoImporter {
+    #schemaClasses;
+
+
+    get schemaClasses() {
+        if (!this.#schemaClasses) this.#buildMap();
+        return this.#schemaClasses;
+    }
+
+
+    shouldImport(obj) {
+        return typeof obj?.documentationSchema === 'function';
+    }
+
+
+    #buildMap() {
+        this.#schemaClasses = new Map();
+        for (const cls of this.imports) {
+            this.#addClass(cls);
+        }
+    }
+
+
+    #addClass(cls) {
+        const name     = cls.documentationSchemaName || cls.name;
+        const existing = this.#schemaClasses.get(name);
+
+        if (existing == cls) return;
+        if (this.#schemaClasses.has(name)) {
+            throw new Error(`Duplicate documentationSchema name: ${name}`);
+        }
+
+        this.#schemaClasses.set(name, cls);
+    }
+}
+
+
+module.exports = { SchemaImporter };

package/lib/server/openApi/schemaRegistry.js

@@ -0,0 +1,43 @@
+const { SchemaImporter } = require('./schemaImporter');
+
+
+class SchemaRegistry {
+    #schemas = {};
+    #classes;
+
+
+    constructor(server = {}) {
+        const importer = new SchemaImporter(server.schemaDirectories || []);
+        this.#classes  = importer.schemaClasses;
+    }
+
+
+    resolve(name) {
+        const cls = this.#classes.get(name);
+        if (!cls) throw new Error(`Unknown schema ref: ${name}`);
+        return cls;
+    }
+
+
+    has(name) {
+        return Object.prototype.hasOwnProperty.call(this.#schemas, name);
+    }
+
+
+    reserve(name) {
+        this.#schemas[name] = {};
+    }
+
+
+    set(name, schema) {
+        this.#schemas[name] = schema;
+    }
+
+
+    get schemas() {
+        return this.#schemas;
+    }
+}
+
+
+module.exports = { SchemaRegistry };

package/lib/server/openApi/schemas.js

@@ -0,0 +1,97 @@
+class Schemas {
+    static for(details, resolveRef) {
+        if (resolveRef && details.ref !== undefined) return resolveRef(details.ref);
+        if (details.isInteger  !== undefined) return this.integerSchema(details.isInteger);
+        if (details.isNumber   !== undefined) return this.numberSchema(details.isNumber);
+        if (details.isString   !== undefined) return this.stringSchema(details.isString);
+        if (details.isBoolean  !== undefined) return this.booleanSchema();
+        if (details.isDateTime !== undefined) return this.dateTimeSchema();
+        if (details.isEnum     !== undefined) return this.enumSchema(details.isEnum);
+        if (details.isArray    !== undefined) return this.arraySchema(details.isArray, resolveRef);
+        if (details.isObject   !== undefined) return this.objectSchema(details.isObject, resolveRef);
+        return {};
+    }
+
+
+    static schemaFor(details, resolveRef) {
+        return this.for(details, resolveRef);
+    }
+
+
+    static isRequired(details) {
+        return details.optional !== true;
+    }
+
+
+    static integerSchema(options) {
+        const schema = { type: 'integer' };
+        if (options?.gte !== undefined) schema.minimum = options.gte;
+        if (options?.lte !== undefined) schema.maximum = options.lte;
+        return schema;
+    }
+
+
+    static numberSchema(options) {
+        const schema = { type: 'number' };
+        if (options?.gte !== undefined) schema.minimum = options.gte;
+        if (options?.lte !== undefined) schema.maximum = options.lte;
+        return schema;
+    }
+
+
+    static booleanSchema() {
+        return { type: 'boolean' };
+    }
+
+
+    static dateTimeSchema() {
+        return { type: 'string', format: 'date-time' };
+    }
+
+
+    static arraySchema(options, resolveRef) {
+        const schema = { type: 'array', items: options?.of ? this.schemaFor(options.of, resolveRef) : {} };
+        if (options?.length?.gte !== undefined) schema.minItems = options.length.gte;
+        if (options?.length?.lte !== undefined) schema.maxItems = options.length.lte;
+        return schema;
+    }
+
+
+    static objectSchema(options, resolveRef) {
+        const properties = {};
+        const required   = [];
+        for (const [name, details] of Object.entries(options?.properties || {})) {
+            properties[name] = this.schemaFor(details, resolveRef);
+            if (this.isRequired(details)) required.push(name);
+        }
+        const schema = { type: 'object', properties };
+        if (required.length) schema.required = required;
+        return schema;
+    }
+
+
+    static stringSchema(options) {
+        const schema = { type: 'string' };
+        if (options?.length?.gte !== undefined) schema.minLength = options.length.gte;
+        if (options?.length?.lte !== undefined) schema.maxLength = options.length.lte;
+        if (options?.regex)                     schema.pattern   = options.regex.source;
+        return schema;
+    }
+
+
+    static enumSchema(options) {
+        return { type: this.enumType(options.enums), enum: [...options.enums] };
+    }
+
+
+    static enumType(enums) {
+        if (!enums.every(value => typeof value === 'number')) return 'string';
+        if (enums.every(value => Number.isInteger(value)))    return 'integer';
+        return 'number';
+    }
+}
+
+
+module.exports = {
+    Schemas
+};

package/lib/server/openApi/tagRegistry.js

@@ -0,0 +1,27 @@
+class TagRegistry {
+    #tags = new Map();
+
+
+    register(name, description = '') {
+        if (!this.#tags.has(name)) {
+            this.#tags.set(name, description);
+            return;
+        }
+        if (!this.#tags.get(name) && description) this.#tags.set(name, description);
+    }
+
+
+    get tags() {
+        return [...this.#tags].map(([name, description]) => this.#tag(name, description));
+    }
+
+
+    #tag(name, description) {
+        const tag = { name };
+        if (description) tag.description = description;
+        return tag;
+    }
+}
+
+
+module.exports = { TagRegistry };

package/lib/server/server.js

@@ -42,6 +42,7 @@ class VidaServer {
     }
 
 
+    get origin() { return `https://${this.host}` }
     get host()   { return this.#host; }
     get port()   { return this.#port; }
     get logger() { return logger.server; }
@@ -240,6 +241,11 @@ class VidaServer {
     }
 
 
+    get schemaDirectories() {
+        return [`${process.cwd()}/models`];
+    }
+
+
     get serverEngineFactory() {
         return express;
     }
@@ -270,6 +276,14 @@ class VidaServer {
     }
 
 
+    /***********************************************************************************************
+    * DOCUMENTATION
+    ***********************************************************************************************/
+    get securitySchemes() {
+        return { apiKeyAuth: { type: 'apiKey', in: 'header', name: 'Authorization' } };
+    }
+
+
     /***********************************************************************************************
     * DEPRECATED PASS THROUGH METHODS
     ***********************************************************************************************/

package/lib/server/serverController.js

@@ -1,8 +1,8 @@
 const   APM        = require('../apm');
 const { camelize } = require('inflection');
 const   crypto     = require('node:crypto');
-const   Errors     = require('./errors');
-const { logger }   = require('../logger');
+const   Errors       = require('./errors');
+const { logger }     = require('../logger');
 
 
 class VidaServerController {
@@ -22,6 +22,7 @@ class VidaServerController {
         this.#logger   = (serverLogger || logger).child(this.requestId);
 
         this._applyCallbacks();
+        this._applyDocumentation();
         this._setupStatusRenderers();
     }
 
@@ -140,12 +141,6 @@ class VidaServerController {
     }
 
 
-    static autoLoadDocumentation() {
-        const docs = this._autoLoadModule(this.documentationDirectory);
-        Object.assign(this, docs);
-    }
-
-
     static _autoLoadModule(path) {
         try {
             return require(path);
@@ -164,7 +159,7 @@ class VidaServerController {
 
 
     static get documentationDirectory() {
-        return `${process.cwd()}/lib/controllers/_docs${this.routePrefix}Controller`;
+        return `${process.cwd()}/docs/controllers${this.routePrefix}Controller`;
     }
 
 

package/lib/server/statusTexts.js

@@ -0,0 +1,38 @@
+const STATUS_TEXTS = {
+    200: 'ok',
+    201: 'created',
+    202: 'accepted',
+    204: 'no content',
+    301: 'moved permanently',
+    302: 'found',
+    304: 'not modified',
+    307: 'temporary redirect',
+    308: 'permanent redirect',
+    400: 'bad request',
+    401: 'unauthorized',
+    402: 'payment required',
+    403: 'forbidden',
+    404: 'not found',
+    405: 'method not allowed',
+    408: 'request timeout',
+    409: 'conflict',
+    410: 'gone',
+    413: 'content too large',
+    415: 'unsupported media type',
+    422: 'unprocessable content',
+    423: 'locked',
+    429: 'too many requests',
+    500: 'server error',
+    501: 'not implemented',
+    502: 'bad gateway',
+    503: 'service unavailable',
+    504: 'gateway timeout',
+};
+
+
+function statusTextFor(code) {
+    return STATUS_TEXTS[code];
+}
+
+
+module.exports = { STATUS_TEXTS, statusTextFor };

package/lib/utils/yamlLoader.js

@@ -0,0 +1,17 @@
+const fs   = require('fs');
+const yaml = require('js-yaml');
+
+
+class YamlLoader {
+    static loadFile(path) {
+        return yaml.load(fs.readFileSync(path, 'utf8')) || {};
+    }
+
+
+    static fileExists(path) {
+        return fs.existsSync(path);
+    }
+}
+
+
+module.exports = { YamlLoader };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.0.11",
+    "version": "2.1.0",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -27,6 +27,7 @@
         "express": "^4.21.2",
         "express-request-id": "1.4.1",
         "express-winston": "^4.0.0",
+        "js-yaml": "^3.14.2",
         "mustache-express": "^1.2.8",
         "newrelic": "^13.0.0",
         "pg": "^8.16.3",
@@ -35,7 +36,8 @@
         "sequelize": "^6.37.7",
         "sequelize-cli": "^6.6.3",
         "socket.io": "^4.4.0",
-        "winston": "^3.0.0"
+        "winston": "^3.0.0",
+        "xmlbuilder2": "^4.0.0"
     },
     "devDependencies": {
         "@vida-global/test-helpers": "^1.0.1",

package/test/activeRecord/baseRecord.test.js

@@ -742,4 +742,105 @@ describe('BaseRecord', () => {
             });
         });
     });
+
+
+    describe('.documentationSchema', () => {
+        const buildModel = (attributes) => {
+            class Thing extends BaseRecord {}
+            jest.spyOn(Thing, 'initialize').mockImplementation(() => {});
+            Thing.getAttributes = () => attributes;
+            return Thing;
+        };
+
+
+        it ('builds a properties map from the table columns', () => {
+            const Thing = buildModel({
+                id:   { type: { key: 'INTEGER' } },
+                name: { type: { key: 'STRING' } },
+            });
+
+            expect(Thing.documentationSchema()).toEqual({
+                id:   { type: 'integer' },
+                name: { type: 'string' },
+            });
+        });
+
+
+        it ('excludes created_at, updated_at and deleted_at', () => {
+            const Thing = buildModel({
+                id:         { type: { key: 'INTEGER' } },
+                created_at: { type: { key: 'DATE' } },
+                updated_at: { type: { key: 'DATE' } },
+                deleted_at: { type: { key: 'DATE' } },
+            });
+
+            expect(Object.keys(Thing.documentationSchema())).toEqual(['id']);
+        });
+
+
+        it.each([
+            ['INTEGER',  { type: 'integer' }],
+            ['BIGINT',   { type: 'integer' }],
+            ['DECIMAL',  { type: 'number' }],
+            ['FLOAT',    { type: 'number' }],
+            ['BOOLEAN',  { type: 'boolean' }],
+            ['DATE',     { type: 'string', format: 'date-time' }],
+            ['JSONB',    { type: 'object', properties: {} }],
+            ['ARRAY',    { type: 'array', items: {} }],
+            ['STRING',   { type: 'string' }],
+            ['UUID',     { type: 'string' }],
+            ['GEOMETRY', { type: 'string' }],
+        ])('maps a %s column to the expected schema', (key, expected) => {
+            const Thing = buildModel({ col: { type: { key } } });
+
+            expect(Thing.documentationSchema().col).toEqual(expected);
+        });
+
+
+        it ('maps an ENUM column to its values', () => {
+            const Thing = buildModel({ status: { type: { key: 'ENUM', values: ['on', 'off'] } } });
+
+            expect(Thing.documentationSchema().status).toEqual({ type: 'string', enum: ['on', 'off'] });
+        });
+    });
+
+
+    describe('#apiResponseColumns', () => {
+        it ('returns the column names exposed by documentationSchema', () => {
+            class Thing extends BaseRecord {}
+            Thing.documentationSchema = () => ({ id: { type: 'integer' }, name: { type: 'string' } });
+            const record = Object.create(Thing.prototype);
+
+            expect(record.apiResponseColumns).toEqual(['id', 'name']);
+        });
+    });
+
+
+    describe('#toApiResponse', () => {
+        const buildRecord = (schema, values) => {
+            class Thing extends BaseRecord {}
+            Thing.documentationSchema = () => schema;
+            const record = Object.create(Thing.prototype);
+            Object.assign(record, values);
+            return record;
+        };
+
+
+        it ('returns only the columns exposed by documentationSchema', () => {
+            const record = buildRecord(
+                { id: { type: 'integer' }, name: { type: 'string' } },
+                { id: 7, name: 'widget', deleted_at: 'now' },
+            );
+
+            expect(record.toApiResponse()).toEqual({ id: 7, name: 'widget' });
+        });
+
+
+        it ('applies overridden getters when building the response', () => {
+            const record = buildRecord({ name: { type: 'string' } }, {});
+            Object.defineProperty(record, 'name', { get: () => 'OVERRIDDEN', configurable: true });
+
+            expect(record.toApiResponse()).toEqual({ name: 'OVERRIDDEN' });
+        });
+    });
 });