What does an asynchronous AJAX call return?

Question

I am trying to create a test case to monitor progress of multiple parallel asynchronous server tasks. I have the code sort-of working, but there are several pieces I don't understand. First, what does the $.ajax call below return? In theory, it should return undefined, but that doesn't seem to be the case.

function doParallel() {    
    var promiseA, promiseB, handleSuccess, handleFailure;
    var dataA = JSON.stringify({ size: a });
    var dataB = JSON.stringify({ size: b });

    promiseA = $.ajax({
        url: testGlobal.urlA, 
        data: dataA,
        type: "POST",
        async: true,
        contentType: 'application/json; charset=utf-8',
        dataType: "json",
        success: function (rtnData) {
            //  Get the result
            result = (rtnData === undefined) ? null : $.parseJSON(rtnData.d);
        },
        error: function (xhr, textStatus, errorThrown) {
            //  Whoops! didn't work
            reportAjaxError(xhr, textStatus, url, data);
        },
        complete: function (xhr, textStatus) {
            //  Errors have already been handled, so only 
            //  deal with success cases
        }
    });  <--- WHAT GETS RETURNED TO PROMISE HERE?

... (same code for promiseB, etc.
    var notifyingPromiseA = intervalPromise(2000, 'a');
    var notifyingPromiseB = intervalPromise(2000, 'b');

...
    promiseA.done(function() {
        log("A done");
    }
    promiseB.done(function() {
        log("B done");
    }
    $.when(promiseA, promiseB).done(function() { log ("All done") });
}

function intervalPromise(millis, source) {
    var deferred = $.Deferred();
    //checkProgress();
    log("Checking progress on " + source);
    var id = setInterval(function () {
        deferred.notify();
        if (testGlobal.aDone && testGlobal.bDone) {
            clearInterval(id);
            deferred.resolve();
        }
    }, millis);
    return deferred.promise();
}

...

Answer 1

$.ajax() returns the XMLHttpRequest object. As of jQuery v1.5, $.ajax() also implements and returns a Promise / Deferred interface.

http://api.jquery.com/jQuery.ajax/

http://api.jquery.com/category/deferred-object/

With a Promise, you can chain additional callbacks based on the results of the original ajax call.

// setup interval / timer to update UI not finished / still working logic

$.ajax().done(function() {
    // clear UI not fninshed / still working logic
});

Answer 2

mmm.. official docs say:

The $.ajax() function returns the XMLHttpRequest object that it creates. Normally jQuery handles the creation of this object internally, but a custom function for manufacturing one can be specified using the xhr option. The returned object can generally be discarded, but does provide a lower-level interface for observing and manipulating the request. In particular, calling .abort() on the object will halt the request before it completes.

http://api.jquery.com/jQuery.ajax/

Answer 3

As of jQuery 1.5, jQuery.ajax() (and various ajax shortcut methods) returns a jqXHR object, which is a superset of the browser's native XMLHttpRequest object and implements inter alia the Promise interface.

Read more about the jqXHR object here.