react-restfully

React Restfully is a set of React Hooks and their analogous vanilla JS functions that assist you in fetching data using the fetch() API.

Version 1.0.0

Quickstart

[TOC]

Hooks

usePost

Example

function hello() {
	const {data, loading, error} = usePost('__URL__', {
		variables: {language: 'english'},
	});
	
	if(loading) return <p>Loading ...</p>;
	return <h1>Hello {data.greeting.message}!</h1>;
}

Function Signature

usePost(
    url: String,
    fetchOptions: fetchOptions = {}, 
    dependencies?: Array = []
): FetchResult

Params

url

| PARAM | TYPE | DESCRIPTION | |----------|---------------|-------------------------------| | url | string | The URL to supply to fetch()|

fetchOptions

| OPTION | TYPE | DESCRIPTION | |---------------|---------------------|------------------------------------------------------------------------------| | headers | array | Headers (See fetch.DefaultHeaders) | | payload | Object∣Map | Data to pass down. (Note: payload is appended to the URL for Get requests) | | onCompleted | function | Callback on successful fetch | | onError | function | Callback on failed fetch | | transform | Transform∣function∣boolean | Overrides default formatting of payload. Setting to FALSE will prevent any transformation to payload. (Note that the Transform object contains default transformation operations). | | onError | ResponseTypes | Function used to handle the response body. |

dependencies

| PARAM | TYPE | DESCRIPTION | |----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| | dependencies | array | The array of dependencies to pass to React's useEffect's second parameter. Used to determine when this hook is fired. Default: []. |

Result

| PROPERTY | TYPE | DESCRIPTION | |-------------|---------------------------|-----------------------------------------| | data | object∣undefined | Data returned from query | | loading | Boolean | Whether or not query is ongoing | | hasErrors | Boolean | Whether or not errors have occurred | | error | object∣undefined | Error returned. Defaults to undefined | | payload | Object | Data passed down |

useGet

Example

function hello() {
	const {data, loading, error} = useGet('__URL__', {
		variables: {language: 'english'},
	});
	
	if(loading) return <p>Loading ...</p>;
	return <h1>Hello {data.greeting.message}!</h1>;
}

Function Signature

useGet(
    url: String,
    fetchOptions?: fetchOptions = {},
    dependencies?: Array = []
): FetchResult

Params

url

| PARAM | TYPE | DESCRIPTION | |----------|---------------|-------------------------------| | url | string | The URL to supply to fetch()|

fetchOptions

| OPTION | TYPE | DESCRIPTION | |---------------|---------------------|------------------------------------------------------------------------------| | headers | array | Headers (See fetch.DefaultHeaders) | | payload | Object∣Map | Data to pass down. (Note: payload is appended to the URL for Get requests) | | onCompleted | function | Callback on successful fetch | | onError | function | Callback on failed fetch | | transform | Transform∣function∣boolean | Overrides default formatting of payload. Setting to FALSE will prevent any transformation to payload. (Note that the Transform object contains default transformation operations). | | onError | ResponseTypes | Function used to handle the response body. |

dependencies

| PARAM | TYPE | DESCRIPTION | |----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| | dependencies | array | The array of dependencies to pass to React's useEffect's second parameter. Used to determine when this hook is fired. Default: []. |

Result

| PROPERTY | TYPE | DESCRIPTION | |-------------|---------------------------|-----------------------------------------| | data | object∣undefined | Data returned from query | | loading | Boolean | Whether or not query is ongoing | | hasErrors | Boolean | Whether or not errors have occurred | | error | object∣undefined | Error returned. Defaults to undefined | | payload | Object | Data passed down |

useSubmit

Example

function Hello() {
	const [loadGreeting, {called, loading, data}] = useSubmit('__URL__', {
		variables: {language: 'english'},
	});

	if(called && loading) return <p>Loading ...</p>
	if(!called) {
		return <button onClick={() => loadGreeting()}>Load greeting</button>
	}
	return <h1>Hello {data.greeting.message}!</h1>;
}

Function Signature

useSubmit(
    url: String,
    fetchOptions?: fetchOptions = {}
): [(function(): void), FetchResult]

Params

url

| PARAM | TYPE | DESCRIPTION | |----------|---------------|-------------------------------| | url | string | The URL to supply to fetch()|

fetchOptions

| OPTION | TYPE | DESCRIPTION | |---------------|---------------------|------------------------------------------------------------------------------| | headers | array | Headers (See fetch.DefaultHeaders) | | payload | Object∣Map | Data to pass down. (Note: payload is appended to the URL for Get requests) | | onCompleted | function | Callback on successful fetch | | onError | function | Callback on failed fetch | | transform | Transform∣function∣boolean | Overrides default formatting of payload. Setting to FALSE will prevent any transformation to payload. (Note that the Transform object contains default transformation operations). | | onError | ResponseTypes | Function used to handle the response body. |

dependencies

| PARAM | TYPE | DESCRIPTION | |----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| | dependencies | array | The array of dependencies to pass to React's useEffect's second parameter. Used to determine when this hook is fired. Default: []. |

Result

| PROPERTY | TYPE | DESCRIPTION | |-------------|---------------------------|---------------------------------------------| | data | object∣undefined | Data returned from query | | loading | Boolean | Whether or not query is ongoing | | hasErrors | Boolean | Whether or not errors have occurred | | error | object∣undefined | Error returned. Defaults to undefined | | payload | Object | Data passed down | | called | Boolean | Whether or not the function has been called |

Vanilla JS

post

Example

function App() {
	const [data, setData] = useState();
	useEffect(() => {
		post('https://gfgfsdagfsdagfsda.free.beeceptor.com/test', {
			payload: {language: 'english'},
		}).then(data => setData(data));
	}, []);

	if(typeof data === 'undefined') return <p>Loading ...</p>;
	return <h1>Hello {data.greeting.message}!</h1>;
}

Function Signature

post(
    url: Object,
    fetchOptions: fetchOptions = {}
): Promise

Params

url

| PARAM | TYPE | DESCRIPTION | |----------|---------------|-------------------------------| | url | string | The URL to supply to fetch()|

fetchOptions

| OPTION | TYPE | DESCRIPTION | |---------------|---------------------|------------------------------------------------------------------------------| | headers | array | Headers (See fetch.DefaultHeaders) | | payload | Object∣Map | Data to pass down. (Note: payload is appended to the URL for Get requests) | | onCompleted | function | Callback on successful fetch | | onError | function | Callback on failed fetch | | transform | Transform∣function∣boolean | Overrides default formatting of payload. Setting to FALSE will prevent any transformation to payload. (Note that the Transform object contains default transformation operations). | | onError | ResponseTypes | Function used to handle the response body. |

get

Example

function Hello() {
	const [data, setData] = useState();
	useEffect(() => {
		get('__URL__', {
			payload: {language: 'english'},
		}).then(data => setData(data));
	}, []);

	if(typeof data === 'undefined') return <p>Loading ...</p>;
	return <h1>Hello {data.greeting.message}!</h1>;
}

Function Signature

get(
    url: Object,
    fetchOptions: fetchOptions = {} 
): Promise

Params

url

| PARAM | TYPE | DESCRIPTION | |----------|---------------|-------------------------------| | url | string | The URL to supply to fetch()|

fetchOptions

| OPTION | TYPE | DESCRIPTION | |---------------|---------------------|------------------------------------------------------------------------------| | headers | array | Headers (See fetch.DefaultHeaders) | | payload | Object∣Map | Data to pass down. (Note: payload is appended to the URL for Get requests) | | onCompleted | function | Callback on successful fetch | | onError | function | Callback on failed fetch | | transform | Transform∣function∣boolean | Overrides default formatting of payload. Setting to FALSE will prevent any transformation to payload. (Note that the Transform object contains default transformation operations). | | onError | ResponseTypes | Function used to handle the response body. |