@vida-global/core 2.3.2 → 2.3.3

package/lib/activeRecord/README.md

@@ -249,7 +249,7 @@ user.fullName; // "Ada Lovelace"
 Opt a model in to Redis-backed caching by overriding `isCacheable`. With caching on:
 
 - `Model.find(id)` and `Model.find([id1, id2])` consult Redis first and fall back to the database for misses, repopulating the cache for next time.
-- `afterSave` and `afterDestroy` hooks automatically invalidate the cached record.
+- An `afterCommit` hook automatically invalidates the cached record, so a write that is rolled back never disturbs the cache.
 - Cache keys are namespaced as `AR:<ClassName>` (`<ClassName>#find:<id>`).
 
 ```js
@@ -294,7 +294,29 @@ User.addHook('afterSave', async (user, options) => {
 });
 ```
 
-See [Sequelize hooks](https://sequelize.org/docs/v6/other-topics/hooks/) for the full list of hook points. The caching layer above uses `afterSave` and `afterDestroy` under the hood when `isCacheable` is true.
+See [Sequelize hooks](https://sequelize.org/docs/v6/other-topics/hooks/) for the full list of hook points.
+
+
+### afterCommit
+
+Every hook above runs *inside* the transaction the write belongs to, so its work is undone if that
+transaction rolls back. Use `afterCommit` for anything that must not happen until the data is
+durable — cache invalidation, broadcasts, enqueuing jobs:
+
+```js
+User.addHook('afterCommit', async (user, options) => {
+    await broadcast('users.changed', { id: user.id });   // never fires if the transaction rolls back
+});
+```
+
+- Fires once per record written, after the transaction commits. A write outside a transaction fires
+  it immediately.
+- Fires on create, update, destroy, restore and upsert. Bulk statements such as
+  `Model.destroy({ where })` only fire it when `individualHooks: true` is set, the same as
+  `afterDestroy`.
+- With nested transactions, only the outermost commit fires it. A savepoint that commits inside a
+  transaction that later rolls back fires nothing.
+- A record written more than once in the same transaction still fires each callback once.
 
 
 ## Associations

package/lib/activeRecord/afterCommitHooks.js

@@ -0,0 +1,167 @@
+// Sequelize has no model level afterCommit hook, only Transaction#afterCommit. This module holds
+// the callbacks registered for one and defers them onto the transaction a write belongs to, so
+// BaseRecord can offer afterCommit alongside the hooks sequelize does provide.
+
+// Keyed by model class so callbacks stay scoped to the model they were registered on. Module scope
+// is what keeps them unreachable from outside: a static # field is unreadable through a subclass,
+// and a plain static field on BaseRecord would be one collection shared by every model.
+const modelCallbacks       = new WeakMap();
+const claimedRegistrations = new WeakMap();
+
+
+/***************************************************************************************************
+* REGISTRATION
+***************************************************************************************************/
+function addCallback(model, name, fn) {
+    const callback = buildCallback(name, fn);
+    ownCallbacks(model).push(callback);
+}
+
+
+// Sequelize's addHook takes either (name, fn) or (fn), and stores the named form as an object so it
+// can be removed by name later. Match both.
+function buildCallback(name, fn) {
+    if (typeof name === 'function') return name;
+
+    return { name, fn };
+}
+
+
+function removeCallback(model, name) {
+    const remaining = ownCallbacks(model).filter(callback => !callbackMatches(callback, name));
+    modelCallbacks.set(model, remaining);
+}
+
+
+// Only named callbacks are removable by name. An unnamed one carries its function name, which would
+// otherwise match a string by accident.
+function callbackMatches(callback, name) {
+    if (typeof name === 'function')  return callback === name;
+    if (typeof callback === 'object') return callback.name === name;
+
+    return false;
+}
+
+
+function ownCallbacks(model) {
+    if (!modelCallbacks.has(model)) modelCallbacks.set(model, []);
+
+    return modelCallbacks.get(model);
+}
+
+
+/***************************************************************************************************
+* LOOKUP
+***************************************************************************************************/
+// Ancestors first, so callbacks run in the order they were registered as you read down a hierarchy.
+function callbacksFor(model) {
+    const callbacks = [];
+    for (const ancestor of modelChain(model)) {
+        callbacks.unshift(...inheritableCallbacks(ancestor));
+    }
+    return callbacks;
+}
+
+
+function inheritableCallbacks(model) {
+    const callbacks = modelCallbacks.get(model) || [];
+    return callbacks.map(callback => callbackFunction(callback));
+}
+
+
+function callbackFunction(callback) {
+    if (typeof callback === 'function') return callback;
+
+    return callback.fn;
+}
+
+
+function* modelChain(model) {
+    let ancestor = model;
+    while (typeof ancestor === 'function') {
+        yield ancestor;
+        ancestor = Object.getPrototypeOf(ancestor);
+    }
+}
+
+
+/***************************************************************************************************
+* DISPATCH
+***************************************************************************************************/
+async function runCallbacks(model, record, options) {
+    const transaction = rootTransaction(options.transaction);
+
+    if (!transaction) return await callImmediately(model, record, options);
+
+    deferToTransaction(transaction, model, record, options);
+}
+
+
+// A savepoint commits while its parent can still roll back, so the callbacks belong to the
+// outermost transaction.
+function rootTransaction(transaction) {
+    let root = transaction;
+    while (root?.parent) {
+        root = root.parent;
+    }
+    return root;
+}
+
+
+async function callImmediately(model, record, options) {
+    for (const callback of callbacksFor(model)) {
+        await callback.call(model, record, options);
+    }
+}
+
+
+function deferToTransaction(transaction, model, record, options) {
+    for (const callback of callbacksFor(model)) {
+        deferCallback(transaction, callback, model, record, options);
+    }
+}
+
+
+function deferCallback(transaction, callback, model, record, options) {
+    if (!claimRegistration(transaction, callback, record)) return;
+
+    transaction.afterCommit(async () => await callback.call(model, record, options));
+}
+
+
+/***************************************************************************************************
+* DEDUPLICATION
+***************************************************************************************************/
+// Overlapping hooks can report the same write twice. Each callback runs once per record per
+// transaction; returns false when this one is already spoken for.
+function claimRegistration(transaction, callback, record) {
+    const records = claimedRecords(transaction, callback);
+    if (records.has(record)) return false;
+
+    records.add(record);
+    return true;
+}
+
+
+// A WeakSet so claiming a record doesn't hold it in memory for the life of the transaction.
+function claimedRecords(transaction, callback) {
+    const callbacks = transactionClaims(transaction);
+    if (!callbacks.has(callback)) callbacks.set(callback, new WeakSet());
+
+    return callbacks.get(callback);
+}
+
+
+function transactionClaims(transaction) {
+    if (!claimedRegistrations.has(transaction)) claimedRegistrations.set(transaction, new Map());
+
+    return claimedRegistrations.get(transaction);
+}
+
+
+module.exports = {
+    addCallback,
+    callbacksFor,
+    removeCallback,
+    runCallbacks,
+}

package/lib/activeRecord/baseRecord.js

@@ -6,10 +6,14 @@ const { Model, Op, Sequelize }            = require('sequelize');
 const   nodeUtil                          = require('util');
 const { redisClientFactory }              = require('../redis');
 const { camelize, tableize }              = require('inflection');
+const   afterCommitHooks                  = require('./afterCommitHooks');
 const   utils                             = require('./utils');
 const   validations                       = require('./validations');
 
 
+const AFTER_COMMIT = 'afterCommit';
+
+
 class BaseRecord extends Model {
     static _connection;
     static _initialized = false;
@@ -197,14 +201,76 @@ class BaseRecord extends Model {
     }
 
 
+    /***********************************************************************************************
+    * HOOKS
+    ***********************************************************************************************/
     static initializeHooks() {
+        this._initializeAfterCommitHooks();
+
         if (this.isCacheable) {
-            this.addHook('afterSave',    this._afterSaveCacheHook);
-            this.addHook('afterDestroy', this._afterDestroyCacheHook);
+            this.addHook(AFTER_COMMIT, this._afterCommitCacheHook);
+        }
+    }
+
+
+    static _initializeAfterCommitHooks() {
+        // Every hook that reports a write to a single record. afterSave is deliberately the only save hook
+        // listed: sequelize proxies it into afterCreate and afterUpdate, so adding those would double fire.
+        const AFTER_COMMIT_SOURCE_HOOKS = ['afterSave', 'afterDestroy', 'afterRestore', 'afterUpsert'];
+        for (const hookType of AFTER_COMMIT_SOURCE_HOOKS) {
+            this.addHook(hookType, this._afterCommitHandler);
         }
     }
 
 
+    static addHook(hookType, name, fn) {
+        if (hookType != AFTER_COMMIT) return super.addHook(hookType, name, fn);
+
+        afterCommitHooks.addCallback(this, name, fn);
+        return this;
+    }
+
+
+    static removeHook(hookType, name) {
+        if (hookType != AFTER_COMMIT) return super.removeHook(hookType, name);
+
+        afterCommitHooks.removeCallback(this, name);
+        return this;
+    }
+
+
+    static hasHook(hookType) {
+        if (hookType != AFTER_COMMIT) return super.hasHook(hookType);
+
+        return Boolean(afterCommitHooks.callbacksFor(this).length);
+    }
+
+
+    // Sequelize aliases hasHooks onto its own hasHook, so overriding hasHook alone leaves it behind.
+    static hasHooks(hookType) {
+        return this.hasHook(hookType);
+    }
+
+
+    // Sequelize generates a shorthand registration method for each of its hook types. Match it.
+    static afterCommit(name, fn) {
+        return this.addHook(AFTER_COMMIT, name, fn);
+    }
+
+
+    static async _afterCommitHandler(recordOrResult, options) {
+        const record = this._afterCommitRecord(recordOrResult);
+        await afterCommitHooks.runCallbacks(this, record, options);
+    }
+
+
+    static _afterCommitRecord(recordOrResult) {
+        if (Array.isArray(recordOrResult)) return recordOrResult[0]; // afterUpsert: [record, created]
+
+        return recordOrResult;
+    }
+
+
     /***********************************************************************************************
     * VALIDATIONS
     ***********************************************************************************************/
@@ -350,7 +416,7 @@ class BaseRecord extends Model {
         const client       = await this._getRedisClient();
         const cachedValues = clear ? [] : await client.mGet(keys);
         const kvPairs      = keys.map((key,idx) => {
-            const val = this._unmarshallCachedData(cachedValues[idx]);
+            const val = this._decodeCachedValue(cachedValues[idx]);
             return [key, val]
         });
         const cachedData   = Object.fromEntries(kvPairs);
@@ -374,7 +440,7 @@ class BaseRecord extends Model {
         const toCache = {};
 
         for (const [key, value] of Object.entries(fetchedData)) {
-            toCache[key] = this._marshallDataForCaching(value);
+            toCache[key] = await this._encodeForCache(value);
         }
 
         const client = await this._getRedisClient();
@@ -448,42 +514,41 @@ class BaseRecord extends Model {
     static get isCacheable() { return false; }
 
 
-    static async _afterSaveCacheHook(record, options) {
+    static async _afterCommitCacheHook(record, options) {
         await record.clearSelfCache();
         await record.updateCache(options);
     }
 
 
-    static async _afterDestroyCacheHook(record, options) {
-        await record.clearSelfCache();
-        await record.updateCache(options);
+    // The data a record contributes to its cache entry. Override to cache associated data
+    // alongside the record so a single cache read returns both.
+    async toCachePayload() {
+        return this.toJSON();
     }
 
 
-    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;
+    // The inverse of toCachePayload: rebuilds a record from its cached data.
+    static fromCachePayload(data) {
+        return new this(data, {isNewRecord: false});
     }
 
 
-    static _unmarshallCachedData(value) {
+    static async _encodeForCache(value) {
+        if (!(value instanceof this)) return JSON.stringify(value);
+
+        const payload = await value.toCachePayload();
+        return `${this.recordCachingPrefix}:${JSON.stringify(payload)}`;
+    }
+
+
+    static _decodeCachedValue(value) {
         if (value == null)            return null;
         if (typeof value != 'string') return value;
+        if (!value.startsWith(this.recordCachingPrefix)) return JSON.parse(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);
-        }
+        const regExp = new RegExp(`^${this.recordCachingPrefix}:`);
+        const data   = JSON.parse(value.replace(regExp, ''));
+        return this.fromCachePayload(data);
     }
 
 

package/lib/server/controllerMixins/validations.js

@@ -70,7 +70,7 @@ const InstanceMethods = {
 
     validateIsString(value, options) {
         if (typeof value !== 'string') return 'must be a string';
-        if (options?.allowEmpty === false && value.length === 0) return 'must not be empty';
+        if (options?.allowEmpty === false && value.trim().length === 0) return 'must not be empty';
 
         if (options?.length?.gte !== undefined) {
             if (value.length < options.length.gte) return `must be greater than or equal to ${options.length.gte} characters`;

package/package.json

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

package/test/activeRecord/afterCommitHooks.test.js

@@ -0,0 +1,326 @@
+const afterCommitHooks = require('../../lib/activeRecord/afterCommitHooks');
+const TestHelpers      = require('@vida-global/test-helpers');
+const Helpers          = require('./helpers/afterCommitHooks');
+
+
+afterEach(() => {
+    jest.clearAllMocks();
+});
+
+
+describe('afterCommitHooks', () => {
+    describe('addCallback', () => {
+        it ('registers an unnamed callback', () => {
+            const model    = Helpers.buildModel();
+            const callback = jest.fn();
+
+            afterCommitHooks.addCallback(model, callback);
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([callback]);
+        });
+
+        it ('registers a named callback', () => {
+            const model    = Helpers.buildModel();
+            const name     = TestHelpers.Faker.Text.randomString();
+            const callback = jest.fn();
+
+            afterCommitHooks.addCallback(model, name, callback);
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([callback]);
+        });
+
+        it ('keeps callbacks in the order they were registered', () => {
+            const model  = Helpers.buildModel();
+            const first  = jest.fn();
+            const second = jest.fn();
+
+            afterCommitHooks.addCallback(model, first);
+            afterCommitHooks.addCallback(model, second);
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([first, second]);
+        });
+    });
+
+
+    describe('removeCallback', () => {
+        it ('removes an unnamed callback by reference', () => {
+            const model     = Helpers.buildModel();
+            const removed   = jest.fn();
+            const remaining = jest.fn();
+            afterCommitHooks.addCallback(model, removed);
+            afterCommitHooks.addCallback(model, remaining);
+
+            afterCommitHooks.removeCallback(model, removed);
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([remaining]);
+        });
+
+        it ('removes a named callback by name', () => {
+            const model     = Helpers.buildModel();
+            const name      = TestHelpers.Faker.Text.randomString();
+            const removed   = jest.fn();
+            const remaining = jest.fn();
+            afterCommitHooks.addCallback(model, name, removed);
+            afterCommitHooks.addCallback(model, remaining);
+
+            afterCommitHooks.removeCallback(model, name);
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([remaining]);
+        });
+
+        it ('leaves unnamed callbacks alone when removing by name', () => {
+            const model    = Helpers.buildModel();
+            const callback = function namedFunction() {};
+            afterCommitHooks.addCallback(model, callback);
+
+            afterCommitHooks.removeCallback(model, 'namedFunction');
+
+            expect(afterCommitHooks.callbacksFor(model)).toEqual([callback]);
+        });
+
+        it ('does not remove callbacks registered on an ancestor', () => {
+            const parent   = Helpers.buildModel();
+            const child    = Helpers.buildModel(parent);
+            const callback = jest.fn();
+            afterCommitHooks.addCallback(parent, callback);
+
+            afterCommitHooks.removeCallback(child, callback);
+
+            expect(afterCommitHooks.callbacksFor(parent)).toEqual([callback]);
+            expect(afterCommitHooks.callbacksFor(child)).toEqual([callback]);
+        });
+    });
+
+
+    describe('callbacksFor', () => {
+        it ('returns an empty list for a model with no callbacks', () => {
+            expect(afterCommitHooks.callbacksFor(Helpers.buildModel())).toEqual([]);
+        });
+
+        it ('includes callbacks registered on an ancestor', () => {
+            const parent         = Helpers.buildModel();
+            const child          = Helpers.buildModel(parent);
+            const parentCallback = jest.fn();
+            const childCallback  = jest.fn();
+            afterCommitHooks.addCallback(parent, parentCallback);
+            afterCommitHooks.addCallback(child, childCallback);
+
+            expect(afterCommitHooks.callbacksFor(child)).toEqual([parentCallback, childCallback]);
+        });
+
+        it ('does not include callbacks registered on a descendant', () => {
+            const parent        = Helpers.buildModel();
+            const child         = Helpers.buildModel(parent);
+            const childCallback = jest.fn();
+            afterCommitHooks.addCallback(child, childCallback);
+
+            expect(afterCommitHooks.callbacksFor(parent)).toEqual([]);
+        });
+
+        it ('does not include callbacks registered on a sibling', () => {
+            const parent           = Helpers.buildModel();
+            const sibling          = Helpers.buildModel(parent);
+            const otherSibling     = Helpers.buildModel(parent);
+            const siblingCallback  = jest.fn();
+            afterCommitHooks.addCallback(sibling, siblingCallback);
+
+            expect(afterCommitHooks.callbacksFor(otherSibling)).toEqual([]);
+        });
+    });
+
+
+    describe('runCallbacks', () => {
+        describe('without a transaction', () => {
+            it ('calls every registered callback with the record and options', async () => {
+                const model    = Helpers.buildModel();
+                const record   = Helpers.buildRecord();
+                const options  = {};
+                const callback = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, record, options);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledWith(record, options);
+            });
+
+            it ('calls the callback with the model as its context', async () => {
+                const model = Helpers.buildModel();
+                let   context;
+                afterCommitHooks.addCallback(model, function() { context = this; });
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), {});
+
+                expect(context).toBe(model);
+            });
+
+            it ('awaits each callback before running the next', async () => {
+                const model = Helpers.buildModel();
+                const order = [];
+                afterCommitHooks.addCallback(model, async () => {
+                    await Promise.resolve();
+                    order.push('first');
+                });
+                afterCommitHooks.addCallback(model, () => order.push('second'));
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), {});
+
+                expect(order).toEqual(['first', 'second']);
+            });
+
+            it ('lets a callback error propagate', async () => {
+                const model   = Helpers.buildModel();
+                const message = TestHelpers.Faker.Text.randomString();
+                afterCommitHooks.addCallback(model, () => { throw new Error(message); });
+
+                await expect(afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), {}))
+                    .rejects.toThrow(message);
+            });
+        });
+
+
+        describe('with a transaction', () => {
+            it ('defers the callback to the transaction instead of running it', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const callback    = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), { transaction });
+
+                expect(transaction.afterCommit).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledTimes(0);
+            });
+
+            it ('calls the callback with the record and options once the transaction commits', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const record      = Helpers.buildRecord();
+                const options     = { transaction };
+                const callback    = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, record, options);
+                await Helpers.commit(transaction);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledWith(record, options);
+            });
+
+            it ('lets a callback error propagate out of the commit', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const message     = TestHelpers.Faker.Text.randomString();
+                afterCommitHooks.addCallback(model, () => { throw new Error(message); });
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), { transaction });
+
+                await expect(Helpers.commit(transaction)).rejects.toThrow(message);
+            });
+
+            it ('defers to the outermost transaction when the write is in a savepoint', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const savepoint   = Helpers.buildSavepoint(transaction);
+                afterCommitHooks.addCallback(model, jest.fn());
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), { transaction: savepoint });
+
+                expect(transaction.afterCommit).toHaveBeenCalledTimes(1);
+                expect(savepoint.afterCommit).toHaveBeenCalledTimes(0);
+            });
+
+            it ('defers to the outermost transaction through nested savepoints', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const outerPoint  = Helpers.buildSavepoint(transaction);
+                const innerPoint  = Helpers.buildSavepoint(outerPoint);
+                afterCommitHooks.addCallback(model, jest.fn());
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), { transaction: innerPoint });
+
+                expect(transaction.afterCommit).toHaveBeenCalledTimes(1);
+                expect(outerPoint.afterCommit).toHaveBeenCalledTimes(0);
+                expect(innerPoint.afterCommit).toHaveBeenCalledTimes(0);
+            });
+        });
+
+
+        describe('deduplication', () => {
+            it ('defers a callback once when the same record is reported twice', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const record      = Helpers.buildRecord();
+                const callback    = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, record, { transaction });
+                await afterCommitHooks.runCallbacks(model, record, { transaction });
+                await Helpers.commit(transaction);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+
+            it ('defers a callback for each distinct record', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const first       = Helpers.buildRecord();
+                const second      = Helpers.buildRecord();
+                const callback    = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, first, { transaction });
+                await afterCommitHooks.runCallbacks(model, second, { transaction });
+                await Helpers.commit(transaction);
+
+                expect(callback).toHaveBeenCalledTimes(2);
+            });
+
+            it ('defers every registered callback for the same record', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const first       = jest.fn();
+                const second      = jest.fn();
+                afterCommitHooks.addCallback(model, first);
+                afterCommitHooks.addCallback(model, second);
+
+                await afterCommitHooks.runCallbacks(model, Helpers.buildRecord(), { transaction });
+                await Helpers.commit(transaction);
+
+                expect(first).toHaveBeenCalledTimes(1);
+                expect(second).toHaveBeenCalledTimes(1);
+            });
+
+            it ('treats the same record in a separate transaction as a new registration', async () => {
+                const model    = Helpers.buildModel();
+                const first    = Helpers.buildTransaction();
+                const second   = Helpers.buildTransaction();
+                const record   = Helpers.buildRecord();
+                const callback = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, record, { transaction: first });
+                await afterCommitHooks.runCallbacks(model, record, { transaction: second });
+                await Helpers.commit(first);
+                await Helpers.commit(second);
+
+                expect(callback).toHaveBeenCalledTimes(2);
+            });
+
+            it ('deduplicates against the outermost transaction across savepoints', async () => {
+                const model       = Helpers.buildModel();
+                const transaction = Helpers.buildTransaction();
+                const savepoint   = Helpers.buildSavepoint(transaction);
+                const record      = Helpers.buildRecord();
+                const callback    = jest.fn();
+                afterCommitHooks.addCallback(model, callback);
+
+                await afterCommitHooks.runCallbacks(model, record, { transaction });
+                await afterCommitHooks.runCallbacks(model, record, { transaction: savepoint });
+                await Helpers.commit(transaction);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+});

package/test/activeRecord/baseRecord.test.js

@@ -844,6 +844,98 @@ describe('BaseRecord', () => {
         });
 
 
+        describe('BaseRecord#toCachePayload', () => {
+            it ('returns the record as JSON', async () => {
+                const attrName = TestHelpers.Faker.Text.randomString();
+                const attrVal  = TestHelpers.Faker.Text.randomString();
+                const person   = new Person({[attrName]: attrVal});
+
+                await expect(person.toCachePayload()).resolves.toEqual({[attrName]: attrVal});
+            });
+        });
+
+
+        describe('BaseRecord.fromCachePayload', () => {
+            it ('builds a record that is not new', () => {
+                const attrName = TestHelpers.Faker.Text.randomString();
+                const attrVal  = TestHelpers.Faker.Text.randomString();
+
+                const person = Person.fromCachePayload({[attrName]: attrVal});
+
+                expect(person instanceof Person).toBeTruthy();
+                expect(person[attrName]).toEqual(attrVal);
+                expect(person.options.isNewRecord).toBeFalsy();
+            });
+        });
+
+
+        describe('cache payload overrides', () => {
+            const EXTRA_KEY = 'nicknames';
+
+            class Player extends Person {
+                #nicknames = null;
+
+
+                get nicknames()      { return this.#nicknames; }
+                set nicknames(names) { this.#nicknames = names; }
+
+
+                async toCachePayload() {
+                    const payload      = await super.toCachePayload();
+                    payload[EXTRA_KEY] = await this.fetchNicknames();
+                    return payload;
+                }
+
+
+                static fromCachePayload(data) {
+                    const { [EXTRA_KEY]: nicknames, ...attributes } = data;
+                    const player     = super.fromCachePayload(attributes);
+                    player.nicknames = nicknames;
+                    return player;
+                }
+
+
+                async fetchNicknames() { return []; }
+            }
+
+            const attrName = TestHelpers.Faker.Text.randomString();
+            const attrVal  = TestHelpers.Faker.Text.randomString();
+            const nickname = TestHelpers.Faker.Text.randomString();
+            const payload  = {[attrName]: attrVal, [EXTRA_KEY]: [nickname]};
+            const cached   = `AR:Player:${JSON.stringify(payload)}`;
+
+            it ('writes the associated data into the cached value', async () => {
+                const key    = TestHelpers.Faker.Text.randomString();
+                const player = new Player({[attrName]: attrVal});
+                jest.spyOn(player, 'fetchNicknames').mockResolvedValue([nickname]);
+
+                await Player._cacheFetchedData({[key]: player});
+
+                expect(redisClient.mSet).toHaveBeenCalledTimes(1);
+                expect(redisClient.mSet).toHaveBeenCalledWith({[key]: cached});
+            });
+
+            it ('restores the associated data when decoding, keeping it out of the attributes', () => {
+                const player = Player._decodeCachedValue(cached);
+
+                expect(player.nicknames).toEqual([nickname]);
+                expect(player[attrName]).toEqual(attrVal);
+                expect(player.dataValues[EXTRA_KEY]).toBeUndefined();
+            });
+
+            it ('returns the record and its associated data from a single cache read', async () => {
+                const id = Math.random();
+                redisClient.mGet.mockImplementation(() => [cached]);
+
+                const player = await Player._cachedFind(id);
+
+                expect(redisClient.mGet).toHaveBeenCalledTimes(1);
+                expect(Player.findAll).not.toHaveBeenCalled();
+                expect(player.nicknames).toEqual([nickname]);
+            });
+        });
+
+
         describe('BaseRecord.clearCacheKey', () => {
             it ('deletes the given key from cache', async () => {
                 const key = `Person#find:${Math.random()}`;
@@ -980,34 +1072,42 @@ describe('BaseRecord', () => {
         });
 
 
-        const hooks = ['Save', 'Destroy'];
-        describe.each(hooks)('BaseRecord._after%sCacheHook', (hook) => {
-            class Cacheable extends BaseRecord {
-                static get isCacheable()       { return true; }
-                static get _redisClientFactory() { return mockRedisClientFactory; }
-            }
-            const hookMethod = `_after${hook}CacheHook`;
+        describe('BaseRecord._afterCommitCacheHook', () => {
+            const buildCacheable = () => {
+                class Cacheable extends BaseRecord {
+                    static get isCacheable()         { return true; }
+                    static get _redisClientFactory() { return mockRedisClientFactory; }
+                }
+                return Cacheable;
+            };
+
+
+            it ('is registered as an afterCommit hook for cached models', () => {
+                const Cacheable = buildCacheable();
+                const addSpy    = jest.spyOn(Cacheable, 'addHook');
 
-            it (`is called as an after ${hook.toLowerCase()} hook for cached models`, () => {
-                expect(Cacheable.addHook).toHaveBeenCalledTimes(0);
                 Cacheable.initialize();
-                expect(Cacheable.addHook).toHaveBeenCalledTimes(2);
-                expect(Cacheable.addHook).toHaveBeenCalledWith(`after${hook}`, Cacheable[hookMethod]);
+
+                expect(addSpy).toHaveBeenCalledWith('afterCommit', Cacheable._afterCommitCacheHook);
             });
 
-            it ('is not called as an after save hook for non cached models', () => {
+            it ('is not registered for non cached models', () => {
                 class Foo extends BaseRecord {}
+                const addSpy = jest.spyOn(Foo, 'addHook');
+
                 Foo.initialize();
-                expect(Cacheable.addHook).toHaveBeenCalledTimes(0);
+
+                expect(addSpy).not.toHaveBeenCalledWith('afterCommit', expect.anything());
             });
 
             it ('calls BaseRecord#clearSelfCache and BaseRecord#updateCache', async () => {
+                const Cacheable = buildCacheable();
                 const person    = new Cacheable();
                 const clearSpy  = jest.spyOn(person, 'clearSelfCache');
                 const updateSpy = jest.spyOn(person, 'updateCache');
                 const options   = {};
 
-                await Cacheable[hookMethod](person,options);
+                await Cacheable._afterCommitCacheHook(person, options);
 
                 expect(clearSpy).toHaveBeenCalledTimes(1);
                 expect(updateSpy).toHaveBeenCalledTimes(1);
@@ -1017,6 +1117,204 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('afterCommit hooks', () => {
+        const sourceHooks = ['afterSave', 'afterDestroy', 'afterRestore', 'afterUpsert'];
+
+        describe('BaseRecord.addHook', () => {
+            it ('delegates hook types sequelize supports to the parent implementation', () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+
+                User.addHook('beforeSave', callback);
+
+                expect(Model.addHook).toHaveBeenCalledTimes(1);
+                expect(Model.addHook).toHaveBeenCalledWith('beforeSave', callback, undefined);
+            });
+
+            it ('does not delegate afterCommit to the parent implementation', () => {
+                class User extends BaseRecord {}
+
+                User.addHook('afterCommit', jest.fn());
+
+                expect(Model.addHook).toHaveBeenCalledTimes(0);
+            });
+
+            it ('registers the callback so it runs on commit', async () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+                const record   = new User();
+                const options  = {};
+                User.addHook('afterCommit', callback);
+
+                await User._afterCommitHandler(record, options);
+
+                expect(callback).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledWith(record, options);
+            });
+
+            it ('registers a named callback', async () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+                User.addHook('afterCommit', TestHelpers.Faker.Text.randomString(), callback);
+
+                await User._afterCommitHandler(new User(), {});
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+
+
+        describe('BaseRecord.removeHook', () => {
+            it ('delegates hook types sequelize supports to the parent implementation', () => {
+                class User extends BaseRecord {}
+                const name = TestHelpers.Faker.Text.randomString();
+
+                User.removeHook('beforeSave', name);
+
+                expect(Model.removeHook).toHaveBeenCalledTimes(1);
+                expect(Model.removeHook).toHaveBeenCalledWith('beforeSave', name);
+            });
+
+            it ('removes a registered afterCommit callback', async () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+                User.addHook('afterCommit', callback);
+
+                User.removeHook('afterCommit', callback);
+                await User._afterCommitHandler(new User(), {});
+
+                expect(Model.removeHook).toHaveBeenCalledTimes(0);
+                expect(callback).toHaveBeenCalledTimes(0);
+            });
+        });
+
+
+        describe('BaseRecord.hasHook', () => {
+            it ('delegates hook types sequelize supports to the parent implementation', () => {
+                class User extends BaseRecord {}
+
+                User.hasHook('beforeSave');
+
+                expect(Model.hasHook).toHaveBeenCalledTimes(1);
+                expect(Model.hasHook).toHaveBeenCalledWith('beforeSave');
+            });
+
+            it ('reports false when no afterCommit callback is registered', () => {
+                class User extends BaseRecord {}
+
+                expect(User.hasHook('afterCommit')).toBe(false);
+            });
+
+            it ('reports true once an afterCommit callback is registered', () => {
+                class User extends BaseRecord {}
+                User.addHook('afterCommit', jest.fn());
+
+                expect(User.hasHook('afterCommit')).toBe(true);
+            });
+        });
+
+
+        describe('BaseRecord.hasHooks', () => {
+            it ('reports on afterCommit the same way hasHook does', () => {
+                class User extends BaseRecord {}
+                User.addHook('afterCommit', jest.fn());
+
+                expect(User.hasHooks('afterCommit')).toBe(true);
+            });
+        });
+
+
+        describe('BaseRecord.afterCommit', () => {
+            it ('registers the callback like addHook does', async () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+
+                User.afterCommit(callback);
+                await User._afterCommitHandler(new User(), {});
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+        });
+
+
+        describe('BaseRecord.initializeHooks', () => {
+            it.each(sourceHooks)('registers the afterCommit handler on %s', (hookType) => {
+                class User extends BaseRecord {}
+
+                User.initialize();
+
+                expect(Model.addHook).toHaveBeenCalledWith(hookType, User._afterCommitHandler, undefined);
+            });
+
+            it ('does not register the handler on afterCreate or afterUpdate', () => {
+                class User extends BaseRecord {}
+
+                User.initialize();
+
+                expect(Model.addHook).not.toHaveBeenCalledWith('afterCreate', expect.anything(), undefined);
+                expect(Model.addHook).not.toHaveBeenCalledWith('afterUpdate', expect.anything(), undefined);
+            });
+        });
+
+
+        describe('BaseRecord._afterCommitHandler', () => {
+            it ('runs callbacks inherited from a parent model', async () => {
+                class User extends BaseRecord {}
+                class Admin extends User {}
+                const callback = jest.fn();
+                User.addHook('afterCommit', callback);
+
+                await Admin._afterCommitHandler(new Admin(), {});
+
+                expect(callback).toHaveBeenCalledTimes(1);
+            });
+
+            it ('does not run callbacks registered on an unrelated model', async () => {
+                class User extends BaseRecord {}
+                class Account extends BaseRecord {}
+                const callback = jest.fn();
+                User.addHook('afterCommit', callback);
+
+                await Account._afterCommitHandler(new Account(), {});
+
+                expect(callback).toHaveBeenCalledTimes(0);
+            });
+
+            it ('unwraps the record from the array afterUpsert reports', async () => {
+                class User extends BaseRecord {}
+                const callback = jest.fn();
+                const record   = new User();
+                const options  = {};
+                User.addHook('afterCommit', callback);
+
+                await User._afterCommitHandler([record, true], options);
+
+                expect(callback).toHaveBeenCalledWith(record, options);
+            });
+
+            it ('defers to the transaction when the write is in one', async () => {
+                class User extends BaseRecord {}
+                const transaction = { afterCommit: jest.fn(), parent: null };
+                const callback    = jest.fn();
+                User.addHook('afterCommit', callback);
+
+                await User._afterCommitHandler(new User(), { transaction });
+
+                expect(transaction.afterCommit).toHaveBeenCalledTimes(1);
+                expect(callback).toHaveBeenCalledTimes(0);
+            });
+
+            it ('lets a callback error propagate', async () => {
+                class User extends BaseRecord {}
+                const message = TestHelpers.Faker.Text.randomString();
+                User.addHook('afterCommit', () => { throw new Error(message); });
+
+                await expect(User._afterCommitHandler(new User(), {})).rejects.toThrow(message);
+            });
+        });
+    });
+
+
     describe('.documentationSchema', () => {
         const buildModel = (attributes) => {
             class Thing extends BaseRecord {}

package/test/activeRecord/helpers/afterCommitHooks.js

@@ -0,0 +1,47 @@
+const TestHelpers = require('@vida-global/test-helpers');
+
+
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function buildTransaction() {
+    return { afterCommit: jest.fn(), parent: null };
+}
+
+
+function buildSavepoint(parent) {
+    return { afterCommit: jest.fn(), parent };
+}
+
+
+// The callbacks module keys everything off the model class itself, so any class works as a stand in.
+function buildModel(parent) {
+    if (parent) return class Child extends parent {};
+
+    return class Model {};
+}
+
+
+function buildRecord() {
+    return { id: TestHelpers.Faker.Text.randomString() };
+}
+
+
+/***************************************************************************************************
+* ASSERTIONS
+***************************************************************************************************/
+// Nothing runs until the transaction commits, so tests drive the deferred callbacks by hand.
+async function commit(transaction) {
+    for (const [deferred] of transaction.afterCommit.mock.calls) {
+        await deferred();
+    }
+}
+
+
+module.exports = {
+    buildModel,
+    buildRecord,
+    buildSavepoint,
+    buildTransaction,
+    commit,
+}

package/test/activeRecord/helpers/baseRecordMocks.js

@@ -27,6 +27,8 @@ class MockModel {
         }
     };
     static addHook             = jest.fn()
+    static removeHook          = jest.fn()
+    static hasHook             = jest.fn()
     static init                = jest.fn()
     static findByPk            = jest.fn();
     static findAll             = jest.fn();