Skip to content

Clarify QueryCollection clearError() timing semantics #539

@KyleAMathews

Description

@KyleAMathews

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?

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions