// ...import{useFetchye}from'fetchye';constMyComponent=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/profile');return(!isLoading&&(<p>{data.body.name}</p>));};

📖 Table of Contents

✨ Features

⬇️ Install & Setup

Quick Install

npm i -S fetchye

// ...import{useFetchye}from'fetchye';constMyComponent=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/profile');return(!isLoading&&(<p>{data?.body.name}</p>));};

FetchyeProvider Install

npm i -S fetchye

import{FetchyeProvider}from'fetchye';constParentComponent=({ children})=>(<FetchyeProvider>{/* Use your Router to supply children components containing useFetchye */}{children}</FetchyeProvider>);

// ...import{useFetchye}from'fetchye';constMyComponent=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/profile');return(!isLoading&&(<p>{data?.body.name}</p>));};

FetchyeReduxProvider Install

npm i -S fetchye redux react-redux

importReactfrom'react';import{createStore}from'redux';import{Provider}from'react-redux';import{FetchyeReduxProvider}from'fetchye-redux-provider';import{SimpleCache}from'fetchye';constfetchyeCache=SimpleCache({// Need to tell Fetchye where the cache reducer will be locatedcacheSelector:(state)=>state,});conststore=createStore(fetchyeCache.reducer);constParentComponent=({ children})=>(<Providerstore={store}><FetchyeReduxProvidercache={fetchyeCache}>{/* Use your Router to supply children components containing useFetchye */}{children}</FetchyeReduxProvider></Provider>);

// ...import{useFetchye}from'fetchye';constMyComponent=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/profile');return(!isLoading&&(<p>{data.body.name}</p>));};

One App Install

npm i -S fetchye fetchye-one-app

// ...import{combineReducers}from'redux-immutable';import{OneFetchyeProvider,OneCache}from'fetchye-one-app';constMyModuleRoot=({ children})=>(<>{/* OneFetchyeProvider is configured to use OneCache */}<OneFetchyeProvider>{/* Use your Router to supply children components containing useFetchye */}{children}</OneFetchyeProvider></>);// ...MyModuleRoot.holocron={name:'my-module-root',reducer:combineReducers({// ensure you scope the reducer under "fetchye", this is important// to ensure that child modules can make use of the single cachefetchye:OneCache().reducer,// ... other reducers}),};

// ...import{useFetchye}from'fetchye';constMyComponent=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/profile');return(!isLoading&&(<p>{data?.body.name}</p>));};

🤹‍ Usage

Real-World Example

importReactfrom'react';import{useFetchye}from'fetchye';constBookList=({ genre})=>{const{ isLoading, error, data}=useFetchye(`http://example.com/api/books/?genre=${genre}`,{headers:{'X-Some-Tracer-Id':1234,},});if(isLoading){return(<p>Loading...</p>);}if(error||data.status!==200){return(<p>Oops!</p>);}return(<><h1>Books by{genre}</h1><ul>{data.body.map((book)=>(<likey={book.id}>{book.title} by{book.author}</li>))}</ul></>);};

Deferred execution

importReactfrom'react';import{useFetchye}from'fetchye';constNewBookForm=()=>{const{ formData, onChange}=useSomeFormHandler();const{ isLoading, run}=useFetchye('http://example.com/api/books',{// include defer heredefer:true,method:'POST',headers:{'Content-Type':'application/json',},body:JSON.stringify({      ...formData,}),});constonSubmit=async(event)=>{event.preventDefault();const{ data, error}=awaitrun();// Check to make sure no error and data.status === 200 for success};return(<formonSubmit={onSubmit}>{/* ...form elements using onChange */}{/* Hide Submit button when sending POST request */}{!isLoading&&<buttontype="submit">Submit</button>}</form>);};

Abort Inflight Requests

importReact,{useEffect}from'react';import{useFetchye}from'fetchye';constAbortComponent=()=>{constcontroller=newAbortController();useFetchye('http://example.com/api/books',{signal:controller.signal});useEffect(()=>()=>controller.abort(),[]);return(<div><h1>abortable component</h1></div>);};

Sequential API Execution

importReactfrom'react';import{useFetchye}from'fetchye';constMyFavoriteBook=()=>{const{isLoading:loadingProfile,error:profileError,data:profile,}=useFetchye('http://example.com/api/profile');constprofileHasBookId=!loadingProfile&&profile?.body?.favoriteBookId;const{isLoading:loadingBook,error:bookError,data:favoriteBook,}=useFetchye('http://example.com/api/books',{defer:!profileHasBookId,method:'POST',body:JSON.stringify({bookId:profile?.body?.favoriteBookId,}),});if(loadingProfile){return(<p>Loading Profile...</p>);}if(profileError||profile.status!==200){return(<p>Oops!</p>);}if(loadingBook){return(<p>Loading Favourite Book...</p>);}if(bookError||favoriteBook.status!==200){return(<p>Oops!</p>);}return(favoriteBook.status===200&&(<><h1>My Favorite Book</h1><h2>{favoriteBook.body.title}</h2></>));};

importReactfrom'react';import{useFetchye}from'fetchye';constMyFavoriteBook=()=>{const{isLoading:loadingProfile,error:profileError,data:profile,}=useFetchye('http://example.com/api/profile');const{isLoading:loadingBook,error:bookError,data:favoriteBook,}=useFetchye(()=>`http://example.com/api/books/${profile.body.favoriteBookId}`);if(loadingProfile){return(<p>Loading Profile...</p>);}if(profileError||profile.status!==200){return(<p>Oops!</p>);}if(loadingBook){return(<p>Loading Favourite Book...</p>);}if(bookError||favoriteBook.status!==200){return(<p>Oops!</p>);}return(favoriteBook.status===200&&(<><h1>My Favorite Book</h1><h2>{favoriteBook.body.title}</h2></>));};

Refreshing

importReactfrom'react';import{useFetchye}from'fetchye';constBookList=({ genre})=>{const{    isLoading,data:booksData,    run,}=useFetchye(`http://example.com/api/books/?genre=${genre}`);if(isLoading){return(<p>Loading...</p>);}return(<>{/* Render booksData */}<buttontype="button"onClick={()=>run()}>Refresh</button></>);};

Custom Fetcher

importReactfrom'react';import{useFetchye}from'fetchye';constgraphqlFetcher=async(fetchClient,key,options)=>{letres;letpayload;leterror;try{res=awaitfetchClient('https://example.com/graphql',{      ...options,method:'POST',headers:{'X-Correlation-Id':12345,'Content-Type':'application/json',},// The key contains the GraphQL object request rather than a URL in this casebody:JSON.stringify(key),});// GraphQL Responseconst{ data, errors}=awaitres.json();// Pass through GraphQL Datapayload={      data,ok:res.ok,status:res.status,};// Assign GraphQL errors to errorerror=errors;}catch(requestError){// eslint-disable-next-line no-console -- error useful to developer in specific error caseconsole.error(requestError);error=requestError;}return{    payload,    error,};};constBookList=({ genre})=>{const{ isLoading,data:booksData, run}=useFetchye({query:`      query BookList($genre: Genre) {        book(genre: $genre) {          title          author        }      }      `,variables:{ genre},},{},graphqlFetcher);if(isLoading){return(<p>Loading...</p>);}return(<>{/* Render booksData */}<buttontype="button"onClick={()=>run()}>Refresh</button></>);};

Controlling the Cache Key

importReactfrom'react';import{useFetchye}from'fetchye';constBookList=({ ssl})=>{const{ isLoading, data}=useFetchye(`${ssl ?'https' :'http'}://example.com/api/books/`,{mapKeyToCacheKey:(key)=>key.replace('https://','http://'),});if(isLoading){return(<p>Loading...</p>);}return({/* Render data */});};

Passing dynamic headers

importReactfrom'react';import{useFetchye,ignoreHeadersByKey}from'fetchye';importuuidfrom'uuid';constBookList=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/books/',{// remove the 'correlationId' header from the headers, as its the only dynamic headermapOptionsToKey:ignoreHeadersByKey(['correlationId']),headers:()=>({// static headers are still fine, and can be specified here like normalstaticHeader:'staticValue',// This header will be generated fresh for every call out of the systemcorrelationId:uuid(),}),});if(isLoading){return(<p>Loading...</p>);}return({/* Render data */});};exportdefaultBookList;

SSR

One App SSR

importReactfrom'react';import{useFetchye}from'fetchye';import{oneFetchye}from'fetchye-one-app';constBookList=()=>{const{ isLoading, data}=useFetchye('http://example.com/api/books/');if(isLoading){return(<p>Loading...</p>);}return({/* Render data */});};BookList.holocron={loadModuleData:async({store:{ dispatch}})=>{if(global.BROWSER){return;}// oneFetchye has same arguments as useFetchye// dispatches events into the server side Redux storeawaitdispatch(oneFetchye('http://example.com/api/books/'));},};exportdefaultBookList;

Next.JS SSR

import{useFetchye,makeServerFetchye,SimpleCache}from'fetchye';constcache=SimpleCache();// Codesandbox takes a second to get Next.JS started...exportdefaultfunctionIndexPage({ initialBookList}){const{ isLoading, data}=useFetchye('http://example.com/api/books/',{initialData:initialBookList,});if(isLoading){return(<p>Loading...</p>);}return({/* Render data */});}constfetchye=makeServerFetchye({  cache,fetchClient:fetch,});exportasyncfunctiongetServerSideProps(){try{// returns { data, error } payload for feeding initialData on client sideconstres=awaitfetchye('http://example.com/api/books/');return{props:{initialBookList:res,},};}catch(error){// eslint-disable-next-line no-console -- error useful to developer in specific error caseconsole.error(error.message);return{};}}

Write your own Cache

import{IS_LOADING,SET_DATA,DELETE_DATA,ERROR,CLEAR_ERROR,}from'fetchye';exportfunctionCustomCache({ cacheSelector=(state)=>state}){return{// The reducer will save each action to state by hash keyreducer:(state,action)=>{switch(action.type){caseIS_LOADING:{// return is loading state changereturnstate;}caseSET_DATA:{// return set data state changereturnstate;}caseDELETE_DATA:{// return delete data state changereturnstate;}caseERROR:{// return error state changereturnstate;}caseCLEAR_ERROR:{// return clear error state changereturnstate;}default:{returnstate;}}},getCacheByKey:(state,key)=>({      data,// dig into state and return data by key hash value      error,// dig into state and return error by key hash value      loading,// dig into state and return loading by key hash value}),    cacheSelector,// pass through optional cacheSelector property};}

import{FetchyeProvider}from'fetchye';import{CustomCache}from'./CustomCache';constParentComponent=({ children})=>(<FetchyeProvidercache={CustomCache()}>{children}</FetchyeProvider>);

🎛️ API

useFetchye

const { isLoading, data, error, run } = useFetchye(key, { defer: Boolean, mapOptionsToKey: options => options, ...fetchOptions }, fetcher);

makeServerFetchye

const fetchye = makeServerFetchye({ cache, fetchClient });const { data, error } = await fetchye(key, options, fetcher);

makeOneServerFetchye

const fetchye = makeOneServerFetchye({ store, fetchClient });const { data, error } = await fetchye(key, options, fetcher);

oneFetchye

const { data, error } = await dispatch(oneFetchye(key, options, fetcher));

Providers

FetchyeProvider

<FetchyeProvider cache={SimpleCache()}>  {children}</FetchyeProvider>

FetchyeReduxProvider

import { FetchyeReduxProvider } from "fetchye-redux-provider";

<Provider>  <FetchyeReduxProvider cache={SimpleCache()}>    {children}  </FetchyeReduxProvider></Provider>

OneFetchyeProvider

import{OneFetchyeProvider}from'fetchye-one-app';

<Provider><OneFetchyeProvider>{children}</OneFetchyeProvider></Provider>;

Caches

SimpleCache

import { SimpleCache } from 'fetchye';const cache = SimpleCache({  cacheSelector,});

ImmutableCache

import { ImmutableCache } from 'fetchye-immutable-cache';const cache = ImmutableCache({  cacheSelector});

OneCache

import { OneCache } from 'fetchye-one-app';const cache = OneCache();

Actions

IS_LOADING

import { IS_LOADING } from 'fetchye-core';

{  type: IS_LOADING,  hash,}

SET_DATA

import { SET_DATA } from 'fetchye-core';

{  type: SET_DATA,  hash,  value,}

DELETE_DATA

import { DELETE_DATA } from 'fetchye-core';

{  type: DELETE_DATA,  hash,}

ERROR

import { ERROR } from 'fetchye-core';

{  type: ERROR,  hash,  error,}

CLEAR_ERROR

import { CLEAR_ERROR } from 'fetchye-core';

{  type: CLEAR_ERROR,  hash,}

mapOptionToKey Helpers

ignoreHeadersByKey

importReactfrom'react';import{useFetchye,ignoreHeadersByKey}from'fetchye';constBookList=({ locale})=>{const{ isLoading, data}=useFetchye('http://example.com/api/books/',{// remove the 'locale' header from the headers when building the cache keymapOptionsToKey:ignoreHeadersByKey(['locale']),headers:{ locale},});// ... rest of component};exportdefaultBookList;

📢 Mission

🏆 Contributing

🗝️ License

🗣️ Code of Conduct