Provide promise based API for core libraries

[olalonde]

I couldn't find any discussion related to that and I've been told core contributors aren't a fan of promises but I thought I'd kick start a discussion anyway. I had assumed this was discussed at length already but couldn't find any relevant links.

The proposal would be to make all async methods of the core library return promises. This could be done in a backwards compatible way by using something like bluebird's nodeify (now asCallback) which would allow both errback / promise styles to co-exist.

[Trott]

Here's one place it's been discussed: nodejs/node#11

[calebmer]

But that issue is closed pending future discussion. So this is future discussion 😊

[Trott]

Right, this is a better place to discuss it. I was providing the link for reference since OP said they couldn't find any previous discussion. There's a previous discussion for context.

[olalonde]

@Trott thanks. Last comment seems to imply it's ok to move discussion here, so will keep open.

[yoshuawuyts]

I think nodejs/node#11 (comment) sums up well why Promises have no place in Node core. Node and LibUV aim to resort to the lowest common denominator and provide the smallest API possible. Adding more ways of doing the same thing that can already be achieved by userland packages is against Node's philosophy.

Last I checked on the Node TC meetings the status was that promise rejection handlers will be added as V8 implements them, making Promises slightly less harmful. In terms of TC members some seem to be excited for potential async/await control flow and some are vocally against Promises as a way of handling async.

I feel that this topic is completely chewed out, and this issue best be closed as I suspect it might (again) spin into a very misinformed back and forth.

[calebmer]

I don't think it's a matter of if promises will be implemented (sorry everyone) I think it's a matter of when. Issues and PRs like this will keep popping up until promises are integrated. That's inevitable. I say keep this issue open as it does provide an outlet (and a URL) for anyone who wants to contribute to the discussion vs. seeing a hundred more issues from now until the promise integration.

[olalonde]

@yoshuawuyts let's imagine for a moment that Node core was initially designed with a promise based API, almost all the same arguments could be made about supporting an errback API. Let's try:

First, promises are not as bad as you think and there are some simple, effective ways to organize callback driven code to avoid common complaints.

Second, callbacks have costs and benefits like anything, and while the benefits are well-advertised, the costs can be hidden and frustrating.

Third, the callback is the fundamental unit of asynchronous programming in JavaScript and Promises are just callbacks with added semantics (a specific type of callback if you will). There is no single abstraction that's perfect for all use cases.

Fourth, promises aren't a silver bulllet. There are whole classes of use cases where promises aren't the right abstraction [...].

Well, I don't have to alter that one. There are some places where promises are indeed not a good abstraction, like event and stream APIs.

Fifth, the design philosophy of node core is to encourage maximum compatibility and discourage decisions that lead to incompatibility. While it is trivial to turn a promise based API into a callback one, the opposite is not always true.

Sixth, integrating with c++ bindings/libuv has only been possible using callbacks. The core team is committed to keeping node lightweight and fast by providing APIs that are as "close to the action" as possible, so they're not going to be introducing a new abstraction to asynchronous programming in core anytime soon: http://blog.trevnorris.com/2014/02/nodejs-es6-and-me.html

In my mind, this is the only substantial argument against promises in Node. From the linked blog post:

When the v8 team introduces an API for generators or promises I will give it honest consideration.

So I guess the question is, has v8 introduced this yet? If not, I'll be happy to shut up until then :)

[Qard]

FWIW, async generators are in the works, which would work pretty nicely for streams. It's like async/await, but you get an await per chunk in a for/of loop. https://github.com/zenparsing/async-iteration/#readme

[jakearchibald]

Returning a promise if a callback/errback is not passed would work.

Promise-based APIs shouldn't thow, they should reject instead https://www.w3.org/2001/tag/doc/promises-guide#always-return-promises - so calls without a callback/errback ideally shouldn't throw. Would this be a compatibility risk?

[caspervonb]

Returning a promise if a callback/errback is not passed would work.

Promise-based APIs shouldn't thow, they should reject instead
https://www.w3.org/2001/tag/doc/promises-guide#always-return-promises - so calls without a
callback/errback ideally shouldn't throw. Would this be a compatibility risk?

Callback vs promises will have different semantics by definition, to keep compatability with error first callbacks, we could rethrow if the callback is present.

function stat(filename, callback) {
  let promise;
  // ...

  try {
    // ...
  } catch (error) {
    if (callback) {
      throw error;
    }

    promise.reject(error);
  }

  // ...
  return promise;
}

[jakearchibald]

Yeah, that's what I meant. The compatibility risk is if someone already does:

whatever.asyncThing();

…where the async throw is meaningful to them, but they're happy to fire & forget the rest. The change we're proposing would change the behaviour here.

[caspervonb]

Ah.. now I'm following you. However omitting the callback from an async function is generally an error, or simply undefined behavior. Documentation does not mark for example, the callbacks in the fs module as optional, they are required.

Taking from the C++ world, if you rely on undefined behavior you're toast. That's my two cents on how this should be treated.

[jakearchibald]

Agreed. Given that, if no callback is provided, return a promise and treat any exceptional failure as rejection, otherwise go with the current behaviour.

[bevacqua]

I like the idea of returning a promise if no callback is provided. I think that'd be pretty backwards compatible.

Also, as an equivalent of event emitters throwing when no error handlers are present, I'd have thrown errors bubble out of the promise if no errback handlers were registered (again, when no callback is passed).

E.g:

// throws at the location of the promise
new Promise(() => { throw 'a' }).then(() => console.log('foo'))

// doesn't throw
new Promise(() => { throw 'a' }).catch(() => {})

Lastly, check out my OP here for extra arguments in favor of promises in Node: nodejs/node#4596 (comment)

[mikeal]

One of the main objections to this has been performance. If someone wants to put together a PR and see how it performs compared to the current API, and quantify any performance cost this would cause on the current API, that would probably be the best way to move this forward.