fetch-please.js
HTTP-transport that supports Promises and cancelable requests (XHR). Great for React!
Moreover it's extra small (minified+gzipped less than 2.5Kb).
Justification
Handling requests with promises is really easy and convenient. But if you need to abort your request you can't do it with fetch. Promises doesn't cancelable outside of the constructor.
This library provides simple API with cancelable requests and XHR under the hood.
Install
npm install fetch-please --save
Examples
;; let api = '/api/' /* Settings here, see list of available settings below */; let SmartComponent = React;
If you want to abort individual request, you can do this with special API:
// ... same part in the previous example { // It's another API, that returns XHR object as a Promise instance let xhr promise = api; promise ; // Save necessary request thisxhr = xhr; this; } { // Abort individual requst with saved XHR object thisxhr; } // ... same part in the previous example
Requirements
ES5 compatible besides Promises. Use polyfill for ES6 Promises.
If you need ES3 compatible version use polyfills for JSON
, Object.keys
, Array.prototype.indexOf
, Array.prototype.map
, Array.prototype.reduce
, Array.prototype.filter
, Array.prototype.forEach
.
API
Constructor
FetchPlease([String path], [Object settings]);
For example:
let api = '/api/' timeout: 3000 // 3s headers: 'Content-Type': 'application/json' 'X-Custom-Header': 'custom' ;
Settings
timeout = 0
A number of milliseconds a request can take before automatically being terminated. The value of 0 means there is no timeout.
headers = {}
An object with HTTP headers for all requests.
handleResponse
Takes XHR object as a single argument and returns it if response looks like acceptable.
Example of custom response handler:
let api = '/api/' { if xhrstatus !== 200 throw 'Nooooooo!'; return xhr; };
handleJson
Takes XHR object as a single argument and returns object corresponding to the given JSON in responseText. Invokes if response header Content-Type: application/json
exists.
Methods
get() and getRequest()
Promise get(String url, [Object params,] [Object settings])
Sends GET request with optional parameters and same optional settings (see above for constructor). Returns an instance of Promise
.
Object getRequests(String url, [Object params,] [Object settings])
Sends GET request. Returns object with two properties: xhr
(instance of XMLHttpRequest
) and promise
(instance of Promise
).
Example:
let api = '/api/';api // sends GET request on /api/users?limit=10&offset=50 ;
post() and postRequest()
Promise post(String url, [Object data,] [Object settings])
Object postRequest(String url, [Object data,] [Object settings])
Sends data as a body of HTTP request. If a data object is an instance of Blob
or FormData
or String
, it will be sent without transformation. Otherwise, data will be sent as serialized JSON string.
Example:
let api = '/api/';api // sends POST request on /api/users ;
put() and putRequest()
Promise put(String url, [Object data,] [Object settings])
Object putRequest(String url, [Object data,] [Object settings])
As well as post()
and postRequest()
.
delete() and deleteRequest()
Promise delete(String url, [Object params,] [Object settings])
Object deleteRequests(String url, [Object params,] [Object settings])
As well as get()
and getRequest()
.
abort()
Aborts all opened requests for appropriate FetchPlease instance. Example:
let api = '/api/'; api ; api;