🧩 Feature Proposal: Add Serialized Transaction Queuing Utility with Strategy Support #35
Description
Summary
Introduce a useSerializedTransaction hook that abstracts common queuing and batching patterns for optimistic transactions in @tanstack/optimistic. This hook simplifies management of concurrent or sequential mutations and provides a clean interface for handling real-world UI interaction patterns like sliders, text inputs, and autosaving forms.
Problem
In components that generate frequent optimistic updates (e.g. sliders, form inputs), developers often need to:
- Avoid flooding the backend with redundant mutations
- Preserve the illusion of immediate UI updates
- Ensure only one transaction is persisted at a time
- Support merging or batching of changes intelligently
Handling these concerns manually is error-prone and verbose. The new hook provides a structured way to manage these needs.
Proposed API
const commit = useSerializedTransaction({
mutationFn: async ({ transaction }) => {
await api.save(transaction.mutations)
},
metadata: { context: 'slider' },
strategy: 'latest', // or 'fifo' | 'debounce' | 'merge'
debounceMs: 1000 // optional, for 'debounce' strategy
})For 'merge' strategy, the hook returns a tuple:
const [commit, commitMerge] = useSerializedTransaction({ strategy: 'merge', ... });Supported Strategies
1. latest (throttle-style)
- ⚡ Persist most recent mutation, discard prior ones still pending
- ✅ Best for: sliders, rapid toggles
- 🧠 Principle: only final state matters
2. fifo (queue-style)
- 🧱 Queue all mutations in order, persist one at a time
- ✅ Best for: chat logs, append-only lists
- 🧠 Principle: every action matters
3. debounce
- ⏱️ Wait for idle pause, then persist a single coalesced mutation
- ✅ Best for: text inputs, autosave forms
- 🧠 Principle: only save after user stops typing
4. merge
- 🧩 Accumulate all mutations into a single long-lived transaction, committed manually
- ✅ Best for: complex forms, batch operations
- 🧠 Principle: user triggers save when ready
Benefits
- Simplifies transaction lifecycle logic in components
- Promotes reuse of queuing patterns across the app
- Reduces accidental backend write contention
- Keeps UI fully optimistic and reactive