electric-sql / electric-sql/electric
Separate data-completeness from connection-health in isUpToDate
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Problem
`isUpToDate` currently serves two distinct purposes in the codebase:
1. **Data completeness** — "Have we received all data up to this point?" Used by `Shape.value` to resolve promises, `#requestShape` for early returns, and `Shape.#awaitUpToDate()`.
2. **Connection health** — "Are we actively connected and receiving updates?" Used by `isLoading()` (which returns `!isUpToDate`).
When `ErrorState` wraps a `LiveState`, `isUpToDate` delegates to `previousState` and returns `true`. This is correct for meaning #1 (the data IS complete) but misleading for meaning #2 (`isLoading()` returns `false` during an error, suggesting everything is fine).
We attempted to fix this by making `ErrorState.isUpToDate` always return `false`, but this broke real user-facing behavior: `Shape.value` stopped resolving, `forceDisconnectAndRefresh` hung, and multiple integration tests timed out.
## Proposed Solution
Split the two concerns:
- Keep `isUpToDate` as a **data-completeness** signal that delegates through `ErrorState` (current behavior)
- Add a separate signal (e.g. `isConnected`, `hasError`, or `connectionState`) for **connection health**
- Update `isLoading()` to use the new signal instead of `!isUpToDate`
This would let consumers choose the right semantic: "do I have data?" vs "is the connection healthy?"
## Context
Discovered during work on the state machine test DSL (#TBD). See branch `kylemathews/add-dsl-for-testing-electricclient` for the attempted change and revert.
Contributor guide
Assessment
This issue has not been assessed yet.