A proposal for ending the wrapping/unwrapping war.

[slightlyoff]

Doing this here because the mailing lists have turned into an unfollowable mess.

First, some cautionary notes: this thread will use the terms "wrapping" and "unwrapping" to refer to APIs that treat Futures as something other than direct values. Posts here that use different terminology will be edited to conform.

Next, please be civil and cordial. Those who don't agree with you aren't bad and they might not even be wrong. Goodwill will get us where we want to go.

OK, down to it:

It seems to me that the contended bit of the design is .then() (and by extension, .catch()). Both pro and anti-unwrapping camps can have their own way at resolution time using .resolve() and .accept() respectively. And both have valid points:

• for those who live in a very Futures-driven world, it's hugely common to want to treat values and Futures/Promises without distinction.
• for those making the transition, or who have different contracts that they want to service with regards to some non-Futures-loving service, having directness can be a virtue.

On top of these points, there are preferences for styles of use. These can't ever be truly enforced with rigor because it's trivial to write wrapping/unwrapping versions of direct functions and vice versa. So there are cultural differences that we must admit with regards to preferred styles of use.

With the caveat that all involved are willing to live-and-let-live, I observe that it is possible to end the current debate in everyone's favor so long as we add a "direct" version of .then(). That is to say, one which has the semantics of .accept() with one level of unwrapping for a returned thenable and not .resolve() (infinite unwrapping) for values returned from callbacks.

I'll submit .when() as a straw-man name, but I'm not precious about it.

So the question now is: is everyone cc'd here willing to make such live-and-let-live compromise? And if not, why not? And is there some other detail which I've missed?

/cc @domenic @dherman @wycats @annevk @tabatkins @erights

[domenic]

a "direct" version of .then(), e.g. one which has the semantics of .accept() and not .resolve() for values returned from callbacks

I think I know what you mean by this, but just to be sure, could you tell us what the fulfillment value ("acceptance value"?) of x, y, and z are in the following?

var a = new Future({ accept } => accept(5));
var b = new Future({ accept } => accept(a));

var x = a.when(() => 5);
var y = a.when(() => a);
var z = a.when(() => b);

[puffnfresh]

I tried reading this but had a hard time understanding in between the cautionary notes and preferences stuff. The idea is to not recursively join promises on then and resolve. when called via new methods?

I know we're in JavaScript-land but some pseudo type-signatures would really clear this up for me.

[slightlyoff]

Hey @domenic:

x == 5, y == 5, and z == a

At least that's my read of the design that @tabatkins was gunning for. I'm open to arguments that would make y == a and z == b, but I've been told that nobody wants that = )

[domenic]

Ah. I don't think that's very conceptually coherent :-/. If you want a counterpart to accept, it should be y ~ a and z ~ b. I think that this desire for conceptual coherence was the main idea behind @erights's "The Paradox of Partial Parametricity".

[slightlyoff]

My goal here is to remove the strain from .then(). I think there is a missing method. What it does, I'm somewhat less concerned about.

Waiting for @tabatkins and @dherman to weigh in.

[sicking]

Like Dominic, I think that if we were to have a separate .when() function, then it would be most useful/consistent if that function gave

x == 5 y == a z == b

This is the result you'd get if the implementation of .when() called .accept(returnValue) rather than .resolve(returnValue).

But I could be biased because I think that .resolve() and .then() should never recursively unwrap promises. I rather think the question is if we should allow them to become deeply wrapped or not.

If we're going to have both .then() and .when() I would strongly prefer to have clearer names. I.e. where it's more clear what the difference in behavior is between them.

[tabatkins]

@domenic
x is 5, y is 5, and z is Future<5>, or a.

@sicking Oh goodness, no. That would make it a map, which is much less useful. What I've wanted this whole time is a monadic bind function, which does single-level unwrapping. (Once you have bind, you get map for free.)

@slightlyoff
If we're going to go this way, I think it would probably be worthwhile to be strict about things, and make .when() strict about the return values of its callbacks. Right now it's loosey-goosey, acting like a bind if it can, and falling back to a map otherwise. Being strict means that x would be a rejected promise containing a TypeError, because the return value of the callback wasn't a promise, then y is 5 and z is a.

That behavior is more predictable, though less generally useful. I might be okay with this - .then() is the really loose, friendly function that accepts direct values or promises, and it fully unwraps so that its returned promise only ever contains direct values. .when() is the stricter and more predictable monadic function.

In that case, let's call the function .chain() instead, like @puffnfresh does in his Fantasy Land spec. It's a good general-purpose name for the monadic binding operation (I never really understood why Haskell calls it "bind" in the first place), which means that other structures can re-use the same name without trouble, and we can do good monadic stuff. It's also further from .then() in name-space, which should help people to distinguish them, and I think it's somewhat clearer in general - you're chaining two promises together, which is why you can't return a non-promise.

[puffnfresh]

👍

https://github.com/puffnfresh/fantasy-land#chain

The chain method would allow us to immediately make use of Fantasy Land derived functions for DOMFutures, which would be really great. The only requirement is that the law associativity is obeyed, which seems to be true.

[tabatkins]

So, some details you missed: ^_^

(Assuming that the new operation is called chain.)

Your proposal details differentiate between then and chain by the way they treat their callback return values, with then fully unwrapping and chain single-unwrapping. This works fine if you only use then or only use chain, but if you mix them, you'll run into trouble - a then callback can receive a Future, or a chain callback can have its argument unceremoniously collapsed.

Instead, they should differentiate on the argument side - if the Future contains nested Futures, the then callbacks don't get called until they all resolve and you end up with a plain value, while the chain callbacks fire as soon as the outer future resolves. It's possible for a then callback to return a nested Future, but if you then continue to use then you won't ever see it.

[jakearchibald]

Anyone willing to create (preferably real-world) JS examples of when & how you'd use one over the other? My first reaction is the single unwrap is weird but feel I'm missing something

[slightlyoff]

Still hoping @dherman will weigh in, but a few observations:

• I'm not opposed to .chain(), particularly not with the strictness stipulations. It's clear that it's dealing in Futures and not values under those conditions, and the name points in that direction.
• It's not clear that we need .chain() right now and it can be added later. A stand-alone chain(f, cb) method that takes a Future and callback gets you there on the back of the current design. You don't need anything new from Futures to effect this, AFAICT. Am I wrong about that?

Thanks.

[tabatkins]

@jakearchibald Lots of discussion about this in the various threads. Single-unwrap helps in scenarios where different futures represent fundamentally different types of things. For example, a database retrieval might return a Future, and the thing stored in the database might be a Future. You may want to just wait for the database retrieval to finish and then get to work on the value immediately, rather than having to wait for both of them to finish.

This is especially true when we add LazyFuture or whatever, which doesn't start its operation until someone registers a callback.

I don't like multi-unwrap at all (unless done explicitly), because I think generally it'll just paper over programming errors, but fuck it, if I can get a good chain out of this, I'll accept a recursive-unwrapping then.

@slightlyoff I don't understand. Your starting post in this thread was attempting to resolve the issue by splitting it into two operations, and now you're trying to suggest that we don't need two operations at all? Don't bait-and-switch me, bro.

But no, you can't build chain on top of recursive-unwrapping then without bullshit extra wrappers designed solely to foil auto-unwrapping, because your Futures won't stack. It would be extremely clumsy and dumb, and wouldn't work like a normal Future at all.

[shogun70]

If only there were an alternative method like .then()which exposed the new Future's resolver to it's callbacks.
Then you could accept / reject / resolve your intended .then() callbacks in anyway you need.
So you could do:

.thenWithResolver( resolveOnce( getSomething ) )  // unwrap once if getSomething(value) returns a promise

.thenWithResolver( accept( getSomething ) ) // always accept, even if only a promise

.thenWithResolver( rejectPromises( getSomething ) ) // Don't give me promises!

.thenWithResolver( rejectPromiseStreams( getSomething ) ) // I'm not trusting your promise a second time!

.thenWithResolver( future_invoke( obj, "getSomething" ) ) // .then( obj.getSomething.bind(obj) )

.thenWithResolver( translatePromises( getSomething ) ) // It's a promise Jimmy, but not as we know it.

It's just an idea off the top of my head really.
In general though, the right way to do all these things is to create another new Future inside a .then() callback.

[tabatkins]

@shogun70 What you're saying doesn't make any sense. Neither have any connection to the question of nested promises.

Returning a Future from a .then() callback is already a useful and accepted pattern - it gets unwrapped and the chained future adopts its state. The question is about returning a Future for a Future.

[tabatkins]

@slightlyoff So, the best, most consistent model is this:

Futures can stack. No magic, nothing special, you can just wrap anything in a Future, including more Futures. then waits until all nested futures have resolved before calling its callbacks with the final non-future value. chain just waits for the outermost future, and calls its callbacks with whatever the value of that is, whether it's a plain value or another future. Both are the "simpler" option, depending on who you ask.

(The treatment of callback return values isn't strictly important, but then can accept either futures or plain values, treating the latter as if it had been wrapped in an accepted future. chain only accepts futures. Both have their chained future adopt the returned future's value, doing single-level unwrapping. Of course, if you keep using then, the fact that it only unwraps the return value one level is invisible, since your callback isn't called until all the levels are unwrapped.)

This solves all problems, forever. If you have a nested Future where the two Futures are substantially different kinds of things, such that you only want to wait for the outer future to finish, not both, you can use chain to interact with it. If you don't care about all those details, and just want the final value, you can use then. There are use-cases for both - I've given use-cases for chain, and the use-cases for then are obvious, and all of the "I don't give a crap about your asynchrony, just call me when you're done" variety.

This also happens to satisfy people who like monads, because chain is the monad operation over futures.

It's possible to build then on top of chain without too much difficulty, but you can't do the opposite without a lot of annoying bullshit, like a non-thenable wrapper object designed solely to foil the recursive resolving.