Clarify QueryCollection clearError() timing semantics #539
Send to my agentRelates to: PR #441 ("add error tracking and retry methods to query collection utils") Scope: DX / reliability / timing behavior Breaking changes: Potentially (if we change default behavior)
Summary#
clearError() currently resets error state before refetch (optimistic behavior), creating a transient window where isError() returns false during a failing retry. This can cause UI flickering and confusion.
Current Behavior (Optimistic)#
clearError: () => {
lastError = undefined // Reset immediately
errorCount = 0 // Reset immediately
lastErrorUpdatedAt = 0 // Reset immediately
return refetch({ throwOnError: true }) // May fail and set error again
}
Problem: Between clearError() call and observer result, isError() briefly returns false even if the retry fails.
Proposed Options#
Option A: Keep optimistic + add isRecovering()#
// Add recovery tracking
let isRecovering = false
clearError: async () => {
isRecovering = true
lastError = undefined
errorCount = 0
try {
await refetch({ throwOnError: true })
} finally {
isRecovering = false
}
}
isRecovering: () => isRecovering
Option B: Reset-on-success with opt-in optimistic#
clearError: async (opts = { optimistic: false }) => {
if (opts.optimistic) {
lastError = undefined
errorCount = 0
}
try {
await refetch({ throwOnError: true })
if (!opts.optimistic) {
lastError = undefined
errorCount = 0
}
} catch (e) {
if (opts.optimistic) {
// Restore error state since optimistic clear failed
lastError = e
errorCount++
}
throw e
}
}
Acceptance Criteria#
- Behavior is documented with timeline diagram or bullet sequence
- If
isRecovering()is added, include tests and docs - Choose default behavior that minimizes UI flickering
- Ensure error state consistency during recovery attempts
- Consider impact on existing users
Open Questions#
- Should we default to optimistic (current) or reset-on-success?
- Is
isRecovering()worth the API complexity? - Should this be configurable per collection or global?
KyleAMathews(GitHub profile, opens in a new tab) added labelsquery-collection
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
Thanks for spelling out the retry timing problem. PR #1940 is merged on main: clearError now keeps the current error visible until a successful result is applied, and the lifecycle oracle covers failed and held retries.