@vida-global/core 2.1.2 → 2.2.1

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 })
+createTable(tableName, details, { timestamps, paranoid })
 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)
@@ -111,8 +113,30 @@ 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 `createTable` to add a nullable `deleted_at` column for soft deletes.
+- Models over that table soft delete without any extra configuration: `initializationOptions` turns on Sequelize's `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
@@ -307,8 +331,3 @@ class User extends ActiveRecord.BaseRecord {
 ```
 
 See [Sequelize validators](https://sequelize.org/docs/v6/core-concepts/validations-and-constraints/).
-
-
-## TODO
-
-- **Paranoid (soft delete).** The infrastructure for a `deleted_at` column is wired in `initializationOptions`, but `paranoid: true` is not set, so soft deletes are not yet usable out of the box.

package/lib/activeRecord/baseRecord.js

@@ -337,30 +337,39 @@ class BaseRecord extends Model {
     }
 
 
-    static _marshallDataForCaching(value) {
-      let marshalledValue;
-      if (value instanceof this) {
-          marshalledValue = JSON.stringify(value.toJSON());
-          marshalledValue = `${this.recordCachingPrefix}:${marshalledValue}`;
-      } else {
-          marshalledValue = JSON.stringify(value);
-      }
-      return marshalledValue;
+    static async clearCacheKey(key) {
+        const client = await this._getRedisClient();
+        await client.del(key);
     }
 
 
-    static _unmarshallCachedData(value) {
-        if (value == null)            return null;
-        if (typeof value != 'string') return value;
+    static async forEachCacheKeyByPattern(pattern, callback, count=100) {
+        const client = await this._getRedisClient();
+        let   batch  = [];
 
-        if (value.startsWith(this.recordCachingPrefix)) {
-            const regExp = new RegExp(`^${this.recordCachingPrefix}:`);
-            value        = value.replace(regExp, '');
-            const data   = JSON.parse(value);
-            return new this(data, {isNewRecord: false});
-        } else {
-            return JSON.parse(value);
+        for await (const scanned of client.scanIterator({ MATCH: pattern, COUNT: count })) {
+            batch.push(...this._scannedKeysAsArray(scanned));
+            if (batch.length < count) continue;
+
+            await callback(batch, client);
+            batch = [];
         }
+
+        if (batch.length) await callback(batch, client);
+    }
+
+
+    // redis 4 yields one key at a time; redis 5 yields an array of keys per scan.
+    static _scannedKeysAsArray(scanned) {
+        if (Array.isArray(scanned)) return scanned;
+        return [scanned];
+    }
+
+
+    static async clearCacheKeysByPattern(pattern) {
+        await this.forEachCacheKeyByPattern(pattern, async (keys, client) => {
+            await client.del(keys);
+        });
     }
 
 
@@ -369,9 +378,8 @@ class BaseRecord extends Model {
 
         const pk     = this.constructor.primaryKeyAttribute;
         const key    = this.constructor._recordCacheKey(this[pk]);
-        const client = await this.constructor._getRedisClient();
+        await this.constructor.clearCacheKey(key);
 
-        await client.del(key);
         this.constructor.debugLog('Cache Del', key);
     }
 
@@ -389,18 +397,6 @@ class BaseRecord extends Model {
     }
 
 
-    static get redisClientFactory() {
-        return redisClientFactory;
-    }
-
-
-    static async _getRedisClient() {
-      const client = this.redisClientFactory();
-      await client.connect();
-      return client;
-    }
-
-
     static get isCacheable() { return false; }
 
 
@@ -416,6 +412,45 @@ class BaseRecord extends Model {
     }
 
 
+    static _marshallDataForCaching(value) {
+      let marshalledValue;
+      if (value instanceof this) {
+          marshalledValue = JSON.stringify(value.toJSON());
+          marshalledValue = `${this.recordCachingPrefix}:${marshalledValue}`;
+      } else {
+          marshalledValue = JSON.stringify(value);
+      }
+      return marshalledValue;
+    }
+
+
+    static _unmarshallCachedData(value) {
+        if (value == null)            return null;
+        if (typeof value != 'string') return value;
+
+        if (value.startsWith(this.recordCachingPrefix)) {
+            const regExp = new RegExp(`^${this.recordCachingPrefix}:`);
+            value        = value.replace(regExp, '');
+            const data   = JSON.parse(value);
+            return new this(data, {isNewRecord: false});
+        } else {
+            return JSON.parse(value);
+        }
+    }
+
+
+    static get _redisClientFactory() {
+        return redisClientFactory;
+    }
+
+
+    static async _getRedisClient() {
+      const client = this._redisClientFactory();
+      await client.connect();
+      return client;
+    }
+
+
     /***********************************************************************************************
     * MISC
     ***********************************************************************************************/

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

@@ -8,6 +8,7 @@ class Migrator {
     #connection;
     #fileName;
     #migrationModule;
+    #transaction = null;
 
     DataTypes = Sequelize.DataTypes;
     Operators = Op;
@@ -22,19 +23,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 +72,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);
@@ -72,9 +94,12 @@ class Migrator {
         if (options.timestamps !== false) {
             details = {...details, ...this.defaultTimestampColumns};
         }
+        if (options.paranoid) {
+            details = {...details, ...this.deletedAtColumn};
+        }
 
         details = this.normalizeTableDetails(details);
-        await this.#sequelizeQueryInterface.createTable(tableName, details);
+        await this.#sequelizeQueryInterface.createTable(tableName, details, this.queryOptions);
     }
 
 
@@ -113,26 +138,35 @@ class Migrator {
     }
 
 
+    get deletedAtColumn() {
+        return {
+            deleted_at: {
+                allowNull: true,
+                type: this.DataTypes.DATE }
+        };
+    }
+
+
     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;
 
@@ -141,20 +175,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/cache/memoryCache.js

@@ -14,6 +14,16 @@ class MemoryCache {
     }
 
 
+    async delete({ namespace, key } = {}) {
+        this.#validateNamespace(namespace);
+
+        const cacheKey         = this.#createCacheKey({ namespace, key });
+        const entryDeleted     = this.#entries.delete(cacheKey);
+        const fetchInvalidated = this.#removePendingFetch(cacheKey);
+        return entryDeleted || fetchInvalidated;
+    }
+
+
     async fetch(options = {}, fetcher) {
         this.#validateNamespace(options.namespace);
         this.#validateTtl(options.ttlSeconds);
@@ -26,13 +36,15 @@ class MemoryCache {
         const pending  = this.#pendingFetches.get(cacheKey);
         if (pending) return this.#buildFetchResult(await pending, false);
 
-        const fetch = this.#fetch(options, fetcher, cacheKey);
+        const fetch = this.#runFetcher(fetcher);
         this.#pendingFetches.set(cacheKey, fetch);
 
         try {
-            return this.#buildFetchResult(await fetch, false);
+            const value = await fetch;
+            this.#cacheFetchedValue(cacheKey, options.ttlSeconds, fetch, value);
+            return this.#buildFetchResult(value, false);
         } finally {
-            this.#pendingFetches.delete(cacheKey);
+            this.#removePendingFetch(cacheKey, fetch);
         }
     }
 
@@ -46,10 +58,22 @@ class MemoryCache {
     }
 
 
-    async #fetch(options, fetcher, cacheKey) {
-        const value = await fetcher();
-        this.#set(cacheKey, options.ttlSeconds, value);
-        return value;
+    async #runFetcher(fetcher) {
+        return fetcher();
+    }
+
+
+    #cacheFetchedValue(cacheKey, ttlSeconds, fetch, value) {
+        if (this.#pendingFetches.get(cacheKey) !== fetch) return;
+        this.#set(cacheKey, ttlSeconds, value);
+    }
+
+
+    #removePendingFetch(cacheKey, expectedFetch) {
+        const currentFetch = this.#pendingFetches.get(cacheKey);
+        if (expectedFetch !== undefined && currentFetch !== expectedFetch) return false;
+
+        return this.#pendingFetches.delete(cacheKey);
     }
 
 

package/package.json

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

package/test/activeRecord/baseRecord.test.js

@@ -3,7 +3,7 @@ const { Connection }            = require('../../lib/activeRecord/db/connection'
 const { getActiveRecordSchema } = require('../../lib/activeRecord/db/schema');
 const   importSchema            = require('../../lib/activeRecord/db/importSchema');
 const { Model, Sequelize }      = require('sequelize');
-const { mockRedisClientFactory } = require('./helpers/baseRecordMocks');
+const { mockRedisClientFactory, mockScannedKeys, randomCacheKeys } = require('./helpers/baseRecordMocks');
 const   TestHelpers             = require('@vida-global/test-helpers');
 const { camelize }              = require('inflection');
 const   Helpers                 = require('./helpers/baseRecord');
@@ -503,7 +503,7 @@ describe('BaseRecord', () => {
     describe('Caching', () => {
         class Person extends BaseRecord {
             static get isCacheable()       { return true; }
-            static get redisClientFactory() { return mockRedisClientFactory; }
+            static get _redisClientFactory() { return mockRedisClientFactory; }
         }
         let redisClient
         beforeEach(() => {
@@ -772,6 +772,116 @@ describe('BaseRecord', () => {
         });
 
 
+        describe('BaseRecord.clearCacheKey', () => {
+            it ('deletes the given key from cache', async () => {
+                const key = `Person#find:${Math.random()}`;
+
+                await Person.clearCacheKey(key);
+                expect(redisClient.del).toHaveBeenCalledTimes(1);
+                expect(redisClient.del).toHaveBeenCalledWith(key);
+            });
+        });
+
+
+        describe('BaseRecord.forEachCacheKeyByPattern', () => {
+            const pattern = `Person#find:*`;
+
+            it ('scans with the given pattern and a default count of 100', async () => {
+                mockScannedKeys([]);
+
+                await Person.forEachCacheKeyByPattern(pattern, jest.fn());
+
+                expect(redisClient.scanIterator).toHaveBeenCalledTimes(1);
+                expect(redisClient.scanIterator).toHaveBeenCalledWith({ MATCH: pattern, COUNT: 100 });
+            });
+
+            it ('passes a custom count to the scan', async () => {
+                const count = TestHelpers.Faker.Math.randomNumber();
+                mockScannedKeys([]);
+
+                await Person.forEachCacheKeyByPattern(pattern, jest.fn(), count);
+
+                expect(redisClient.scanIterator).toHaveBeenCalledWith({ MATCH: pattern, COUNT: count });
+            });
+
+            it ('buffers the individually yielded keys into one batch per count', async () => {
+                const keys     = randomCacheKeys(5);
+                const callback = jest.fn();
+                mockScannedKeys(keys);
+
+                await Person.forEachCacheKeyByPattern(pattern, callback, 2);
+
+                expect(callback).toHaveBeenCalledTimes(3);
+                expect(callback).toHaveBeenNthCalledWith(1, keys.slice(0, 2), redisClient);
+                expect(callback).toHaveBeenNthCalledWith(2, keys.slice(2, 4), redisClient);
+                expect(callback).toHaveBeenNthCalledWith(3, keys.slice(4), redisClient);
+            });
+
+            it ('invokes the callback once when fewer keys than the count are scanned', async () => {
+                const keys     = randomCacheKeys(2);
+                const callback = jest.fn();
+                mockScannedKeys(keys);
+
+                await Person.forEachCacheKeyByPattern(pattern, callback);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledWith(keys, redisClient);
+            });
+
+            it ('flattens keys yielded as arrays', async () => {
+                const keys     = randomCacheKeys(3);
+                const callback = jest.fn();
+                mockScannedKeys([keys.slice(0, 2), keys.slice(2)]);
+
+                await Person.forEachCacheKeyByPattern(pattern, callback);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledWith(keys, redisClient);
+            });
+
+            it ('does not invoke the callback when the scan yields nothing', async () => {
+                const callback = jest.fn();
+                mockScannedKeys([]);
+
+                await Person.forEachCacheKeyByPattern(pattern, callback);
+
+                expect(callback).not.toHaveBeenCalled();
+            });
+        });
+
+
+        describe('BaseRecord.clearCacheKeysByPattern', () => {
+            const pattern = `Person#find:*`;
+
+            it ('scans for matching keys with the given pattern', async () => {
+                mockScannedKeys([]);
+
+                await Person.clearCacheKeysByPattern(pattern);
+
+                expect(redisClient.scanIterator).toHaveBeenCalledTimes(1);
+                expect(redisClient.scanIterator).toHaveBeenCalledWith({ MATCH: pattern, COUNT: 100 });
+            });
+
+            it ('deletes all scanned keys in a single batched call', async () => {
+                const keys = randomCacheKeys(3);
+                mockScannedKeys(keys);
+
+                await Person.clearCacheKeysByPattern(pattern);
+
+                expect(redisClient.del).toHaveBeenCalledTimes(1);
+                expect(redisClient.del).toHaveBeenCalledWith(keys);
+            });
+
+            it ('does not delete when the scan yields nothing', async () => {
+                mockScannedKeys([]);
+
+                await Person.clearCacheKeysByPattern(pattern);
+
+                expect(redisClient.del).not.toHaveBeenCalled();
+            });
+        });
+
+
         describe('BaseRecord.#clearSelfCache', () => {
             it ('deletes the key from cache', async () => {
                 const pk     = Person.primaryKeyAttribute;
@@ -783,6 +893,18 @@ describe('BaseRecord', () => {
                 expect(redisClient.del).toHaveBeenCalledTimes(1);
                 expect(redisClient.del).toHaveBeenCalledWith(key);
             });
+
+            it ('delegates deletion to clearCacheKey', async () => {
+                const pk       = Person.primaryKeyAttribute;
+                const id       = Math.random();
+                const key      = Person._recordCacheKey(id);
+                const person   = new Person({[pk]: id});
+                const clearSpy = jest.spyOn(Person, 'clearCacheKey');
+
+                await person.clearSelfCache();
+                expect(clearSpy).toHaveBeenCalledTimes(1);
+                expect(clearSpy).toHaveBeenCalledWith(key);
+            });
         });
 
 
@@ -790,7 +912,7 @@ describe('BaseRecord', () => {
         describe.each(hooks)('BaseRecord._after%sCacheHook', (hook) => {
             class Cacheable extends BaseRecord {
                 static get isCacheable()       { return true; }
-                static get redisClientFactory() { return mockRedisClientFactory; }
+                static get _redisClientFactory() { return mockRedisClientFactory; }
             }
             const hookMethod = `_after${hook}CacheHook`;
 

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

@@ -45,6 +45,97 @@ 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' },
@@ -58,7 +149,39 @@ describe('Migrator', () => {
 
             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 nullable deleted_at column when paranoid is set', async () => {
+            const tableName = Helpers.randomString();
+            const details = { ...defaultColumns };
+
+            await Helpers.migrator.createTable(tableName, details, { paranoid: true });
+
+            expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, {
+                ...defaultColumns,
+                deleted_at: { allowNull: true, type: 'DATE' },
+            }, Helpers.noTransaction);
+        });
+
+        it ('omits deleted_at when paranoid is not set', async () => {
+            const tableName = Helpers.randomString();
+
+            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 });
+
+            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 () => {
@@ -70,7 +193,7 @@ describe('Migrator', () => {
             expect(Helpers.mockQueryInterface.createTable).toHaveBeenCalledWith(tableName, {
                 ...defaultColumns,
                 my_column: 1,
-            });
+            }, Helpers.noTransaction);
         });
     });
 
@@ -95,7 +218,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);
         });
     });
 
@@ -108,12 +231,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);
@@ -126,8 +249,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()];
@@ -137,9 +260,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

@@ -10,6 +10,11 @@ const dataTypeKey2   = TestHelpers.Faker.Text.randomString();
 const dataTypeValue2 = TestHelpers.Faker.Text.randomString();
 
 
+function randomCacheKeys(count) {
+    return Array.from({ length: count }, () => `Person#find:${TestHelpers.Faker.Text.randomString()}`);
+}
+
+
 /***************************************************************************************************
 * MOCKS
 ***************************************************************************************************/
@@ -42,14 +47,26 @@ class MockSequelize {
 
 
 const redisClient = {
-    del:     jest.fn(),
-    mGet:    jest.fn(),
-    mSet:    jest.fn(),
-    connect: jest.fn(),
+    del:          jest.fn(),
+    mGet:         jest.fn(),
+    mSet:         jest.fn(),
+    connect:      jest.fn(),
+    scanIterator: jest.fn(),
 }
 const mockRedisClientFactory = () => redisClient;
 
 
+// redis 4's scanIterator yields one key string at a time. Pass an array element to model the
+// batches redis 5 yields instead.
+function mockScannedKeys(scanned) {
+    redisClient.scanIterator.mockImplementation(async function* () {
+        for (const item of scanned) {
+            yield item;
+        }
+    });
+}
+
+
 module.exports = {
     dataTypeKey1,
     dataTypeValue1,
@@ -57,5 +74,7 @@ module.exports = {
     dataTypeValue2,
     MockModel,
     mockRedisClientFactory,
+    mockScannedKeys,
     MockSequelize,
+    randomCacheKeys,
 }

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(),
@@ -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/cache/memoryCache.test.js

@@ -16,6 +16,82 @@ describe('MemoryCache', () => {
     });
 
 
+    describe('#delete', () => {
+        const options = {
+            namespace: 'squire:shop-data',
+            key: { shopId: 'shop-1' },
+            ttlSeconds: 300,
+        };
+
+
+        it('deletes a cached value', async () => {
+            await cache.fetch(options, async () => ({ version: 1 }));
+
+            await expect(cache.delete(options)).resolves.toBe(true);
+            await expect(cache.fetch(options, async () => ({ version: 2 }))).resolves.toEqual({
+                value: { version: 2 },
+                cacheHit: false,
+            });
+        });
+
+
+        it('deletes values using an equivalent object key', async () => {
+            await cache.fetch({
+                ...options,
+                key: { agentId: 'agent-1', shopId: 'shop-1' },
+            }, async () => ({ version: 1 }));
+
+            await expect(cache.delete({
+                namespace: options.namespace,
+                key: { shopId: 'shop-1', agentId: 'agent-1' },
+            })).resolves.toBe(true);
+        });
+
+
+        it('returns false when the value is not cached', async () => {
+            await expect(cache.delete(options)).resolves.toBe(false);
+        });
+
+
+        it('invalidates an in-flight fetch without interfering with its replacement', async () => {
+            let resolveOldFetch;
+            let resolveNewFetch;
+            const oldFetcher = jest.fn(() => new Promise((resolve) => {
+                resolveOldFetch = resolve;
+            }));
+            const newFetcher = jest.fn(() => new Promise((resolve) => {
+                resolveNewFetch = resolve;
+            }));
+            const oldFetch = cache.fetch(options, oldFetcher);
+            await expect(cache.delete(options)).resolves.toBe(true);
+            const newFetch = cache.fetch(options, newFetcher);
+
+            resolveOldFetch({ version: 1 });
+            await expect(oldFetch).resolves.toEqual({ value: { version: 1 }, cacheHit: false });
+            const joinedFetcher = jest.fn();
+            const joinedFetch   = cache.fetch(options, joinedFetcher);
+            resolveNewFetch({ version: 2 });
+
+            await expect(Promise.all([newFetch, joinedFetch])).resolves.toEqual([
+                { value: { version: 2 }, cacheHit: false },
+                { value: { version: 2 }, cacheHit: false },
+            ]);
+            expect(oldFetcher).toHaveBeenCalledTimes(1);
+            expect(newFetcher).toHaveBeenCalledTimes(1);
+            expect(joinedFetcher).not.toHaveBeenCalled();
+            await expect(cache.fetch(options, joinedFetcher)).resolves.toEqual({
+                value: { version: 2 },
+                cacheHit: true,
+            });
+        });
+
+
+        it('requires a namespace', async () => {
+            await expect(cache.delete()).rejects.toThrow('MemoryCache namespace is required.');
+        });
+    });
+
+
     describe('#fetch', () => {
         const options = {
             namespace: 'squire:shop-data',