Proposal: data with better type elimination from createResource

[lxsmnsyc]

const [data] = createResource(...);

Currently, data returns an accessor that returns the current result of the resource. To check if it is still loading, we use data.loading and use data.error when checking for failures. This is great but not for Typescript.

https://github.com/solidjs/solid/blob/main/packages/solid/src/reactive/signal.ts#L216-L233

The accessor returns T | undefined but that is incorrect for 3 reasons:

• Suspense should guarantee the type is exactly what is returned for data.
• undefined is a valid value for a Promise to result into.
• The presence of data.loading and data.error is not exclusive enough to perform type elimination.

There is a way to fix this but would introduce a breaking change:

interface Pending {
  status: 'pending';
  value?: undefined;
}
interface Success<T> {
  status: 'success';
  value: T;
}
interface Failure {
  status: 'failure';
  value: any;
}
type Result<T> = Success<T> | Failure | Pending;

// Either the bottom one or a proxy for Result<T>
type ResourceData<T> = () => Result<T>;

This way, the result is deterministic, exclusive and can be type-eliminated.

const result = data(); // Result<T>;
switch (result.status) {
  case 'pending': // Pending
    return null;
  case 'success': // Success<T>
    return <h1>Success! {result.value}</h1>;
  case 'failure': // Failure
    return <h1>Something went wrong. {result.value.message}</h1>;
}

edit:

interface Pending {
  status: 'pending';
  loading: boolean;
  error: any;
  (): undefined;
}
interface Success<T> {
  status: 'success';
  loading: false;
  error: any;
  (): T;
}
interface Failure {
  status: 'failure';
  loading: boolean;
  error: any;
  (): undefined;
}
interface Stale<T> {
  status: 'stale';
  loading: true;
  error: any;
  (): T;
}

Playground

[ryansolid]

I see. That's interesting. I guess with that API it doesn't even need to be a function accessor. It just has 2 getters. My instant hesitation was I liked the whole feels like a Signal thing.. with Suspense you rarely use the loading or error states.

We can't do that union trick the other way I guess. Like this won't fly?

interface Pending {
  loading: true;
  error: false;
  (): undefined;
}
interface Success<T> {
  loading: false;
  error: false;
  (): T;
}
interface Failure {
  loading: false;
  error: any;
  (): undefined;
}

I'm gathering not or you would have suggested it.

Hmm, it is breaking though which ties my hands I think for now.

[otonashixav]

This solution would work if not for any (and unknown) shadowing false. For instance https://tsplay.dev/WzO24w: {} | null | undefined is equivalent to unknown, but does not cause false to get shadowed. However example.error could still be a falsy error, so there's no way for typescript to guarantee that !example.error means no error.

If example.error itself is intended to check for the presence of an error then it should not be able to contain falsy errors.

[lxsmnsyc]

The best approach here I think is to use status: 'success' | 'failure' | 'pending' because false and other falsy values are valid values for a resolving/rejecting Promise

[ryansolid]

Yeah falsey errors were never in my thinking. Especially undefined errors. That does seem weird to me but here we are.

Ultimately .loading should go away and we should just have .status and potentially .error I guess. I don't think "stale" is needed now that we have .latest and can use that with transitions.

Thing I'm wondering most about now is if resources should start "pending" unless set with an initial value. Regardless of whether they generate a promise initially. Super not obvious but it would allow differentiating between things that need to resolve and ones that we are pushing back. The chained resources thing got me thinking about this. In that scenario you are pending conceptually. This would be one solve.

[lxsmnsyc]

They should only be pending if the data isn't available and a promise is yet to be resolved. In this case, since an initial value is provided, I don't think you shouldn't use "pending"

[ryansolid]

I meant in the other case. There is no promise if the source is falsey at first, but we should probably set it as pending if there is no initial value.

Also any time there is a promise that is not resolved it is considered pending.

[lxsmnsyc]

I think that should work as well! Although I'm not sure if we can correctly eliminate the types (for instance, checking for data.error doesn't really eliminate into Failure). Is it a good thing to add a similar field to data.status? status helps brand the types.

https://www.typescriptlang.org/play?#code/JYOwLgpgTgZghgYwgAgAoRAE1Ac2QbwChkTkBnMOMAVzIC5kByABw2xB0YG5jSAbAPZx2OBgCMBAvhDggepZNCgCoDWQE95pABQBKBtSwQYoCJh4BfQoVCRYiFAGVqCJGTIAeACoA+ArxIKKloGRjIXNzJuAORBYVxxSWlZLRIlFTUQTRi9Bi9La1toeCRkADE4YD5qKBQiBSCaeiZ4KpqIaIU4kUSpGTkY9NVkDVTkXORDTGNTc0IrQjB1VmQAJQhwvjBvPwBeNDZcZAAfZGdXDc9fE-LK6tqeQgQBEApFAA84AFtmaWR9gDyYgAVhAEGAAHRwdzAHAgbR6f5+eB8MgQAA0-galCaoXCF3cjHRMW6CWQKLRxIUQwYFIx810IzIaw21C2HgkfVkPkeZAA7sAwAgABbjCCfH7SCGNWiM+qkBDQlBhCKXRgMeUKEjPV59CGCHDacXfX4QPS6MYWMZiWpwADWY0VaJad3a6qxWu1LzIeoNRolpvNMStMRtMgdMSdytYWFw7s1Wp1PqlfuNkrNugtwcsQA

[ryansolid]

Yeah this shows a lot of my misunderstanding of TS I was thinking keeping things in their own lanes would help typing instead of pushing the error through data. As I was saying loading and error were sort of secondary considerations. I don't want data to hold the error incase people aren't checking for it. I think status is probably fine addition and wouldn't be breaking.

[lxsmnsyc]

I added a TypeScript playground link to demonstrate type eliminations with your idea (+ status). Seems to be behaving as expected.

[ryansolid]

Yeah we can do that I need to figure out which state is the source of truth.. status is probably derived like

{
  get status() {
     return error() ? "failure" : loading() ? "pending" : "success"
  }
}

Question of which strings we should use. Is it "success"? is it "failure"? Sometimes resources will start at "success" I guess. .

Is there a 4th state when it's never run and isn't triggered initially?

[lxsmnsyc]

"pending" is set before the fetcher is run. "success" and "failure" corresponds to both when Promise resolves (the statuses were derived from the Promise spec). I think "pending" is also enough for when the fetcher itself hasn't been evaluated yet. Is there a case scenario for a potential 4th state?

Edit:

const [status, setStatus] = createSignal('pending');

// ...
setStatus('pending');
fetcher().then(
  (value) => {
    if (notDisposed) {
      setStatus('success');
    }
  },
  (value) => {
    if (notDisposed) {
      setStatus('failure');
    }
  },
);

[ryansolid]

Ok yeah because it is just boolean not true. And that's fine because status enough to type narrow ok. Yeah I am onboard for this then. Let's see if anyone has any thoughts. But I think we can get this out in the next minor version I guess.

[lxsmnsyc]

After re-evaluating, I think there is a possible 4th state: "stale", a cross between "pending" and "success". It is loading: true while (): T. A resource becomes "stale" when a refetch is performed while there's an existing "success" value.

[rturnq]

I think this proposal is fine, though I'm not sure about "stale". Before moving forward with it, I think we should examine some realistic use-cases to see how well it works in practice. Switching on a string value using a real JS switch works well but I doubt this would be the way people actually end up using it. More likely I expect people to use JSX <Switch>+<Match>, <Show>, or ternaries. That being the case having to check against a string value ends up being pretty verbose.

function Comp() {
  const [data] = createResource(...);

  return (
    <Switch>
      <Match when={data.status === 'pending'}>
        <h3>Loading...</h3>
      </Match>
      <Match when={data.status === 'failure'}>
        <h3>{data.error}</h3>
      </Match>
      <Match when={true}>
        <div>{data()}</div>
      </Match>
    </Switch>
  );
}

While not a reason to do nothing here, when using the control flow components, type narrowing doesn't really work anyways thought I'm hopeful we may be able to do more with TypeScript 4.4. Should probably try out the beta.

[lxsmnsyc]

"stale" is yet optional, but the current behavior of createResource suggest that it will never be applied.

There's not much in 4.4 that can help us narrow types here. <Show> is the closest one I can think of since it also allows proper type elimination through render prop the last time I checked.

[ryansolid]

That works but it also changes the behavior. It basically keys it since data being passed through can change. Not just boolean. So type narrowing is just hard. Because our control flow isn't even keywords. Im not even sure LSP hacks make sense.

[ryansolid]

I looked at React query they have 4 states as well. "idle", "loading", "success", "error". They consider it idle whenever it is in a don't fetch state ie.. if the query is null in our case. They don't have "stale" but also have a "isFetching". To be fair I use "loading" this way and it's up to the user whether they unmount it. But it appears React query only gives the "loading" status when there is no data available. I'm not sure there needs to be a no data check other than checking for data yourself.

It is interesting because changing the query in Solid doesn't wipe the resource value. We keep it around so I realize our proposed types aren't quite right. We can use "stale" for that I guess. But it also doesn't remove from the "success" state in a sense. So there is a question of whether we cater status for this initial load story because that is not how I've node the independent states.

[lxsmnsyc]

Pending, Success and Failure are all states that I derived from the original Promise behavior.
We can consider Idle in SSR context however the values that it represents are completely similar (and behaves similarly) to that of Pending. Pending usually means "the promise is yet to resolve" so far of that resolution cycle is "when to begin fetching".

Meanwhile, Stale is completely derived from stale-while-revalidate strategy (give stale data while fetching new one). Not all data-fetching libraries have this behavior tho, and was completely opt-in by other libraries like React Query and Relay.

[lxsmnsyc]

Here's a flowchart.

1. Pending is the initial state of a resource. It transitions to Success when resolving while Failure when it throws an error.
2. Success will transition back to Pending during a re-fetch. This is only applicable when the behavior is "network-only" (there's no cache).
3. Success will transition to Stale if the behavior is stale-while-revalidate.
4. Stale is similar to Pending except that there's a cached data from the previous Promise.
5. Stale will transition to Pending if the the resolution time is more of the stale age (this is a completely optional behavior). In React, this behavior is akin to a useDeferredValue/useTransition that takes more than 5 seconds to apply (based on the RAIL model).

Stale is a completely optional behavior. It can be emulated with the right implementation of useDeferredValue.

[ryansolid]

Yeah I think it's interesting because React Query's is____ properties are like the current create resource but their status is closer to what is being proposed here. But if we include stale the success path of the switch like @rturnq posted above includes both success and stale. That's my only concern since it regresses from success which might not be obvious. React Query doesn't. But I do think you are right in that they are separate states.

useTransition handles stale pretty well. useDeferredValue allowing means to inverse the stale propagation. I do think with fine-grained we might be able to find a different way to handle this. Like tell the resource to only trigger on initial load etc.. I think useDeferredValue is super awkward way to detect stale state since we deal with containers rather than values. Our experiments only cemented that I don't think it's the best way but that's tertiary to what is being discussed here.

The main case for idle is fetching on demand. Like when the component loads you don't load it. But then on click load data. It isn't treated like loading since there is no intention perhaps of ever loading.

[lxsmnsyc]

The main case for idle is fetching on demand. Like when the component loads you don't load it. But then on click load data. It isn't treated like loading since there is no intention perhaps of ever loading.

Is there an example case-scenario for this? I do think this works well for call-to-action fetches (e.g. POST) and not for data-derived UI. I may be wrong tho.

Edit:
Idle looks like is applicable for this scenario, since createResource itself is an on-demand read.

[snnsnn]

Hi everyone, I have been thinking about asynchronous rendering and the API surrounds it. I tried to formalize my findings and ideas in an RFC like format.

Lets start with the data to be tracked inside createResource. Once we decide what to track, then we can encode this information into signals. Translation does not have be one-to-one, we can merge them into a single signal.

Data To Track Inside createResource

• State of the request, pending or settled

• Result of the computation, success value or error value

• If a request or subsequent request is underway.

Currently this is represented as refetching but I am not sure why do we need this? In order to block consecutive requests? Or communicate that a request is underway? If so, pending state already does that. If it is to indicate an literal refetch (data is already returned and a subsequent request is made) is underway, then where do we use it and for what purpose? Tracking the literal refetch seems more realistic use case.

• Cache

First of all, do we need caching inside createResource since it can be handled inside the fetcher function. createResource can not make a direct network call anyway. If I understand the API correctly, the value returned from the browser's fetch function has no use in createResource, like so:

const fetcher = (params: QueryParams) => fetch('/data');
const [data, { refetch }] = createResource(queryParameters, fetcher);

So, createResource depends on the fetcher function for its data.

We have to be sure if we need really need to support caching out of the box. Either way, caching should be optional if it is supported.

An important reminder here, we are designing this API to be used in Suspense but sometimes discussion moves to React Query which is designed for fetch on render. Suspense support is added later. Here is a note from https://react-query.tanstack.com/guides/suspense#_top:

NOTE: Suspense mode for React Query is experimental, same as Suspense for data fetching itself. These APIs WILL change and should not be used in production unless you lock both your React and React Query versions to patch-level versions that are compatible with each other.

Requirements for createResource

1. The signal's state returned should reflect the mutually exclusive nature of a promise.

2. It should be impossible or very hard to have an inconsistent UI state, without resorting to complex conditionals.

A promise can be resolved with null or undefined. Data branch should be able to render without needing to check the error branch. Currently you have to check both success and error values if the promise resolves to undefined.

Issues with current implementation

1. Current implementation uses three different signals for each possible states. Consequently the outcome does not reflect the mutually exclusivity.

2. We can not use type constrains.

3. Relatively complex API with some uncommon usage, like signals having signals as their property, i.e data.error.

Discussion

Here we are going to discuss how to encode the state of a request (pending | success | error) and its result once the promise is settled (any on success | error on error).

We have several alternatives. We will discuss their benefits and downsides.

1. Union of objects:

This comes in two possible shapes

a. Using the same property name for both error and success values:

type Result = 
| { status: 'pending' }
| { status: 'success', value: any }
| { status: 'error', value: Error }
;

But value updates whenever status updates, which may cause inconsistencies when the value is not properly wrapped in conditionals, especially in UI.

b. Using different property names for different states:

type Result = 
| { status: 'pending' }
| { status: 'success', success: any }
| { status: 'error', error: Error }
;

This way the result can be used even without checking the status, which reduces chances for error. Here, we use the status values as the property name to make them more memorable. If it feels icky and want to pursue more contrast:

type Result = 
| { status: 'pending' }
| { status: 'success', data: any }
| { status: 'fail', error: Error }
;

We can simplify the API by dissolving the info object into the returned value:

// By moving its properties directly  into the array
const [result, refetch, refetching, mutate] = createResource(fether, queryParams);

// Or by merging it into the signal
const result = createResource(fether, queryParams);

Pros:

• Can tract state atomically under a single signal
• Less room for error

Cons

No obvious cons when having different property names for error and success cases.

2. Array of signals: one for the status and other one for the data object.

type Status = 'pending' | 'success' | 'error';
type Data = { success?: any, error: Error };

const [status, data, info] = createResource(fether, queryParams);

Pros

• Easy to use, does not require re-assignment in case of multiple resources
• Data accurately encodes the result of the promise, hard to make mistakes

Cons

• Tracking state requires either two signals or extra deriving functions

3. A Tuple of signals:

type RESULT = 
| ['pending' undefined, info]
| ['success', any, info]
| ['error', Error, info]

const result: Result = createResource(fetcher, queryParams);

We encode the status and the result in form of a tuple, the state is always consistent:

type RESULT = 
| ['pending' undefined, info]
| ['success', value, info]
| ['error', error, info]

Pros

The easiest one to use, but there is room for error if not used carefully.

Cons

• Tracking state requires either two signals or extra deriving functions
• Easies one to have an inconsistent UI if developer is not careful enough.

Decision

A union of objects with contents of the info object moved into the array seems the most flexible API:

type Result = 
| { status: 'pending' }
| { status: 'success', success: any }
| { status: 'error', error: Error }
;

Edit: I removed some parts of this post because I elaborated some of those ideas further with examples which you can find
#1009