Add .toPromise as analogy to .asCallback

Very simple and useful addition:

Stream.prototype.toPromise = function() {
    return new Promise((resolve, reject) => {
       this.toCallback((err, res) => err ? reject(err) : resolve(res));
    });
};

Pros:

• Enables direct integration with APIs designed to work with promises
• Enables direct integration with language constructs like async/await

Cons:

• Won’t work in Node 0.10 and Internet Explorer without Promise polyfill.

[vqvu]

I don’t think it’s so odd. Highland consumes a lot of things that it doesn’t let you get back out (like arrays or Iterables). In fact, streams are strictly more powerful than promises (since they can handle multiple asynchronous values instead of just one), so I would expect it to be easier to convert from Promises to streams than the other way around.

Plus, I’m not saying we shouldn’t have an easy way to convert back to a promise (toCallback was partly written to facilitate this). I’m just saying that since Promises aren’t completely universal yet, users need to take the (imo minor) step of providing a Promise constructor when they convert.

[vqvu]

I understand that polyfills exist. They are not the problem. The problem isn’t even an implicit dependency on a global Promise—not by itself anyway. As I’ve said before, there’s nothing wrong with depending on Promise if it is core to the functionality of the library. Axios is a perfect example of such a library. Highland is not.

It comes down to a trade-off between developer user experience and implicit dependency on global state. For example, axios can choose to make all of its API require the user pass in a promise constructor, but that would be extremely annoying for their users. In their case, the improved user experience outweighs any issues that depending on Promise can cause.

For Highland, I think it’s the opposite. toPromise is only useful when you need to interop with libraries or language features that require promises. It’s use should be rare in comparison to other parts of the Highland API. The slight improvement in user experience from not requiring the promise constructor is not worth it. It’s a value judgement. You may disagree.

Note that #628 was merged, so I’m not completely opposed to the idea of a toPromise method.