Skip to content
Source
Sign inSign up
TanStack/db

Clarify QueryCollection clearError() timing semantics #539

Send to my agent
ClosedKyleAMathews(GitHub profile, opens in a new tab) opened this issue 1 comment

Relates 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

  1. Should we default to optimistic (current) or reset-on-success?
  2. Is isRecovering() worth the API complexity?
  3. Should this be configurable per collection or global?
  1. KyleAMathews(GitHub profile, opens in a new tab) added labelsquery-collection

  2. 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.

Sign in to join this conversation.