Skip to content

Add first-class error tracking to base Collection class #672

@KyleAMathews

Description

@KyleAMathews

Background

Currently, error state tracking is inconsistent across collection types:

  • query-db-collection: Tracks lastError and errorCount in closure variables, exposing them via utility functions (collection.utils.lastError(), collection.utils.isError(), collection.utils.errorCount())
  • electric-db-collection: Has no error tracking at all - errors are thrown or logged but not stored
  • Base Collection: Has status: 'error' state but no associated error information

This creates an inconsistent developer experience where error handling differs depending on which collection type you're using.

Proposal

Make error tracking a first-class concern in the base Collection class, similar to how status is handled today.

API Changes

Add to CollectionLifecycleManager:

public error: Error | null = null
public errorCount: number = 0

public markError(error?: Error): void {
  if (error) {
    this.error = error
    this.errorCount++
  }
  this.setStatus('error')
}

Expose on Collection:

// Direct property access (like status)
collection.error // Error | null
collection.errorCount // number

// Events
collection.on('error', (event) => {
  console.log('Error occurred:', event.error)
})

Benefits

  1. Consistency: All collection types have the same error API
  2. Better DX: Access collection.error directly instead of collection.utils.lastError()
  3. Framework integration: React, Angular, Vue adapters can reactively bind to error state
  4. Debugging: Errors are preserved and inspectable, not just logged
  5. Retry logic: errorCount enables exponential backoff strategies

Migration Path

  1. Add error tracking to base Collection (non-breaking - new properties)
  2. Update query-db-collection to use base error tracking instead of closure variables (internal change)
  3. Update electric-db-collection to pass errors to markError() instead of just throwing
  4. Deprecate collection.utils.lastError() in favor of collection.error (breaking in next major)

Open Questions

  • Should markError() clear the error on successful recovery, or should we have a separate clearError() method?
  • Should errors emit events (collection.on('error', ...)) in addition to status events?
  • What should happen to errorCount on recovery - reset to 0 or preserve for analytics?
  • Should we track error history (last N errors) or just the most recent?

Related


This came out of the discussion in #671 where we realized error tracking should be baked into the core Collection rather than being add-on utilities.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions