Skip to content

Document QueryCollection clearError() throwing behavior #538

@KyleAMathews

Description

@KyleAMathews

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.

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