Skip to content
Source
Sign inSign up
TanStack/db

Document QueryCollection clearError() throwing behavior #538

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: Documentation / DX Breaking changes: None (documenting existing behavior)

Summary

QueryCollection.utils.clearError() can throw errors when the refetch fails, but this behavior is not documented. Users need clear guidance on proper error handling patterns.

Current Implementation

// In packages/query-db-collection/src/query.ts:735-740
clearError: () => {
  lastError = undefined
  errorCount = 0
  lastErrorUpdatedAt = 0
  return refetch({ throwOnError: true }) // This can throw!
}

The method does throw on refetch failure, but this isn't documented anywhere.

Proposed Documentation

Add to error handling guide and JSDoc:

/**
 * Clear the error state and trigger a refetch of the query
 * @returns Promise that resolves when the refetch completes successfully
 * @throws Error if the refetch fails
 * @example
 * try {
 *   await collection.utils.clearError()
 *   // success: error state cleared; data refreshed
 * } catch (e) {
 *   // still in error; show toast/backoff, etc.
 * }
 */
clearError: () => Promise<void>

Acceptance Criteria

  • Error handling guide explicitly states that clearError() throws on failure
  • JSDoc includes @throws annotation with example
  • Example uses try/catch pattern
  • Document interaction with disabled queries (when combined with exact refetch targeting)
  • Add to QueryCollectionUtils interface documentation

Additional Context

This is especially important when combined with the exact refetch targeting (#537), as disabled/unobserved queries may behave differently.

  1. KyleAMathews(GitHub profile, opens in a new tab) added labelsquery-collection

  2. Closing as obsolete: #2168 removed query-db's utils.clearError() (along with lastError, isError, and errorCount). Failures now show in collection.health (failureReason while the Query retries, error once it stops), and collection.reload() is the retry. The migration table in the #2168 changeset lists the replacements.

Sign in to join this conversation.