docs: clarify that mutationFn must await server sync before returning

[KyleAMathews]

Summary

• Added important documentation explaining that createOptimisticAction's mutationFn must ensure server writes have synced back before returning
• Updated examples to demonstrate using collection-specific helpers like utils.refetch() to ensure synchronization
• This clarification helps users understand that optimistic state is dropped when the mutation function returns

Context

The documentation previously didn't explain that inside your mutationFn, you need to ensure that your server writes have synced back before you return. This is critical because the optimistic state is dropped when you return from a mutationFn.

Users generally need to use collection-specific helpers to ensure sync, such as:

• Query's utils.refetch()
• Direct write APIs
• Electric's utils.awaitTxId()

Changes

• Updated docs/overview.md with the clarification and improved examples
• Updated JSDoc comments in packages/db/src/optimistic-action.ts (which generates the reference docs)

Test plan

• Documentation changes only - no code functionality changed
• Examples demonstrate the correct pattern

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2d49de0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

More templates

• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 2d49de0

[github-actions]

Size Change: 0 B

Total Size: 65 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/change-events.js	1.13 kB
./packages/db/dist/esm/collection.js	10.5 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.1 kB
./packages/db/dist/esm/index.js	1.52 kB
./packages/db/dist/esm/indexes/auto-index.js	745 B
./packages/db/dist/esm/indexes/base-index.js	605 B
./packages/db/dist/esm/indexes/btree-index.js	1.74 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.25 kB
./packages/db/dist/esm/local-only.js	827 B
./packages/db/dist/esm/local-storage.js	2.03 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.87 kB
./packages/db/dist/esm/query/builder/functions.js	575 B
./packages/db/dist/esm/query/builder/index.js	3.83 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	890 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.48 kB
./packages/db/dist/esm/query/compiler/expressions.js	631 B
./packages/db/dist/esm/query/compiler/group-by.js	2.09 kB
./packages/db/dist/esm/query/compiler/index.js	2.16 kB
./packages/db/dist/esm/query/compiler/joins.js	2.36 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.23 kB
./packages/db/dist/esm/query/compiler/select.js	655 B
./packages/db/dist/esm/query/ir.js	466 B
./packages/db/dist/esm/query/live-query-collection.js	333 B
./packages/db/dist/esm/query/live/collection-config-builder.js	2.58 kB
./packages/db/dist/esm/query/live/collection-subscriber.js	2.4 kB
./packages/db/dist/esm/query/optimizer.js	2.63 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	2.29 kB
./packages/db/dist/esm/utils.js	943 B
./packages/db/dist/esm/utils/btree.js	6.02 kB
./packages/db/dist/esm/utils/comparison.js	718 B
./packages/db/dist/esm/utils/index-optimization.js	1.62 kB

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

[github-actions]

Size Change: 0 B

Total Size: 1.16 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	152 B
./packages/react-db/dist/esm/useLiveQuery.js	1.01 kB

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