gotch v1.2.3
Features
- Promise based
- Configurable and chainable API
- Automatically transforms for JSON data
- Supports request body transforms
- Monitor download and upload progress
- Cancel requests
Installation
Using npm:
$ npm install gotch --save
Using yarn:
$ yarn add gotch
Using CDN:
<script src="https://unpkg.com/gotch/dist/gotch.min.js"></script>
Basic Usage
Import
import gotch from 'gotch';
Send a GET
request
// handle with promise chaining
gotch
.get('/users/1')
.then((res) => {
console.log(res);
})
.catch((e) => {
console.log(e);
});
// handle with async/await syntax
// NOTE: you should wrap the following code in an async function
try {
const res = await gotch.get('/users/1');
console.log(res);
} catch (e) {
console.log(e);
}
Send a POST
request
// handle with promise chaining
gotch
.post('/users', {
firstName: 'Jermey',
lastName: 'Lin',
})
.then((res) => {
console.log(res);
})
.catch((e) => {
console.log(e);
});
// handle with async/await syntax
// NOTE: you should wrap the following code in an async function
try {
const res = await gotch
.post('/users', {
firstName: 'Jermey',
lastName: 'Lin',
});
console.log(res);
} catch (e) {
console.log(e);
}
Create an instance
const exampleAPI = gotch.create({
baseURL: 'https://example.com/api/v1',
timeout: 2000,
});
// exampleAPI
// .get(...)
// .then(...)
// .catch(...);
Instance configuration
Available configuration for creating an instance by using .create([config])
{
// `baseURL` will be prepended to the request url unless it is absolute`
baseURL: '',
// `requestType` determines how Gotch transform your request parameters and
// set a coresponding Content-Type in request headers automatically
// Acceptable values are: 'text', 'json', 'form'
// - 'text': 'text/plain;charset=UTF-8'
// - 'json': 'application/json;charset=UTF-8'
// - 'form': automatically generated by browser
requestType: 'json',
// `responseType` determines how Gotch transform your response data
// Acceptable values are: 'text', 'json', 'blob'
// - 'text': response.data will be a string
// - 'json': response.data will be a object, fallback to 'text' if not parsable
// - 'blob': response.data will be a blob
responseType: 'json',
// `tag` will be used to grouping requests, request(s) with a tag can
// be canceled by using .cancel(tag)
tag: '',
// `timeout` is a number of milliseconds, if the request takes longer
// than this number, it will be aborted
timeout: 0,
// `credentials` determines whether or not cross-site Access-Control
// requests should be made using credentials
// Acceptable values are: 'include', 'same-origin', 'omit'
credentials: 'same-origin',
// `authorization` is a string or a function that returns a string which
// to authenticate a user agent with a server
authorization: undefined,
// `onUploadProgress` is a function to handle upload progress event
onUploadProgress: undefined,
// `onDownloadProgress` is a function to handle download progress event
onDownloadProgress: undefined,
}
Request options
Available options for sending a request by using .request(url[, options])
{
// `method` is the request method
method: 'GET',
// `headers` are custom headers to be sent with the request
headers: {},
// `body` is the data to be sent as the request body
body: undefined,
}
API
NOTE:
.with*
methods are chainable and can be used to overwrite the instance configuration, but the overwritten configuration will just works once for the next request, so if you want to reuse the same configuration multiple times, please create an instance by using.create([config])
.create(config)
Create a new instance of Gotch
gotch.create({
baseURL: 'https://example.com/api/v1',
});
// returns a Gotch instance
.withBaseURL(baseURL)
Overwrite baseURL
for next request
gotch.withBaseURL('https://example.com/api/v1');
// returns a Gotch instance
.withRequestType(requestType)
Overwrite requestType
for next request
gotch.withRequestType('json');
// returns a Gotch instance
.withResponseType(responseType)
Overwrite responseType
for next request
gotch.withResponseType('json');
// returns a Gotch instance
.withTag(tag)
Overwrite tag
for next request
gotch.withTag('get-user-req');
// returns a Gotch instance
.withTimeout(timeout)
Overwrite timeout
for next request
gotch.withTimeout(2000);
// returns a Gotch instance
.withCredentials(credentials)
Overwrite credentials
for next request
gotch.withCredentials('include');
// returns a Gotch instance
.withAuthorization(authorization)
Overwrite authorization
for next request
gotch.withAuthorization('Bearer ***********');
// returns a Gotch instance
// or
gotch.withAuthorization(() => {
const token = window.localStorage.getItem('token');
return `Bearer ${token}`;
});
// returns a Gotch instance
.withOnUploadProgress(handleEvent)
Overwrite onUploadProgress
for next request
gotch.withOnUploadProgress((e) => {
console.log(e.loaded / e.total);
});
// returns a Gotch instance
.withOnDownloadProgress(handleEvent)
Overwrite onDownloadProgress
for next request
gotch.withOnDownloadProgress((e) => {
console.log(e.loaded / e.total);
});
// returns a Gotch instance
.request(url, options)
Send a customized request
gotch.request('/users', {
method: 'POST',
headers: {
Authorization: 'Bearer xxxxx.yyyyy.zzzzz',
'Content-Type': 'application/json;charset=UTF-8',
},
body: '{"firstName":"Jeremy","lastName":"Lin"}'
});
// returns a promise
.get(url)
Send a GET
request
gotch.get('/users/1');
// returns a promise
.post(url, params)
Send a POST
request
gotch.post('/users', {
firstName: 'Jeremy',
lastName: 'Lin',
});
// returns a promise
.put(url, params)
Send a PUT
request
gotch.put('/users/1', {
firstName: 'Jeremy',
lastName: 'Lin',
});
// returns a promise
.patch(url, params)
Send a PATCH
request
gotch.patch('/users/1', {
age: 99,
});
// returns a promise
.delete(url)
Send a DELETE
request
gotch.delete('/users/1');
// returns a promise
.cancel(tag)
Cancel request(s) grouping by the same tag
gotch.cancel('get-user-req');
// all the requests have the `get-user-req` tag will be aborted
License
MIT