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>
} 

[CxRes]

Thanks for such a detailed response and explanation; it is rare to get to see the thought process of a project lead. If you feel that discussion is at any time going out of bounds, please let me know... the very last think I want to do is keep you from working towards a production release of Solid 2.0.

Right of the bat, let me agree with you that design you have is consistent and minimal (nothing falls down AFAICT!). This is more of an human interface argument than a functional one. Referring back to the example 10 & 11 on the stream of 6 Feb 2026 and our discussion in the comments thereafter, I would like to see a DX that strongly encourages developers to specify loading and error handling for any component handling async data (rather than making it seem optional). It should really be an opt-out rather than an opt-in (the organ donor argument). If the developer chooses not to specify the boundaries with async data, the framework should really be asking (even if implicitly or as a warning), "Buddy, do you really think this is a good idea to leave that space empty?"

---

In Solid 2.0 they also have different conceptual lifecycles. Loading only happens when we don't have a value to show, i.e. 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).

I would have thought the boundaries having mutually exclusive temporal lifecycles exactly the reason to combine them. If I consider the <AsyncSlot> to be the component, it can be in 3 (maybe 4) UI states.

1. UI shows that the data is loading.
2. UI shows that the data
3. UI shows an error due to:
   a. data loading failed.
   b. computational error which throws or produces a value that the component cannot handle

If we further add in, what you are calling Projections, you have further states:

2. UI shows the data with:
   a. more data incoming
   b. done.
3. UI shows a further error:
   c. data loading partially failed.

And if we now throw in writes:

2. UI maybe shows future data.
   UI shows update failed. (This is not an error per se, since the current value is still available). This imho is important to prevent cognitive dissonance of dropped updates and my main source of concern.
3. UI shows loading/update is pending.

1, (2,3) and 4 are mutually exclusive lifecycle states within the <AsyncSlot>. Further, developers ought to handle 1 and 4 if they are dealing with async data. And if conditions for 1 and 4 have not occurred, we can always assume state 2. If anything, I would argue that having them together encourages cohesive design.

(Also, maybe a difference between our though processes is that you think in terms of boundaries whereas I am thinking in terms of fallback states of UI)

---

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.

With the exception of the lifecycle argument above and the aside below, I'll grant you that my suggestion might be a preference about the core primitives and userland is always an option.

Aside: In the world of systems complexity (which was my academic research area), there are essentially two approaches: How can the system be constructed from primitives or how a generic system can be parameterized to create the specific system. There is no right or wrong approach technically, but for a consumer the two can lead to different measurements or outcomes.

---

pending is more interesting...

Agreed. While you could have a separate pending component (which shows data and value, so not just loading), the repaint would almost always be wasteful.

---

<Show> not only removes inversion of control, i.e. the discoverability of Async, you are not mounting <Page>.

Even if you had isLoading(), <Show> would not suffice, you need a non-blocking <ShowAsync> or <AsyncSlot> primitive in lieu/in addition to boundary primitives.

However the use case I had in mind was more like:

<Loading fallback="<EMPTY-PAGE/>"><Page /></Loading>
<div id="statusbar">
	<Show when={isLoading(user)}>Loading...</Show>
	<Show when={isErrored(user)}>Error!</Show>
</div>

where a status bar does not conceptually belong inside a page (See my next comment for the elaborated use-case). Perhaps, you have an alternate way of dealing with this. Do tell!

[CxRes]

I am putting a simplified version of use case on StackBlitz. The separate comment is to isolate the use-case from the DX discussion or allow you to move it to a separate thread.

https://stackblitz.com/edit/solidjs-templates-phjktrui

Motivation

I want to build data-first reactive malleable software environment. That is, an environment that can components just by looking at the data type and user intent and load data into that component. And do so recursively. By reclusively, I mean that if that data contains other linked items to be transcluded, and component provides space for such transclusion, the environment can load components and data into those spaces and repeat the process for those child components.

The idea here is that once you point the environment to some data source (say, an RDF source), the environment can automatically create the entirety of the UX automatically (by reading from a registry of generic components) just by "following its nose" through the data. I have demonstrated this with an operating environment prototype I had developed called Syntropize (and there are a few other people moving in a similar direction in Malleable Systems and Substrates communities), but did not develop it further because asynchronous reactivity was an unsolved problem at the time and was taking all of my effort fighting Angular 1.x (not that migrating to another framework would have helped all that much).

Sample

I have create a sample code in Stackblitz with two examples of <Hole> component, which works, but does not work correctly. For the simplified example, <Hole> receives a URL, and it lazy loads component based on the media type and passes the response body to it.

In the ideal case, there should be two loading boundaries one for the loading of the component, the second for the loading of the data itself. I can swap components as the data in the hole changes. But as you can see, the loading boundaries do not work as expected, and I get a blank area, before the component is first loaded.

The second is an optimized case where the data and component loading both race and we have a single loading boundary. Again the boundary does not seem to work.

My pain point is that it is not obvious how to do the right thing here. Some of that is lack of using Solid for anything but toy examples. Some is the 2.0 is still in beta. A lot of it is that I am not all that smart. But it still took me so much time, that too with AI helping me out, to end up with a not fully correct example. That's why I think there is still room in Solid to cut through the complexity without sacrificing on the physics!