silkapp/rest — pull request #51 by mbrock (2014-07-30 14:08:39+00:00)
Title: Use Q promises

So, the new Node.js support has a major type discrepancy compared to the jQuery-based request code used in the browser: specifically, the return values of API requests are XHR objects in the browser, and Request objects in Node. This is undesirable, because code written to assume either will be bound to either Node or the browser.

jQuery's XHR objects are similar to promises, but widely acknowledged to be broken and bad. If we want a unified API that works in Node and browsers, I don't think we should try to simulate jQuery XHR in Node, but rather use a (semi-)standardized promise implementation in both cases.

This PR introduces a dependency on Q for both Node and the browser, and makes all API calls return Q promises (or A+ promises, as the spec is known).

An open question is whether we should have some option for the browser mode to disable the use of Q and just return ordinary XHR objects. This might be preferrable for some users of `rest` who don't want to introduce a promise library into their JavaScript code base.

(I also snuck in a way to add custom default HTTP headers to all API requests, because this was something that came up during some Node prototyping.)