docs(db): clarify mutate callback is sync-only

[KyleAMathews]

Summary

Clarifies the Transaction#mutate docstring to match the current intended behavior:

• mutate callbacks are synchronous optimistic-write scopes only.
• The transaction context is active only for the synchronous duration of the callback.
• Collection operations after await boundaries are not part of the transaction.
• Async persistence work belongs in mutationFn.
• Manual transactions can call mutate multiple times before committing to add more synchronous operations to the same transaction.

This resolves the documentation mismatch highlighted by #1522 without changing runtime behavior.

Testing

Not run; documentation-only change.

Summary by CodeRabbit

• Documentation
  • Updated documentation to clarify that transaction context is only active during synchronous code execution and is not maintained across asynchronous boundaries within transaction callbacks.
  • Added example demonstrating how to perform multiple synchronous mutations within transactions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 897751e9-16ff-4c0c-ac56-5600769e68f8

📥 Commits

Reviewing files that changed from the base of the PR and between 2224ddb and a31bf39.

📒 Files selected for processing (1)

• packages/db/src/transactions.ts

---

📝 Walkthrough

Walkthrough

The Transaction.mutate JSDoc is updated to clarify that the transaction context is active only during synchronous callback execution, and collection operations after await boundaries are excluded from the transaction.

Changes

Transaction Context Documentation

Layer / File(s)	Summary
Transaction.mutate callback documentation & example packages/db/src/transactions.ts	JSDoc for the callback parameter clarifies that transaction context is synchronous-only and does not extend across await boundaries within the callback; the manual-transaction example adds an explicit second tx.mutate(() => { ... }) for additional synchronous mutations before committing.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

📜 A rabbit hopped through docs so clear,
"Transactions sync—don't cross the tier!
Beyond await, the context ends,
Where async paths must make amends." 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(db): clarify mutate callback is sync-only' accurately summarizes the main change—updating JSDoc documentation to clarify that Transaction.mutate callbacks are synchronous only.
Description check	✅ Passed	The PR description covers the key changes and rationale, though it does not complete the provided template's checklist items (testing and release impact sections).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/mutate-sync-docstring

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

More templates

• todos
• offline-first-electron
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• offline-transactions-react-native
• shopping-list-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1538

@tanstack/browser-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1538

@tanstack/capacitor-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1538

@tanstack/cloudflare-durable-objects-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1538

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1538

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1538

@tanstack/db-sqlite-persistence-core

npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1538

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1538

@tanstack/electron-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1538

@tanstack/expo-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1538

@tanstack/node-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1538

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1538

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1538

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1538

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1538

@tanstack/react-native-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1538

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1538

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1538

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1538

@tanstack/tauri-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1538

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1538

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1538

commit: a31bf39

[github-actions]

Size Change: +111 B (+0.1%)

Total Size: 114 kB

📦 View Changed

Filename	Size	Change
packages/db/dist/esm/transactions.js	3.02 kB	+111 B (+3.82%)

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/collection/change-events.js	1.39 kB
packages/db/dist/esm/collection/changes.js	1.38 kB
packages/db/dist/esm/collection/cleanup-queue.js	810 B
packages/db/dist/esm/collection/events.js	434 B
packages/db/dist/esm/collection/index.js	3.61 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.69 kB
packages/db/dist/esm/collection/mutations.js	2.47 kB
packages/db/dist/esm/collection/state.js	5.26 kB
packages/db/dist/esm/collection/subscription.js	3.74 kB
packages/db/dist/esm/collection/sync.js	2.88 kB
packages/db/dist/esm/collection/transaction-metadata.js	144 B
packages/db/dist/esm/deferred.js	207 B
packages/db/dist/esm/errors.js	4.92 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3 kB
packages/db/dist/esm/indexes/auto-index.js	830 B
packages/db/dist/esm/indexes/base-index.js	729 B
packages/db/dist/esm/indexes/basic-index.js	2.05 kB
packages/db/dist/esm/indexes/btree-index.js	2.17 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	538 B
packages/db/dist/esm/local-only.js	890 B
packages/db/dist/esm/local-storage.js	2.1 kB
packages/db/dist/esm/optimistic-action.js	359 B
packages/db/dist/esm/paced-mutations.js	496 B
packages/db/dist/esm/proxy.js	3.75 kB
packages/db/dist/esm/query/builder/functions.js	919 B
packages/db/dist/esm/query/builder/index.js	5.25 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.2 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.62 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	2.69 kB
packages/db/dist/esm/query/compiler/index.js	4.13 kB
packages/db/dist/esm/query/compiler/joins.js	2.34 kB
packages/db/dist/esm/query/compiler/order-by.js	1.72 kB
packages/db/dist/esm/query/compiler/select.js	1.11 kB
packages/db/dist/esm/query/effect.js	4.78 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir.js	829 B
packages/db/dist/esm/query/live-query-collection.js	360 B
packages/db/dist/esm/query/live/collection-config-builder.js	7.88 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	1.95 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/utils.js	1.64 kB
packages/db/dist/esm/query/optimizer.js	2.62 kB
packages/db/dist/esm/query/predicate-utils.js	2.97 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/subset-dedupe.js	960 B
packages/db/dist/esm/scheduler.js	1.3 kB
packages/db/dist/esm/SortedMap.js	1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js	247 B
packages/db/dist/esm/strategies/queueStrategy.js	428 B
packages/db/dist/esm/strategies/throttleStrategy.js	246 B
packages/db/dist/esm/utils.js	927 B
packages/db/dist/esm/utils/array-utils.js	273 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	5.61 kB
packages/db/dist/esm/utils/comparison.js	1.05 kB
packages/db/dist/esm/utils/cursor.js	457 B
packages/db/dist/esm/utils/index-optimization.js	1.54 kB
packages/db/dist/esm/utils/type-guards.js	157 B
packages/db/dist/esm/virtual-props.js	360 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 4.24 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/index.js	249 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.32 kB
packages/react-db/dist/esm/useLiveQuery.js	1.34 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	567 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}