react-async-stateful ·

A consistent method of storing state for async calls to reduce boilerplate in react code

npm i react-async-stateful

Usage

// plain js
import {useAsyncState} from "react-async-stateful";

const AsyncComponent = (props) => {
    const [submitResult, _, updateSubmitResult] = useAsyncState();    

    const submit = useCallback(async () => {
        const {resolvedAt} = await updateSubmitResult(async () => {
            const response = await fetch("https://example.com/api/v1/squeal-loudly");
            return response.json();
        });
        console.log(`API responded at: ${new Date(resolvedAt).toString()}`)
    });
    
    return <div>
        <button onClick={submit}>Call the API!</button>
        {submitResult.resolved && <div>The response: {JSON.stringify(submitResult.value)}</div>}
    </div>;
};

Demos

• API Example

useAsyncState hook

The useAsyncState hook returns:

    const [asyncState, setAsyncState, updateAsyncState] = useAsyncState(defaultValue);

• asyncState is the the current value of the async state
• setAsyncState is usually never needed but can be useful to synchronously update the state, eg:

  import AsyncState from "react-async-stateful";
  
  const updateFromLocalStorage = () => {
    setAsyncState(asyncState => {
        const value = localStorage.getItem("key");
        return AsyncState.resolve(asyncState, value);
    });
  };

• updateAsyncState is the recommended way of updating. It will automatically update the state and re-render your component with a pending state allowing you to dipslay loading spinners ect.

  const submit = useCallback(() => {
    updateAsyncState(/*promise or an async function*/ async () => {
        const response = await api.get(`user/${userId}`); // thrown errors are automatically handled
        const user = formatUserObject(response.data);
        return user;
    });
  }, [userId]);
  
  // component will receive:
  asyncState.pending === true
  
  // then
  asyncState.resolved === true
  asyncState.value    === user // resolved value
  
  // or if a rejection
  asyncState.rejected === true
  asyncState.error    === Error // error instance

Submit vs Refresh

The default behaviour is that when the updateAsyncState function is called, the current value and errors are wiped and the state is put into an empty pending state.

This can be undesirable if you are merely refreshing data and want to keep the previous value whilst the new request is being made. To fix this you can pass the refresh option so that these are kept:

const refreshList = () => {
    updateList(async () => {
        const response = await api.get("list");
        return response.data;
    }, {refresh: true} /* <-- keep the current value whilst we are pending */);
};

whether submit or refresh were used is stored as submitType on the async state object

The AsyncState object

Note: All operations on async state do not mutate the original object

// typescript
import AsyncState from "react-async-stateful";

// creating the state
const state = AsyncState.create("hello");
console.log(state.pristine); // true
console.log(state.value); // hello

// resolving the state
const resolvedState = AsyncState.resolve(state, "world");
console.log(state.resolved); // true
console.log(state.value); // world

Properties

| key | type | description | --- | --- | --- | defaultValue | T or undefined | default value set at the object creation
| pristine | boolean | have we been updated yet? | pending | boolean | is there an update to the state happening now? | pendingAt | number or null | when the update started | resolved | boolean | do we have a resolved value? if this is true then value must not be undefined | resolvedAt | number or null | when the value the was resolved
| rejected | boolean | if an error occurred or the update was rejected. if this is true then error must not be undefined | rejectedAt | number or null | when the rejection happened 😢 | settled | boolean | if the object is resolved/rejected and not pending | settledAt | number or null | when it was settled | value | T or undefined | the currently resolved value, if undefined we are not resolved
| error | Error or undefined | the reason for the rejection, if undefined we are not rejected
| submitType | AsyncStateSubmitType or undefined | what kind of submit was it? can be either submit or refresh

Typescript Utils

Typescript has a cool feature allowing you to narrow the type of an object using methods. Supplied are some methods that will make null checking your async state objects easier:

import AsyncState, {useAsyncState} from "react-async-stateful";

const [asyncState, _, updateAsyncState] = useAsyncState<UserData>();

runUpdateThatWillHappenInTheFuture();

/* Typescript will complain about the line below 😫 
   Even though our library provides a contract that if resolved is true
   `value` cannot be undefined the typescript compiler has no way of knowing this! */
// return asyncState.resolved ? <div>{asyncState.value.id}</div> : "Loading";

// Use `isResolved` and the compiler will be happy that it is definitely present:
return AsyncState.isResolved(asyncState) ? <div>{asyncState.value.id}</div> : "Loading";

To-Do

• [ ] tests
• [ ] better docs
• [ ] redux actions + reducers