[tests] and docs for transaction listener mutation

Author: jamesgpearce

src/types/docs/store.js

@@ -4630,6 +4630,10 @@
    * the transaction. Since this is called at the start, they will both be
    * `false`!
    *
+   * Note that a TransactionListener added to the Store with this method can
+   * mutate the Store, and its changes will be treated as part of the
+   * transaction that is starting.
+   *
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at start end of the
@@ -4681,6 +4685,11 @@
    * value of `cellsTouched` and `valuesTouched` in the listener will be `false`
    * because all changes have been reverted.
    *
+   * Note that a TransactionListener added to the Store with this method can
+   * mutate the Store itself, and its changes will be treated as part of the
+   * transaction that is starting (and may fire non-mutating listeners after
+   * this).
+   *
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the
@@ -4773,6 +4782,9 @@
    * value of `cellsTouched` and `valuesTouched` in the listener will be `false`
    * because all changes have been reverted.
    *
+   * Note that a TransactionListener added to the Store with this method
+   * _cannot_ mutate the Store itself, and attempts to do so will fail silently.
+   *
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that is called at the end of the

test/unit/store-listeners.test.ts

@@ -3132,7 +3132,7 @@ describe('Listeners', () => {
     });
   });
 
-  describe('Will and did finish transaction', () => {
+  describe('transaction', () => {
     beforeEach(() => {
       store = createStore();
       listener = createStoreListener(store);
@@ -4901,6 +4901,45 @@ describe('Mutating listeners', () => {
     });
   });
 
+  describe('transaction', () => {
+    beforeEach(() => {
+      store = createStore();
+    });
+
+    test('start can mutate', () => {
+      const listener = jest.fn(() => {
+        store.setValue('mutated', true);
+      });
+      store.addStartTransactionListener(listener);
+      store.setCell('t1', 'r1', 'c1', 'r1');
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'r1'}}});
+      expect(store.getValues()).toEqual({mutated: true});
+    });
+
+    test('willFinish can mutate', () => {
+      const listener = jest.fn(() => {
+        store.setValue('mutated', true);
+      });
+      store.addWillFinishTransactionListener(listener);
+      store.setCell('t1', 'r1', 'c1', 'r1');
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'r1'}}});
+      expect(store.getValues()).toEqual({mutated: true});
+    });
+
+    test('didFinish cannot mutate', () => {
+      const listener = jest.fn(() => {
+        store.setValue('mutated', true);
+      });
+      store.addDidFinishTransactionListener(listener);
+      store.setCell('t1', 'r1', 'c1', 'r1');
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(store.getTables()).toEqual({t1: {r1: {c1: 'r1'}}});
+      expect(store.getValues()).toEqual({});
+    });
+  });
+
   describe('Miscellaneous', () => {
     beforeEach(() => {
       store = createStore();