[docs] Transaction sequence

Author: jamesgpearce

docs/guides/the-basics/transactions/article.html

@@ -86,4 +86,4 @@
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>startListenerId<span class="punctuation">)</span>
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>willFinishListenerId<span class="punctuation">)</span>
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>didFinishListenerId<span class="punctuation">)</span><span class="punctuation">;</span>
-</code></pre><h3 id="summary">Summary</h3><p>We&#x27;ve covered all of the essential basics of working with a TinyBase <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>, but that&#x27;s still just the start!</p><p>Before we move on, we have a quick aside about how to use various flavors of TinyBase in your app, in the <a href="/guides/the-basics/importing-tinybase/">Importing TinyBase</a> guide.</p></section>
+</code></pre><h3 id="transaction-lifecycle">Transaction Lifecycle</h3><p>Since TinyBase now has multiple phases around a transaction, it helps to think of one complete transaction in this order:</p><ol><li>The transaction starts.</li><li><code>startTransaction</code> listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/addstarttransactionlistener/"><code>addStartTransactionListener</code></a> method).</li><li>Your transaction actions run.</li><li>For each attempted write in those actions, middleware callbacks run first (as added with the addWillSetRow method, for example).</li><li><a href="/api/store/type-aliases/transaction/changes/"><code>Changes</code></a> are buffered in the transaction log; non-mutating listeners are not called yet.</li><li>Mutating listeners fire for net changes and invalid attempts (as added with the <a href="/api/the-essentials/listening-for-changes/addrowlistener/"><code>addRowListener</code></a> method, for example, with the final <code>mutator</code> flag set).</li><li>Any writes made by mutating listeners also go through middleware, but do not trigger mutating listeners again.</li><li>If provided to the <a href="/api/the-essentials/setting-data/transaction/"><code>transaction</code></a> method or the <a href="/api/store/interfaces/store/store/methods/transaction/starttransaction/"><code>startTransaction</code></a> method, <code>doRollback</code> runs with the transaction log after all mutating listeners and their writes.</li><li>If <code>doRollback</code> returns <code>true</code>, TinyBase rolls back the transaction changes.</li><li><code>willFinish</code> transaction listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/addwillfinishtransactionlistener/"><code>addWillFinishTransactionListener</code></a> method).</li><li>Non-mutating listeners fire for the final committed result (if the transaction has not rolled back).</li><li><code>didFinish</code> transaction listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/adddidfinishtransactionlistener/"><code>addDidFinishTransactionListener</code></a> method).</li></ol><p>If transactions are nested, this full lifecycle only happens when the outermost transaction finishes.</p><h3 id="summary">Summary</h3><p>We&#x27;ve covered all of the essential basics of working with a TinyBase <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>, but that&#x27;s still just the start!</p><p>Before we move on, we have a quick aside about how to use various flavors of TinyBase in your app, in the <a href="/guides/the-basics/importing-tinybase/">Importing TinyBase</a> guide.</p></section>

docs/guides/the-basics/transactions/index.html

@@ -86,4 +86,4 @@
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>startListenerId<span class="punctuation">)</span>
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>willFinishListenerId<span class="punctuation">)</span>
   <span class="punctuation">.</span><span class="function"><a href="/api/store/interfaces/store/store/methods/listener/dellistener/">delListener</a></span><span class="punctuation">(</span>didFinishListenerId<span class="punctuation">)</span><span class="punctuation">;</span>
-</code></pre><h3 id="summary">Summary</h3><p>We&#x27;ve covered all of the essential basics of working with a TinyBase <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>, but that&#x27;s still just the start!</p><p>Before we move on, we have a quick aside about how to use various flavors of TinyBase in your app, in the <a href="/guides/the-basics/importing-tinybase/">Importing TinyBase</a> guide.</p></section></article><aside></aside></main><footer><nav><a id="gh" href="https://github.com/tinyplex/tinybase" target="_blank">GitHub</a><a id="bs" href="https://bsky.app/profile/tinybase.bsky.social" target="_blank">Bluesky</a><a id="tw" href="https://x.com/tinybasejs" target="_blank">X / Twitter</a><a id="dc" href="https://discord.com/invite/mGz3mevwP8" target="_blank">Discord</a></nav><nav><a href="/">TinyBase <span id="version"></span></a> © 2022-</nav></footer><script>window.dataLayer=window.dataLayer||[];function g(){dataLayer.push(arguments);}g('js',new Date());g('config','G-D1MGR8VRWJ');</script></body></html>
+</code></pre><h3 id="transaction-lifecycle">Transaction Lifecycle</h3><p>Since TinyBase now has multiple phases around a transaction, it helps to think of one complete transaction in this order:</p><ol><li>The transaction starts.</li><li><code>startTransaction</code> listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/addstarttransactionlistener/"><code>addStartTransactionListener</code></a> method).</li><li>Your transaction actions run.</li><li>For each attempted write in those actions, middleware callbacks run first (as added with the addWillSetRow method, for example).</li><li><a href="/api/store/type-aliases/transaction/changes/"><code>Changes</code></a> are buffered in the transaction log; non-mutating listeners are not called yet.</li><li>Mutating listeners fire for net changes and invalid attempts (as added with the <a href="/api/the-essentials/listening-for-changes/addrowlistener/"><code>addRowListener</code></a> method, for example, with the final <code>mutator</code> flag set).</li><li>Any writes made by mutating listeners also go through middleware, but do not trigger mutating listeners again.</li><li>If provided to the <a href="/api/the-essentials/setting-data/transaction/"><code>transaction</code></a> method or the <a href="/api/store/interfaces/store/store/methods/transaction/starttransaction/"><code>startTransaction</code></a> method, <code>doRollback</code> runs with the transaction log after all mutating listeners and their writes.</li><li>If <code>doRollback</code> returns <code>true</code>, TinyBase rolls back the transaction changes.</li><li><code>willFinish</code> transaction listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/addwillfinishtransactionlistener/"><code>addWillFinishTransactionListener</code></a> method).</li><li>Non-mutating listeners fire for the final committed result (if the transaction has not rolled back).</li><li><code>didFinish</code> transaction listeners fire (as added with the <a href="/api/store/interfaces/store/store/methods/listener/adddidfinishtransactionlistener/"><code>addDidFinishTransactionListener</code></a> method).</li></ol><p>If transactions are nested, this full lifecycle only happens when the outermost transaction finishes.</p><h3 id="summary">Summary</h3><p>We&#x27;ve covered all of the essential basics of working with a TinyBase <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>, but that&#x27;s still just the start!</p><p>Before we move on, we have a quick aside about how to use various flavors of TinyBase in your app, in the <a href="/guides/the-basics/importing-tinybase/">Importing TinyBase</a> guide.</p></section></article><aside></aside></main><footer><nav><a id="gh" href="https://github.com/tinyplex/tinybase" target="_blank">GitHub</a><a id="bs" href="https://bsky.app/profile/tinybase.bsky.social" target="_blank">Bluesky</a><a id="tw" href="https://x.com/tinybasejs" target="_blank">X / Twitter</a><a id="dc" href="https://discord.com/invite/mGz3mevwP8" target="_blank">Discord</a></nav><nav><a href="/">TinyBase <span id="version"></span></a> © 2022-</nav></footer><script>window.dataLayer=window.dataLayer||[];function g(){dataLayer.push(arguments);}g('js',new Date());g('config','G-D1MGR8VRWJ');</script></body></html>

site/guides/01_the_basics/6_transactions.md

@@ -44,10 +44,10 @@ store.delListener(listenerId);
 If multiple changes are made to a piece of Store data throughout the
 transaction, a relevant listener will only be called with the final value
 (assuming it is different to the value at the start of the transaction),
-regardless of the changes that happened in between. For example, if a Cell
-had a value `'a'` and then, within a transaction, it was changed to `'b'`
-and then `'c'`, any CellListener registered for that cell would be called
-once as if there had been a single change from `'a'` to `'c'`:
+regardless of the changes that happened in between. For example, if a Cell had a
+value `'a'` and then, within a transaction, it was changed to `'b'` and then
+`'c'`, any CellListener registered for that cell would be called once as if
+there had been a single change from `'a'` to `'c'`:
 
 ```js
 const listenerId2 = store.addCellListener(
@@ -152,6 +152,37 @@ store
   .delListener(didFinishListenerId);
 ```
 
+## Transaction Lifecycle
+
+Since TinyBase now has multiple phases around a transaction, it helps to think
+of one complete transaction in this order:
+
+1. The transaction starts.
+2. `startTransaction` listeners fire (as added with the
+   addStartTransactionListener method).
+3. Your transaction actions run.
+4. For each attempted write in those actions, middleware callbacks run first (as
+   added with the addWillSetRow method, for example).
+5. Changes are buffered in the transaction log; non-mutating listeners are not
+   called yet.
+6. Mutating listeners fire for net changes and invalid attempts (as added with
+   the addRowListener method, for example, with the final `mutator` flag set).
+7. Any writes made by mutating listeners also go through middleware, but do not
+   trigger mutating listeners again.
+8. If provided to the transaction method or the startTransaction method,
+   `doRollback` runs with the transaction log after all mutating listeners and
+   their writes.
+9. If `doRollback` returns `true`, TinyBase rolls back the transaction changes.
+10. `willFinish` transaction listeners fire (as added with the
+    addWillFinishTransactionListener method).
+11. Non-mutating listeners fire for the final committed result (if the
+    transaction has not rolled back).
+12. `didFinish` transaction listeners fire (as added with the
+    addDidFinishTransactionListener method).
+
+If transactions are nested, this full lifecycle only happens when the outermost
+transaction finishes.
+
 ## Summary
 
 We've covered all of the essential basics of working with a TinyBase Store, but