qwest 4.4.6
A complete rewrite of qwest in ES6 with many improvements is planned soon. Keep in touch!
Qwest is a simple ajax library based on promises
and that supports XmlHttpRequest2
special data like ArrayBuffer
, Blob
and FormData
.
Install
npm install qwest
bower install qwest
jam install qwest
Qwest is also available via CDNJS : https://cdnjs.com/libraries/qwest
Quick examples
qwest.get('example.com')
.then(function(xhr, response) {
alert(response);
});
qwest.post('example.com', {
firstname: 'Pedro',
lastname: 'Sanchez',
age: 30
})
.then(function(xhr, response) {
})
.catch(function(e, xhr, response) {
});
Basics
qwest.`method`(`url`, `data`, `options`, `before`)
.then(function(xhr, response) {
})
.catch(function(e, xhr, response) {
})
.complete(function() {
});
The method is either get
, post
, put
or delete
. The data
parameter can be a multi-dimensional array or object, a string, an ArrayBuffer, a Blob, etc... If you don't want to pass any data but specify some options, set data to null
.
The available options
are :
- dataType :
post
(by default), json
, text
, arraybuffer
, blob
, document
or formdata
(you don't need to specify XHR2 types since they're automatically detected) - responseType : the response type; either
auto
(default), json
, xml
, text
, arraybuffer
, blob
or document
- cache : browser caching; default is
false
- async :
true
(default) or false
; used to make asynchronous or synchronous requests - user : the user to access to the URL, if needed
- password : the password to access to the URL, if needed
- headers : javascript object containing headers to be sent
- withCredentials :
false
by default; sends credentials with your XHR2 request (more info in that post) - timeout : the timeout for the request in ms;
30000
by default (allowed only in async mode) - attempts : the total number of times to attempt the request through timeouts; 1 by default; if you want to remove the limit set it to
null
You can change the default data type with :
qwest.setDefaultDataType('json');
If you want to make a call with another HTTP method, you can use the map()
function :
qwest.map('PATCH', 'example.com')
.then(function() {
});
If you need to do a sync
request, you must call send()
at the end of your promise :
qwest.get('example.com', {async: false})
.then(function() {
})
.send();
Since service APIs often need the same type of request, you can set default options for all of your requests with :
qwest.setDefaultOptions({
dataType: 'arraybuffer',
responseType: 'json',
headers: {
'My-Header': 'Some-Value'
}
});
Group requests
Sometimes we need to call several requests and execute some tasks after all of them are completed. You can simply do it by chaining your requests like :
qwest.get('example.com/articles')
.get('example.com/users')
.post('example.com/login', auth_data)
.then(function(values) {
console.log(values);
});
If an error is encountered then catch()
will be called and all requests will be aborted.
Base URI
You can define a base URI for your requests. The string will be prepended to the other request URIs.
qwest.base = 'http://example.com';
qwest.get('/somepage')
.then(function() {
});
Request limit
One of the greatest qwest functionnalities is the request limit. It avoids browser freezes and server overloads by freeing bandwidth and memory resources when you have a whole bunch of requests to do at the same time. Set the request limit and when the count is reached qwest will stock all further requests and start them when a slot is free.
Let's say we have a gallery with a lot of images to load. We don't want the browser to download all images at the same time to have a faster loading. Let's see how we can do that.
<div class="gallery">
<img data-src="images/image1.jpg" alt="">
<img data-src="images/image2.jpg" alt="">
<img data-src="images/image3.jpg" alt="">
<img data-src="images/image4.jpg" alt="">
<img data-src="images/image5.jpg" alt="">
...
</div>
qwest.limit(4);
$('.gallery').children().forEach(function() {
var $this = $(this);
qwest.get($this.data('src'), {responseType: 'blob'})
.then(function(xhr, response) {
$this.attr('src', window.URL.createObjectURL(response));
$this.fadeIn();
});
});
If you want to remove the limit, set it to null
.
CORS and preflight requests
According to #90 and #99, a CORS request will send a preflight OPTIONS
request to the server to know what is allowed and what's not. It's because we're adding a Cache-Control
header to handle caching of requests. The simplest way to avoid this OPTIONS
request is to set cache
option to true
. If you want to know more about preflight requests and how to really handle them, read this : https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
Aborting a request
var request = qwest.get('example.com')
.then(function(xhr, response) {
})
.catch(function(xhr, response) {
});
request.abort();
Not that only works with asynchroneous requests since synchroneous requests are... synchroneous.
Set options to the XHR object
If you want to apply some manual options to the XHR
object, you can use the before
option
qwest.get('example.com', null, null, function(xhr) {
xhr.upload.onprogress = function(e) {
};
})
.then(function(xhr, response) {
});
Handling fallbacks
XHR2 is not available on every browser, so, if needed, you can simply verify the XHR version with :
if(qwest.xhr2) {
}
else {
}
Receiving binary data in older browsers
Getting binary data in legacy browsers needs a trick, as we can read it on MDN. In qwest, that's how we could handle it :
qwest.get('example.com/file', null, null, function(xhr) {
xhr.overrideMimeType('text\/plain; charset=x-user-defined');
})
.then(function(response) {
});
Compatibility notes
According to this compatibility table, IE7/8 do not support using catch
and delete
as method name because these are reserved words. If you want to support those browsers you should write :
qwest.delete('example.com')
.then(function(){})
.catch(function(){});
Like this :
qwest['delete']('example.com')
.then(function(){})
['catch'](function(){});
XHR2 does not support arraybuffer
, blob
and document
response types in synchroneous mode.
The CORS object shipped with IE8 and 9 is XDomainRequest
. This object does not support PUT
and DELETE
requests and XHR2 types. Moreover, the getResponseHeader()
method is not supported too which is used in the auto
mode for detecting the reponse type. Then, the response type automatically fallbacks to json
when in auto
mode. If you expect another response type, please specify it explicitly. If you want to specify another default response type to fallback in auto
mode, you can do it like this :
qwest.setDefaultXdrResponseType('text');
Last notes
- Blackberry 10.2.0 (and maybe others) can log an error saying json is not supported : set
responseType
to auto
to avoid the issue - the
catch
handler will be executed for status codes different from 2xx
; if no data has been received when catch
is called, response
will be null
auto
mode is only supported for xml
, json
and text
response types; for arraybuffer
, blob
and document
you'll need to define explicitly the responseType
option- if the response of your request doesn't return a valid (and recognized)
Content-Type
header, then you must explicitly set the responseType
option - the default
Content-Type
header for a POST
request is application/x-www-form-urlencoded
, for post
and xhr2
data types - if you want to set or get raw data, set
dataType
option to text
- as stated on StackOverflow, XDomainRequest forbid HTTPS requests from HTTP scheme and vice versa
- XDomainRequest only supports
GET
and POST
methods
License
MIT license everywhere!