jqx

Description

Basic ajax utility. Wraps jQuery#ajax in Q promises and provides a primal API for request / response / error interceptors.

Expects a CommonJS environment, depends on both jquery and q.

Usage

Making a request

Arguments are passed straight to jQuery#ajax, so call it the same way:

jqx(url, options).then(function (data) {
  // do stuff with data
}).catch(/* log it */)
 
jqx(options).then(function (data) {
  // do stuff with data
}).catch(/* log it */)

Adding interceptors

jqx has three groups of interceptors:

jqx.reqInterceptors  -- applied to the `data` of each request
 
jqx.resInterceptors  -- applied to each success response
 
jqx.errInterceptors  -- applied to each failed request

Success interceptors are called with the jQuery success callback arguments: (data, status, jqXhr). For error interceptors, the arguments order is reversed: (error, status, jqXhr), allowing for easier callback reuse. If a success interceptor returns a non-undefined value, it replaces the previous data value. In other words, interceptors are also transformers, or filters.

Interceptors are applied in the same order as you add them.

jqx.addReqInterceptor([... functions])

Adds a request interceptor or multiple.

Example:

jqx.addReqInterceptor(function (data) {
  return data.sort()
})

jqx.addResInterceptor([... functions])

Adds a response interceptor or multiple.

Example:

jqx.addResInterceptor(function (data, status, jqXhr) {
  var msg = jqXhr.getResponseHeader('Easter-Egg')
  if (msg) {
    console.log('-- message from Santa:', msg)
  }
  // returning undefined -> no change in data
  // returning any other value would replace data
})

jqx.addErrInterceptor([... functions])

Adds an error interceptor or multiple.

Example:

jqx.addErrInterceptor(function (error, status, jqXhr) {
  console.error(error)
  alert('Debug your flops')
})