Implement Promise.series

[epoberezkin]

When you have the list of values to be passed to the same function sequentially, so that the next call is only made only when the promise returned by the previous call is resolved, you either have to "manually" chain promises or use Promise.reduce, which both looks a bit ugly and also not so obvious.

It could be nice to have something like this:

Promise.series = function (arr, iteratorAsync) {
    return Promise.reduce(arr, function(memo, item) {
        return iteratorAsync(item);
    }, 0);
}

[benjamingr]

How is this any different from .reduce apart from the arbitrary 0 default value?

Also, duplicate of #109 and #70

[epoberezkin]

Sorry. Correct. Maybe it's still needed this way or another as I'm the third to suggest it :)
It's probably that control-flow mentality coming from callbacks.
The difference is in using 1 line of code:

Promise.series(arr, iteratorAsync);

instead of 3 lines (or 1 long not too readable line):

Promise.reduce(arr, function(memo, item) {
    return iteratorAsync(item);
}, 0);

And in case when the results are collected in array as somebody suggested (mapSeries) it becomes even bigger difference.

[petkaantonov]

The problem is this:

You are pulling iteratorAsync out of nowhere but not doing the same for reduce case.

A fair comparison would be:

Promise.reduce(arr, reducerAsync, 0);

So you have not gained anything because instead of making iteratorAsync function you will just make reducerAsync function. And there is no difference with array case at all - you just pass array as initial value instead of 0.

[petkaantonov]

The reason for popularity of this suggestion is misunderstanding of promises and thinking of Promise.all as some kind of "parallel" which needs a sequential equivalent.

But Promise.all doesn't "parallelize" promises or anything, it does nothing to the input promises - it is simply just telling you whether the promises you already are controlling from somewhere else are completed or not.

So because promises are not being controlled from the collection methods, Promise.all cannot have a .sequence equivalent - a Promise.sequence would always need a tailored "iteratorAsync" function to go with it - just like reduce so no net savings of lines of code are gained .

[epoberezkin]

I agree in general that desire to have serial equivalent comes from callbacks world.
But there is an important difference between reduce and "Promise.seq", "mapSeq" etc. iteratorAsync does not come form nowhere - it is usually a function that already exists (or can be made with promisify) and does something useful; it often already takes one parameter and returns a promise (and even if it takes more than one parameter it can be transformed with partial application) .
On the other hand, the function for reduce is almost always specially constructed, as its signature is defined by reduce and dictated by the task of collecting multiple values into one.
And while reduce can be adapted for a different task, namely "chaining" promises generated by the same function using array of parameters, it feels unnatural to use it for such purpose and will always cause additional anonymous function that is never defined.
But it is ok. Case closed.
If you reconsider, I'm happy to implement. Seq's (or whatever you would call it) presence would definitely simplify adoption of promises by callback-minded people who are unfortunately still a majority :).

[spion]

@epoberezkin, I agree with all you said, but I think there is a tradeoff there.

Before switching to promises, I used to use callbacks. At a certain point, I realized that there is no equivalent of mapSeries provided by most promise libraries, and I asked for it.

However, when I saw a simple implementation of mapSeries for the first time, I had a revelation. Oh wow, with promises, mapSeries is just a map over an array with an intermediate variable that makes sure operations are ordered correctly!

It really helped me grasp the power of promises. What I realized then is that their application is much broader than just simple arrays, and that having unfinished computations as values, (if done right) can provide endless flexibility in combining them.

If the library I picked then (Q) had a mapSeries eqivalent, I'm not sure that any of this would've happened. I don't think I would've seen the point of promises at all. I'd gloss over it, see the same old functions as in caolan's async, no improvements - why would I even use these when I can use caolan's async without any wrapping at all?

[epoberezkin]

Interesting. Usually it's the only way revelations happen - because of the lack of something :)

[ericclemmons]

Thank God I found this issue. I was under the impression that Promise.all was iterative. (I was .push'ing promises onto an Array, expecting sequential execution).

[yourcelf]

It's not just "callback-minded people" that need mapSeries-like operation. Sometimes the things you're doing just need to be run serially.

A real world example I've been working on today: a unit test that runs a promise chain a bunch of times, with different parameters each time. Something like:

for each parameterSet in testcases:
    run promise chain with parameterSet
done

Since a single shared state (a live server, database, etc) was being altered by each iteration of the promise chain, the tests couldn't run in parallel, or they'd trip each other up.

I'm happy with Promise.reduce as a way to accomplish what I wanted. But it's not a semantically accurate for what I'm doing -- someone reading my code will understand it less well, because I'm using reduce for the side effect of sequential iteration, rather than using it to produce a reduced value. Obviously this is not a major issue: but a mapSeries would make my code more semantially accurate and readable, and would've saved me 15 minutes of reading to figure out how to accomplish what I needed.

[ericclemmons]

Yes, the use-case is legitimate, so I'm not sure why the author is against it's implementation.

We have a lot of Promise.reduce (to perform series) and Promise.reduce alls to aggregate, so our code's actually less clear.

Luckily, we've been able to drop the library entirely by switching to --harmony and yield'ing the results.

Hopefully this semantic improvement lands for the rest of you guys, though!

[bendrucker]

@yourcelf For your case you have the concurrency option on map. There's also each which runs in order that can be used for side effects (the return values are not used). Sounds like each is what you need since you're running tests (i.e. the result of the callback should either be an exception or nothing).

This isn't a case of a legitimate need being refused for no reason. If you read through the pages of comments asking for a series or sequence method you'll see that most of the use cases are imagined and once you try to write real code it's not helpful.

[spion]

I've actually changed my mind regarding mapSeries. In practical everyday use in my code, there have been more cases where the mapping operation is done in series to avoid race conditions, compared to cases where there is a big benefit from parallelism. Unfortunately the concurrency option of .map is kinda ugly to read because its far from the start

things.map(function(item) {
  // do things with item
  // and then
  return result;
}, {concurrency: 1})

So yeah, I've often found myself wishing there was a mapSeries method.