@vida-global/core 2.2.0 → 2.3.0

package/lib/activeRecord/README.md

@@ -72,6 +72,8 @@ Wire up the migration CLI by adding scripts to `package.json`:
 
 Generate a migration with `npm run db:create_migration createUsers`. Pass `-- --databaseId metrics` to scope the migration to a non-default database. Run `npm run db:migrate` to apply migrations or `npm run db:rollback` to undo the most recent one.
 
+Migration files are named `<timestamp>_<description>.js`, with the database id appended before the extension when one is given — for example `1754500000000_createUsers.js` or `1754500000000_createUsers.metrics.js`. The leading timestamp is the version recorded in `migration_versions` and the order migrations run in, so files sort chronologically by name. Files that don't match this pattern are ignored.
+
 ```js
 module.exports = {
     up: async function() {
@@ -98,11 +100,11 @@ module.exports = {
 Available migration helpers:
 
 ```js
-createTable(tableName, details, { timestamps, paranoid })
+createTable(tableName, details, { timestamps, paranoid, id })
 dropTable(tableName)
 addColumn(tableName, columnName, columnDetails)
 removeColumn(tableName, columnName)
-addIndex(tableName, fields, { concurrently, unique, name, where })
+addIndex(tableName, fields, { concurrently, unique, name, using, where })
 removeIndex(tableName, indexNameOrAttributes, concurrently=false)
 renameColumn(tableName, oldName, newName)
 changeColumn(tableName, columnName, dataTypeOrOptions)
@@ -110,10 +112,33 @@ changeColumn(tableName, columnName, dataTypeOrOptions)
 
 **Conventions:**
 
-- `createTable` adds an auto-increment `id` primary key and `created_at` / `updated_at` columns by default. Pass `{ timestamps: false }` to skip the timestamps.
-- Pass `{ paranoid: true }` to add a nullable `deleted_at` column. Models over that table soft delete: `initializationOptions` turns on `paranoid` for any table whose schema has `deleted_at`, so `destroy()` sets the column and ordinary queries skip the row. Unique indexes on a paranoid table should be partial — `where: { deleted_at: null }` — or a deleted row will still block re-creating the same one.
+- `createTable` adds a `BIGINT` auto-increment `id` primary key and `created_at` / `updated_at` columns by default. Pass `{ timestamps: false }` to skip the timestamps.
+- Pass `{ id: 'uuid' }` for a UUID primary key, or `{ id: 'int' }` for a 4-byte integer one. A UUID key has no database default — models generate the value, so a record has its id before it is saved. An `id` written into the details object still wins over all of this.
+- A `BIGINT` column reads back as a string (`'42'`, not `42`). Postgres returns 64-bit integers as text so nothing is lost above `Number.MAX_SAFE_INTEGER`, and nothing converts them on the way in.
+- Pass `{ paranoid: true }` to `createTable` to add a nullable `deleted_at` column for soft deletes.
+- Models over that table soft delete without any extra configuration: `initializationOptions` turns on `paranoid` for any table whose schema has `deleted_at` alongside the timestamp columns, so `destroy()` sets `deleted_at` and ordinary queries skip the row. A table created with `{ paranoid: true, timestamps: false }` has the column but does not qualify.
+- Unique indexes on a paranoid table should be partial — `where: { deleted_at: null }` — or a soft-deleted row will still block re-creating the same one.
+- An index created without a `name` gets `idx_<table>_<columns>`, so `addIndex('users', ['team_id', 'email'])` creates `idx_users_team_id_email`. `removeIndex` applies the same default, which means an index added by its columns can be dropped by its columns. Postgres truncates identifiers at 63 characters, so name long multi-column indexes explicitly.
 - Column names are automatically converted to snake_case, so `teamId` in the details object becomes `team_id` in the database.
-- Each migration runs inside a transaction.
+- Each migration runs inside a transaction, so a migration that throws part way through leaves the database untouched.
+
+Postgres refuses a few statements inside a transaction block — `CREATE INDEX CONCURRENTLY` and `DROP INDEX CONCURRENTLY` most of all. A migration that needs one of those opts out of the transaction entirely:
+
+```js
+module.exports = {
+    transactional: false,
+
+    up: async function() {
+        await this.addIndex('users', ['team_id'], { concurrently: true });
+    },
+
+    down: async function() {
+        await this.removeIndex('users', ['team_id'], true);
+    }
+}
+```
+
+An opted-out migration is **not** rolled back if it fails, so keep it to the single statement that needs it and put everything else in its own migration.
 
 
 ## Models
@@ -163,7 +188,7 @@ More query examples: [Sequelize model querying basics](https://sequelize.org/doc
 
 ### Aggregators and functions
 
-Sequelize's `fn` and `col` helpers are exposed on the model class:
+The `fn` and `col` helpers are exposed on the model class:
 
 ```js
 const rows = await User.findAll({
@@ -204,7 +229,7 @@ User.initialize();
 
 ## Virtual fields
 
-Add a derived attribute by defining `_virtualGet${PropertyName}` (and optionally `_virtualSet${PropertyName}`). The framework registers a Sequelize `VIRTUAL` column for it, so the property appears in `dataValues`, `toJSON()`, and `toApiResponse()`. Virtual accessors are inherited through the class hierarchy.
+Add a derived attribute by defining `_virtualGet${PropertyName}` (and optionally `_virtualSet${PropertyName}`). The framework registers a `VIRTUAL` column for it, so the property appears in `dataValues`, `toJSON()`, and `toApiResponse()`. Virtual accessors are inherited through the class hierarchy.
 
 ```js
 class User extends ActiveRecord.BaseRecord {
@@ -257,7 +282,7 @@ This feature requires the Redis client wired up via `lib/redis`.
 
 ## Hooks
 
-`BaseRecord` inherits Sequelize's full hook system. Register a hook on the model class with `addHook`:
+`BaseRecord` inherits a full hook system. Register a hook on the model class with `addHook`:
 
 ```js
 User.addHook('beforeCreate', async (user, options) => {
@@ -274,7 +299,7 @@ See [Sequelize hooks](https://sequelize.org/docs/v6/other-topics/hooks/) for the
 
 ## Associations
 
-Define associations using Sequelize's standard API after the model is initialized:
+Define associations using the standard association API after the model is initialized:
 
 ```js
 User.initialize();
@@ -289,22 +314,43 @@ See [Sequelize associations](https://sequelize.org/docs/v6/core-concepts/assocs/
 
 ## Validators
 
-Sequelize's column-level validators continue to work — declare them on the model's column definition or via the `validate` option:
+Register validations with `addValidation` after the model is initialized, the same way hooks are registered. Config keys are the [standard validators](https://sequelize.org/docs/v6/core-concepts/validations-and-constraints/), plus the ones listed below:
 
 ```js
-class User extends ActiveRecord.BaseRecord {
-    static get initializationOptions() {
-        const opts = super.initializationOptions;
-        opts.options.validate = {
-            adminMustHaveTeam() {
-                if (this.is_admin && !this.team_id) {
-                    throw new Error('admin users must belong to a team');
-                }
-            }
-        };
-        return opts;
+User.initialize();
+
+User.addValidation('email', { isEmail: true, len: [1, 255] });
+```
+
+A custom validation is a function. It is called with the record as `this` and the column's value as its only argument, and fails by throwing:
+
+```js
+User.addValidation('team_id', {
+    matchesOrg(value) {
+        if (value && !this.org_id) throw new Error('a team member needs an org');
     }
-}
+});
+```
+
+Leave the column out to validate the record as a whole:
+
+```js
+User.addValidation({
+    adminMustHaveTeam() {
+        if (this.is_admin && !this.team_id) throw new Error('admin users must belong to a team');
+    }
+});
 ```
 
-See [Sequelize validators](https://sequelize.org/docs/v6/core-concepts/validations-and-constraints/).
+### unique
+
+There is no standard uniqueness validator — a `unique` column option builds an index, it does not check anything — so `addValidation` supplies one:
+
+```js
+Tag.addValidation('normalized_name', { unique: { scope: ['org_id'] } });
+Account.addValidation('subdomain',   { unique: true });
+```
+
+`scope` names the columns the value has to be unique *within*. The record never counts as its own duplicate, and soft-deleted rows are ignored on paranoid models. The query only runs when the column or one of its scope columns changed.
+
+This is a read-then-check, so two simultaneous requests can both pass it. Keep a unique index on the table — the validation is there for the error message, the index is what makes it true.

package/lib/activeRecord/baseRecord.js

@@ -7,6 +7,7 @@ const   nodeUtil                          = require('util');
 const { redisClientFactory }              = require('../redis');
 const { camelize, tableize }              = require('inflection');
 const   utils                             = require('./utils');
+const   validations                       = require('./validations');
 
 
 class BaseRecord extends Model {
@@ -204,6 +205,53 @@ class BaseRecord extends Model {
     }
 
 
+    /***********************************************************************************************
+    * VALIDATIONS
+    ***********************************************************************************************/
+    static addValidation(column, config) {
+        if (!config) return this._addModelValidations(column);
+
+        this._assertValidatableColumn(column);
+
+        this._mergeColumnValidations(column, validations.buildColumnValidations(column, config));
+        return this;
+    }
+
+
+    static _addModelValidations(config) {
+        this._assertInitialized();
+
+        this.options.validate = { ...this.options.validate, ...config };
+        return this;
+    }
+
+
+    // Sequelize reads a column's validations off the prototype but rebuilds them from the attribute
+    // whenever the model is refreshed, so both have to point at the one object.
+    static _mergeColumnValidations(column, columnValidations) {
+        const attribute    = this.rawAttributes[column];
+        attribute.validate = { ...attribute.validate, ...columnValidations };
+
+        this.prototype.validators[column] = attribute.validate;
+    }
+
+
+    static _assertValidatableColumn(column) {
+        this._assertInitialized();
+
+        if (this.rawAttributes[column]) return;
+
+        throw new Error(`Cannot validate ${this.name}.${column}: the column is not in the schema`);
+    }
+
+
+    static _assertInitialized() {
+        if (this._initialized) return;
+
+        throw new Error(`${this.name} must be initialized before validations are added`);
+    }
+
+
     /***********************************************************************************************
     * DB CONNECTION
     ***********************************************************************************************/

package/lib/activeRecord/db/migration.js

@@ -101,7 +101,7 @@ function generateMigrationFile(description, databaseId) {
 
 
 function fileNameForMigration(description, databaseId) {
-    const name     = `${description}_${new Date().getTime()}`;
+    const name     = `${new Date().getTime()}_${description}`;
     const dbSuffix = databaseId ? `.${databaseId}` : '';
     return `${name}${dbSuffix}.js`;
 }
@@ -113,7 +113,7 @@ function fileNameForMigration(description, databaseId) {
 function getMigrations() {
     const files = fs.readdirSync(utils.migrationsDirectory);
     const migrations = files.map(f => {
-        const m = f.match(/_(?<version>\d+)(\.(?<databaseId>\w+))?\.js$/);
+        const m = f.match(/^(?<version>\d+)_[^.]+(\.(?<databaseId>\w+))?\.js$/);
         if (!m) return;
         return {fileName: f, databaseId: m.groups.databaseId, version: m.groups.version};
     });

package/lib/activeRecord/db/migrator.js

@@ -3,11 +3,15 @@ const   utils           = require('../utils');
 const { Sequelize, Op } = require('sequelize');
 const { underscore }    = require('inflection');
 
+const ID_TYPES        = ['bigint', 'int', 'uuid'];
+const DEFAULT_ID_TYPE = 'bigint';
+
 
 class Migrator {
     #connection;
     #fileName;
     #migrationModule;
+    #transaction = null;
 
     DataTypes = Sequelize.DataTypes;
     Operators = Op;
@@ -22,19 +26,32 @@ class Migrator {
     async run() {
         if (!this.migrationModule.up) throw new Error('Missing migration `up`');
 
-        const migrator = this;
-        await this.#connection.queryInterface.transaction(async () => {
-            await migrator.migrationModule.up.call(migrator);
-        });
+        await this.perform(() => this.migrationModule.up.call(this));
     }
 
 
     async rollback() {
         if (!this.migrationModule.down) return;
 
-        const migrator = this;
-        await this.#connection.queryInterface.transaction(async () => {
-            await migrator.migrationModule.down.call(migrator);
+        await this.perform(() => this.migrationModule.down.call(this));
+    }
+
+
+    async perform(callback) {
+        if (!this.transactional) return await callback();
+
+        await this.performInTransaction(callback);
+    }
+
+
+    async performInTransaction(callback) {
+        await this.#connection.queryInterface.transaction(async transaction => {
+            this.#transaction = transaction;
+            try {
+                await callback();
+            } finally {
+                this.#transaction = null;
+            }
         });
     }
 
@@ -58,6 +75,14 @@ class Migrator {
     }
 
 
+    // Migrations opt out with `transactional: false`. Needed for statements Postgres refuses to
+    // run inside a transaction block, most notably CREATE/DROP INDEX CONCURRENTLY. An opted-out
+    // migration is not rolled back when it fails.
+    get transactional() {
+        return this.migrationModule.transactional !== false;
+    }
+
+
     importMigrationModule() {
         const filePath = `${utils.migrationsDirectory}/${this.#fileName}`;
         return require(filePath);
@@ -68,7 +93,7 @@ class Migrator {
     * MIGRATION ACTIONS
     ***********************************************************************************************/
     async createTable(tableName, details, options={}) {
-        details = {...this.defaultIdColumn, ...details};
+        details = {...this.idColumn(options.id), ...details};
         if (options.timestamps !== false) {
             details = {...details, ...this.defaultTimestampColumns};
         }
@@ -77,7 +102,7 @@ class Migrator {
         }
 
         details = this.normalizeTableDetails(details);
-        await this.#sequelizeQueryInterface.createTable(tableName, details);
+        await this.#sequelizeQueryInterface.createTable(tableName, details, this.queryOptions);
     }
 
 
@@ -93,13 +118,42 @@ class Migrator {
     }
 
 
-    get defaultIdColumn() {
+    idColumn(idType=DEFAULT_ID_TYPE) {
+        if (!ID_TYPES.includes(idType)) {
+            throw new Error(`Unknown id type "${idType}". Use one of: ${ID_TYPES.join(', ')}`);
+        }
+
+        return this[`${idType}IdColumn`];
+    }
+
+
+    get bigintIdColumn() {
+        return this.autoIncrementIdColumn(this.DataTypes.BIGINT);
+    }
+
+
+    get intIdColumn() {
+        return this.autoIncrementIdColumn(this.DataTypes.INTEGER);
+    }
+
+
+    get uuidIdColumn() {
+        return {
+          id: {
+            allowNull:  false,
+            primaryKey: true,
+            type:       this.DataTypes.UUID, }
+        };
+    }
+
+
+    autoIncrementIdColumn(type) {
         return {
           id: {
             allowNull:     false,
             autoIncrement: true,
             primaryKey:    true,
-            type:          this.DataTypes.INTEGER, }
+            type:          type, }
         };
     }
 
@@ -116,8 +170,6 @@ class Migrator {
     }
 
 
-    // Records use soft deletes when the table has this column: initializationOptions turns paranoid
-    // on for any model whose schema includes it.
     get deletedAtColumn() {
         return {
             deleted_at: {
@@ -128,25 +180,25 @@ class Migrator {
 
 
     async dropTable(tableName) {
-        await this.#sequelizeQueryInterface.dropTable(tableName);
+        await this.#sequelizeQueryInterface.dropTable(tableName, this.queryOptions);
     }
 
 
     async addColumn(tableName, columnName, columnDetails) {
-        await this.#sequelizeQueryInterface.addColumn(tableName, columnName, columnDetails);
+        await this.#sequelizeQueryInterface.addColumn(tableName, columnName, columnDetails, this.queryOptions);
     }
 
 
     async removeColumn(tableName, columnName) {
-        await this.#sequelizeQueryInterface.removeColumn(tableName, columnName);
+        await this.#sequelizeQueryInterface.removeColumn(tableName, columnName, this.queryOptions);
     }
 
 
-    async addIndex(tableName, fields, { concurrently, unique, name, using, where }) {
-        const options = {fields: fields};
+    async addIndex(tableName, fields, { concurrently, unique, name, using, where }={}) {
+        const options = {fields: fields, ...this.queryOptions};
+        options.name = name || this.defaultIndexName(tableName, fields);
         if (concurrently) options.concurrently = true;
         if (unique)       options.unique       = true;
-        if (name)         options.name         = name;
         if (using)        options.using        = using;
         if (where)        options.where        = where;
 
@@ -155,20 +207,53 @@ class Migrator {
 
 
     async removeIndex(tableName, indexNameOrAttributes, concurrently=false) {
-        const options = {};
+        const options   = this.queryOptions;
         if (concurrently) options.concurrently = true;
-        await this.#sequelizeQueryInterface.removeIndex(tableName, indexNameOrAttributes, options);
+
+        const indexName = this.indexNameFor(tableName, indexNameOrAttributes);
+        await this.#sequelizeQueryInterface.removeIndex(tableName, indexName, options);
+    }
+
+
+    /***********************************************************************************************
+    * INDEX NAMING
+    ***********************************************************************************************/
+    // Indexes created without an explicit name get `idx_<table>_<columns>`. removeIndex applies the
+    // same default so an index can be dropped by its columns, the way it was added.
+    indexNameFor(tableName, indexNameOrAttributes) {
+        if (typeof indexNameOrAttributes === 'string') return indexNameOrAttributes;
+        return this.defaultIndexName(tableName, indexNameOrAttributes);
+    }
+
+
+    defaultIndexName(tableName, fields) {
+        const columnNames = fields.map(field => this.indexColumnName(field));
+        return `idx_${tableName}_${columnNames.join('_')}`;
+    }
+
+
+    indexColumnName(field) {
+        if (typeof field === 'string') return field;
+        return field.name;
     }
 
 
     async renameColumn(tableName, oldName, newName) {
         newName = underscore(newName);
-        await this.#sequelizeQueryInterface.renameColumn(tableName, oldName, newName);
+        await this.#sequelizeQueryInterface.renameColumn(tableName, oldName, newName, this.queryOptions);
     }
 
 
     async changeColumn(tableName, columnName, dataTypeOrOptions) {
-        await this.#sequelizeQueryInterface.changeColumn(tableName, columnName, dataTypeOrOptions);
+        await this.#sequelizeQueryInterface.changeColumn(tableName, columnName, dataTypeOrOptions, this.queryOptions);
+    }
+
+
+    /***********************************************************************************************
+    * QUERY OPTIONS
+    ***********************************************************************************************/
+    get queryOptions() {
+        return { transaction: this.#transaction };
     }
 
 

package/lib/activeRecord/validations.js

@@ -0,0 +1,85 @@
+const UNIQUE = 'unique';
+
+
+/***************************************************************************************************
+* CONFIGURATION
+***************************************************************************************************/
+function buildColumnValidations(column, config) {
+    const validations = {};
+    for (const [key, value] of Object.entries(config)) {
+        validations[key] = buildColumnValidation(column, key, value);
+    }
+    return validations;
+}
+
+
+function buildColumnValidation(column, key, value) {
+    if (key != UNIQUE) return value;
+
+    return buildUniqueValidation(column, value);
+}
+
+
+/***************************************************************************************************
+* UNIQUENESS
+***************************************************************************************************/
+function buildUniqueValidation(column, config) {
+    const options = uniqueOptions(config);
+
+    return function(value) {
+        return validateUniqueness(this, column, value, options);
+    };
+}
+
+
+function uniqueOptions(config) {
+    if (config === true) return {};
+
+    return config;
+}
+
+
+async function validateUniqueness(record, column, value, options) {
+    if (!uniquenessChanged(record, column, options)) return;
+
+    const duplicate = await record.constructor.findOne({
+        where: uniquenessConditions(record, column, value, options)
+    });
+    if (duplicate) throw new Error(`${column} must be unique`);
+}
+
+
+function uniquenessChanged(record, column, options) {
+    const columns = [column, ...scopeColumns(options)];
+    return columns.some(scopedColumn => record.changed(scopedColumn));
+}
+
+
+function uniquenessConditions(record, column, value, options) {
+    const primaryKey = record.constructor.primaryKeyAttribute;
+
+    return {
+        [column]:     value,
+        [primaryKey]: { [record.constructor.Operators.ne]: record[primaryKey] },
+        ...scopeConditions(record, options)
+    };
+}
+
+
+function scopeConditions(record, options) {
+    const conditions = {};
+    for (const column of scopeColumns(options)) {
+        conditions[column] = record[column];
+    }
+    return conditions;
+}
+
+
+function scopeColumns(options) {
+    return options.scope || [];
+}
+
+
+module.exports = {
+    buildColumnValidations
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.2.0",
+    "version": "2.3.0",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",

package/test/activeRecord/baseRecord.test.js

@@ -268,6 +268,78 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('BaseRecord.addValidation', () => {
+        function buildModel() {
+            class User extends BaseRecord {}
+            User.initialize();
+            return User;
+        }
+
+
+        it ('adds the validations to the column', () => {
+            const User = buildModel();
+
+            User.addValidation(Helpers.colName, {notEmpty: true});
+
+            expect(User.rawAttributes[Helpers.colName].validate).toEqual({notEmpty: true});
+        });
+
+
+        it ('reads the column validations off the prototype and the attribute as one object', () => {
+            const User = buildModel();
+
+            User.addValidation(Helpers.colName, {notEmpty: true});
+
+            expect(User.prototype.validators[Helpers.colName]).toBe(User.rawAttributes[Helpers.colName].validate);
+        });
+
+
+        it ('keeps the validations already registered for the column', () => {
+            const User      = buildModel();
+            const validator = jest.fn();
+
+            User.addValidation(Helpers.colName, {notEmpty: true});
+            User.addValidation(Helpers.colName, {isTaken: validator});
+
+            expect(User.rawAttributes[Helpers.colName].validate).toEqual({notEmpty: true, isTaken: validator});
+        });
+
+
+        it ('returns the model so calls can be chained', () => {
+            const User = buildModel();
+
+            expect(User.addValidation(Helpers.colName, {notEmpty: true})).toBe(User);
+        });
+
+
+        it ('adds the validations to the model itself when no column is named', () => {
+            const User      = buildModel();
+            const validator = jest.fn();
+
+            User.addValidation({teamIsPresent: validator});
+
+            expect(User.options.validate).toEqual({teamIsPresent: validator});
+        });
+
+
+        it ('refuses a column that is not in the schema', () => {
+            const User    = buildModel();
+            const colName = TestHelpers.Faker.Text.randomString();
+
+            expect(() => User.addValidation(colName, {notEmpty: true}))
+                .toThrow(`Cannot validate User.${colName}: the column is not in the schema`);
+        });
+
+
+        it ('refuses a model that has not been initialized', () => {
+            class User extends BaseRecord {}
+
+            expect(() => User.addValidation(Helpers.colName, {notEmpty: true}))
+                .toThrow('User must be initialized before validations are added');
+        });
+    });
+
+
     describe('BaseRecord.configureVirtualAccessors', () => {
         it ('adds a VIRTUAL column when a _virtualGet method is defined on the subclass', () => {
             const getter = jest.fn();

package/test/activeRecord/db/migrator.test.js

@@ -45,23 +45,158 @@ describe('Migrator', () => {
     });
 
 
+    describe('Migrator transaction threading', () => {
+        it ('passes the open transaction to operations run inside `up`', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.runInMigration(async function() {
+                await this.createTable(tableName, {});
+            });
+
+            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(
+                tableName,
+                expect.any(Object),
+                Helpers.inTransaction,
+            );
+        });
+
+        it ('passes the open transaction to operations run inside `down`', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.migrationModule.down.mockImplementationOnce(async function() {
+                await this.dropTable(tableName);
+            });
+
+            await Helpers.migrator.rollback();
+
+            expect(Helpers.mockQueryInterface.dropTable).toHaveBeenCalledWith(tableName, Helpers.inTransaction);
+        });
+
+        it ('clears the transaction once the migration finishes', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.runInMigration(async function() {});
+            await Helpers.migrator.dropTable(tableName);
+
+            expect(Helpers.mockQueryInterface.dropTable).toHaveBeenCalledWith(tableName, Helpers.noTransaction);
+        });
+
+        it ('clears the transaction when the migration throws', async () => {
+            const tableName = Helpers.randomString();
+
+            await expect(Helpers.runInMigration(async function() {
+                throw new Error('migration blew up');
+            })).rejects.toThrow('migration blew up');
+            await Helpers.migrator.dropTable(tableName);
+
+            expect(Helpers.mockQueryInterface.dropTable).toHaveBeenCalledWith(tableName, Helpers.noTransaction);
+        });
+    });
+
+
+    describe('Migrator opting out of the transaction', () => {
+        afterEach(() => {
+            delete Helpers.migrationModule.transactional;
+        });
+
+        it ('runs `up` outside a transaction when the migration sets transactional to false', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.migrationModule.transactional = false;
+
+            await Helpers.runInMigration(async function() {
+                await this.addIndex(tableName, ['name'], { concurrently: true });
+            });
+
+            expect(Helpers.transactionSpy).not.toHaveBeenCalled();
+            expect(Helpers.mockQueryInterface.addIndex).toHaveBeenCalledWith(tableName, {
+                fields: ['name'],
+                name: `idx_${tableName}_name`,
+                concurrently: true,
+                ...Helpers.noTransaction,
+            });
+        });
+
+        it ('runs `down` outside a transaction when the migration sets transactional to false', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.migrationModule.transactional = false;
+            Helpers.migrationModule.down.mockImplementationOnce(async function() {
+                await this.dropTable(tableName);
+            });
+
+            await Helpers.migrator.rollback();
+
+            expect(Helpers.transactionSpy).not.toHaveBeenCalled();
+            expect(Helpers.mockQueryInterface.dropTable).toHaveBeenCalledWith(tableName, Helpers.noTransaction);
+        });
+
+        it ('still uses a transaction when transactional is unset', async () => {
+            await Helpers.migrator.run();
+
+            expect(Helpers.transactionSpy).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
     describe('Migrator#createTable', () => {
         const defaultColumns = {
-            id: { allowNull: false, autoIncrement: true, primaryKey: true, type: 'INTEGER' },
+            id: { allowNull: false, autoIncrement: true, primaryKey: true, type: 'BIGINT' },
             created_at: { allowNull: false, type: 'DATE' },
             updated_at: { allowNull: false, type: 'DATE' },
         };
 
+        it ('gives the table a bigint auto-increment id', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {});
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'BIGINT' });
+        });
+
+        it ('gives the table an integer id when asked for one', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: 'int' });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'INTEGER' });
+        });
+
+        it ('gives the table a uuid id that the database does not generate', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: 'uuid' });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual({ allowNull: false, primaryKey: true, type: 'UUID' });
+        });
+
+        it ('refuses an id type it does not recognize', async () => {
+            const idType = Helpers.randomString();
+
+            await expect(Helpers.migrator.createTable(Helpers.randomString(), {}, { id: idType }))
+                .rejects.toThrow(`Unknown id type "${idType}". Use one of: bigint, int, uuid`);
+        });
+
+        it ('lets the details override the id column', async () => {
+            const tableName = Helpers.randomString();
+            const id        = { allowNull: false, primaryKey: true, type: 'UUID' };
+
+            await Helpers.migrator.createTable(tableName, { id });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).toEqual(id);
+        });
+
         it ('creates tables with provided details', async () => {
             const tableName = Helpers.randomString();
             const details = { ...defaultColumns, [Helpers.randomString().toLowerCase()]: Helpers.randomNumber() };
 
             await Helpers.migrator.createTable(tableName, details);
 
-            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, details);
+            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, details, Helpers.noTransaction);
         });
 
-        it ('adds a deleted_at column for paranoid tables', async () => {
+        it ('adds a nullable deleted_at column when paranoid is set', async () => {
             const tableName = Helpers.randomString();
             const details = { ...defaultColumns };
 
@@ -70,16 +205,27 @@ describe('Migrator', () => {
             expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, {
                 ...defaultColumns,
                 deleted_at: { allowNull: true, type: 'DATE' },
-            });
+            }, Helpers.noTransaction);
         });
 
-        it ('leaves deleted_at off tables that are not paranoid', async () => {
+        it ('omits deleted_at when paranoid is not set', async () => {
             const tableName = Helpers.randomString();
-            const details = { ...defaultColumns };
 
-            await Helpers.migrator.createTable(tableName, details);
+            await Helpers.migrator.createTable(tableName, { ...defaultColumns });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns).not.toHaveProperty('deleted_at');
+        });
+
+        it ('adds deleted_at alongside timestamps: false', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { paranoid: true, timestamps: false });
 
-            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, defaultColumns);
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns).toHaveProperty('deleted_at');
+            expect(columns).not.toHaveProperty('created_at');
+            expect(columns).not.toHaveProperty('updated_at');
         });
 
         it ('snake_cases created table columns', async () => {
@@ -91,7 +237,7 @@ describe('Migrator', () => {
             expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, {
                 ...defaultColumns,
                 my_column: 1,
-            });
+            }, Helpers.noTransaction);
         });
     });
 
@@ -116,7 +262,7 @@ describe('Migrator', () => {
 
             await Helpers.migrator.renameColumn(tableName, oldName, 'myColumn');
 
-            expect(Helpers.mockQueryInterface.renameColumn).toHaveBeenCalledWith(tableName, oldName, 'my_column');
+            expect(Helpers.mockQueryInterface.renameColumn).toHaveBeenCalledWith(tableName, oldName, 'my_column', Helpers.noTransaction);
         });
     });
 
@@ -129,12 +275,12 @@ describe('Migrator', () => {
         ])('builds addIndex options for %s', async (_label, options) => {
             const tableName = Helpers.randomString();
             const fields = [Helpers.randomString(), Helpers.randomString()];
-            const expectedOptions = { fields };
+            const expectedOptions = { fields, ...Helpers.noTransaction };
 
             if (options.concurrently) expectedOptions.concurrently = true;
             if (options.unique) expectedOptions.unique = true;
             if (options.where) expectedOptions.where = options.where;
-            if (options.name) expectedOptions.name = options.name;
+            expectedOptions.name = options.name || `idx_${tableName}_${fields.join('_')}`;
             if (options.using) expectedOptions.using = options.using;
 
             await Helpers.migrator.addIndex(tableName, fields, options);
@@ -147,8 +293,8 @@ describe('Migrator', () => {
 
     describe('Migrator#removeIndex', () => {
         it.each([
-            ['default options', false, {}],
-            ['concurrently', true, { concurrently: true }],
+            ['default options', false, { transaction: null }],
+            ['concurrently', true, { concurrently: true, transaction: null }],
         ])('passes removeIndex options for %s', async (_label, concurrently, expectedOptions) => {
             const tableName = Helpers.randomString();
             const fields = [Helpers.randomString(), Helpers.randomString()];
@@ -158,9 +304,54 @@ describe('Migrator', () => {
             expect(Helpers.mockQueryInterface.removeIndex).toHaveBeenCalledTimes(1);
             expect(Helpers.mockQueryInterface.removeIndex).toHaveBeenCalledWith(
                 tableName,
-                fields,
+                `idx_${tableName}_${fields.join('_')}`,
                 expectedOptions,
             );
         });
+
+        it ('leaves an explicit index name alone', async () => {
+            const tableName = Helpers.randomString();
+            const indexName = Helpers.randomString();
+
+            await Helpers.migrator.removeIndex(tableName, indexName);
+
+            expect(Helpers.mockQueryInterface.removeIndex).toHaveBeenCalledWith(
+                tableName,
+                indexName,
+                Helpers.noTransaction,
+            );
+        });
+    });
+
+
+    describe('Migrator#defaultIndexName', () => {
+        it ('builds idx_<table>_<columns> from a single column', () => {
+            expect(Helpers.migrator.defaultIndexName('users', ['team_id'])).toBe('idx_users_team_id');
+        });
+
+        it ('joins multiple columns with underscores', () => {
+            expect(Helpers.migrator.defaultIndexName('users', ['team_id', 'email'])).toBe('idx_users_team_id_email');
+        });
+
+        it ('reads the column name off object-style fields', () => {
+            const fields = ['team_id', { name: 'email', order: 'DESC' }];
+
+            expect(Helpers.migrator.defaultIndexName('users', fields)).toBe('idx_users_team_id_email');
+        });
+    });
+
+
+    describe('Migrator#addIndex default naming', () => {
+        it ('names an index when no options are passed at all', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.addIndex(tableName, ['team_id']);
+
+            expect(Helpers.mockQueryInterface.addIndex).toHaveBeenCalledWith(tableName, {
+                fields: ['team_id'],
+                name: `idx_${tableName}_team_id`,
+                ...Helpers.noTransaction,
+            });
+        });
     });
 });

package/test/activeRecord/helpers/baseRecordMocks.js

@@ -30,10 +30,18 @@ class MockModel {
     static init                = jest.fn()
     static findByPk            = jest.fn();
     static findAll             = jest.fn();
+    static findOne             = jest.fn();
     static primaryKeyAttribute = TestHelpers.Faker.Text.randomString();
     toJSON()                   { return this.dataValues }
 }
 MockModel.findAll.mockImplementation(() => []);
+// Sequelize stores the schema and the options it was initialized with, and anything reading a
+// model's validations expects them to have been reset by then.
+MockModel.init.mockImplementation(function(schema, options) {
+    this.rawAttributes        = schema;
+    this.options              = options;
+    this.prototype.validators = {};
+});
 
 
 class MockSequelize {

package/test/activeRecord/helpers/migrator.js

@@ -13,6 +13,9 @@ const connectionConfig   = { database: ' ', host: ' ', password: ' ', username:
 const migrationModule    = { up: jest.fn(), down: jest.fn() };
 const randomNumber       = TestHelpers.Faker.Math.randomNumber
 const randomString       = TestHelpers.Faker.Text.randomString;
+const transaction        = { id: randomString() };
+const noTransaction      = { transaction: null };
+const inTransaction      = { transaction };
 const mockQueryInterface = {
     createTable: jest.fn(),
     dropTable: jest.fn(),
@@ -35,7 +38,7 @@ function randomColumnDetails() {
 ***************************************************************************************************/
 jest.mock('sequelize', () => {
     class MockSequelize {
-        static DataTypes = { INTEGER: 'INTEGER', DATE: 'DATE' };
+        static DataTypes = { BIGINT: 'BIGINT', DATE: 'DATE', INTEGER: 'INTEGER', UUID: 'UUID' };
     }
     return { Sequelize: MockSequelize };
 });
@@ -52,7 +55,7 @@ jest.spyOn(migrator, 'migrationModule', 'get').mockImplementation(() => migratio
 
 
 const transactionSpy = jest.spyOn(QueryInterface.prototype, 'transaction');
-transactionSpy.mockImplementation(callback => callback());
+transactionSpy.mockImplementation(callback => callback(transaction));
 
 
 /***************************************************************************************************
@@ -61,18 +64,29 @@ transactionSpy.mockImplementation(callback => callback());
 async function expectQueryInterfaceCall(methodName, args) {
     await migrator[methodName](...args);
     expect(mockQueryInterface[methodName]).toHaveBeenCalledTimes(1);
-    expect(mockQueryInterface[methodName]).toHaveBeenCalledWith(...args);
+    expect(mockQueryInterface[methodName]).toHaveBeenCalledWith(...args, noTransaction);
+}
+
+
+// Runs `operation` from inside a migration's `up` so it sees the open transaction.
+async function runInMigration(operation) {
+    migrationModule.up.mockImplementationOnce(operation);
+    await migrator.run();
 }
 
 
 module.exports = {
   expectQueryInterfaceCall,
   ...Fixtures,
+  inTransaction,
   migrationModule,
   migrator,
   mockQueryInterface,
+  noTransaction,
   randomColumnDetails,
   randomNumber,
   randomString,
+  runInMigration,
+  transaction,
   transactionSpy,
 };

package/test/activeRecord/helpers/validations.js

@@ -0,0 +1,38 @@
+const TestHelpers = require('@vida-global/test-helpers');
+
+
+/***************************************************************************************************
+* VARIABLES / VARIABLE GENERATION
+***************************************************************************************************/
+const NOT_EQUAL           = Symbol('ne');
+const PRIMARY_KEY         = 'id';
+const column              = TestHelpers.Faker.Text.randomString();
+const scopeColumn         = TestHelpers.Faker.Text.randomString();
+
+
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+// The validations only reach a record through the few members Sequelize gives every model instance,
+// so a plain object stands in for one and keeps a live model out of these tests.
+function buildRecord({changed = () => true, ...attributes} = {}) {
+    return {
+        [PRIMARY_KEY]: null,                            // sequelize's value for an unsaved record
+        ...attributes,
+        changed:     jest.fn(changed),
+        constructor: {
+            findOne:             jest.fn().mockResolvedValue(null),
+            primaryKeyAttribute: PRIMARY_KEY,
+            Operators:           {ne: NOT_EQUAL}
+        }
+    };
+}
+
+
+module.exports = {
+    buildRecord,
+    column,
+    NOT_EQUAL,
+    PRIMARY_KEY,
+    scopeColumn
+}

package/test/activeRecord/validations.test.js

@@ -0,0 +1,117 @@
+const { buildColumnValidations } = require('../../lib/activeRecord/validations');
+const   Helpers                  = require('./helpers/validations');
+const   TestHelpers              = require('@vida-global/test-helpers');
+
+
+const COLUMN       = Helpers.column;
+const SCOPE_COLUMN = Helpers.scopeColumn;
+
+
+afterEach(() => {
+    jest.clearAllMocks();
+});
+
+
+describe('buildColumnValidations', () => {
+
+    it ('passes a built-in validation through untouched', () => {
+        expect(buildColumnValidations(COLUMN, {len: [1, 255]})).toEqual({len: [1, 255]});
+    });
+
+
+    it ('passes a custom validation function through untouched', () => {
+        const validator = jest.fn();
+
+        expect(buildColumnValidations(COLUMN, {isTaken: validator})).toEqual({isTaken: validator});
+    });
+
+
+    describe('unique', () => {
+        function buildUnique(config = {scope: [SCOPE_COLUMN]}) {
+            return buildColumnValidations(COLUMN, {unique: config}).unique;
+        }
+
+
+        it ('takes only the value, so sequelize awaits it instead of handing it a callback', () => {
+            expect(buildUnique().length).toEqual(1);
+        });
+
+
+        it ('looks for another record holding the value', async() => {
+            const id     = TestHelpers.Faker.Text.randomString();
+            const record = Helpers.buildRecord({id, [SCOPE_COLUMN]: 17});
+            const value  = TestHelpers.Faker.Text.randomString();
+
+            await buildUnique().call(record, value);
+
+            expect(record.constructor.findOne).toHaveBeenCalledTimes(1);
+            expect(record.constructor.findOne).toHaveBeenCalledWith({
+                where: {
+                    [COLUMN]:              value,
+                    [SCOPE_COLUMN]:        17,
+                    [Helpers.PRIMARY_KEY]: {[Helpers.NOT_EQUAL]: id}
+                }
+            });
+        });
+
+
+        it ('looks for a duplicate anywhere when the validation is not scoped', async() => {
+            const id     = TestHelpers.Faker.Text.randomString();
+            const record = Helpers.buildRecord({id});
+            const value  = TestHelpers.Faker.Text.randomString();
+
+            await buildUnique(true).call(record, value);
+
+            expect(record.constructor.findOne).toHaveBeenCalledWith({
+                where: {[COLUMN]: value, [Helpers.PRIMARY_KEY]: {[Helpers.NOT_EQUAL]: id}}
+            });
+        });
+
+
+        it ('compares against the empty key of a record that has not been saved yet', async() => {
+            const record = Helpers.buildRecord();
+            const value  = TestHelpers.Faker.Text.randomString();
+
+            await buildUnique(true).call(record, value);
+
+            expect(record.constructor.findOne).toHaveBeenCalledWith({
+                where: {[COLUMN]: value, [Helpers.PRIMARY_KEY]: {[Helpers.NOT_EQUAL]: null}}
+            });
+        });
+
+
+        it ('does not look for a duplicate when neither the value nor its scope changed', async() => {
+            const record = Helpers.buildRecord({changed: () => false});
+
+            await buildUnique().call(record, TestHelpers.Faker.Text.randomString());
+
+            expect(record.constructor.findOne).not.toHaveBeenCalled();
+        });
+
+
+        it ('looks again when the scope changed even though the value did not', async() => {
+            const record = Helpers.buildRecord({changed: (column) => column == SCOPE_COLUMN});
+
+            await buildUnique().call(record, TestHelpers.Faker.Text.randomString());
+
+            expect(record.constructor.findOne).toHaveBeenCalledTimes(1);
+        });
+
+
+        it ('passes when nothing else holds the value', async() => {
+            const record = Helpers.buildRecord();
+
+            await expect(buildUnique().call(record, TestHelpers.Faker.Text.randomString()))
+                .resolves.toBeUndefined();
+        });
+
+
+        it ('fails when something else already holds the value', async() => {
+            const record = Helpers.buildRecord();
+            record.constructor.findOne.mockResolvedValue({id: TestHelpers.Faker.Text.randomString()});
+
+            await expect(buildUnique().call(record, TestHelpers.Faker.Text.randomString()))
+                .rejects.toThrow(`${COLUMN} must be unique`);
+        });
+    });
+});