`createFragment` and `createLazyLoadQuery` disagree on the `"loading"` `FragmentState`

[nyanrus]

relay-runtime's observeFragmentExperimental publishes three possible states: "ok", "error", and "loading". The two solid-relay primitives that subscribe to that observable handle "loading" differently — and one of them does so accidentally.

createLazyLoadQuery ignores "loading" entirely (stale-while-revalidate). createFragment clears data and error whenever the snapshot is in "loading", but only as a side effect of unconditional pre-clears at the top of its batch; the switch itself has no "loading" case. Whichever behaviour is intended, the two primitives should agree.

Where

createFragment.ts — pre-clears apply on every snapshot; switch has only "ok" / "error". For a "loading" snapshot, the net effect is data → undefined, error → undefined, pending unchanged:

batch(() => {
  setResult("data", undefined);    // unconditional pre-clear
  setResult("error", undefined);   // unconditional pre-clear
  switch (res.state) {
    case "ok": /* … */ break;
    case "error": /* … */ break;
    // no "loading" case
  }
});

createLazyLoadQuery.ts — no pre-clears; switch has only "ok" / "error". For a "loading" snapshot, nothing is written; the store keeps its previous values:

batch(() => {
  if (state.state === "ok") { /* … */ }
  else if (state.state === "error") { /* … */ }
  // "loading" is a no-op
});

Both files are referenced from relay-runtime/lib/store/observeFragmentExperimental.js, where snapshotToFragmentState returns { state: 'loading' } when:

• snapshot.missingLiveResolverFields.length > 0, or
• snapshot.missingClientEdges.length > 0, or
• snapshot.isMissingData and there's a pending operation affecting the owner.

So "loading" is not a rare or initial-only state — it surfaces during normal operation any time a record temporarily lacks data while a related request is in flight.

Why this matters

The two behaviours give different UX:

• createFragment today (clear on loading) — any user-facing component bound to the fragment momentarily renders its empty/loading state on every "loading" tick, even when the previous data was still perfectly displayable.
• createLazyLoadQuery today (no-op on loading) — components keep displaying the previous data while the network catches up; pending could be set if the consumer wants to indicate "refreshing".

For a fragment rendered into a card on a timeline, the second is normally what users want (no flicker). For a fragment that is conceptually "the thing you're loading right now", the first might be more accurate.

Whichever the project considers the canonical behaviour, the inconsistency itself is a footgun: a consumer that depends on the loading state's effects can be transplanted between primitives without warning and silently behave differently.

Discussion

The two cleanest resolutions:

A. Stale-while-revalidate everywhere

Both primitives ignore "loading"; consumers that want to surface an in-flight indication read pending. PR #68 takes this direction in createFragment as a side effect of dropping the pre-clears that were defeating reconcile (see the linked issue for that part).

Mechanical change for createLazyLoadQuery: none — it already does this.

Mechanical change for createFragment: covered by PR #68.

B. Flicker-to-empty everywhere

Both primitives explicitly clear data and error on "loading"; consumers see an empty state on every transient missing-data snapshot.

Mechanical change for createLazyLoadQuery: add an explicit "loading" branch.

Mechanical change for createFragment: add an explicit "loading" branch instead of relying on the implicit pre-clear behaviour (PR #68 would need a follow-up).

case "loading":
  setResult("data", undefined);
  setResult("error", undefined);
  break;

C. Something in between

For instance: set pending: true on "loading" without touching data (so the previous data stays visible but pending flips). This is the React Suspense-ish model. Same case-shape as B but with pending instead of clearing.

case "loading":
  setResult("pending", true);
  break;

the A can be simple fix because:

• It's already what createLazyLoadQuery does today, so the path of least disruption.
• Stale-while-revalidate matches what most Relay-backed UIs in production seem to want (Relay's own useFragment in React behaves this way too — it doesn't suspend on partial updates, it just keeps the previous snapshot until the new one is ready).
• Consumers retain the option to read pending to drive their own "refreshing" indicator.

But this is a UX call, not a correctness call, and the maintainer should pick the direction explicitly so the two primitives can be aligned with a comment that makes the intent clear.

Related

• Identity-preservation defeat in createFragment — separate issue / PR fix: preserve fragment data identity across snapshot updates #68. The two are linked because the current createFragment loading-clear is implemented via the same pre-clears that defeat reconcile; deciding the direction here decides whether PR fix: preserve fragment data identity across snapshot updates #68's drop of those pre-clears needs an explicit "loading" case added back.

AI disclosure

Drafted with Claude (Opus 4.7) as a programming assistant. The state-machine behaviour referenced above was verified by reading relay-runtime/lib/store/observeFragmentExperimental.js and both primitives in this package; the references above point into that source for review.

[nyanrus]

Updated after #68 was merged. The original framing of this issue — "the two primitives disagree on loading" — is now resolved (createFragment no-ops on loading, matching createLazyLoadQuery). What's left is the forward-looking question of whether loading should additionally toggle pending.

Current state after #68

res.state	data	error	pending
ok	reconcile(value)	undefined	false
error	undefined	res.error	false
loading	unchanged	unchanged	unchanged

createLazyLoadQuery behaves the same way (it has always had only "ok" / "error" branches). So both primitives now show stale-while-revalidate for transient loading snapshots — consumers keep seeing the last successful data while the underlying record temporarily lacks fields.

This is the right default. A quick sweep of the ecosystem (Relay's own React bindings, TanStack Query, SWR, Apollo Client, Vue Pinia Colada, Nuxt useFetch, Remix / React Router 7, React 18's useTransition/useDeferredValue) — every mainstream client-side data library keeps showing the previous data during a refresh and exposes "in-flight" as a separate flag rather than clearing data. The reasons cited across docs are perceived performance (no flicker), layout stability (no CLS bump from skeleton-replacement), and composition (consumers that want flicker can opt in by gating on the flag; consumers that want stale-while-revalidate can't opt back in once data has been cleared).

So far so good. But there's a gap.

The gap: no flag flips on transient loading

Right now pending in solid-relay only flips during the resource generator's initial fetch (true while awaiting the async fetcher, false after the first "ok" snapshot arrives). It does not flip when the observer subsequently receives state: "loading" (for example: a related field becomes temporarily missing, or relay-runtime decides another pending operation could yet affect the record).

That means a consumer who wants the "refreshing" UI that TanStack Query / SWR / Apollo all expose has nothing to subscribe to:

• data() doesn't change (stale-while-revalidate, good).
• error doesn't change (no error, good).
• pending doesn't change either (no signal that a refresh is in flight — gap).

The result: it's impossible to render a "spinner overlay while we refresh in the background" without reaching past solid-relay into the Relay store and inspecting operation tracker state ourselves. That's the same cost solid-relay otherwise saves us.

Proposal: route "loading" through pending

Add a single explicit case in both primitives' subscribers:

case "loading":
  setResult("pending", true);
  break;

After this change:

res.state	data	error	pending
ok	reconcile(value)	undefined	false
error	undefined	res.error	false
loading	unchanged	unchanged	true

This gives pending a single, consistent meaning across the lifetime of a fragment / lazy query: "a fetch affecting this fragment is happening right now, regardless of whether we have data". That's exactly the semantics TanStack Query gives to isFetching and SWR to isValidating.

Consumer code can then write straightforward "refresh indicator over stale data" UI without any further plumbing:

<Show when={user()}>
  {(user) => (
    <div class:opacity-50={user.pending}>
      {/* always shows the latest data we have */}
      <UserCard user={user()} />
      <Show when={user.pending}>
        <Spinner />
      </Show>
    </div>
  )}
</Show>

Consumers who don't care about the in-flight state simply don't read pending. Nothing in their behaviour changes.

Why both primitives

This should land in createFragment and createLazyLoadQuery in the same change. The pending field semantics should be consistent across primitives; having one toggle on loading and the other not would re-introduce the kind of inconsistency #68 just removed.

Costs / risks

• Behavioural: any current consumer that read pending and assumed "this can only be true during the initial fetch" would be surprised. I don't think this assumption is documented, but it's still a behavioural change that should be a minor version bump.
• No data / error change — the perceived-performance / layout-stability benefit of fix: preserve fragment data identity across snapshot updates #68 is preserved.
• Each branch still owns its full state transition, so the structural cleanliness of the post-fix: preserve fragment data identity across snapshot updates #68 observer is preserved.

Alternative: leave it alone

If the maintainer's view is that a "refreshing" indicator is the consumer's problem to build out of their own state, this issue can be closed. The current post-#68 behaviour is internally consistent — loading is a no-op on the store — and the missing in-flight signal can be reconstructed by the consumer (e.g., by tracking pending of the parent query, or by setting their own signal alongside a refetch() call).

The argument for doing it inside solid-relay is mostly economy: the information the consumer needs is sitting in the observed snapshot, and routing it through the same pending field makes it consumer-discoverable without anyone having to know that "loading" is a thing.

References

• TanStack Query useQuery reference — isLoading ("is true whenever the first fetch for a query is in-flight"), isFetching (any fetch in progress), and isRefetching (background refetch only). data stays populated across background refetches; consumers gate refresh UI on isFetching / isRefetching rather than hiding data.
• SWR useSWR reference — isLoading ("if there's an ongoing request and no 'loaded data'") and isValidating ("if there's a request or revalidation loading"). data from the previous successful fetch remains visible during revalidation of the same key.
• Apollo Client useQuery reference — notifyOnNetworkStatusChange defaults to true, so loading does flip to true during background refetches. data from cache still stays populated; the loading boolean is a consumer signal, not data invalidation. (Apollo overloads a single flag where TanStack Query / SWR split into two, but the underlying pattern is the same: data preserved, an in-flight flag toggled.)
• React Router (v7) useNavigation — exposes state: "idle" | "loading" | "submitting" separately from useLoaderData(), which returns the previous route's data until the new loader resolves.
• React 18 useDeferredValue — "During updates, React will first attempt a re-render with the old value (so it will return the old value), and then try another re-render in the background with the new value." Same principle: the previous committed value stays visible while a new one is in flight.
• Relay (React) useFragment — suspends only when data is missing and being fetched by a parent query; subsequent updates / refetches do not suspend the fragment. Loading is an attribute of the operation, not of the fragment's render.