Promise API

[floatdrop]

This is just a proposal - feel free to share ideas, criticize, etc.

Idea

Get Promise API into got with polyfill for Promise in Node.JS 0.10 like this:

got('google.com'); // => Promise

got('google.com', function (err, body) {
    // ...
});

Motivation

✨Generators✨ are awesome for flow-control and we finally can forget about callback hell and move on (with some help of co-like libraries) to yield:

co(function *() {
    var results = yield [got('google.com'), got('github.com')];
    console.log(results);
});

To support this, we should return Promise from got.

Also new fetch API based on Promises landed in Chrome 42.

When ES7 will come to play, we will be able to go even further with async/await:

async function () {
    let site = await got('google.com');
};

Problems

Promise API conflicts with Stream API

Atm I have no idea how to merge them (and if it is possible, I would vote against it), so one way is to move Stream API under stream property, like this:

var stream = got.stream('google.com');

This will be breaking change, so "brace yourselves, major release is coming" (hah). What we can do in 3.x version, to warn users - add promise property first and deprecation warning of Stream API.

Resolve format

There are two ways, with which Promise can resolve request. This will affect, how results can be destructed into variables:

Resolve into Array of response and body (like then-got):

// Assume co-wrapper in all examples below ↓

var [response, body] = yield got('google.com');

Resolve into response Object with body property (like got-promise):

var {body, headers} = yield got('google.com');

It seems like resolving to Object make much more sens - order of vars is not matters and user can access body, without response (or vice versa with different order).

TS: @sindresorhus
Related: request/request#796

[sindresorhus]

Agree with everything 🌟 👍

It seems like resolving to Object make much more sens - order of vars is not matters and user can access body, without response (or vice versa with different order).

Yes, I would prefer an object too.

@kevva @julien-f @silverwind @arthurvr @shinnn

[arthurvr]

I'm all for this! 👍

It seems like resolving to Object make much more sens - order of vars is not matters and user can access body, without response (or vice versa with different order).

Yes, I would prefer an object too.

Me too.

[kevva]

👍 Great idea.