cb-fetch
A truly cross-browser and forward-compatible library to do asynchronous HTTP requests that follows the callback pattern.
Table of Contents
Usage
Installation
npm
npm install --save cb-fetch
yarn
yarn add cb-fetch
jspm
jspm install cb-fetch
bower
bower install --save cb-fetch
jsDelivr
<script src="//cdn.jsdelivr.net/combine/npm/@string/isstring/isString.min.js,npm/cb-fetch/index.min.js" type="text/javascript"></script>
Importation
AMD
define(function (require) {
var request = require('cb-fetch');
});
CJS
standard compliant
var request = require('cb-fetch')['default'];
Node.js compatible
var request = require('cb-fetch');
YUI
YUI({
modules: { 'is-string': 'path/to/@string/isstring.js' }
}).use('is-string', 'cb-fetch', function (Y) {
var request = Y['default'];
});
TS
import request = require('cb-fetch');
Global Namespace
If none of the previously listed module registration methods are supported, a global variable named request
will be exposed.
Examples
// here's your typical request
request('http://www.example.com?key1=value1&key2=value2')
.done(response => { /* ā¦ */ });
// taking a comprehensive approach is encouraged though
request()
.get('http://www.example.com')
.query('key1=value1&key2=value2')
.done(onSuccessCallback, onErrorCallback);
// passing an object offers options not available otherwise
let abort = request({
url: new URL('http://www.example.com'),
parameters: new URLSearchParams('_csrf=TOKEN'),
mode: 'cors',
credentials: 'include',
responseType: 'json'
}).get('/segment')
.query({ foo: ['bar', 'qux'] })
.pass('Content-Type', 'application/json')
.hook('download', e => { /* ā¦ */ })
.done({
success: onSuccessCallback,
error: onErrorCallback,
abort: onAbortCallback
});
// forcefully aborts the request
abort();
Support
-
fetch
-
XMLHttpRequest
-
XDomainRequest
- Universal Module Definition
- WebDAV
- TypeScript
- Flow
Methods
get / head / delete / post / patch / put
(Options.url?) => Object
query
(Options.parameters?) => Object
send
(Options.body?) => Object
hook
loadstart
('loadstart', () => Boolean | Void) => Object
download
('download', Object => Any) => Object
loadend
('loadend', () => Any) => Object
pass
{
(name: String, value: String),
(headers: Object | Headers)
} => Object
// assigns
.pass(new Headers({ key: 'value' }))
// appends
.pass({ key: 'value' })
// sets
.pass('key', 'value')
done
{
(onSuccess?: Function, onError?: Function),
({
success?: Function,
error?: Function,
timeout?: Function,
abort?: Function
})
} => () => Void,
throws: TypeError
Properties
Request Options
Property | Default | Value(s) |
---|---|---|
body | null | BufferSource, Blob, DocumentĀ², FormData, String, URLSearchParams, ReadableStream |
credentials | 'sameāorigin' | 'include', 'omit'ā¶, 'same-origin' |
headers | {} | Object, HeadersĀ³ |
method | 'GET' | String |
mode | 'sameāorigin' | 'cors', 'no-cors'Ā¹, 'same-origin' |
password | null | String |
parameters | URLSearchParams, Object, String | |
responseMediaTypeĀ² | String | |
responseType | 'text', 'json', 'blob', 'document', 'arraybuffer', 'formdata'Ā¹, 'moz-blob', 'moz-chunked-arraybuffer', 'moz-chunked-text', 'msxml-document' | |
timeout | 0 | ā |
username | null | String |
url | location.href | String, URL |
multipartā· | false | Boolean |
tunnelingāµ | false | Boolean |
XSLPatternā“ | false | Boolean |
Progress Event
Property | Type |
---|---|
chunk | String, ArrayBuffer, Blob, Uint8Array, null |
aggregate | String, ArrayBuffer, Blob, Uint8Array, null |
loaded | ā |
total | ā |
lengthComputable | Boolean |
Response
Property | Type |
---|---|
body | Object, String, Document, ArrayBuffer, Blob, FormDataĀ¹, ReadableStreamĀ¹, null |
headers | Object |
instance | XMLHttpRequest, XDomainRequest, Response, AnonXMLHttpRequest |
statusCode | ā |
statusText | String |
url | String |
Ā¹ fetch only
Ā² XHR only
Ā³ except Gecko 34ā43
ā“ MSXML 3.0 only
āµ method override
ā¶ fetch, Gecko 16+, Presto/2.10.232ā2.12.423
ā· Gecko 1.7Ī²ā22
Gotchas
delete
reserved keyword
In pre-ES5 environments, the delete method requires the use of the bracket notation.
Gecko
For the browsers powered by Gecko 1.9.1ā20 to have the exposed response headers
populated into the headers
property, the following conditions must be met:
-
Access-Control-Expose-Headers
response header exposes itself -
Access-Control-Expose-Headers
field value is not*
-
mode
set tocors
Trident
XDomainRequest
intrinsic limitations
- only support GET and POST methods
- cannot set request headers
- no credentials
- same scheme restriction
- the informational and redirection status code classes are considered errors
- the response's status code and status text are not supplied
- same-origin requests also require the server to respond with an
Access-Control-Allow-Origin
header of either*
or the exact URL of the requesting document
Platform for Privacy Preferences
Internet Explorerās default settings restrict the use of 3rd party cookies unless a P3P compact policy
declaration has been included through a custom HTTP response header; hence, the "include"
credentials mode cannot be
fully honored if a cookie has been deemed unsatisfactory.