Promises based API

[wilhelmmatilainen]

Webtorrent is something new.
Compared to events, promises are something new in node.js.

How about writing webtorrent using bluebird promises?
https://github.com/petkaantonov/bluebird#what-are-promises-and-why-should-i-use-them

[madd512]

let torrent = yield client.add('leaves of grass.torrent')
let book = yield torrent.getBuffer('leaves of grass.epub')
read(book)

Yeah, a promise API would be nice.

[wilhelmmatilainen]

Or like this

client.download('<magnet-uri>')
    .then(seed)
    .catch(log.error);

[feross]

I don't use promises, but I'm willing to consider adding promises to WebTorrent if it's backwards compatible and doesn't add a ton of extra code. Rather than include a library like bluebird, I'd prefer to just use the built-in platform Promises, if they exist.

PR welcome!

[eabay]

jwalton/node-promise-breaker can be a good fit for the implementation.

[wilhelmmatilainen]

Why bluebird:
http://programmers.stackexchange.com/questions/278778/why-are-native-es6-promises-slower-and-more-memory-intensive-than-bluebird

How

var promise = require('bluebird');

function oldFunction(a, b, callback) {
  if(a === b)
    callback(); // Success
  else
    callback(new Error('a does not equal to b')); // Fail
}

function newFunction(a, b) {
  return new promise(function(success, fail) {
    oldFunction(a, b, function(error) {
      if(error)
        return fail(error);
      return success();
    });
  });
}

function someFunctionUsingTheNewFunction(a, c) {
  return newFunction(a, c+1);
}

function letsChainStuff() {
  return newFunction(1, 1)
    .then(function() {
      return newFunction(2, 2);
    }).then(function() {
      return newFunction(3, 3);
    }).then(function() {
      return newFunction(4, 4);
    }).then(function() {
      return newFunction(1, 333); // This will fail
    });
}

letsChainStuff()
.then(function() {
  console.log('all done');
}).catch(function(error) {
  console.error(error); // Some nasty error happened
});

Notice that someFunctionUsingTheNewFunction?
There's no additional success or fail check. Why?
The promise it returns contains the information.

If you won't return a promise, a chain will continue directly to the next function.
When you return a promise, it's waited for before continuing to the next function.

With bluebird promises it's also possible and very easy to make something execute in _series_ or in _parallel_.

[feross]

Sorry, we're not bundling bluebird. That's 161KB of additional JavaScript that browser users would need to download.

[feross]

I think the best way to get promises into webtorrent core is for someone who uses promises regularly (not me) to publish a new package webtorrent-promise as an experiment to show what the API would work like. If it's nice, we can merge it into core.

[FluorescentHallucinogen]

In 2018 the JS promises are supported in the browsers and Node.js natively.

@feross

to show what the API would work like

For example

client.add(magnetURI).then(torrent => {
  console.log(torrent.infoHash);
}).catch(error => {
  console.error(error);
})

instead of

client.add(magnetURI, function(torrent) {
  console.log(torrent.infoHash);
})

and

client.seed(files).then(torrent => {
  console.log(torrent.infoHash);
}).catch(error => {
  console.error(error);
})

instead of

client.seed(files, function(torrent) {
  console.log(torrent.infoHash);
})

and so on…

@feross

I'm willing to consider adding promises to WebTorrent if it's backwards compatible

See how Firebase team has solved this problem: https://firebase.googleblog.com/2016/01/keeping-our-promises-and-callbacks_76.html. They added promises, but keep callbacks for backward compatibility. All functions in Firebase API now accept both Promise and callback-style methods.

[feross]

The ecosystem around Promises has matured quite a bit since I closed this issue. It's important to consider how to add Promises to the codebase without making the control flow hard to follow. I think I'd rather remove callbacks entirely to simplify maintenance, reduce the amount of code we need to test, etc.