React-Query-Async

A HOC utility tool built for react-query however also supports swr and @apollo/graphql as well as any custom data fetch hook.

Features

• Async (HOC)
• useAsync (Hook)
• AsyncProvider (Config exposed to all instances of Async and useAsync)

Quick Setup

import { RQMergeStatesFn, SWRMergeStatesFn, GQLMergeStatesFn } from "react-query-async" 

Out of the box configured with RQMergeStatesFn which supports react-query however SWRMergeStatesFn and GQLMergeStatesFn provided for convenience. The latter two have not been fully tested yet.

Usage with React-Query

Without Async

import { useQuery, useMutation } from "react-query"

const Loading = () => <div>Loading</div>;
const Error = () => <div>Error</div>;
const NoData = () => <div>No Data</div>;

const App = () => {
  const todosQuery = useQuery('todos', () => API.getTodos());
  const { mutate, ...createTodoMutation } = useMutation(API.createTodo);
  
  if (todosQuery.isLoading || createTodoMutation.isLoading) return <Loading />
  
  if (todosQuery.isError || createTodoMutation.isError) return <Error />
  
  if (!!todosQuery.data) return <NoData />
  
  const { data: todos } = todosQuery;
  
  return (
    <>
      {todos.map(todo => <div>{todo.name}</div>)}
      
      <button 
        onClick={() => {
          mutate({ name: "I'm a new Todo!"})
        }}
      >
        Create New Todo
      </button>
    </>    
  )
};

With Async

Instead of having to constantly define stateful views, write it once and feed it into the Async HOC. Wrap your code with the Async HOC and it will do the rest.

import { Async } from "react-query-async"
import { useQuery, useMutation } from "react-query"

const Loading = () => <div>Loading</div>;
const Error = () => <div>Error</div>;
const NoData = () => <div>No Data</div>;

const App = () => {
  const todosQuery = useQuery('todos', () => API.getTodos());
  const { mutate, ...createTodoMutation} = useMutation(API.createTodo);

  return (
    <Async 
      queries={{ todosQuery }} 
      mutations={{ createTodoMutation }} 
      components={{ Loading, Error, NoData }}
    >
      {({
        queries: {
          todosQuery: { data: todos }
        }
      }) => (
        <>
          {todos.map(todo => <div>{todo.name}</div>)}
          <button 
            onClick={() => {
              mutate({ name: "I'm a new Todo!"})
            }}
          >
            Create New Todo
          </button>
        </>
      )}
    </Async>
  );
};

With AsyncProvider

Don't want to supplement the components prop everytime? Set up the config to whatever you want with.

import { Async } from "react-query-async"

const Loading = () => <div>Loading</div>;
const Fetching = () => <div>Fetching</div>;
const Error = () => <div>Error</div>;
const NoData = () => <div>No Data</div>;

const config = {
  showFetching: true,
  components: { Loading, Error, NoData, Fetching }  
}

ReactDOM.render( 
  <AsyncProvider config={config}> // Config will be passed to all instances of Async
    <App />
  </AsyncProvider>,
document.getElementById('root')
);

API

Async

<Async 
  queries={{ query1, query2 }} 
  mutations={{ mutation1 }} 
  showFetching 
  components={{ 
    Loading: () => "Custom Loading", // Supports React Components or 
    Fetching: "Fetching!" // even just a string!
  }}
  ErrorBoundary={MyCustomErrorBoundary} // Wrap instance with your own error boundary
>
  {({
   queries,
   mutations,
   queryState,
   mutationState.
  }) => "Data here!"}
</Async>

Parameters

• queries?: any

  • Any async operation that fetches data
  • Takes in a key value hash i.e queries={{ todosQuery, postsQuery }}

• mutations?: any

  • Any async operation that updates data
  • Takes in a key value hash i.e mutations={{ addTodosMutation, deleteTodoMutation }}

• isLoading?: boolean | (() => boolean)

• isFetching?: boolean | (() => boolean)

• hasError?: boolean | (() => boolean)

• hasData?: boolean | (() => boolean)

• showFetching?: boolean

  • By default false so Fetch State will not be displayed

• components?: DefaultComponents

  • DefaultComponents
    • Loading: ({ queryState, mutationState, queries, mutations }) => any | React.ReactNode | string
    • Fetching: ({ queryState, mutationState, queries, mutations }) => any | React.ReactNode | string
    • Error: ({ queryState, mutationState, queries, mutations }) => any | React.ReactNode | string
    • NoData: ({ queryState, mutationState, queries, mutations }) => any | React.ReactNode | string
  • Feel free to configure state to whatever you want. All the information you need is passed back so it's as flexible as possible

• mergeQueryStatesFn?: (operations: any) => OperationState

  • Out of the box it is defaulted to support react-query however see Examples to configure to swr, @apollo/graphql or any custom hook!

  • Any custom hook supported as long as operations is reduced to:

    • isLoading
    • hasError
    • hasData
    • isFetching - Optional

  • React Query Example - Default used

    const RQMergeStatesFn = (operations: any) => {
      return Object.values(operations)
        .filter((el: any) => el.status !== 'idle')
        .reduce(
          (acc: any, el: any) => ({
            ...acc,
            isLoading: !!(acc.isLoading || el.isLoading),
            isPaused: !!(acc.isPaused || el.isPaused),
            isFetching: !!(acc.isFetching || el.isFetching),
            hasError: !!(acc.hasError || el.isError),
            isSuccess: !!(acc.isSuccess === undefined ? el.isSuccess : acc.isSuccess && el.isSuccess),
            hasData: !!(acc.hasData === undefined
              ? getHasData(el.data)
              : acc.hasData && getHasData(el.data)),
            status: getStatus({
              isLoading: acc.isLoading || el.isLoading,
              hasError: acc.hasError || el.isError,
              isSuccess: acc.isSuccess === undefined ? el.isSuccess : acc.isSuccess && el.isSuccess
            })
          }),
          {}
        ) as OperationState;
    };

• mergeMutationStatesFn?: (operations: any) => OperationState

  • Out of the box it is defaulted to support react-query however see Examples to configure to swr, @apollo/graphql or any custom hook!
  • Don't like that mutations also trigger hard loading? Redefine the mergeMutationStatesFn to to exclude hard loading states!
  • Any custom hook supported as long as operations is reduced to:
    • isLoading
    • hasError
    • hasData
    • isFetching - Optional

• ErrorBoundary?: any

  • In case you want each instance of the Async HOC to have an Error Boundary as a fall back.

• errorBoundaryProps?: any

  • Props to be passed to ErrorBoundary

Returns

• queryState: OperationState
  • The state of all queries
  • OperationState
    • isLoading if at least 1 query is loading
    • isFetching if at least 1 query is fetching
    • hasError if at least 1 query has error
    • hasData if at least 1 query has no Data
• mutationState: OperationState
  • The state of all mutations
  • OperationState
    • isLoading if at least 1 query is loading
    • isFetching if at least 1 query is fetching
    • hasError if at least 1 query has error
    • hasData if at least 1 query has no Data
• queries: any
  • Same as Params
• mutations: any
  • Same as Params

useAsync

const [queryState, mutationState] = useAsync({ queries: { query1, query2 }, mutations: { mutation1 }})

Parameters

• queries?: any
  • Same as Async
• mutations?: any
  • Same as Async
• mergeQueryStatesFn?: (operations: any) => OperationState
  • Same as Async
• mergeMutationStatesFn?: (operations: any) => OperationState
  • Same as Async

Returns

• queryState: OperationState
  • The state of all queries
  • OperationState
    • isLoading if at least 1 query is loading
    • isFetching if at least 1 query is fetching
    • hasError if at least 1 query has error
    • NoData if at least 1 query has no Data
• mutationState: OperationState
  • The state of all mutations
  • OperationState
    • isLoading if at least 1 query is loading
    • isFetching if at least 1 query is fetching
    • hasError if at least 1 query has error
    • NoData if at least 1 query has no Data

AsyncProvider

<AsyncProvider 
  config={
    showFetching: false,
    components={{
      Loading: "Custom Loading",
      Fetching: "Custom Fetching",
      Error: () => "Custom Error",
      NoData: () => "Custom No Data"
    }}
    mergeQueryStatesFn={customMergeFn}
    mergeMutationStatesFn={customMergeFn}
    ErrorBoundary={MyCustomErrorBoundary}
    errorBoundaryProps={ fallback: "I'm an error fallback"}
  }
>
  <App />
</AsyncProvider>

• config
  • Same as Async

Examples

• Basic w/ React-Query
• Basic w/ Custom Hooks
• More to come...