qwest

qwest 1.0.0

Qwest is a simple ajax library based on promises behaviour and that supports XmlHttpRequest2 special data like ArrayBuffer, Blob and FormData.

Install

You can pick the minified library or install it with :

jam install qwest
bower install qwest
npm install qwest --save-dev

Changes since 0.7

• use then() and catch() promises instead of success() and error()
• the type option has been replaced by responseType
• dataType option has been added
• the before callback has now its own promise (see it in action at the bottom of the doc)
• added CORS support; XDomainRequest for IE8/9 is supported as well
• added timeout/retries support
• handle PUT/DELETE requests

Quick examples

qwest.get('example.com')
	 .then(function(response){
		alert(response);
	 });

qwest.post('example.com',{
		firstname: 'Pedro',
		lastname: 'Sanchez',
		age: 30
	 })
	 .then(function(response){
		// Make some useful actions
	 })
	 .catch(function(message){
		// Print the error message
	 });

Basics

qwest.<method>(<url>,[data],[options])
	 .then(function(response){
		// Run when the request is successful
	 })
	 .catch(function(message){
		// Process error message
	 })
	 .complete(function(){
		// Always run
	 });

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 'json' (by default), 'js', 'xml', 'text', 'arraybuffer', 'blob' or 'document'
• cache : browser caching; default is false for GET requests and true for POST requests
• 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; 3000 by default
• retries : the number of times the request would be runned if the timeout is reached; 3 by default; if you want to remove the limit set it to null

In each callback, the this keyword refers to the XmlHttpRequest object, so you can do some specific tasks you may need.

qwest.get('example.com')
	 .then(function(response){
		// Blah blah blah
	 })
	 .catch(function(message){
		log(this.responseText);
		throw message;
	 });

Request limitation

One of the great qwest's functionnalities is the request limitation. 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 (when you load a gallery, per example). You just need to set the request limit and when the count is reached qwest will stock all further requests and start them when a slot is free.

qwest.limit(4);

$('.foo').forEach(function(){
	qwest.get(this.data('some_url_to_get'));
});

If you want to remove the limit, do qwest.limit(null).

Set options to XHR

If you want to apply some manual options to the XHR object, you can use the before promise. It must be called before any other promise. The this keyword refers to the XHR object itself.

qwest.before(function(){
		this.uploadonprogress=function(e){
			// Upload in progress
		};
	 })
	 .get('example.com')
	 .then(function(response){
		// Blah blah blah
	 });

Handling fallbacks

XHR2 is not available on every browser, so, if needed, you can simply verify the XHR version.

if(qwest.xhr2){
	// Actions for XHR2
}
else{
	// Actions for XHR1
}

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.before(function(){
		this.overrideMimeType('text\/plain; charset=x-user-defined');
	 })
	 .get('example.com/file')
	 .then(function(response){
	 	// response is now a binary string
	 });

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(){});

The CORS object shipped with IE8 and 9 is XDomainRequest. This object does not support PUT and DELETE requests.

XHR2 does not support arraybuffer, blob and document response types in synchroneous mode.

Last notes

• if an error occurs in a then() callback, it will be catched by the catch() promise
• the default Content-Type header is application/x-www-form-urlencoded for post and xhr2 data types, with a POST request
• the js response type executes a remote javascript file and returns its raw code in the then() promise
• if you want to set or get raw data, set the related option to text

License

MIT license everywhere!