Skip to content

Latest commit

 

History

History
335 lines (278 loc) · 7.25 KB

README.md

File metadata and controls

335 lines (278 loc) · 7.25 KB
Raw

Gotch

A simple, elegant and lightweight HTTP client for browser

npm version npm bundle size install size dev dependencies github license

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