tinybase 1.2.1 → 1.3.0-beta.0

package/lib/checkpoints.js

@@ -1 +1 @@
-const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,s=e=>0==n(e),o=e=>e.slice(1),r=(e,t)=>e.push(t),c=e=>e.pop(),l=e=>null==e,i=(e,t,n)=>l(e)?n?.():t(e),d=(e,t)=>e?.has(t)??!1,a=e=>l(e)||0==(e=>e.size)(e),h=(e,t)=>e?.forEach(t),u=(e,t)=>e?.delete(t),p=e=>new Map(e),C=(e,t)=>e?.get(t),g=(e,t,n)=>l(n)?(u(e,t),e):e?.set(t,n),k=(e,t,n,s)=>(d(e,t)||(s?.(n),e.set(t,n)),C(e,t)),f=e=>new Set(e),L=(e,t,r)=>n(r)<2?((e,t)=>e?.add(t))(s(r)?e:k(e,r[0],f()),t):L(k(e,r[0],p()),t,o(r)),v=e=>{const n=(r,c,...l)=>i(r,(r=>s(l)?e(r,c):t([l[0],null],(e=>n(C(r,e),c,...o(l))))));return n},w=Object.freeze,S=(e=>{const t=new WeakMap;return n=>(t.has(n)||t.set(n,e(n)),t.get(n))})((o=>{let S,z,E,I=100,M=p(),b=1;const j=f(),x=p(),[y,B,F]=(e=>{let s,o=0;const d=[],a=p();return[(t,n,r=[])=>{s??=e();const l=c(d)??""+o++;return g(a,l,[t,n,r]),L(n,l,r),l},(e,t=[],...n)=>v(h)(e,(e=>i(C(a,e),(([e])=>e(s,...t,...n)))),...t),e=>i(C(a,e),(([,t,s])=>(v(u)(t,e,...s),g(a,e),n(d)<1e3&&r(d,e),s)),(()=>[])),(e,o,r)=>i(C(a,e),(([e,,c])=>{const i=(...d)=>{const a=n(d);a==n(c)?e(s,...d,...r(d)):l(c[a])?t(o[a](...d),(e=>i(...d,e))):i(...d,c[a])};i()}))]})((()=>V)),O=p(),T=p(),W=[],m=[],q=(e,t)=>{b=0,o.transaction((()=>h(C(O,t),((t,n)=>h(t,((t,s)=>h(t,((t,r)=>l(t[e])?o.delCell(n,s,r,!0):o.setCell(n,s,r,t[e]))))))))),b=1},A=e=>{g(O,e),g(T,e),B(x,[e])},D=(e,s)=>t(((e,t)=>e.splice(0,t))(e,s??n(e)),A),G=()=>D(W,n(W)-I),H=o.addCellListener(null,null,null,((e,t,n,s,o,l)=>{if(b){i(S,(()=>{r(W,S),G(),D(m),S=void 0,E=1}));const e=k(M,t,p()),d=k(e,n,p()),h=k(d,s,[void 0,void 0],(e=>e[0]=l));h[1]=o,h[0]===h[1]&&a(g(d,s))&&a(g(e,n))&&a(g(M,t))&&(S=c(W),E=1),P()}})),J=(e="")=>(l(S)&&(S=""+z++,g(O,S,M),R(S,e),M=p(),E=1),S),K=()=>{s(W)||(m.unshift(J()),q(0,S),S=c(W),E=1)},N=()=>{s(m)||(r(W,S),S=m.shift(),q(1,S),E=1)},P=()=>{E&&(B(j),E=0)},Q=e=>{const t=J(e);return P(),t},R=(e,t)=>(U(e)&&C(T,e)!==t&&(g(T,e,t),B(x,[e])),V),U=e=>d(O,e),V={setSize:e=>(I=e,G(),V),addCheckpoint:Q,setCheckpoint:R,getStore:()=>o,getCheckpointIds:()=>[[...W],S,[...m]],forEachCheckpoint:e=>{return t=e,h(T,((e,n)=>t(n,e)));var t},hasCheckpoint:U,getCheckpoint:e=>C(T,e),goBackward:()=>(K(),P(),V),goForward:()=>(N(),P(),V),goTo:t=>{const n=e(W,t)?K:e(m,t)?N:null;for(;!l(n)&&t!=S;)n();return P(),V},addCheckpointIdsListener:e=>y(e,j),addCheckpointListener:(e,t)=>y(t,x,[e]),delListener:e=>(F(e),V),clear:()=>(D(W),D(m),l(S)||A(S),S=void 0,z=0,Q(),V),destroy:()=>{o.delListener(H)},getListenerStats:()=>({})};return w(V.clear())}));export{S as createCheckpoints};
+const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,s=e=>0==n(e),r=e=>e.slice(1),o=(e,t)=>e.push(t),c=e=>e.pop(),l=e=>null==e,i=(e,t,n)=>l(e)?n?.():t(e),a=(e,t)=>e?.has(t)??!1,d=e=>l(e)||0==(e=>e.size)(e),h=(e,t)=>e?.forEach(t),u=(e,t)=>e?.delete(t),p=e=>new Map(e),C=(e,t)=>e?.get(t),g=(e,t,n)=>l(n)?(u(e,t),e):e?.set(t,n),k=(e,t,n)=>(a(e,t)||e.set(t,n()),C(e,t)),f=e=>new Set(e),L=(e,t,o)=>n(o)<2?((e,t)=>e?.add(t))(s(o)?e:k(e,o[0],f),t):L(k(e,o[0],p),t,r(o)),w=e=>{const n=(o,c,...l)=>i(o,(o=>s(l)?e(o,c):t([l[0],null],(e=>n(C(o,e),c,...r(l))))));return n},v=Object.freeze,S=(e=>{const t=new WeakMap;return n=>(t.has(n)||t.set(n,e(n)),t.get(n))})((r=>{let S,z,E,I=100,M=p(),b=1;const j=f(),x=p(),[y,B,F]=(e=>{let s,r=0;const a=[],d=p();return[(t,n,o=[])=>{s??=e();const l=c(a)??""+r++;return g(d,l,[t,n,o]),L(n,l,o),l},(e,t=[],...n)=>w(h)(e,(e=>i(C(d,e),(([e])=>e(s,...t,...n)))),...t),e=>i(C(d,e),(([,t,s])=>(w(u)(t,e,...s),g(d,e),n(a)<1e3&&o(a,e),s)),(()=>[])),(e,r,o)=>i(C(d,e),(([e,,c])=>{const i=(...a)=>{const d=n(a);d==n(c)?e(s,...a,...o(a)):l(c[d])?t(r[d](...a),(e=>i(...a,e))):i(...a,c[d])};i()}))]})((()=>V)),O=p(),T=p(),W=[],m=[],q=(e,t)=>{b=0,r.transaction((()=>h(C(O,t),((t,n)=>h(t,((t,s)=>h(t,((t,o)=>l(t[e])?r.delCell(n,s,o,!0):r.setCell(n,s,o,t[e]))))))))),b=1},A=e=>{g(O,e),g(T,e),B(x,[e])},D=(e,s)=>t(((e,t)=>e.splice(0,t))(e,s??n(e)),A),G=()=>D(W,n(W)-I),H=r.addCellListener(null,null,null,((e,t,n,s,r,l)=>{if(b){i(S,(()=>{o(W,S),G(),D(m),S=void 0,E=1}));const e=k(M,t,p),a=k(e,n,p),h=k(a,s,(()=>[l,void 0]));h[1]=r,h[0]===r&&d(g(a,s))&&d(g(e,n))&&d(g(M,t))&&(S=c(W),E=1),P()}})),J=(e="")=>(l(S)&&(S=""+z++,g(O,S,M),R(S,e),M=p(),E=1),S),K=()=>{s(W)||(m.unshift(J()),q(0,S),S=c(W),E=1)},N=()=>{s(m)||(o(W,S),S=m.shift(),q(1,S),E=1)},P=()=>{E&&(B(j),E=0)},Q=e=>{const t=J(e);return P(),t},R=(e,t)=>(U(e)&&C(T,e)!==t&&(g(T,e,t),B(x,[e])),V),U=e=>a(O,e),V={setSize:e=>(I=e,G(),V),addCheckpoint:Q,setCheckpoint:R,getStore:()=>r,getCheckpointIds:()=>[[...W],S,[...m]],forEachCheckpoint:e=>{return t=e,h(T,((e,n)=>t(n,e)));var t},hasCheckpoint:U,getCheckpoint:e=>C(T,e),goBackward:()=>(K(),P(),V),goForward:()=>(N(),P(),V),goTo:t=>{const n=e(W,t)?K:e(m,t)?N:null;for(;!l(n)&&t!=S;)n();return P(),V},addCheckpointIdsListener:e=>y(e,j),addCheckpointListener:(e,t)=>y(t,x,[e]),delListener:e=>(F(e),V),clear:()=>(D(W),D(m),l(S)||A(S),S=void 0,z=0,Q(),V),destroy:()=>{r.delListener(H)},getListenerStats:()=>({})};return v(V.clear())}));export{S as createCheckpoints};

package/lib/debug/checkpoints.js

@@ -28,10 +28,9 @@ const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
-const mapEnsure = (map, key, defaultValue, onWillAdd) => {
+const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    onWillAdd?.(defaultValue);
-    map.set(key, defaultValue);
+    map.set(key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -52,11 +51,11 @@ const getCreateFunction = (getFunction) => {
 const addDeepSet = (deepSet, value, ids) =>
   arrayLength(ids) < 2
     ? setAdd(
-        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew()),
+        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew),
         value,
       )
     : addDeepSet(
-        mapEnsure(deepSet, ids[0], mapNew()),
+        mapEnsure(deepSet, ids[0], mapNew),
         value,
         arrayFromSecond(ids),
       );
@@ -181,16 +180,11 @@ const createCheckpoints = getCreateFunction((store) => {
           currentId = void 0;
           checkpointsChanged = 1;
         });
-        const table = mapEnsure(delta, tableId, mapNew());
-        const row = mapEnsure(table, rowId, mapNew());
-        const oldNew = mapEnsure(
-          row,
-          cellId,
-          [void 0, void 0],
-          (addOldNew) => (addOldNew[0] = oldCell),
-        );
+        const table = mapEnsure(delta, tableId, mapNew);
+        const row = mapEnsure(table, rowId, mapNew);
+        const oldNew = mapEnsure(row, cellId, () => [oldCell, void 0]);
         oldNew[1] = newCell;
-        if (oldNew[0] === oldNew[1]) {
+        if (oldNew[0] === newCell) {
           if (collIsEmpty(mapSet(row, cellId))) {
             if (collIsEmpty(mapSet(table, rowId))) {
               if (collIsEmpty(mapSet(delta, tableId))) {

package/lib/debug/indexes.js

@@ -39,10 +39,9 @@ const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
-const mapEnsure = (map, key, defaultValue, onWillAdd) => {
+const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    onWillAdd?.(defaultValue);
-    map.set(key, defaultValue);
+    map.set(key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -179,11 +178,11 @@ const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
 const addDeepSet = (deepSet, value, ids) =>
   arrayLength(ids) < 2
     ? setAdd(
-        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew()),
+        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew),
         value,
       )
     : addDeepSet(
-        mapEnsure(deepSet, ids[0], mapNew()),
+        mapEnsure(deepSet, ids[0], mapNew),
         value,
         arrayFromSecond(ids),
       );

package/lib/debug/metrics.js

@@ -44,10 +44,9 @@ const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
-const mapEnsure = (map, key, defaultValue, onWillAdd) => {
+const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    onWillAdd?.(defaultValue);
-    map.set(key, defaultValue);
+    map.set(key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -182,11 +181,11 @@ const getCreateFunction = (getFunction) => {
 const addDeepSet = (deepSet, value, ids) =>
   arrayLength(ids) < 2
     ? setAdd(
-        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew()),
+        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew),
         value,
       )
     : addDeepSet(
-        mapEnsure(deepSet, ids[0], mapNew()),
+        mapEnsure(deepSet, ids[0], mapNew),
         value,
         arrayFromSecond(ids),
       );

package/lib/debug/relationships.js

@@ -34,10 +34,9 @@ const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
-const mapEnsure = (map, key, defaultValue, onWillAdd) => {
+const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    onWillAdd?.(defaultValue);
-    map.set(key, defaultValue);
+    map.set(key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -172,11 +171,11 @@ const getCreateFunction = (getFunction) => {
 const addDeepSet = (deepSet, value, ids) =>
   arrayLength(ids) < 2
     ? setAdd(
-        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew()),
+        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew),
         value,
       )
     : addDeepSet(
-        mapEnsure(deepSet, ids[0], mapNew()),
+        mapEnsure(deepSet, ids[0], mapNew),
         value,
         arrayFromSecond(ids),
       );

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.
@@ -566,6 +592,10 @@ export type StoreListenerStats = {
    * The number of CellListeners registered with the Store.
    */
   cell?: number;
+  /**
+   * The number of InvalidCellListeners registered with the Store.
+   */
+  invalidCell?: number;
 };
 
 /**
@@ -1648,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
@@ -1767,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.
@@ -2742,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.