Home

Awesome

qwest 4.5.0

⚠ I finally decided to archive this repository. ⚠

At first, I developed Qwest because at the time other libraries were lacking of a proper XHR2 support, concurrent requests, IE8+ support, with a small footprint. The Qwest adventure was a great one but with the emergence of the Fetch API, the Axios.js library and the fact that I do not have much time to maintain it since a few years, I came to the conclusion that the project needed an end.

I advice you to stop using this library as it won't be maintained anymore and use fetch with p-limit to achieve concurrent requests with an elegant and native API. Fetch is still a work in progress but has good support amongst browsers and can be extended with many libraries.

That's all folks!

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

Qwest is also available via CDNJS : https://cdnjs.com/libraries/qwest

If you need to import qwest in TypeScript, do :

import * as qwest from '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) {
        // Make some useful actions
     })
     .catch(function(e, xhr, response) {
        // Process the error
     });

Basics

qwest.`method`(`url`, `data`, `options`, `before`)
     .then(function(xhr, response) {
        // Run when the request is successful
     })
     .catch(function(e, xhr, response) {
        // Process the error
     })
     .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 :

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

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() {
         // Blah blah
     })
     .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'
    }
});

Note : if you want to send your data as a query string parameter chain, pass queryString to the dataType option.

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) {
         /*
            Prints [ [xhr, response], [xhr, response], [xhr, response] ]
        */
         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';

// Will make a request to 'http://example.com/somepage'
qwest.get('/somepage')
     .then(function() {
         // Blah blah
     });

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>

// Browsers are limited in number of parallel downloads, setting it to 4 seems fair
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

// Start the request
var request = qwest.get('example.com')
                   .then(function(xhr, response) {
                       // Won't be called
                   })
                   .catch(function(xhr, response) {
                       // Won't be called either
                   });

// Some code

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) {
            // Upload in progress
        };
     })
     .then(function(xhr, response) {
        // Blah blah blah
     });

Handling fallbacks

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

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.get('example.com/file', null, null, function(xhr) {
        xhr.overrideMimeType('text\/plain; charset=x-user-defined');
     })
     .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(){});

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

License

MIT license everywhere!