@vida-global/core 1.1.0

package/README.md

@@ -0,0 +1,9 @@
+# Vida/Core
+This package is intended to contain core elements used across all Vida Apps. Keep in mind that it's included in the `vida-apps-tools` package, so customers developing Vida Apps will have access to it.
+
+# Guides
+
+- [ActiveRecord](lib/active_record)
+- [HttpClient](lib/http)
+- [Logger](lib/logger)
+- [VidaServer](lib/server)

package/index.js

@@ -0,0 +1,17 @@
+const { HttpClient, HttpError } = require('./lib/http/client');
+const { AuthorizationError,
+        VidaServer,
+        VidaServerController }  = require('./lib/server');
+const { logger }                = require('./lib/logger');
+const   ActiveRecord            = require('./lib/active_record');
+
+
+module.exports = {
+    ActiveRecord,
+    AuthorizationError,
+    HttpClient,
+    HttpError,
+    logger,
+    VidaServer,
+    VidaServerController,
+};

package/lib/active_record/README.md

@@ -0,0 +1,205 @@
+# Configuration
+To configure your database, create a `config.js` file in the `config/db/` directory of your project. That file should follow this format:
+```
+module.exports = {
+    default: {
+        development: {
+            database: process.env.DATABASE,
+            host: process.env.DB_HOST,
+            password: process.env.DB_PASSWORD,
+            username: process.env.DB_USERNAME
+        },
+        production: {
+            ...
+        },
+        ...
+    }
+}
+```
+
+Add additional entries for multiple databases
+```
+module.exports = {
+    default: {
+        ...
+    },
+    metrics: {
+        development: {
+            database: process.env.DATABASE,
+            host: process.env.DB_HOST,
+            password: process.env.DB_PASSWORD,
+            username: process.env.DB_USERNAME
+        },
+        production: {
+            ...
+        },
+        ...
+    },
+    ...
+}
+```
+
+
+### Connection Pooling
+Minimum and maximum connection pool sizes can be configured in config.js, but default to 0 and 5, respectively.
+```
+development: {
+    database: process.env.DATABASE,
+    host: process.env.DB_HOST,
+    password: process.env.DB_PASSWORD,
+    username: process.env.DB_USERNAME,
+    pool: {
+        min: 1,
+        max: 10
+    }
+}
+```
+
+
+### Replication
+Read replicas can be configured by adding a `readers` key to your configuration
+```
+development: {
+    database: process.env.DATABASE,
+    host: process.env.DB_HOST,
+    password: process.env.DB_PASSWORD,
+    username: process.env.DB_USERNAME,
+    readers: [
+        {
+            database: ...
+            host: ...
+            password: ...
+            username: ...
+        },
+        {
+            ...
+        }
+    }
+}
+```
+
+
+# Migrations
+To prepare your project to run database migrations, add the following lines to the `scripts` section of your `package.json`:
+```
+"db:create_migration": "node node_modules/@vida-global/core/scripts/active_record/migrate.js create_migration",
+"db:migrate": "node node_modules/@vida-global/core/scripts/active_record/migrate.js migrate",
+"db:rollback": "node node_modules/@vida-global/core/scripts/active_record/migrate.js rollback"
+```
+
+To generate a new migration file, run: `npm run db:create_migration createUsers`. This will automatically generate a migration file. Your migration can create tables, create indexes, and add, remove, or update columns.
+```
+module.exports = {
+    up: async function() {
+        await this.createTable('users', {
+            email: this.DataTypes.STRING,
+            team_id: this.DataTypes.INTEGER,
+            is_admin: {
+                type: this.DataTypes.BOOLEAN,
+                defaultValue: false,
+                allowNull: false,
+            }
+        });
+
+        await this.addIndex('users', ['team_id'], {where: {team_id: {[this.Operators.ne]: null}}});
+        await this.addIndex('users', ['email'], {unique: true});
+    },
+
+    down: async function () {
+        await this.dropTable('users');
+    }
+}
+```
+Available migrations are:
+```
+createTable(tableName, details)
+dropTable(tableName)
+addColumn(tableName, columnName, columnDetails)
+removeColumn(tableName, columnName)
+addIndex(tableName, fields, { concurrently, unique, name, where })
+removeIndex(tableName, indexNameOrAttributes, concurrently=false)
+renameColumn(tableName, oldName, newName)
+changeColumn(tableName, columnName, dataTypeOrOptions)
+```
+To run your migrations, run `npm run db:migrate` or `npm run db:rollback` to rollback a single migration.
+
+**NOTE**: By default, `createTable` automatically adds an autoincrement, primary key `id` column, a `created_at` column, and an `updated_at` column.
+
+
+# Models
+The following code will create a basic model representing a user in our database:
+```
+const { ActiveRecord } = require('@vida-global/core')
+
+class User extends ActiveRecord.BaseRecord {
+}
+
+User.initialize();
+
+const user = new User({email: 'mark@vida.inc', team_id: 1, is_admin: false});
+await user.save();
+
+user.is_admin = true;
+await user.save();
+
+await user.destroy();
+```
+
+
+### Querying Models
+```
+const users = await User.findAll();
+const users = await User.findAll{where: {team_id: 1}});
+const users = await User.findAll{where: User.Operator
+
+const users = await User.findAll({where: {
+    team_id: {
+        [Recording.Operators.or]: [1,2]
+    }
+}});
+
+```
+
+
+### Aggregators and Functions
+```
+const rows = await User.findAll({
+    attributes: ['team_id', [User.fn('MAX', User.col('id')), 'max_id']],
+    group: 'team_id'
+});
+
+const { count, users } = await User.findAndCountAll({
+    where: {
+        email: {
+            [User.Operators.like]: '%@vida.inc',
+        },
+    },
+    offset: 0,
+    limit: 1,
+});
+
+const totalCount = await User.count({where: {team_id: 1}});
+```
+More examples can be found here, https://sequelize.org/docs/v6/core-concepts/model-querying-basics/.
+
+**Note** The `sequelize.fn`, `sequelize.col`, and `Op` properties have been added as helpers on the Model (e.g. `User.fn('MAX', User.col('id'), 'max_id')` and `User.Operators.or`)
+
+
+### Associations
+**TODO**
+
+
+### Validators
+**TODO**
+
+
+### Hooks
+**TODO**
+
+
+### Paranoid
+**TODO**
+
+
+# Closing Connections
+When cleaning up your application, close all open connections with `User.closeAllConnections()`. This will close all connections for all models, not just the `User` model.

package/lib/active_record/baseRecord.js

@@ -0,0 +1,112 @@
+const { Connection, DEFAULT_DATABASE_ID } = require('./db/connection');
+const { getActiveRecordSchema }           = require('./db/schema');
+const { Model, Op }                       = require('sequelize');
+const { tableize }                        = require('inflection');
+const   utils                             = require('./utils');
+const   nodeUtil                          = require('util');
+
+
+
+class BaseRecord extends Model {
+    static _connection;
+    static _initialized = false;
+
+
+    static Operators = Op;
+    static get fn()  { return this.connection._sequelize.fn }
+    static get col() { return this.connection._sequelize.col }
+
+
+    constructor() {
+        if (new.target == BaseRecord) throw new Error("BaseRecord must be subclasses");
+        super(...arguments);
+    }
+
+
+    /***********************************************************************************************
+    * QUERIES
+    ***********************************************************************************************/
+    static async find(id) {
+        return await this.findByPk(id);
+    }
+
+
+    static async where(where, options={}) {
+        const parameters = {...options, where };
+        return await this.findAll(parameters);
+    }
+
+
+    /***********************************************************************************************
+    * INITIALIZATION
+    ***********************************************************************************************/
+    static initialize() {
+        if (this == BaseRecord) throw new Error("BaseRecord must be subclasses");
+
+        if (this._initialized) return;
+
+        const schema  = getActiveRecordSchema(this._tableName, this.databaseId, this.connection.dialect);
+        const options = {
+            createdAt: 'created_at',
+            deletedAt: 'deleted_at',
+            modelName: this.name,
+            sequelize: this.connection._sequelize,
+            tableName: this._tableName,
+            updatedAt: 'updated_at',
+        }
+
+        if (!schema.created_at || !schema.updated_at) {
+            options.timestamps = false;
+        }
+
+        this.init(schema, options);
+
+        this._initialized = true;
+    }
+
+
+    /***********************************************************************************************
+    * DB CONNECTION
+    ***********************************************************************************************/
+    static get connection() {
+        if (!this._connection) {
+            this._connection = new Connection(this.constructor.databaseId);
+        }
+        return this._connection;
+    }
+
+
+    static get databaseId() {
+        return DEFAULT_DATABASE_ID;
+    }
+
+
+    static get _tableName() {
+        return tableize(this.name);
+    }
+
+
+    static closeConnection() {
+        this.connection.close();
+    }
+
+
+    static closeAllConnections() {
+        Connection.closeAll();
+    }
+
+
+    /***********************************************************************************************
+    * MISC
+    ***********************************************************************************************/
+    [nodeUtil.inspect.custom](opts) {
+        const args = Array.from(arguments);
+        args.shift();
+        return nodeUtil.inspect(this.dataValues, ...args);
+    }
+}
+
+
+module.exports = {
+    BaseRecord
+};

package/lib/active_record/db/connection.js

@@ -0,0 +1,128 @@
+const { QueryInterface }          = require('./queryInterface');
+const { ConnectionConfiguration } = require('./connectionConfiguration');
+const { Sequelize }               = require('sequelize');
+
+
+let   sequelizeConnectionsCache = {};
+const DEFAULT_DATABASE_ID       = 'default';
+
+
+class Connection {
+    #configuration;
+    #databaseId;
+    #options;
+
+    constructor(databaseId, options={}) {
+        this.#databaseId    = databaseId || DEFAULT_DATABASE_ID;
+        this.#configuration = new ConnectionConfiguration(this.#databaseId);
+        this.#options       = options;
+    }
+
+
+    close() {
+        this._sequelize.close();
+    }
+
+
+    static closeAll() {
+        Object.values(sequelizeConnectionsCache).forEach(sequelize => {
+            sequelize.close();
+        });
+    }
+
+
+    static clearConnectionsCache() {
+        this.closeAll();
+        sequelizeConnectionsCache = {};
+    }
+
+
+    get queryInterface() {
+        return new QueryInterface(this);
+    }
+
+
+    get _sequelize() {
+        if (sequelizeConnectionsCache[this.#databaseId]) return sequelizeConnectionsCache[this.#databaseId];
+
+        const connection = new Sequelize(null, null, null, this.sequelizeOptions);
+        sequelizeConnectionsCache[this.#databaseId] = connection;
+
+        return connection;
+    }
+
+
+    get sequelizeOptions() {
+        const options = {
+            ...this.dialectOptions,
+            define:  { underscored: true },
+            dialect: this.dialect,
+        };
+
+        if (!this.loggingEnabled) options.logging = false;
+
+        return options;
+    }
+
+
+    get dialectOptions() {
+        if (this.dialect == 'sqlite') {
+            return this.sqliteSequelizeOptions;
+        } else {
+            return this.postgresSequelizeOptions;
+        }
+    }
+
+
+    get postgresSequelizeOptions() {
+        const options = {
+            pool: this.#configuration.pool,
+        };
+
+        const primaryConfig = {
+            database: this.#configuration.database,
+            host:     this.#configuration.host,
+            password: this.#configuration.password,
+            port:     this.#configuration.port,
+            username: this.#configuration.username
+        };
+
+        if (this.#configuration.readers.length) {
+            options.replication = {
+                write: primaryConfig,
+                read: this.#configuration.readers
+            }
+        } else {
+            Object.assign(options, primaryConfig);
+        }
+
+        if (this.#configuration.ssl) options.dialectOptions = {ssl: {require: true}};
+        return options;
+    }
+
+
+    get sqliteSequelizeOptions() {
+        return {
+            storage: this.#configuration.storage
+        };
+    }
+
+
+    get loggingEnabled() {
+        if (this.#options.hasOwnProperty('loggingEnabled')) {
+            return this.#options.loggingEnabled;
+        }
+        return this.#configuration.loggingEnabled;
+    }
+
+
+    get dialect() {
+        return this.#configuration.dialect;
+    }
+}
+
+
+module.exports = {
+    Connection,
+    DEFAULT_DATABASE_ID
+}

package/lib/active_record/db/connectionConfiguration.js

@@ -0,0 +1,114 @@
+const utils = require('../utils');
+
+
+class ConnectionConfiguration {
+    #_config;
+    #databaseId;
+
+    constructor(databaseId) {
+        this.#databaseId = databaseId;
+        this.#validateConfiguration();
+    }
+
+
+    get databaseId()     { return this.#databaseId };
+
+    get dialect()        { return this.#config.dialect || 'postgres' };
+    get database()       { return this.#config.database };
+    get host()           { return this.#config.host };
+    get password()       { return this.#config.password };
+    get port()           { return this.#config.port || 5432 };
+    get username()       { return this.#config.username };
+    get ssl()            { return Boolean(this.#config.ssl) };
+    get storage()        { return `${utils.configDirectory}/database.${this.env}.sqlite` };
+
+    get readers()        { return this.#config.readers || [] };
+
+    get pool()           { return {min: this.#poolMin, max: this.#poolMax}}
+    get #poolMin()       { return this.#config.pool?.min || 0 }
+    get #poolMax()       { return this.#config.pool?.max || 5 }
+
+    get loggingEnabled() { return this.env == 'development' };
+
+
+    #validateConfiguration() {
+        const config = this.#config;
+        this.#keysToValidate.forEach(key => {
+            if (!config[key]) throw new Error(`Missing ${key} for database configuration ${this.#configId}`);
+        });
+    }
+
+
+    get #keysToValidate() {
+        if (this.dialect == 'postgres') {
+            return ['database', 'host', 'password', 'username'];
+        }
+        return [];
+    }
+
+ 
+    get #configId() {
+        return `${this.#databaseId}.${this.env}`;
+    }
+
+
+    get #config() {
+        if (this.#_config) return this.#_config[this.env];
+
+        if (!this._allConfigs) throw new Error(`Missing database configuration`);
+
+        const config = this._allConfigs[this.#databaseId];
+        if (!config || !config[this.env]) throw new Error(`Missing database configuration for ${this.#configId}`);
+
+        this.#_config = config;
+        return this.#_config[this.env];
+    }
+
+
+    /***********************************************************************************************
+    * "ALL" CONFIGS 
+    ***********************************************************************************************/
+    static get _allConfigs() {
+        return structuredClone(this._fetchAllConfigs());
+    }
+
+
+    static _fetchAllConfigs() {
+        try {
+            return require(this.configFilePath);
+        } catch(err) {
+            throw new Error(`Missing or invalid ${this.configFilePath}`);
+        }
+    }
+
+
+    static get configFilePath() {
+        return `${utils.configDirectory}/config.js`;
+    }
+
+
+    static get env() {
+        return process.env.NODE_ENV || 'development';
+    }
+
+
+    get _allConfigs()    { return this.constructor._allConfigs; }
+    get configFilePath() { return this.constructor.configFilePath; }
+    get env()            { return this.constructor.env; }
+
+
+    static configuredDatabaseIds() {
+        const databaseIds = [];
+
+        for (const [databaseId, config] of Object.entries(this._allConfigs)) {
+            if (config[this.env]) databaseIds.push(databaseId);
+        }
+
+        return databaseIds
+    }
+}
+
+
+module.exports = {
+    ConnectionConfiguration
+};

package/lib/active_record/db/importSchema.js

@@ -0,0 +1,4 @@
+// This is in a separate file so that it can be easily mocked during testing
+module.exports = function(filePath, tableName) {
+    return structuredClone(require(filePath)[tableName]);
+}