Asynchronous Data Queries
Recoil provides a way to map state and derived state to React components via a data-flow graph. What's really powerful is that the functions in the graph can also be asynchronous. This makes it easy to use asynchronous functions in synchronous React component render functions. Recoil allows you to seamlessly mix synchronous and asynchronous functions in your data-flow graph of selectors. Simply return a Promise to a value instead of the value itself from a selector get
callback, the interface remains exactly the same. Because these are just selectors, other selectors can also depend on them to further transform the data.
Selectors can be used as one way to incorporate asynchronous data into the Recoil data-flow graph. Please keep in mind that selectors represent "idempotent" functions: For a given set of inputs they should always produce the same results (at least for the lifetime of the application). This is important as selector evaluations may be cached, restarted, or executed multiple times. Because of this, selectors are generally a good way to model read-only DB queries. For mutable data you can use a Query Refresh or to synchronize mutable state, persist state, or for other side-effects consider the experimental Atom Effects API.
#
Synchronous ExampleFor example, here is a simple synchronous atom and selector to get a user name:
#
Asynchronous ExampleIf the user names were stored in some database we need to query, all we need to do is return a Promise
or use an async
function. If any dependencies change, the selector will be re-evaluated and execute a new query. The results are cached, so the query will only execute once per unique input.
The interface of the selector is the same, so the component using this selector doesn't need to care if it was backed with synchronous atom state, derived selector state, or asynchronous queries!
But, since React render functions are synchronous, what will it render before the promise resolves? Recoil is designed to work with React Suspense to handle pending data. Wrapping your component with a Suspense boundary will catch any descendants that are still pending and render a fallback UI:
#
Error HandlingBut what if the request has an error? Recoil selectors can also throw errors which will then be thrown if a component tries to use that value. This can be caught with a React <ErrorBoundary>
. For example:
#
Queries with ParametersSometimes you want to be able to query based on parameters that aren't just based on derived state. For example, you may want to query based on the component props. You can do that using the selectorFamily
helper:
#
Data-Flow GraphRemember, by modeling queries as selectors, we can build a data-flow graph mixing state, derived state, and queries! This graph will automatically update and re-render React components as state is updated.
The following example will render the current user's name and a list of their friends. If a friend's name is clicked on, they will become the current user and the name and list will be automatically updated.
#
Concurrent RequestsIf you notice in the above example, the friendsInfoQuery
uses a query to get the info for each friend. But, by doing this in a loop they are essentially serialized. If the lookup is fast, maybe that's ok. If it's expensive, you can use a concurrency helper such as waitForAll
to run them in parallel. This helper accepts both arrays and named objects of dependencies.
You can use waitForNone
to handle incremental updates to the UI with partial data
#
Pre-FetchingFor performance reasons you may wish to kick off fetching before rendering. That way the query can be going while we start rendering. The React docs give some examples. This pattern works with Recoil as well.
Let's change the above example to initiate a fetch for the next user info as soon as the user clicks the button to change users:
#
Query Default Atom ValuesA common pattern is to use an atom to represent local editable state, but use a selector to query default values:
If you would like bi-directional syncing of data, then consider atom effects
#
Async Queries Without React SuspenseIt is not necessary to use React Suspense for handling pending asynchronous selectors. You can also use the useRecoilValueLoadable()
hook to determine the status during rendering:
#
Query RefreshWhen using selectors to model data queries, it's important to remember that selector evaluation should always provide a consistent value for a given state. Selectors represent state derived from other atom and selector states. Thus, selector evaluation functions should be idempotent for a given input, as it may be cached or executed multiple times. Practically, that means a single selector should not be used for a query where you expect the results to vary during the application's lifetime.
There are a few patterns you can use for working with mutable data:
#
Use a Request IDSelector evaluation should provide a consistent value for a given state based on input (dependent state or family parameters). So, you could add a request ID as either a family parameter or a dependency to your query. For example:
#
Use an AtomAnother option is to use an atom, instead of a selector, to model the query results. You can imperatively update the atom state with the new query results based on your refresh policy.
One downside to this approach is that atoms do not currently support accepting a Promise
as the new value in order to automatically take advantage of React Suspense while the query refresh is pending, if that is your desired behavior. However, you could store an object which manually encodes the loading status as well as the results if desired.
Also consider atom effects for query synchronization of atoms.