electric-sql / electric-sql/electric

Separate data-completeness from connection-health in isUpToDate

Open
#3,843 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.