RFC: Change to Resource APIs

[ryansolid]

Summary

(Updated Feb 2nd 2020) - remove createResourceMemo

In this RFC I'm looking for feedback on some proposed changes to the Resource APIs. This is inspired mostly from wanting to keep the interfaces simpler to make learning Solid easier, and to remove complicated edge cases from SSR.

The most important changes is I intend to remove createResourceState and change the behavior of createResource to be more dynamic.

Background

Resources are an essential part to handling asynchronicity in Solid. Async is not always easy and the library having knowledge let us it do a lot for you in terms of making it easier to control flow. While one can opt into Async updates at anytime simply by plugging a signals into promises:

promise.then(setData).catch(setError)

we can use resources as a way to coordinate placeholders with Suspense, do some navigations with useTransition, and to know both when we are done rendering on the server, and serve as a channel to stream data.

Proposal

Solid will have 1 resource primitive createResource.

createResource

The new version will carry this signature

export function createResource<T, U>(
  source: U | false | (() => U | false),
  fetcher: (k: U, getPrev: () => T | undefined) => T | Promise<T>,
  init?: T
): [
  {
  (): T | undefined;
  loading: boolean;
  },
  {
    mutate: (v: T | undefined) => T | undefined;
    refetch: () => void;
  }
]

The source will be a literal or a function that tracks. This is where we generate the data we send to the fetcher. If the source is falsey we do not execute the fetcher. mutate does a synchronous update to the data and refetch triggers the whole thing again even if it hasn't changed.

import { createSignal, createResource } from "solid-js";
import { render } from "solid-js/web";

const fetchUser = (id) =>
  fetch(`https://swapi.dev/api/people/${id}/`).then((r) => r.json());

const App = () => {
  const [userId, setUserId] = createSignal(),
    [user] = createResource(userId, fetchUser);

  return (
    <>
      <input
        type="number"
        min="1"
        placeholder="Enter Numeric Id"
        onInput={(e) => setUserId(e.target.value)}
      />
      <span>{user.loading && "Loading..."}</span>
      <div>
        <code>{JSON.stringify(user())}</code>
      </div>
    </>
  );
};

This example doesn't load until you set the signal as it starts with an undefined. In so we keep loading semantics. But we can also just have it autoload both single time or every time props update:

// will only fetch once
const [user] = createResource(props.userId, fetchUser);

// will only fetch every time `props.userId` updates
const [user] = createResource(() => props.userId, fetchUser);

There are many patterns we can use here. You define many types of fetcher. Your fetcher could be generic shared across all your resources and you pass the query as the source. Maybe you use GraphQL. The fetcher returns a promise, but it can be a promise for anything. It can also return data synchronously, so building a query cache is possible. By default Solid does nothing special with the source but a library could build on this and get SWR or React Query functionality.

Using Resources with State

We still have a gap though when dealing state. The solution is leveraging the fact that Solid state objects accept other reactive primitives. Furthermore we can use the transform on load to reconcile state differences. In this way we could refresh our data and only notify the specific properties that update.

const [user, { refetch }] = createResource(props.userId,  (id, prev) => {
 const value = await fetch(`https://swapi.dev/api/people/${id}/`).then((r) => r.json())
 return reconcile(value)(prev());
});

const [state, createState] = createState({
  get user() {
    return user();
  }
});

// sometime later to apply updates
refetch();

Impact

This change removes createResourceState so it is important that we consider all use cases. If you have been using createResourceState I'm very interested if these scenarios cover your usage. The biggest challenge with createResourceState was it dynamically created resources on the fly based on property access which are challenging for SSR/Hydration where we need to align them to automatically serialize data across. But this does mean that lists are generally going to be explicit or share a single resource which can mean triggering Suspense more often. With transitions this is smooth, but I might be not considering cases where it would trigger falling back to skeleton loading states unintentionally.

This also starts a pattern of leveraging nested signals in state. This already existed but this is the first time it has become the defacto solution. I worry about the verbosity of the API. However, since we need to get the source function out of the create it makes sense to create the resource separately. I'm also open to feedback about this as well.

[amoutonbrady]

I like where this is going. I do see how this makes sense looking forward and tighten things up together in a cohesive sets of primitives.

On thought occurred to me while integrating with the createState and how to "group" related stuff together. If we are willing to go one step further in compiler analysis (assuming this kind of stuff is possible), we might take the getters function of a createStep and determine if the returned value is a promise or not.

Today, a getter is wrapped into a createMemo. How about wrapping a getter that return a promise into a createRessourceMemo of some sort?

function fetchArticle(slug) {
   return fetch(`https://api.com/article/${slug}`).then(r => r.json());
}

const [state, createState] = createState({
  get article() {
    return fetchArticle(props.slug);
  }
});

[ryansolid]

Thanks for your thoughts.

Knowing it returns a promise might require significant analysis because it can be cross-module, right into node modules etc.. Not even component files we would usually process. A runtime approach could work but it would require bringing this into every project to support the possibility. Part of me wants to be able to store anything in state.. promise/function whatever and not assume it has execution characteristics. The getter itself is the exception but I'm not sure the return value is.

It does occur to me that createResourceMemo might be the more primitive of the two APIs and I should explore that more. I've been looking at SWR for some influence but there are still many questions here since I do want to make these primitives simple. The hardest challenge is it isn't just managing the promise input be we need to control the read for suspense. So custom fetching/caches/transforms almost needs a way to be injected. For that reason alone API simplicity like this might need to be the last consideration until we are sure we have everything. The createResourceMemo shown above is actually much less featured than createResource. If we were to bring them to parity or make it the fundamental one then that changes what it looks like to integrate it with state.

State is still the problem and hierarchical at that makes it really tricky. You almost want to be able to synchronize parts of it, but the challenge is the reads need to be registered resources up front (or read from a resource) to track properly on updates. So you can't just be replacing parts of the tree as you wish unless the resource is at the root of that change. But that ties all nested resources together.