2.0.0 Unsolicited Suggestions for the Async API

[CxRes]

Following @ryansolid streams, I find the work on managing Async Data in Solid 2.0 to be very impressive, and I am still trying to work out the implications of it. The UI (or the store powering it) indeed needs to track a current and future value during the course of an update. However, I feel the proposed UI is minimalist rather than being symmetric, which offends my physics sensibilities.

I'll start by observing that isPending(fn) is necessitated by the need to show to the consumer what is going on, often overlaid on the data itself. But I would argue that for consistency you should instead also have isLoading(), isErrored() as well.

Consider the UI where you want to show the data and status separately, might be far away from each other, say the status is next to a refresh button or on a status bar. The boundaries are not convenient for building such a UI, whereas the functions allow one to independently calculate and show the status (as well as possibly block a refresh button, if that's what the designer wants).

As far as the component boundaries are concerned (which I see as a common case convenience), I would suggest looking at it as a unified <AsyncSlot/> which should have an API like so:

<AsyncSlot
  loading={}
  pending={}
  errored={}
>
  <Page/>
</AsyncSlot>

with the <Page/> being shown for any undefined attributes.

Or even

<AsyncSlot
  loading={}
  loaded={}
  pending={}
  errored={}
/>

if you want to be super consistent. But the latter might not be ergonomic.

This will encourage developers to think about providing pending and errored states whenever they write a component with Async Data, rather than thinking of it as outside the component. Think of it as a psychological Nudge.

These changes are backwards compatible. Ideally, <Loading> and <Errored> should be made redundant, but that is a breaking change.

[rvlzzr]

Pending doesn't and can't really throw, so you can't catch it like you can errored and loading, so the AsyncSlot idea wouldn't work.

[CxRes]

Pending doesn't and can't really throw

That does not really matter. Pending is shown when true and not when it is false. Loading/Pending/Errored will be mutually exclusive on the same data.

Edit: This is an outline. I expect some bikesheding before it lands!

[ryansolid]

I'm going to transfer this to a discussion but I love the time you spent to lay this out because by answering this I think I can shine a light on some of the design decisions here and how they differ from other solutions. We've looked at this API shape before. And don't worry about breaking changes. We are still in beta. Now is exactly the time to talk about this.

The first thing to point out is the naming is the last part. The important part is the mechanics. So we should start there. It is possible that the naming is wrong but I think the shape of the mechanics dictate the outcome in a few places.

Boundaries

Let's start with boundaries. Boundaries exist for one reason to be able to bail out of UI that we can't render. The reason we wouldn't be able to render it is that it is incomplete or inconsistent. The 2 primary causes of that is something is errored, or we don't have have a value yet to display. Those 2 can often be related as they are around say data fetching but also can be completely independent. It is quite possible to have different affordance levels for where you show loading vs where you show errors. You might have individual error boundaries but a single loading or vice versa.

In Solid 2.0 they also have different conceptual lifecycles. Loading only happens when we don't have a value to show, ie initially, whereas Errored can happen at any point in the future. Their behavior is asymmetrical so combining them can cause confusion around lifecycle. It also lets us more cleanly add attributes that work for only one mode vs others. Like the new on property on the Loading component (that gives it a way to temporarily reactively reset it).

Also since boundaries work by inner most catches it is important to be deliberate where these are. A generic boundary that catches both might no be what you want in all cases. You could take a perspective of if the callback isn't implemented then it doesn't catch and pass through. But that is a looser contract than a component that guarantees it catches. Having separate components lets the code be more streamlined as it doesn't need to conditionally create different internal primitives. Including Errored doesn't mean you are including Loading effectively.

That all being said none of this stops someone making a convenience wrapper like you are suggesting for loading/errored on top of the primitives we provide. So that door is open we just keep the core primitives streamlined and effective.

Non-Boundary States

Now the other 2 states pending and loaded are a bit different. They do not prevent rendering unless we designed them that way (more on that in a minute). As you called out loaded especially is odd. It is because it isn't ephemeral, once something is loaded it doesn't become unloaded (depending on the definition). It also is the given state of the boundary. If the boundary is being shown it is loaded probably. It isn't branching logic. It could be a hook to set some state but then API shape might be better served by passing into the main children callback, but since it never reverts to false it probably has no use there.

Ie.

<AsyncSlot
  loading={}
  errored={}
>
  {(loaded) => <Page loaded={loaded()} />}
</AsyncSlot>

pending is more interesting. It too isn't a boundary condition becaues something can be pending without reseting the fallback loading(as suggested by @rvlzzr). Like showing a different pending UI is possible but at that point it is basically just loading. Like if you rip out the UI for updates as well (like React Suspense does) then you aren't saving anything to suggest pending is different. Like you can say Updating... instead of Loading... but you could do that with an overeager Loading mechanism and some state above that remembers if it has been there before. Pending whole point is to not rip out the UI and to support transitional UI changes. Ie hold the current state while things update in the background. It's a bit like the browsers paint holding on navigation. The browser only shows you the next page when it has enough content to show you as to avoid white flicker which can be jarring.

So to making pending fit that there was an early design where I was thinking we'd do:

<AsyncSlot
  loading={}
  errored={}
>
  {(pending) => <Page loaded={pending()} />}
</AsyncSlot>

This actually my starting point when I went to implement 2.0. A shared boundary with pending fed in. I think even Svelte 5 more or less has this shape. But as Svelte also realized that pending was a insufficient for updates (they have $effect.pending() as well).

The challenge here is that transitions are conceptually a global thing. If you aren't being caught by a boundary then you rise to the top level. If you don't do that then you introduce tearing. It basically defeats the whole point if you want this to align:

// top level control
const [userId] = createSignal(1); 

// async to be used somewhere lower
const user = createMemo(() => fetchUser(userId())); 

Like if not being under a boundary is enough to update userId before user updates we've lost the point. The problem is that transitional changes need to start from write not from read. While UI affordances are read based, the decision to transactionally hold a change needs to propagate from the start of that change and things like boundaries aren't responsible for that. They can block inclusion in this transaction by saying, hey I've got this, but once you get past boundary, ie it is rendered async has to bubble upwards.

So the key realization when working on this was that if we made the pending state queryable we could basically collapse the need for transitional/transactional pending state into a single primitive. If you ask isPending(() => user()) then you can get the answer for that async directly as it is on the page in front of you. But also if you ask isPending(() => currentTab()) you can ask about the async on the next page as it is loading. Because any async of the next tab driven off that signal will also let us know that.

Like if you load different data depending on whether you are on the "details" vs the "settings" tab and you are on the details tab the only thing you have in front of you are the fetched details. That is the UI you are showing the user. How do you indicate to them the next page is coming without showing a Loading spinner. Ie if you want to basically paint hold. You isPending(() => tab()) since the moment they click on that they start loading the next tab and we still have the means to show that in the current UI.

Other Non-Boundary States

I often the biggest mistake I made with Solid 1.0 is having resource.error followed closely by resource.loading. createResource was our async primitive and some users asked for .error on it and I was like that isn't the best pattern here but what is the harm? Well the harm well I kept getting issues where people weren't using boundaries and were confused when things snapped out on them. They were trying to guard their resources using error/loading basically bypassing the use of boundaries but then they'd accidently read the value somewhere at the wrong time and trigger the boundary anyway. Basically these subverted expectation and provided a parallel way to accomplish the same things without playing to the system.

The saving grace of isPending is that is false initially which means that it clearly doesn't mess with boundaries. Like initially we only have 2 options here. Set it to false or have it throw. Either is fine and I defaulted both ways at different points of the Solid 2.0 exploration but I opted for false in the end because it allowed more flexibility on boundary positioning. It was acknowledgement this wasn't a boundary consideration. This could go either way and is worth debating.

isLoading and isErrored aren't like that. They overlap entirely with the boundary condition and if they were to prevent the boundary from operating they'd break things that depend on them. First all you lose the benefit of things working in the background. These aren't equivalent:

<Loading fallback="Loading..."><Page /></Loading>
<Show when={!isLoading(user)}><Page /></Show>

<Show> not only removes inversion of control, ie the discoverability of async, you are not mounting <Page>. Further downstream async isn't being parallelized. Show is blocking. Loading holds on to it offscreen. Obviously a show component could be made to do that but then it would have a bunch of extra logic that doesn't make sense for the base case. The difference with boundaries is the expectation is that the fallback will clear. That it is only a temporary state.

The other difference is SSR/Hydration. Streaming needs to know how to flush HTML. Show isn't special. We could make it work but then you'd be streaming data and the client would be rendering it. That's fine in some cases arguably (and how the earliest versions of streaming worked in Solid) but it delays the content swap until hydration. Where as with Loading since we know and can set it to this purpose we can stream in the content before Solid ever loads in the client.

Ok let's say you are fine with using Loading for streaming. What about other things with isLoading? Well the challenge is that boundaries let us hold hydration. We have clear division of when something is read or not. We might be showing it because we streamed it in, but we won't hydrate it until JS is ready and we have the data (to be fair we won't stream it in until we have the data). But my point is we make that decision via boundary. So if something outside the boundary is reading isLoading and it gets true, and flushes immediately but then the stream finishes before hydration starts, we get to a state potentially where it hydrates with isLoading false even though it rendered with isLoading true. And we get a hydration mismatch.

This is tricky to resolve because either you have to make an assumption that might not be right isLoading always true/false during hydration. Or you need to serialize it for each boundary flush as a separate snapshot and update it as you hydrate through so that client matches server. It overcomplicates things for a scenario that is already designed to work with boundaries.

Stepping Back

I think the current design is consistent, minimal, directed for good behavior patterns, but this suggestion indicates there is a feeling that something is missing. I'd like to understand the shape of those patterns a bit more. Where does this fall down? What are you missing that isn't a convenience wrapper that can be done in user space?

I especially want to understand:

This will encourage developers to think about providing pending and errored states whenever they write a component with Async Data, rather than thinking of it as outside the component. Think of it as a psychological Nudge.

As I feel that is what the current proposed APIs do. We don't tie boundaries to components but data so you can put the <Loading> inside your component, underneath your data fetching. It bundles the Boundaries with the async in a single unit instead of pulling outside as a wrapper.

function User(props) {
  // async to be used somewhere lower
  const user = createMemo(() => fetchUser(props.userId));

  return <Loading fallback={`Loading User ${props.userId}`}>
    <SomewhereLower user={user()} />
  </Loading>
}