+<nav><ul><li><a href="/">TinyBase</a></li><li><a href="/guides/">Guides</a></li><li><a href="/guides/the-basics/">The Basics</a></li><li><a href="/guides/the-basics/transactions/">Transactions</a></li></ul></nav><section class="s1" id="/guides/the-basics/transactions/" data-id="T"><h1>Transactions</h1><p>This guide shows you how to wrap multiple changes to the data in a <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>.</p><p>A transaction is a sequence of changes made to a <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a>. No listeners will be fired until the full transaction is complete. This is a useful way to debounce listener side-effects and ensure that you are only responding to net changes. <a href="/api/store/type-aliases/transaction/changes/"><code>Changes</code></a> 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.</p><p>A transaction can also be rolled back and the original state of the <a href="/api/the-essentials/creating-stores/store/"><code>Store</code></a> will be restored.</p><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>Start transaction listeners fire (<code>addStartTransactionListener</code>).</li><li>Your transaction actions run.</li><li>For each attempted write in those actions (and in mutating listeners later), middleware callbacks run first.</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.</li><li>Any writes made by mutating listeners also go through middleware, but do not trigger mutating listeners again.</li><li><code>doRollback</code> runs (if provided) 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>Will-finish transaction listeners fire (<code>addWillFinishTransactionListener</code>).</li><li>Non-mutating listeners fire for the final committed result (after rollback logic, if any).</li><li>Did-finish transaction listeners fire (<code>addDidFinishTransactionListener</code>).</li></ol><p>If transactions are nested, this full lifecycle only happens when the outermost transaction finishes.</p><h3 id="creating-transactions">Creating Transactions</h3><p>The <a href="/api/the-essentials/setting-data/transaction/"><code>transaction</code></a> method takes a function that makes multiple mutations to the store, buffering all calls to the relevant listeners until it completes.</p><pre><code><span class="keyword">import</span> <span class="punctuation">{</span>createStore<span class="punctuation">}</span> <span class="keyword">from</span> <span class="string">'tinybase'</span><span class="punctuation">;</span>
0 commit comments