Fetch API wrapper to take the pain out of making requests
source link: https://github.com/WebsiteBeaver/far-fetch
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
FarFetch Class
Modern Fetch API wrapper for simplicity.
Install
npm i @websitebeaver/far-fetch
Then include it in the files you want to use it in like so:
import FarFetch from '@websitebeaver/far-fetch'; // If you need to manually handle errors import FarFetch, { FarFetchError } from '@websitebeaver/far-fetch';
Instantiating Class
const ff = new FarFetch();
This is how you'd create a class in its simplest form in FarFetch
. You can
check outall the options you can use here.
It is recommended to then import the initialized class on every page used.
Why Use FarFetch?
While JavaScript's native Fetch API
was an amazing feature added, it
introduced a myriad of inconsistencies, which cause you to have to copy and
paste StackOverflow questions for simple boilerplate code often times. This is
especially the case with uploading files and I find it hard to believe anyone
just straight memorizes how to do it. There's so many things to think about. It
would have been so much better in a unified experience.
The core philosophy of FarFetch
to is keep things as similar as possible to
native JavaScript fetch, and merely improve upon it. This way, you're not really
learning a completely new API. Instead, the aim of this class is almost to pitch
which features I think are missing in Fetch API
. The aim of this class isn't
to recreate the wheel, but rather, to improve upon Fetch API
, with a super
thin wrapper. The main advantages over vanilla Fetch
are as follows:
-
Ability to call syntactic sugar methods like
ff.get()
,ff.post()
,ff.put
, etc., rather thanfetch(url, { method: 'GET' })
.FarFetch
allows both ways. - Ability to"automatically" throw and handle errorsfor every call in a unified manner with a global error handler.
-
Ability to do actions before every request
with
beforeSend()
andafterSend(response)
hooks . - Ability topass data to each call in a consistent manner.
-
- Passing in Data to Request
-
- Uploading Multiple Files
- Uploading Multiple Files with Distinct File Names
-
Passing in Fetch API init options
- Set Options for Single Request
- Set Global Options for Every Request
-
- Retrieving Response Data
-
Before/After Send Hook
- Turn off Before/After Send Hook on Single Request
-
- Modifying the Default Error Message Template
- Overriding Default Error Message for Single Request
- Catching Exceptions Manually
-
-
- new FarFetch([options])
- farFetch.setDefaultOptions([...options])
-
farFetch.fetch(url, options) ⇒
Promise.<ResponsePlus>
-
farFetch.get(url, [...options]) ⇒
Promise.<ResponsePlus>
-
farFetch.post(url, [...options]) ⇒
Promise.<ResponsePlus>
-
farFetch.put(url, [...options]) ⇒
Promise.<ResponsePlus>
-
farFetch.patch(url, [...options]) ⇒
Promise.<ResponsePlus>
-
farFetch.delete(url, [...options]) ⇒
Promise.<ResponsePlus>
-
farFetch.head(url, [...options]) ⇒
Promise.<ResponsePlus>
-
FarFetchError ⇐
Error
- new FarFetchError(message)
-
RequestException :
object
-
ResponsePlus :
object
-
errorHandlerCallback :
function
-
afterSendCallback :
function
-
errorMsgTemplateCallback ⇒
string
-
RequestOptions :
object
-
Passing in Data to Request
Passing in data in Fetch API
is exceedingly inconsistent. In this regard, it
really took a step backwards from how jQuery implemented passing in data, in my
opinion, at least from a usability standpoint. Of course Fetch API
's body
options offers more versatility, which is why FarFetch
supports using body
.
However, it really shouldn't necessary in the majority of use cases. Adding data
to a GET
and POST
request is done in two separate ways in Fetch API
. GET
requests must use appended URL query parameters, while POST
requests generally
use a stringified object used as the body
property.
Fetch API
// GET async getPerson() { const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const queryString = `?${new URLSearchParams(Object.entries(data))}`; const response = await fetch(`https://example.com/people${queryString}`, { method: 'GET', }); if(response.status !== 200) throw new Error('Server error.'); return response.json(); } // POST async addPerson() { const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const response = await fetch(`https://example.com/people`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), }); if(response.status !== 200) throw new Error('Server error.'); return response.json(); } // application/x-www-form-urlencoded async addPerson() { const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const response = await fetch(`https://example.com/people`, { method: 'POST', headers: { 'application/x-www-form-urlencoded' }, body: new URLSearchParams(Object.entries(data)), }); if(response.status !== 200) throw new Error('Server error.'); return response.json(); }
FarFetch
// GET async getPerson() { const { responseJSON } = await ff.get('https://example.com/people', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, }); return responseJSON; } // POST async addPerson() { const { responseJSON } = await ff.post('https://example.com/people', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, }); return responseJSON; } // application/x-www-form-urlencoded async addPerson() { const { responseJSON } = await ff.post('https://example.com/people', { headers: { 'application/x-www-form-urlencoded' }, data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, }); return responseJSON; }
Notice how it's completely predictable and doesn't require you to throw an
exception if it's not a 200
status code. Notice how it's not much different
than any other request with FarFetch. Sure, it's not horrible anymore in regular
Javascript, thanks to features like URLSearchParams
and Object.entries
, but
it's so much easier to not have to think much when you program. FarFetch
's
consistent API makes it a breeze to make any sort of request.
Uploading Files
Uploading One File
Fetch API
async uploadFile() { const [file] = document.querySelector('#my-file').files; const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const formData = new FormData(); formData.append('file', file); Object.keys(data).forEach((key) => { formData.append(key, data[key]); // Add server data to formData }); const response = await fetch('https://example.com/people', { method: 'POST', body: formData, }); if(response.status !== 200) throw new Error('Server error.'); }
FarFetch
async uploadFile() { const [file] = document.querySelector('#my-file').files; await ff.post('https://example.com/people', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, files: file, }); }
Uploading Multiple Files
Fetch API
async uploadFiles() { const files = document.querySelector('#my-files').files; const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const formData = new FormData(); Object.keys(data).forEach((key) => { formData.append(key, data[key]); // Add server data to formData }); files.forEach((file) => { formData.append('files[]', file); // Add files array to formData }); await fetch('https://example.com/people', { method: 'POST', body: formData, }); if(response.status !== 200) throw new Error('Server error.'); }
FarFetch
async uploadFiles() { const files = document.querySelector('#my-files').files; await ff.post('https://example.com/people', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, files, }); }
Uploading Multiple Files with Distinct File Names
Fetch API
async uploadFiles() { const photos = document.querySelector('#photos').files; const videos = document.querySelector('#videos').files; const documents = document.querySelector('#documents').files; const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; const formData = new FormData(); Object.keys(data).forEach((key) => { formData.append(key, data[key]); // Add server data to formData }); photos.forEach((photo) => { formData.append('photos[]', photo); // Add files array to formData }); videos.forEach((video) => { formData.append('videos[]', video); // Add files array to formData }); documents.forEach((document) => { formData.append('documents[]', document); // Add files array to formData }); await fetch('https://example.com/people', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: formData, }); if(response.status !== 200) throw new Error('Server error.'); }
FarFetch
async uploadFiles() { const photos = document.querySelector('#photos').files; const videos = document.querySelector('#videos').files; const documents = document.querySelector('#documents').files; await ff.post('https://example.com/people', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 22 }, files: { photos, videos, documents }, }); }
Look at how much more comprehensible the code becomes with FarFetch
. This is
practically even readable by a non-programmer, as this reads as: Let's add a 22
year old man named Bobby, along with uploading his following files: photos,
videos and documents
.
Passing in Fetch API init options
FarFetch
accepts all Fetch API init
options
.
It's even possible to pass in the native fetch body
, though its use is
discouraged in most cases, in favor of, FarFetch
's data
parameter.
Set Options for Single Request
await ff.get('https://example.com', { headers: { 'Content-Type': 'application/json' }, cache: 'reload', })
Set Global Options for Every Request
This is really handy for when you know for a fact you will be using the same
options on either every request or nearly all. You can accomplish this by
declaring these options when you instantiate FarFetch
.
const ff = new FarFetch({ headers: { 'Content-Type': 'application/json' }, cache: 'reload', });
Sometimes you might not want to set a particular option when FarFetch is
created. Let's say you're using a login system. You don't want to have the JWT
be evaluated when you instantiate the class, since it won't work properly if a
user accesses the page logged out. The header would never reevaluate. This is
why FarFetch
has a handy setDefaultOptions()
function, which you can combine
with the global beforeSend()
option.
const ff = new FarFetch({ beforeSend() { // Set header to token if token set in localStorage if (localStorage.getItem('token')) { this.setDefaultOptions({ headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${localStorage.getItem('token')}`, }, }); } }, });
It should be noted that nested options, like headers
, will currently override
what was set on instantiation
. For instance, if headers were set
initialization, like in the first example of this section, it would have the
following options:
{ headers: { Authorization: `Bearer ${localStorage.getItem('token')}`, }, cache: reload, }
As stated before, only nested
options get overridden, as cache: reload
was
kept. The reason is because behind the scenes, setDefaultOptions()
simply does
the following: this.defaultOptions = { ...this.defaultOptions, ...options };
.
The same applies for when you override on individual requests as well.
Getting Response
Retrieving Response Data
FarFetch
returns a Response
object
, so you can
use
the Body
methods
: arrayBuffer()
, blob()
, formData()
, json()
and text()
. This is exactly
how you'd be doing it in native Fetch
as well.
FarFetch
supports the vanilla Fetch
way of retrieving data, by awaiting for
the the Response
Body
and transforming it to your type.
const response = await ff.get('https://example.com/people'); const responseJSON = await response.json(); return responseJSON;
You can also use FarFetch
's handy responseJSON
and responseText
properties for your convenience, instead of having to await for either response.json()
or response.text()
, if the response header type is either application/json
or text/plain
, respectively. These are properties that were simply added to the Response
object. What's also nice about this is that it ensures that getting
the JSON won't result in an error, due to a mismatch in header, as FarFetch
checks for this already, internally.
const { responseJSON } = await ff.get('https://example.com/people'); return responseJSON;
const { responseText } = await ff.get('https://example.com/people'); return responseText;
Before/After Send Hook
You can use the built-in beforeSend()
hook to do something before every
request and the afterSend(response)
one to do something after every request.
const ff = new FarFetch({ beforeSend() { console.log('do this before every request'); }, afterSend(response) { console.log('do this before every request'); }, });
Turn off Before/After Send Hook on Single Request
You might want to use the beforeSend()
or afterSend(response)
hook on nearly
all requests, but turn it off certain ones.
await ff.get('http://example.com/', { globalBeforeSend: false, globalAfterSend: false, });
Error Handling
Another annoyance of Fetch API
is that it doesn't automatically throw an error
on a failed request, and forces you to throw your own.
Fetch API
const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 }; try { const response = await fetch('https://example.com/people', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), }); if(response.status !== 200) throw new Error('Server error.'); } catch { alert('Error adding person'); }
Thankfully you don't need to worry about this with FarFetch
. With FarFetch
,
you can just append the noun to errorMsgNoun
and it'll append to a
default template, dependent on the CRUD type.
FarFetch
try { await ff.post('https://example.com/person', { data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 }, errorMsgNoun: 'person' }); } catch {}
Your global handler would then handle it as such:
const ff = new FarFetch({ errorHandler({ error, userMessage, response }) { if(response.status === 401) { // Unauthorized router.push('/login'); // Go to login page if logged out } // Error message will be presented to the user in an alert alert(userMessage); }, });
If an error occurs, this will result in an alert with the following message:
Error adding person.
You might be wondering how this works behind the scenes.
Here's the basic template of what going into the userMessage
parameter
property.
let action = ''; if (method === 'GET' || method === 'HEAD') { action = 'fetching'; } else if (method === 'POST') { action = 'adding'; } else if (method === 'PUT' || method === 'PATCH') { action = 'updating'; } else if (method === 'DELETE') { action = 'deleting'; } const userMessage = `Error ${action} ${errorMsgNoun}`;
Modifying the Default Error Message Template
You can even override this default template with the errorMsgTemplate
property, which accepts function.
const ff = new FarFetch({ errorMsgTemplate: ({ method, errorMsgNoun }) => { let action = ''; if (method === 'GET' || method === 'HEAD') { action = 'retrieving'; } else if (method === 'POST') { action = 'posting'; } else if (method === 'PUT' || method === 'PATCH') { action = 'changing'; } else if (method === 'DELETE') { action = 'removing'; } return `Error ${action} ${errorMsgNoun}.`; }, });
In case you couldn't tell by this contrived example, I merely used synonyms of the default template. However, this allows flexibility to tailor to custom requirements.
Overriding Default Error Message for Single Request
Sometimes you might just want to change the message for a unique request. You
can accomplish this via the errorMsg
property.
await ff.get('https://example.com/users', { errorMsg: 'Oh no! We are having trouble retrieving your friends!', });
Catching Exceptions Manually
Using the global errorHandler()
, along with errorMsgNoun
or errorMsg
should work fine in most cases, but sometimes you might need to handle multiple
cases. You can easily achieve this by simply omitting both errorMsgNoun
and errorMsg
. FarFetch
will then know not to run the global error handler. You
can then can the errors in a try/catch
. Take a register account example for
instance.
async register(type) { try { const response = await ff.post(`http://127.0.0.1:3333/${type}`, { data: { email: this.email, password: this.password, }, }); const responseData = await response.json(); localStorage.setItem('token', responseData.token); this.$router.push('/'); } catch (e) { if (e instanceof FarFetchError) { let userMessage = ''; const { response, error } = e; if (response.status === 409) { // Conflict userMessage = 'Email is already in system'; ff.errorHandler({ error, response, userMessage }); } else if (response.status === 400) { // Validation failed const { field, validationMsg } = response.responseJSON; userMessage = `${field} is ${validationMsg}`; ff.errorHandler({ error, response, userMessage }); } } else { userMessage = e.message; ff.errorHandler({ error, userMessage }); } } }
Each case his handled individually. You can then add the string to the global
error handler you created on instantiation, with ff.errorHandler({ error, response, userMessage })
.
Empty Try/Catch
It is required
to use a try/catch
on every request in FarFetch
, in order
to stop execution on an error. This isn't because there's anything
unique about how this library does anything; the same recommendation would apply
to any async request in JavaScript that relies on sequential steps occurring on
success. FarFetch
specifically throws an error to stop the further execution
of code. Perhaps an example would help illustrate my point better.
Consider how a simple register account might work, like in the previous example.
You make a request and if there aren't any issues, like email already taken or
validation issues, you set the localStorage
to the JWT
and then route to the
logged in page. The problem is that if you an exception isn't thrown, there's
nothing to stop the script's execution, and it'll always
set localStorage
and try to route to the logged in route, even if the request failed.
API
Classes
CRUD class to simplify fetch API and uploading.
FarFetch Error class.
Typedefs
:object
The Request exception object.
object
Request object plus responseJSON and responseText properties if correct header type.
function
Callback for global error handler.
function
Callback for global after send hook.
string
Callback for overriding default error message template.
object
The request object options.
FarFetch
CRUD class to simplify fetch API and uploading.
Kind: global class
-
- new FarFetch([options])
- .setDefaultOptions([...options])
-
⇒
Promise.<ResponsePlus>
-
.get(url, [...options])⇒
Promise.<ResponsePlus>
-
.post(url, [...options])⇒
Promise.<ResponsePlus>
-
.put(url, [...options])⇒
Promise.<ResponsePlus>
-
.patch(url, [...options])⇒
Promise.<ResponsePlus>
-
.delete(url, [...options])⇒
Promise.<ResponsePlus>
-
.head(url, [...options])⇒
Promise.<ResponsePlus>
new FarFetch([options])
Create FarFetch object.
Param
Type
Default
Description
[options]
object
{}
Set options.
[options.beforeSend]
function
Function to do something before each fetch request.
[options.afterSend]
Function to do something after each fetch request.
[options.errorHandler]
Global error handler.
[options.errorMsgTemplate]
errorMsgTemplateCallback
Function to modify the default error message template for errorMsgNoun
.
[...options.RequestOptions]
Example
const ff = new FarFetch({ beforeSend() { console.log('Doing something before every request'); }, afterSend(response) { console.log('Doing after before every request'); }, errorHandler({ error, userMessage, response }) { if(response.status === 401) { // Unauthorized router.push('/login'); } alert(userMessage); // Error message from either errorMsg or errorMsgNoun will be used }, headers: { 'Content-Type': 'application/json' }, });
farFetch.setDefaultOptions([...options])
Set default options.
Kind: instance method of
Param Type [...options]
farFetch.fetch(url, options) ⇒
Promise.<ResponsePlus>
Request function called on every CRUD function.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
options
object
options.method
'GET'
| 'POST'
| 'PUT'
| 'PATCH'
| 'DELETE'
| 'HEAD'
The CRUD method.
[...options.RequestOptions]
Example
await ff.fetch('https://my-website.com/users', { method: 'GET', data: { id: 23 }, errorMsgNoun: 'users', });
farFetch.get(url, [...options]) ⇒
Promise.<ResponsePlus>
GET fetch request.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.get('https://my-website.com/users', { data: { id: 23 }, errorMsgNoun: 'users', });
farFetch.post(url, [...options]) ⇒
Promise.<ResponsePlus>
POST fetch request. Will default to 'Content-Type': 'application/json'
for the request header
if FarFetch
data option is provided.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.post('https://my-website.com/user/23', { data: { gender: 'male', age: 39 }, errorMsgNoun: 'user', });
farFetch.put(url, [...options]) ⇒
Promise.<ResponsePlus>
PUT fetch request. Will default to 'Content-Type': 'application/json'
for the request header
if FarFetch
data option is provided.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.put('https://my-website.com/user/47', { data: { gender: 'female', age: 22 }, errorMsgNoun: 'user', });
farFetch.patch(url, [...options]) ⇒
Promise.<ResponsePlus>
PATCH fetch request. Will default to 'Content-Type': 'application/json'
for the request
header if FarFetch
data option is provided.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.patch('https://my-website.com/user/91', { data: { age: 18 }, errorMsgNoun: 'user', });
farFetch.delete(url, [...options]) ⇒
Promise.<ResponsePlus>
DELETE fetch request.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.delete('https://my-website.com/user/107', { errorMsgNoun: 'user', });
farFetch.head(url, [...options]) ⇒
Promise.<ResponsePlus>
HEAD fetch request.
Kind: instance method of
Throws:
Param Type Description urlstring
The URL.
[...options]
Example
await ff.head('https://my-website.com/user/107');
FarFetchError ⇐ Error
FarFetch Error class.
Kind: global class
Extends :Error
new FarFetchError(message)
Param Type Description messagestring
| object.<string, *>
Will be in the message
property if a string or its own properties if object.
RequestException : object
The Request exception object.
Kind: global typedef
Properties
Name Type Description errorFarFetchError
FarFetch error.
response
Fetch API response plus added properties for syntactic sugar.
ResponsePlus : object
Request object plus responseJSON and responseText properties if correct header type.
Kind: global typedef
Properties
Name Type Description responseResponse
Fetch API response Response object
.
[response.responseJSON]
object
FarFetch added property that transforms the body to JSON for syntactic sugar if the same response header type.
[response.responseText]
string
FarFetch added property that transforms the body to text for syntactic sugar if the same response header type.
errorHandlerCallback : function
Callback for global error handler.
Kind: global typedef
Param Type Description optionsobject
options.error
FarFetchError
| Error
The FarFetchError option. Will throw regular error if needed.
options.response
Request object plus responseJSON and responseText properties if correct header type.
options.userMessage
string
The message given to the user.
afterSendCallback : function
Callback for global after send hook.
Kind: global typedef
Param Type Description response Request object plus responseJSON and responseText properties if correct header type.
errorMsgTemplateCallback ⇒ string
Callback for overriding default error message template.
Kind: global typedef
Returns: string
- Full error message string.
'GET'
| 'POST'
| 'PUT'
| 'PATCH'
| 'DELETE'
| 'HEAD'
The CRUD method.
errorMsgNoun
string
The error message noun.
RequestOptions : object
The request object options.
Kind: global typedef
Properties
Name Type Default Description [data]object.<string, (string|number|null|boolean)>
{}
Data sent to server on request.
[files]
File
| Array.<File>
| object.<string, File>
| object.<string, Array.<File>>
Files to upload to server. Will use file
as key if literal and files[]
if array; if object, will use properties as keys.
[errorMsgNoun]
string
''
Appended error message noun to global error handler.
[errorMsg]
string
''
Error message used to global error handler. Overrides errorMsgNoun
[globalBeforeSend]
boolean
true
Will this specific request use the beforeSend() hook?
[globalAfterSend]
boolean
true
Will this specific request use the afterSend() hook?
[defaultOptionsUsed]
boolean
true
Will this specific request use the default options specified on instantiation or with setDefaultOptions()
?
[...rest]
object
{}
Init options
from Fetch API.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK