Skip to content
TanStackDB

Content temporarily unavailable

Candidate: the source health channel and live-query health tree

Superseded (2026-10-16). The error surface was redesigned: status crashed, node failureReason/error, fail(), reload(), and collection.health. Read error-surface/README.md and error-surface/RULES.md, the shipped docs/guides/error-handling.md, and packages/db/src/query/live/ARCHITECTURE.md laws 14, 16, and 17.

Status: superseded candidate design, version 1. It came from a Field Lab design-grammar run. The shipped design differs; read PLAN.md, the shipped guides, and packages/db/src/query/live/ARCHITECTURE.md laws 16 and 17.

Success standard (frozen, user-confirmed)

  • H1 After the first ready, a sync failure is metadata. Status stays ready; data stays, even if increasingly stale.
  • H2 Before the first ready, the gate is unchanged: a final failure is markError, reaches every consumer, and readiness waits reject.
  • H3 The framework never heals or retries. Health reports what the source last said; only the source clears its failure by reporting healthy sync again.
  • H4 A live query carries its sources' health, through joins, includes, and nested live queries.
  • H5 Hooks expose health without changing data, isReady, or status. No flicker; Suspense does not throw after ready.
  • H6 (open) A subset load for new demand that fails after ready is decided per request: it affects the requesting query, not the source.
  • H7 One adapter API reports post-ready failures, replacing today's mix of ready-to-error transitions and adapter utilities.
  • H8 query-db's utils.lastError, isError, and errorCount keep working.
  • H9 An Effect hears about health changes after ready instead of being disposed.
  • H10 A persisted collection keeps serving local rows when upstream sync fails after ready; health says upstream is degraded.
  • H11 useLiveQuery returns an health structure describing the tree of collections it depends on. It always has the same shape, shows whether each node is in error, and carries detailed error info when in error, so apps can parse it.

Prior law (frozen earlier): a source either keeps trying (loading), becomes ready, or reports a final error for its sync attempt; the framework never heals an attempt; recovery is app-level (cleanup() then preload()).

Source trace (current code)

  • Status is the only propagated channel: live queries handle sources' status:change (db/src/query/live/collection-config-builder.ts:1104); hooks derive isError from status (react-db/src/useLiveQuery.ts).
  • Electric (electric.ts:2628, 2708) and PowerSync (powersync.ts:826) switch a ready collection to error after ready; PowerSync then heals with markReady (powersync.ts:813).
  • query-db exposes utils.lastError, isError, errorCount, reset after a successful result (query-db-collection/src/query.ts:325-332).
  • Hooks already expose a parallel metadata channel for persistence: persistedStatus, persistedError (react-db/src/useLiveQuery.ts).
  • A live query's direct sources come from extractCollectionSources(query) (collection-config-builder.ts:197); a source can itself be a live-query Collection.

The candidate

Two independent axes

  • Gate (status): idle | loading | ready | error | cleaned-up. Decided only by the initial sync of an attempt. Unchanged from today except that error is final for the attempt.
  • Health: healthy | error, plus error info. Meaningful after the first ready. Only the source changes it.

Adapter API (sync function params)

ts
sync: ({ begin, write, commit, markReady, markError, reportError, reportHealthy }) => { ... }
  • markError(error) before the first ready: the final initial failure (gate).
  • reportError(error) after the first ready: health becomes error with this cause. Status and rows do not change.
  • reportHealthy(): the source has synced successfully again; health becomes healthy.
  • markError(error) after the first ready is forwarded to reportError(error) with a development warning, so existing adapters keep working while they migrate.
  • Calling markReady() after markError() in one attempt throws (contract violation).

Collection surface

ts
collection.health // { isError: boolean, error: CollectionErrorInfo | null }
collection.on('health:change', (event) => { ... })

type CollectionErrorInfo = {
  phase: 'initial' | 'sync' | 'request'
  name: string
  message: string
  cause: unknown
  at: number // epoch milliseconds
}

phase: 'initial' mirrors a gate error; phase: 'sync' is a post-ready health report; phase: 'request' is a subset load failure (H6).

The health tree

Every live-query Collection exposes health, and every framework hook returns it beside data:

ts
type HealthNode = {
  collectionId: string
  kind: 'source' | 'live-query'
  status: CollectionStatus          // the node's gate
  isError: boolean                  // this node: gate error, health error, or request error
  hasErrors: boolean                // this node or any descendant
  error: CollectionErrorInfo | null // detail when isError
  sources: Array<HealthNode>     // dependencies; [] for a base source
}
  • The root is the live query itself. Its sources are the query's collections in query order (from, then joins, then includes), each recursing through nested live queries.
  • The shape is fixed by the query: every dependency is present whether or not it is in error. A collection reached by two paths appears once per path.
  • Nodes mirror their collections in the same update as the change.
  • A post-ready request failure (H6) sets error with phase: 'request' on the live-query node that issued the request. The source stays healthy.
  • isError on the hook result keeps its current meaning: the gate is error. health.hasErrors reports anything anywhere in the tree.

Effects

createEffect({ onSourceHealth?: (health: HealthNode) => void }). After the first ready a health change calls it; the Effect is not disposed. Before the first ready, a gate error still disposes the Effect through onSourceError.

Adapters

  • Electric and PowerSync replace post-ready markError with reportError and call reportHealthy after their next successful sync. PowerSync's markReady recovery becomes reportHealthy.
  • query-db keeps utils.lastError/isError/errorCount and also calls reportError/reportHealthy; it no longer calls markReady from error.
  • Persisted collections: local storage failures stay on persistedError; upstream failures after ready are the collection's health.

Recovery

App-level only. cleanup() then preload() starts a fresh attempt and resets health to healthy.

Model check

SourceHealth.tla checks stable shape, mirroring through a nested live query, only-the-source-clears, gate independence after ready, and that a gate error is explained by a tree node. Five weakened designs each produce their counterexample. The model has two sources and one nested live query; it does not cover a collection reached by two paths.

Edit on GitHub
Overview