Add first-class error tracking to base Collection class

[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

• Fix error propagation from sync clients to collections #671 - Fixed error propagation where errors weren't being set on collections at all

---

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.

[samwillis]

I like most of this, it's a great improvement, but I think the transitioning out of error state need some more thought - see comment on the PR

[KyleAMathews]

This also blocks the error contract in the live-query framework bindings RFC (#1623).

Confirmed on the current PR #1724 head: a source collection can drive a live query to status: "error" and isError: true, while the adapter-visible error remains undefined.

The loss happens before any framework adapter:

• CollectionLifecycleManager.setStatus("error") records only the status.
• status:change events carry no error value.
• LiveQuerySnapshot therefore has no source error to expose.
• LiveQueryWindowController can expose its own pagination error, but falls back to undefined when its observer reports a source error.

Suggested acceptance criteria for this issue:

1. Base collections retain the current error as unknown, not only Error, since sync sources may throw any value.
2. The status and error are published as one observable transition; consumers must not see isError: true with a stale or missing error.
3. Recovery defines when the retained error is cleared and publishes that change atomically too.
4. Derived live-query collections preserve or wrap the originating source error instead of replacing it with only a log message.
5. LiveQuerySnapshot carries error: unknown, and the infinite window snapshot composes it with pagination errors.
6. The shared adapter conformance suite induces a source failure with a sentinel value and checks that every adapter exposes that exact value.

Issue #1260 is related but narrower: it reports a query collection staying ready rather than entering the error state. This issue remains the better place for retaining and propagating the actual error once the status is correct.