tinybase 1.2.3 → 1.3.0-beta.0

package/lib/debug/store.d.ts

@@ -176,6 +176,32 @@ export type MapCell = (cell: CellOrUndefined) => Cell;
  */
 export type GetCell = (cellId: Id) => CellOrUndefined;
 
+/**
+ * The TransactionListener type describes a function that is used to listen to
+ * the completion of a transaction for the Store.
+ *
+ * A TransactionListener is provided when using the
+ * addWillFinishTransactionListener and addDidFinishTransactionListener methods.
+ * See those methods for specific examples.
+ *
+ * When called, a TransactionListener is simply given a reference to the Store
+ * and a boolean to indicate whether Cell values have been touched during the
+ * transaction. The latter flag is intended as a hint about whether non-mutating
+ * listeners might be being called at the end of the transaction.
+ *
+ * Here, 'touched' means that Cell values have either been changed, or changed
+ * and then changed back to its original value during the transaction. The
+ * exception is a transaction that has been rolled back, for which the value of
+ * `cellsTouched` in the listener will be `false` because all changes have been
+ * reverted.
+ *
+ * @param store A reference to the Store that is completing a transaction.
+ * @param cellsTouched Whether Cell values have been touched during the
+ * transaction.
+ * @category Listener
+ */
+export type TransactionListener = (store: Store, cellsTouched: boolean) => void;
+
 /**
  * The TablesListener type describes a function that is used to listen to
  * changes to the whole Store.
@@ -1652,7 +1678,7 @@ export interface Store {
 
   /**
    * The transaction method takes a function that makes multiple mutations to
-   * the store, buffering all calls to the relevant listeners until it
+   * the Store, buffering all calls to the relevant listeners until it
    * completes.
    *
    * This method is useful for making bulk changes to the data in a Store, and
@@ -1771,6 +1797,135 @@ export interface Store {
     ) => boolean,
   ): Return;
 
+  /**
+   * The startTransaction allows you to explicitly start a transaction that will
+   * make multiple mutations to the Store, buffering all calls to the relevant
+   * listeners until it completes when you call the finishTransaction method.
+   *
+   * Transactions are useful for making bulk changes to the data in a Store, and
+   * when you don't want listeners to be called as you make each change. Changes
+   * are made silently during the transaction, and listeners relevant to the
+   * changes you have made will instead only be called when the whole
+   * transaction is complete.
+   *
+   * Generally it is preferable to use the transaction method to wrap a block of
+   * code as a transaction. It simply calls both the startTransaction and
+   * finishTransaction methods for you. See that method for several transaction
+   * examples.
+   *
+   * Use this startTransaction method when you have a more 'open-ended'
+   * transaction, such as one containing mutations triggered from other events
+   * that are asynchronous or not occurring inline to your code. You must
+   * remember to also call the finishTransaction method explicitly when it is
+   * done, of course.
+   *
+   * @returns A reference to the Store.
+   * @example
+   * This example makes changes to two Cells, first outside, and secondly
+   * within, a transaction that is explicitly started and finished. In the
+   * second case, the Row listener is only called once.
+   *
+   * ```js
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * store.addRowListener('pets', 'fido', () => console.log('Fido changed'));
+   *
+   * store.setCell('pets', 'fido', 'color', 'brown');
+   * store.setCell('pets', 'fido', 'sold', false);
+   * // -> 'Fido changed'
+   * // -> 'Fido changed'
+   *
+   * store.startTransaction();
+   * store.setCell('pets', 'fido', 'color', 'walnut');
+   * store.setCell('pets', 'fido', 'sold', true);
+   * store.finishTransaction();
+   * // -> 'Fido changed'
+   * ```
+   * @category Transaction
+   */
+  startTransaction(): Store;
+
+  /**
+   * The finishTransaction allows you to explicitly finish a transaction that
+   * has made multiple mutations to the Store, triggering all calls to the
+   * relevant listeners.
+   *
+   * Transactions are useful for making bulk changes to the data in a Store, and
+   * when you don't want listeners to be called as you make each change. Changes
+   * are made silently during the transaction, and listeners relevant to the
+   * changes you have made will instead only be called when the whole
+   * transaction is complete.
+   *
+   * Generally it is preferable to use the transaction method to wrap a block of
+   * code as a transaction. It simply calls both the startTransaction and
+   * finishTransaction methods for you. See that method for several transaction
+   * examples.
+   *
+   * Use this finishTransaction method when you have a more 'open-ended'
+   * transaction, such as one containing mutations triggered from other events
+   * that are asynchronous or not occurring inline to your code. There must have
+   * been a corresponding startTransaction method that this completes, of
+   * course, otherwise this function has no effect.
+   *
+   * @param doRollback An optional callback that should return `true` if you
+   * want to rollback the transaction at the end.
+   * @returns A reference to the Store.
+   * @example
+   * This example makes changes to two Cells, first outside, and secondly
+   * within, a transaction that is explicitly started and finished. In the
+   * second case, the Row listener is only called once.
+   *
+   * ```js
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * store.addRowListener('pets', 'fido', () => console.log('Fido changed'));
+   *
+   * store.setCell('pets', 'fido', 'color', 'brown');
+   * store.setCell('pets', 'fido', 'sold', false);
+   * // -> 'Fido changed'
+   * // -> 'Fido changed'
+   *
+   * store.startTransaction();
+   * store.setCell('pets', 'fido', 'color', 'walnut');
+   * store.setCell('pets', 'fido', 'sold', true);
+   * store.finishTransaction();
+   * // -> 'Fido changed'
+   * ```
+   * @example
+   * This example makes multiple changes to the Store, including some attempts
+   * to update a Cell with invalid values. The `doRollback` callback receives
+   * information about the changes and invalid attempts, and then judges that
+   * the transaction should be rolled back to its original state.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   *
+   * store.startTransaction();
+   * store.setCell('pets', 'fido', 'color', 'black');
+   * store.setCell('pets', 'fido', 'eyes', ['left', 'right']);
+   * store.setCell('pets', 'fido', 'info', {sold: null});
+   * store.finishTransaction((changedCells, invalidCells) => {
+   *   console.log(store.getTables());
+   *   // -> {pets: {fido: {species: 'dog', color: 'black'}}}
+   *   console.log(changedCells);
+   *   // -> {pets: {fido: {color: ['brown', 'black']}}}
+   *   console.log(invalidCells);
+   *   // -> {pets: {fido: {eyes: [['left', 'right']], info: [{sold: null}]}}}
+   *   return invalidCells['pets'] != null;
+   * });
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
+   * ```
+   * @category Transaction
+   */
+  finishTransaction(
+    doRollback?: (
+      changedCells: ChangedCells,
+      invalidCells: InvalidCells,
+    ) => boolean,
+  ): Store;
+
   /**
    * The forEachTable method takes a function that it will then call for each
    * Table in the Store.
@@ -2746,6 +2901,143 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addWillFinishTransactionListener method registers a listener function
+   * with the Store that will be called just before other non-mutating listeners
+   * are called at the end of the transaction.
+   *
+   * This is useful if you need to know that a set of listeners are about to be
+   * called at the end of a transaction, perhaps to batch _their_ consequences
+   * together.
+   *
+   * The provided TransactionListener will receive a reference to the Store and
+   * a boolean to indicate whether Cell values have been touched during the
+   * transaction. The latter flag is intended as a hint about whether
+   * non-mutating listeners might be being called at the end of the transaction.
+   *
+   * Here, 'touched' means that Cell values have either been changed, or changed
+   * and then changed back to its original value during the transaction. The
+   * exception is a transaction that has been rolled back, for which the value
+   * of `cellsTouched` in the listener will be `false` because all changes have
+   * been reverted.
+   *
+   * @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
+   * transaction, just before its listeners will be called. The transactions
+   * shown here variously change, touch, and rollback cells, demonstrating how
+   * the `cellsTouched` parameter in the listener works.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addWillFinishTransactionListener(
+   *   (store, cellsTouched) => console.log(`Cells touched: ${cellsTouched}`),
+   * );
+   * const listenerId2 = store.addTablesListener(() =>
+   *   console.log('Tables changed'),
+   * );
+   *
+   * store.transaction(() => store.setCell('pets', 'fido', 'color', 'brown'));
+   * // -> 'Cells touched: false'
+   *
+   * store.transaction(() => store.setCell('pets', 'fido', 'color', 'walnut'));
+   * // -> 'Cells touched: true'
+   * // -> 'Tables changed'
+   *
+   * store.transaction(() => {
+   *   store.setRow('pets', 'felix', {species: 'cat'});
+   *   store.delRow('pets', 'felix');
+   * });
+   * // -> 'Cells touched: true'
+   *
+   * store.transaction(
+   *   () => store.setRow('pets', 'fido', {species: 'dog'}),
+   *   () => true,
+   * );
+   * // -> 'Cells touched: false'
+   * // Transaction was rolled back.
+   *
+   * store.callListener(listenerId);
+   * // -> 'Cells touched: undefined'
+   * // It is meaningless to call this listener directly.
+   *
+   * store.delListener(listenerId).delListener(listenerId2);
+   * ```
+   * @category Listener
+   */
+  addWillFinishTransactionListener(listener: TransactionListener): Id;
+
+  /**
+   * The addDidFinishTransactionListener method registers a listener function
+   * with the Store that will be called just after other non-mutating listeners
+   * are called at the end of the transaction.
+   *
+   * This is useful if you need to know that a set of listeners have just been
+   * called at the end of a transaction, perhaps to batch _their_ consequences
+   * together.
+   *
+   * The provided TransactionListener will receive a reference to the Store and
+   * a boolean to indicate whether Cell values have been touched during the
+   * transaction. The latter flag is intended as a hint about whether
+   * non-mutating listeners might have been called at the end of the
+   * transaction.
+   *
+   * Here, 'touched' means that Cell values have either been changed, or changed
+   * and then changed back to its original value during the transaction. The
+   * exception is a transaction that has been rolled back, for which the value
+   * of `cellsTouched` in the listener will be `false` because all changes have
+   * been reverted.
+   *
+   * @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
+   * transaction, just after its listeners have been called. The transactions
+   * shown here variously change, touch, and rollback cells, demonstrating how
+   * the `cellsTouched` parameter in the listener works.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addDidFinishTransactionListener(
+   *   (store, cellsTouched) => console.log(`Cells touched: ${cellsTouched}`),
+   * );
+   * const listenerId2 = store.addTablesListener(() =>
+   *   console.log('Tables changed'),
+   * );
+   *
+   * store.transaction(() => store.setCell('pets', 'fido', 'color', 'brown'));
+   * // -> 'Cells touched: false'
+   *
+   * store.transaction(() => store.setCell('pets', 'fido', 'color', 'walnut'));
+   * // -> 'Tables changed'
+   * // -> 'Cells touched: true'
+   *
+   * store.transaction(() => {
+   *   store.setRow('pets', 'felix', {species: 'cat'});
+   *   store.delRow('pets', 'felix');
+   * });
+   * // -> 'Cells touched: true'
+   *
+   * store.transaction(
+   *   () => store.setRow('pets', 'fido', {species: 'dog'}),
+   *   () => true,
+   * );
+   * // -> 'Cells touched: false'
+   * // Transaction was rolled back.
+   *
+   * store.callListener(listenerId);
+   * // -> 'Cells touched: undefined'
+   * // It is meaningless to call this listener directly.
+   *
+   * store.delListener(listenerId).delListener(listenerId2);
+   * ```
+   * @category Listener
+   */
+  addDidFinishTransactionListener(listener: TransactionListener): Id;
+
   /**
    * The callListener method provides a way for you to manually provoke a
    * listener to be called, even if the underlying data hasn't changed.

package/lib/debug/store.js

@@ -209,6 +209,7 @@ const idsChanged = (ids, id, added) =>
   mapSet(ids, id, mapGet(ids, id) == -added ? void 0 : added);
 const createStore = () => {
   let hasSchema;
+  let cellsTouched;
   let nextRowId = 0;
   let transactions = 0;
   const changedTableIds = mapNew();
@@ -227,6 +228,7 @@ const createStore = () => {
   const cellIdsListeners = mapNewPair();
   const cellListeners = mapNewPair();
   const invalidCellListeners = mapNewPair();
+  const finishTransactionListeners = mapNewPair(setNew);
   const [addListener, callListeners, delListenerImpl, callListenerImpl] =
     getListenerFunctions(() => store);
   const validateSchema = (schema) =>
@@ -459,75 +461,73 @@ const createStore = () => {
         )
       : 0;
   const callListenersForChanges = (mutator) => {
-    if (!collIsEmpty(changedCells)) {
-      const emptyIdListeners =
-        collIsEmpty(cellIdsListeners[mutator]) &&
-        collIsEmpty(rowIdsListeners[mutator]) &&
-        collIsEmpty(tableIdsListeners[mutator]);
-      const emptyOtherListeners =
-        collIsEmpty(cellListeners[mutator]) &&
-        collIsEmpty(rowListeners[mutator]) &&
-        collIsEmpty(tableListeners[mutator]) &&
-        collIsEmpty(tablesListeners[mutator]);
-      if (!(emptyIdListeners && emptyOtherListeners)) {
-        const changes = mutator
-          ? [
-              mapClone(changedTableIds),
-              mapClone2(changedRowIds),
-              mapClone(changedCellIds, mapClone2),
-              mapClone(changedCells, mapClone2),
-            ]
-          : [changedTableIds, changedRowIds, changedCellIds, changedCells];
-        if (!emptyIdListeners) {
-          collForEach(changes[2], (rowCellIds, tableId) =>
-            collForEach(rowCellIds, (changedIds, rowId) => {
-              if (!collIsEmpty(changedIds)) {
-                callListeners(cellIdsListeners[mutator], [tableId, rowId]);
-              }
-            }),
-          );
-          collForEach(changes[1], (changedIds, tableId) => {
+    const emptyIdListeners =
+      collIsEmpty(cellIdsListeners[mutator]) &&
+      collIsEmpty(rowIdsListeners[mutator]) &&
+      collIsEmpty(tableIdsListeners[mutator]);
+    const emptyOtherListeners =
+      collIsEmpty(cellListeners[mutator]) &&
+      collIsEmpty(rowListeners[mutator]) &&
+      collIsEmpty(tableListeners[mutator]) &&
+      collIsEmpty(tablesListeners[mutator]);
+    if (!(emptyIdListeners && emptyOtherListeners)) {
+      const changes = mutator
+        ? [
+            mapClone(changedTableIds),
+            mapClone2(changedRowIds),
+            mapClone(changedCellIds, mapClone2),
+            mapClone(changedCells, mapClone2),
+          ]
+        : [changedTableIds, changedRowIds, changedCellIds, changedCells];
+      if (!emptyIdListeners) {
+        collForEach(changes[2], (rowCellIds, tableId) =>
+          collForEach(rowCellIds, (changedIds, rowId) => {
             if (!collIsEmpty(changedIds)) {
-              callListeners(rowIdsListeners[mutator], [tableId]);
+              callListeners(cellIdsListeners[mutator], [tableId, rowId]);
             }
-          });
-          if (!collIsEmpty(changes[0])) {
-            callListeners(tableIdsListeners[mutator]);
+          }),
+        );
+        collForEach(changes[1], (changedIds, tableId) => {
+          if (!collIsEmpty(changedIds)) {
+            callListeners(rowIdsListeners[mutator], [tableId]);
           }
+        });
+        if (!collIsEmpty(changes[0])) {
+          callListeners(tableIdsListeners[mutator]);
         }
-        if (!emptyOtherListeners) {
-          let tablesChanged;
-          collForEach(changes[3], (rows, tableId) => {
-            let tableChanged;
-            collForEach(rows, (cells, rowId) => {
-              let rowChanged;
-              collForEach(cells, ([oldCell, newCell], cellId) => {
-                if (newCell !== oldCell) {
-                  callListeners(
-                    cellListeners[mutator],
-                    [tableId, rowId, cellId],
-                    newCell,
-                    oldCell,
-                    getCellChange,
-                  );
-                  tablesChanged = tableChanged = rowChanged = 1;
-                }
-              });
-              if (rowChanged) {
+      }
+      if (!emptyOtherListeners) {
+        let tablesChanged;
+        collForEach(changes[3], (rows, tableId) => {
+          let tableChanged;
+          collForEach(rows, (cells, rowId) => {
+            let rowChanged;
+            collForEach(cells, ([oldCell, newCell], cellId) => {
+              if (newCell !== oldCell) {
                 callListeners(
-                  rowListeners[mutator],
-                  [tableId, rowId],
+                  cellListeners[mutator],
+                  [tableId, rowId, cellId],
+                  newCell,
+                  oldCell,
                   getCellChange,
                 );
+                tablesChanged = tableChanged = rowChanged = 1;
               }
             });
-            if (tableChanged) {
-              callListeners(tableListeners[mutator], [tableId], getCellChange);
+            if (rowChanged) {
+              callListeners(
+                rowListeners[mutator],
+                [tableId, rowId],
+                getCellChange,
+              );
             }
           });
-          if (tablesChanged) {
-            callListeners(tablesListeners[mutator], [], getCellChange);
+          if (tableChanged) {
+            callListeners(tableListeners[mutator], [tableId], getCellChange);
           }
+        });
+        if (tablesChanged) {
+          callListeners(tablesListeners[mutator], [], getCellChange);
         }
       }
     }
@@ -656,61 +656,79 @@ const createStore = () => {
     if (transactions == -1) {
       return;
     }
-    transactions++;
+    startTransaction();
     const result = actions?.();
-    transactions--;
-    if (transactions == 0) {
-      transactions = 1;
-      callInvalidCellListeners(1);
-      callListenersForChanges(1);
-      transactions = -1;
-      if (
-        doRollback?.(
-          mapToObj(
-            changedCells,
-            (table) =>
-              mapToObj(
-                table,
-                (row) =>
-                  mapToObj(
-                    row,
-                    (cells) => [...cells],
-                    ([oldCell, newCell]) => oldCell === newCell,
-                  ),
-                objIsEmpty,
-              ),
-            objIsEmpty,
-          ),
-          mapToObj(invalidCells, (map) => mapToObj(map, mapToObj)),
-        )
-      ) {
+    finishTransaction(doRollback);
+    return result;
+  };
+  const startTransaction = () => {
+    transactions++;
+    return store;
+  };
+  const finishTransaction = (doRollback) => {
+    if (transactions > 0) {
+      transactions--;
+      if (transactions == 0) {
+        cellsTouched = !collIsEmpty(changedCells);
         transactions = 1;
-        collForEach(changedCells, (table, tableId) =>
-          collForEach(table, (row, rowId) =>
-            collForEach(row, ([oldCell], cellId) =>
-              isUndefined(oldCell)
-                ? delCell(tableId, rowId, cellId, true)
-                : setCell(tableId, rowId, cellId, oldCell),
+        callInvalidCellListeners(1);
+        if (cellsTouched) {
+          callListenersForChanges(1);
+        }
+        transactions = -1;
+        if (
+          doRollback?.(
+            mapToObj(
+              changedCells,
+              (table) =>
+                mapToObj(
+                  table,
+                  (row) =>
+                    mapToObj(
+                      row,
+                      (cells) => [...cells],
+                      ([oldCell, newCell]) => oldCell === newCell,
+                    ),
+                  objIsEmpty,
+                ),
+              objIsEmpty,
             ),
-          ),
+            mapToObj(invalidCells, (map) => mapToObj(map, mapToObj)),
+          )
+        ) {
+          transactions = 1;
+          collForEach(changedCells, (table, tableId) =>
+            collForEach(table, (row, rowId) =>
+              collForEach(row, ([oldCell], cellId) =>
+                isUndefined(oldCell)
+                  ? delCell(tableId, rowId, cellId, true)
+                  : setCell(tableId, rowId, cellId, oldCell),
+              ),
+            ),
+          );
+          transactions = -1;
+          cellsTouched = false;
+        }
+        callListeners(finishTransactionListeners[0], [], cellsTouched);
+        callInvalidCellListeners(0);
+        if (cellsTouched) {
+          callListenersForChanges(0);
+        }
+        callListeners(finishTransactionListeners[1], [], cellsTouched);
+        transactions = 0;
+        arrayForEach(
+          [
+            changedCells,
+            invalidCells,
+            changedTableIds,
+            changedRowIds,
+            changedCellIds,
+          ],
+          collClear,
         );
-        transactions = -1;
       }
-      callInvalidCellListeners(0);
-      callListenersForChanges(0);
-      transactions = 0;
-      arrayForEach(
-        [
-          changedCells,
-          invalidCells,
-          changedTableIds,
-          changedRowIds,
-          changedCellIds,
-        ],
-        collClear,
-      );
     }
-    return result;
+    return store;
   };
   const forEachTable = (tableCallback) =>
     collForEach(tablesMap, (tableMap, tableId) =>
@@ -752,6 +770,10 @@ const createStore = () => {
       rowId,
       cellId,
     ]);
+  const addWillFinishTransactionListener = (listener) =>
+    addListener(listener, finishTransactionListeners[0]);
+  const addDidFinishTransactionListener = (listener) =>
+    addListener(listener, finishTransactionListeners[1]);
   const callListener = (listenerId) => {
     callListenerImpl(listenerId, [getTableIds, getRowIds, getCellIds], (ids) =>
       isUndefined(ids[2]) ? [] : arrayPair(getCell(...ids)),
@@ -800,6 +822,8 @@ const createStore = () => {
     delCell,
     delSchema,
     transaction,
+    startTransaction,
+    finishTransaction,
     forEachTable,
     forEachRow,
     forEachCell,
@@ -811,6 +835,8 @@ const createStore = () => {
     addCellIdsListener,
     addCellListener,
     addInvalidCellListener,
+    addWillFinishTransactionListener,
+    addDidFinishTransactionListener,
     callListener,
     delListener,
     getListenerStats,