-
Notifications
You must be signed in to change notification settings - Fork 98
Open
Labels
Description
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.