From a31bf39fdf4d9b8522f59ba5e61b4c6b4e06c2cb Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Mon, 18 May 2026 08:31:16 -0600
Subject: [PATCH] docs(db): clarify mutate callback is synchronous

---
 packages/db/src/transactions.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/packages/db/src/transactions.ts b/packages/db/src/transactions.ts
index 858772be2..84e2bb0d5 100644
--- a/packages/db/src/transactions.ts
+++ b/packages/db/src/transactions.ts
@@ -245,9 +245,12 @@ class Transaction<T extends object = Record<string, unknown>> {
 
   /**
    * Execute collection operations within this transaction
-   * @param callback - Function containing collection operations to group together. If the
-   * callback returns a Promise, the transaction context will remain active until the promise
-   * settles, allowing optimistic writes after `await` boundaries.
+   * @param callback - Synchronous function containing collection operations to group together.
+   * The transaction context is active only for the synchronous duration of this callback.
+   * Async work should happen in `mutationFn`; collection operations after `await` boundaries
+   * inside this callback will not be part of this transaction. For manual transactions, call
+   * `mutate` multiple times before committing to add more synchronous operations to the same
+   * transaction.
    * @returns This transaction for chaining
    * @example
    * // Group multiple operations
@@ -281,6 +284,11 @@ class Transaction<T extends object = Record<string, unknown>> {
    *   collection.insert({ id: "1", text: "Item" })
    * })
    *
+   * // Add more synchronous mutations to the same transaction
+   * tx.mutate(() => {
+   *   collection.update("1", draft => { draft.text = "Updated item" })
+   * })
+   *
    * // Commit later when ready
    * await tx.commit()
    */