Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/D-Marc1/far-fetch
Modern Fetch API wrapper for simplicity.
https://github.com/D-Marc1/far-fetch
Last synced: about 2 months ago
JSON representation
Modern Fetch API wrapper for simplicity.
- Host: GitHub
- URL: https://github.com/D-Marc1/far-fetch
- Owner: D-Marc1
- License: mit
- Created: 2020-05-12T02:50:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-11-28T03:04:55.000Z (almost 2 years ago)
- Last Synced: 2024-07-03T16:19:25.474Z (3 months ago)
- Language: JavaScript
- Homepage: https://farfetch.js.org
- Size: 94.7 KB
- Stars: 58
- Watchers: 6
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```js
import FarFetch from '@websitebeaver/far-fetch';
// If you need to manually handle errors
import FarFetch, { FarFetchError } from '@websitebeaver/far-fetch';
```
## Instantiating Class
```js
const ff = new FarFetch();
```
This is how you'd create a class in its simplest form in `FarFetch`. You can
check out [all the options you can use here](#new-farfetchoptions).
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:
1. Ability to call syntactic sugar methods like `ff.get()`, `ff.post()`,
`ff.put`, etc., rather than `fetch(url, { method: 'GET' })`. `FarFetch`
allows both ways.
2. Ability to ["automatically" throw and handle errors](#error-handling) for
every call in a unified manner with a global error handler.
3. Ability to use default [request init options](#passing-in-fetch-api-init-options)
on every call.
4. Ability to do actions before every request
with [`beforeSend()` and `afterSend(response)` hooks](#beforeafter-send-hook).
5. Ability to [pass data to each call in a consistent manner](#passing-in-data-to-request).
6. Ability to [upload files](#uploading-files) in a consistent manner.
- [FarFetch Class](#farfetch-class)
- [Install](#install)
- [Instantiating Class](#instantiating-class)
- [Why Use FarFetch?](#why-use-farfetch)
- [Passing in Data to Request](#passing-in-data-to-request)
- [GET Request](#get-request)
- [POST Request](#post-request)
- [application/x-www-form-urlencoded Request](#applicationx-www-form-urlencoded-request)
- [Array or Object as Value for Key for GET Request](#array-or-object-as-value-for-key-for-get-request)
- [Passing in URLParams to Request](#passing-in-urlparams-to-request)
- [Uploading Files](#uploading-files)
- [Uploading One File](#uploading-one-file)
- [Uploading Multiple Files](#uploading-multiple-files)
- [Uploading Multiple Files with Distinct File Names](#uploading-multiple-files-with-distinct-file-names)
- [Passing in Fetch API init options](#passing-in-fetch-api-init-options)
- [Set Options for Single Request](#set-options-for-single-request)
- [Set Global Options for Every Request](#set-global-options-for-every-request)
- [Set Dynamic Options for Every Request](#set-dynamic-options-for-every-request)
- [Getting Response](#getting-response)
- [Retrieving Response Data](#retrieving-response-data)
- [Set Base URL](#set-base-url)
- [Before/After Send Hook](#beforeafter-send-hook)
- [Turn off Before/After Send Hook on Single Request](#turn-off-beforeafter-send-hook-on-single-request)
- [Error Handling](#error-handling)
- [Modifying the Default Error Message Template](#modifying-the-default-error-message-template)
- [Overriding Default Error Message for Single Request](#overriding-default-error-message-for-single-request)
- [Catching Exceptions Manually](#catching-exceptions-manually)
- [Empty Try/Catch](#empty-trycatch)
- [API](#api)
- [FarFetch](#farfetch)
- [new FarFetch([options])](#new-farfetchoptions)
- [farFetch.fetch(url, options) ⇒ Promise.<ResponsePlus>](#farfetchfetchurl-options--promiseresponseplus)
- [farFetch.get(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchgeturl-options--promiseresponseplus)
- [farFetch.post(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchposturl-options--promiseresponseplus)
- [farFetch.put(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchputurl-options--promiseresponseplus)
- [farFetch.patch(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchpatchurl-options--promiseresponseplus)
- [farFetch.delete(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchdeleteurl-options--promiseresponseplus)
- [farFetch.head(url, [...options]) ⇒ Promise.<ResponsePlus>](#farfetchheadurl-options--promiseresponseplus)
- [FarFetchError ⇐ Error](#farfetcherror--error)
- [new FarFetchError(message)](#new-farfetcherrormessage)
- [RequestException : Object](#requestexception--object)
- [ResponsePlus : Object](#responseplus--object)
- [RequestOptionsNoInit : Object](#requestoptionsnoinit--object)
- [RequestOptions : Object](#requestoptions--object)
- [dynamicOptionsCallback ⇒ RequestInit](#dynamicoptionscallback--requestinit)
- [beforeSendCallback : function](#beforesendcallback--function)
## 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 be 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.
### GET Request
**Fetch API**
```js
async getPerson() {
const data = { name: 'Bobby Big Boy', gender: 'Male', age: 5 };
const queryString = `?${new URLSearchParams(data)}`;
const response = await fetch(`https://example.com/people${queryString}`, {
method: 'GET',
});
if(!response.ok) throw new Error('Server error.');
return response.json();
}
```
**FarFetch**
```js
async getPerson() {
const { responseJSON } = await ff.get('https://example.com/people', {
data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 },
});
return responseJSON;
}
```
### POST Request
**Fetch API**
```js
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.ok) throw new Error('Server error.');
return response.json();
}
```
**FarFetch**
```js
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 Request
**Fetch API**
```js
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/x-www-form-urlencoded' },
body: new URLSearchParams(data),
});
if(!response.ok) throw new Error('Server error.');
return response.json();
}
```
**FarFetch**
```js
async addPerson() {
const { responseJSON } = await ff.post('https://example.com/people', {
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 },
});
return responseJSON;
}
```
### Array or Object as Value for Key for GET Request
**Fetch API**
```js
async getPerson() {
const queryString = `?${new URLSearchParams({
name: 'Bobby Big Boy',
hobbies: JSON.stringify(['collecting stamps', 'sports']),
location: JSON.stringify({ city: 'Miami', state: 'Florida' }),
})}`;
const response = await fetch(`https://example.com/people${queryString}`, {
method: 'GET',
});
if(!response.ok) throw new Error('Server error.');
return response.json();
}
```
This can be a bit cumbersome to have to have to `JSON.stringify()` each value
that's an array or object. `FarFetch` automatically takes care of this.
**FarFetch**
```js
async getPerson() {
const { responseJSON } = await ff.get(`https://example.com/people`, {
data: {
name: 'Bobby Big Boy',
hobbies: ['collecting stamps', 'sports'],
location: { city: 'Miami', state: 'Florida' },
},
});
return responseJSON;
}
```
Notice how each request is completely predictable in `FarFetch` and doesn't
require you to throw an exception if it's not a status code in the `200-299`
range (`response.ok`). Sure, using the native javascript `Fetch API` isn't
horrible anymore in regular Javascript, thanks to features like
`URLSearchParams`, 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.
*Note: The content type header for a `POST`, `PUT` and `PATCH` request will
always be `application/json`, unless `application/x-www-form-urlencoded` is
specified or if it's a file upload*.
### Passing in URLParams to Request
This is specifically for converting to a `URL query string`, which differs from
`data`, which *detects* the default type (`body` or `query string`).
It's recommended to strictly use the `URLParams` option in cases where `POST`,
`POST` and `PATCH` are used, as the default behavior for passing in `data` in
this case will result in passing in the object to `body`. You can still pass in
`URLParams` on `GET`, `HEAD` and `DELETE`, but you can't combine it with `data`.
This is for consistency purposes, as it would be confusing as to why you'd be
using `data` and `URLParams` in the latter ones, as they would achieve the same
result in this case. In fact, `FarFetch` even throws an exception in this
senario.
```js
async addPerson() {
const { responseJSON } = await ff.post('https://example.com/people', {
URLParams: { weight: 75 },
data: { name: 'Bobby Big Boy', gender: 'Male', age: 5 },
});
return responseJSON;
}
```
Converted to `Fetch API`, the following will result in:
```js
const response = await fetch(`https://example.com/people?weight=75`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Bobby Big Boy', gender: 'Male', age: 5 }),
});
```
## Uploading Files
### Uploading One File
**Fetch API**
```js
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.ok) throw new Error('Server error.');
}
```
**FarFetch**
```js
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**
```js
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.ok) throw new Error('Server error.');
}
```
**FarFetch**
```js
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**
```js
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.ok) throw new Error('Server error.');
}
```
**FarFetch**
```js
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 and upload his following files: photos, videos and
documents*.
## Passing in Fetch API init options
`FarFetch` accepts all [Fetch API init
options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters).
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
```js
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`.
```js
const ff = new FarFetch({
headers: { 'Content-Type': 'application/json' },
cache: 'reload',
});
```
### Set Dynamic Options for Every Request
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 allows you to return options you want to use on specific
conditions on the global `dynamicOptions()` function. These options will then
get deep merged, with the `dynamicOptions()` return taking precedence.
Obviously passing options into a specific request will take the highest
precedence of them all, however.
```js
const ff = new FarFetch({
headers: { 'Content-Type': 'application/json' },
cache: 'reload',
dynamicOptions() {
// Use authorization header if token set in localStorage
if (localStorage.getItem('token')) {
return {
headers: {
Authorization: `Bearer ${localStorage.getItem('token')}`,
},
};
}
},
});
```
So if you're logged in, your request would have the following options.
```js
{
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${localStorage.getItem('token')}`,
},
cache: reload,
}
```
Notice how the `Content-Type` is set to `text/plain`, rather than
`application/json`. As stated before, this is because the return on
`beforeSend()` takes precedence on the deep merge.
## Getting Response
### Retrieving Response Data
`FarFetch` returns a [Response
object](https://developer.mozilla.org/en-US/docs/Web/API/Response), so you can
use [the `Body`
methods](https:/developer.mozilla.org/en-US/docs/Web/API/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.
```js
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.
```js
const { responseJSON } = await ff.get('https://example.com/people');
return responseJSON;
```
```js
const { responseText } = await ff.get('https://example.com/people');
return responseText;
```
## Set Base URL
Most applications will likely use the same domain for most or even all requests.
`FarFetch` has a `baseURL` option you can use when you instantiate the class.
```js
const ff = new FarFetch({
baseURL: 'https://example.com',
});
```
Now request like the following will work.
```js
await ff.get('/people');
```
But what if you want to use a different base URL for just a few requests in your
application? `FarFetch` automatically detects if an absolute path is used, and
will override the `baseURL`.
```js
await ff.get('https://notexample.com/posts');
```
## 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.
```js
const ff = new FarFetch({
beforeSend({
url,
fetchAPIOptions,
data,
URLParams,
files,
errorMsg,
errorMsgNoun,
globalBeforeSend,
globalAfterSend,
defaultOptionsUsed,
}) {
console.log('do this before every request');
},
afterSend(response) {
console.log('do this after 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.
```js
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**
```js
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.ok) 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**
```js
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:
```js
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.
```js
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.
```js
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.
```js
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.
```js
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';
} 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
- FarFetch
CRUD class to simplify fetch API and uploading.
- FarFetchError
FarFetch Error class.
## Typedefs
-
RequestException :Object -
The Request exception object.
-
ResponsePlus :Object -
Request object plus responseJSON and responseText properties if correct header type.
-
RequestOptionsNoInit :Object -
The request object options without Fetch API options.
-
RequestOptions :Object -
The request object options.
-
dynamicOptionsCallback ⇒RequestInit -
Callback for global dynamic options. Allows a dynamic option to be set, like a token stored in
localStorage. -
beforeSendCallback :function -
Callback for global before send hook.
-
afterSendCallback :function -
Callback for global after send hook.
-
errorHandlerCallback :function -
Callback for global error handler.
-
errorMsgTemplateCallback ⇒string -
Callback for overriding default error message template.
## FarFetch
CRUD class to simplify fetch API and uploading.
**Kind**: global class
* [FarFetch](#FarFetch)
* [new FarFetch([options])](#new_FarFetch_new)
* [.fetch(url, options)](#FarFetch+fetch) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.get(url, [...options])](#FarFetch+get) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.post(url, [...options])](#FarFetch+post) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.put(url, [...options])](#FarFetch+put) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.patch(url, [...options])](#FarFetch+patch) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.delete(url, [...options])](#FarFetch+delete) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
* [.head(url, [...options])](#FarFetch+head) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
### new FarFetch([options])
Create FarFetch object.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [options] | Object | {} | Set options. |
| [options.baseURL] | string | '' | Base URL for each request. |
| [options.dynamicOptions] | [dynamicOptionsCallback](#dynamicOptionsCallback) | | Function that allows a dynamic option to be set, like a token stored in localStorage. |
| [options.beforeSend] | [beforeSendCallback](#beforeSendCallback) | | Function to do something before each fetch request. Can return object with RequestOptions to add or override options. |
| [options.afterSend] | [afterSendCallback](#afterSendCallback) | | Function to do something after each fetch request. |
| [options.errorHandler] | [errorHandlerCallback](#errorHandlerCallback) | | Global error handler. |
| [options.errorMsgTemplate] | [errorMsgTemplateCallback](#errorMsgTemplateCallback) | | Function to modify the default error message template for `errorMsgNoun`. |
| [...options.defaultOptions] | RequestInit | {} | [Init options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) from Fetch API. |
**Example**
```js
const ff = new FarFetch({
baseURL: 'https://my-url.com',
dynamicOptions() {
// Use authorization header if token set in localStorage
if (localStorage.getItem('token')) {
return {
headers: {
Authorization: `Bearer ${localStorage.getItem('token')}`,
},
}
}
},
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.fetch(url, options) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
Request function called on every CRUD function.
**Kind**: instance method of [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| options | Object | |
| options.method | 'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' | The CRUD method. |
| [...options.RequestOptions] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.fetch('https://my-website.com/users', {
method: 'GET',
data: { id: 23 },
errorMsgNoun: 'users',
});
```
### farFetch.get(url, [...options]) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
GET fetch request.
**Kind**: instance method of [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.get('https://my-website.com/users', {
data: { id: 23 },
errorMsgNoun: 'users',
});
```
### farFetch.post(url, [...options]) ⇒ [Promise.<ResponsePlus>](#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 [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.post('https://my-website.com/user/23', {
data: { gender: 'male', age: 39 },
errorMsgNoun: 'user',
});
```
### farFetch.put(url, [...options]) ⇒ [Promise.<ResponsePlus>](#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 [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.put('https://my-website.com/user/47', {
data: { gender: 'female', age: 22 },
errorMsgNoun: 'user',
});
```
### farFetch.patch(url, [...options]) ⇒ [Promise.<ResponsePlus>](#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 [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.patch('https://my-website.com/user/91', {
data: { age: 18 },
errorMsgNoun: 'user',
});
```
### farFetch.delete(url, [...options]) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
DELETE fetch request.
**Kind**: instance method of [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
await ff.delete('https://my-website.com/user/107', {
errorMsgNoun: 'user',
});
```
### farFetch.head(url, [...options]) ⇒ [Promise.<ResponsePlus>](#ResponsePlus)
HEAD fetch request.
**Kind**: instance method of [FarFetch](#FarFetch)
**Throws**:
- [RequestException](#RequestException)
| Param | Type | Description |
| --- | --- | --- |
| url | string | The URL. |
| [...options] | [RequestOptions](#RequestOptions) | |
**Example**
```js
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 |
| --- | --- | --- |
| message | string \| 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 |
| --- | --- | --- |
| error | FarFetchError | FarFetch error. |
| response | [ResponsePlus](#ResponsePlus) | 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 | Default | Description |
| --- | --- | --- | --- |
| response | Response | | Fetch API response. [Response object](https://developer.mozilla.org/en-US/docs/Web/API/Response). |
| [response.responseJSON] | Object | | FarFetch added property that transforms the body to JSON for syntactic sugar if the same response header type. |
| [response.responseText] | string | null | FarFetch added property that transforms the body to text for syntactic sugar if the same response header type. |
## RequestOptionsNoInit : Object
The request object options without Fetch API options.
**Kind**: global typedef
**Properties**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [data] | Object.<string, (string\|number\|null\|boolean\|Array\|Object)> | {} | Data sent to server on request. Will use `body` for: POST, PUT, PATCH and `URL query params string` for: GET, HEAD, DELETE. |
| [URLParams] | Object.<string, (string\|number\|null\|boolean\|Array\|Object)> | {} | URL query params string. Don't use both `data` and `URLParams` together with GET, HEAD or DELETE, as they're redundant in these cases. Pick one or the other, as they will both have the same effect. |
| [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 and the return value of `dynamicOptions()`? |
## RequestOptions : Object
The request object options.
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| [...requestOptionsNoInit] | [RequestOptionsNoInit](#RequestOptionsNoInit) | |
| [...rest] | RequestInit | [Init options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) from Fetch API. |
## dynamicOptionsCallback ⇒ RequestInit
Callback for global dynamic options. Allows a dynamic option to be set, like a token stored in
localStorage.
**Kind**: global typedef
**Returns**: RequestInit - [Init options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters)
from Fetch API.
## beforeSendCallback : function
Callback for global before send hook.
**Kind**: global typedef
| Param | Type | Description |
| --- | --- | --- |
| [options] | Object | |
| [options.url] | string | The URL. |
| [options.fetchAPIOptions] | RequestInit | [Init options](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters) from Fetch API. |
| [...options.requestOptions] | [RequestOptionsNoInit](#RequestOptionsNoInit) | The request object options without Fetch API options. |
## afterSendCallback : function
Callback for global after send hook.
**Kind**: global typedef
| Param | Type | Description |
| --- | --- | --- |
| response | [ResponsePlus](#ResponsePlus) | Request object plus responseJSON and responseText properties if correct header type. |
## errorHandlerCallback : function
Callback for global error handler.
**Kind**: global typedef
| Param | Type | Description |
| --- | --- | --- |
| [options] | Object | |
| [options.error] | FarFetchError \| Error | The FarFetchError option. Will throw regular error if needed. |
| [options.response] | [ResponsePlus](#ResponsePlus) | Request object plus responseJSON and responseText properties if correct header type. |
| [options.userMessage] | string | The message given to the user. |
## errorMsgTemplateCallback ⇒ string
Callback for overriding default error message template.
**Kind**: global typedef
**Returns**: string - Full error message string.
| Param | Type | Description |
| --- | --- | --- |
| [options] | Object | |
| [options.method] | 'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' | The CRUD method. |
| [options.errorMsgNoun] | string | The error message noun. |