externally iterable sequences (aka: asynquence "generators")

[getify]

Normal asynquence sequences are internally iterable, that is, each step of the sequence gets its own completion trigger to advance the sequence iteration to the next step.

However, there's also a need for an asynquence sequence to be externally iterable. That is, have a sequence of steps set up, where the control-flow for advancing the sequence is outside the sequence. For instance, a for-of loop, or other such things, which advance a queue of steps.

The question is, should all sequences be both internally and externally iterable, or should there be two different kinds of sequences, one for each.

IOW:

var steps = ASQ()
.then(function(done){
   // step 1
})
.then(function(done){
  // step 2
});

For that sequence, should you be able to do something like:

steps.next();
steps.next();

The problem with that is if you externally advance a sequence and that step itself has a completion trigger, it's kind of a race to see who goes first, and you could accidentally advance.

---

By contrast, you could construct separate sequence types, for iterables, like:

var steps = ASQ.iterable()
.then(function(msg){
  // step 1
  // return a message instead of sending it on
})
.then(function(msg){
  // step 2
});

In this way, the iterable sequence is only controllable externally (no done triggers), so each step doesn't get a completion trigger as it normally would.

This would make the sequence basically like a generator (indeed it might end up someday implemented with them).

Instead of step 1 passing a message onto step 2 directly, it looks like:

var ret1 = steps.next("step 1");

steps.next(ret1.value); // pass the output message from step-1 onto step-2

For consistency/compatibility sake, the return value from next() would always be an object of { value: ..., done: true/false } format, just like with normal generators. The value is any return value from the function, and done is if the sequence currently has no more steps registered on it.

Obviously, an iterable sequence would not have all the other API methods/helpers that normal internal sequences do, such as gate(), seq() and val(), as they don't make any sense in this usage context. It would only have then() for steps, and or() for error handling.

Like generators, you could do steps.throw(..) to throw an error at the sequence at that current step. Or, inside a step, throwing an error (intentionally or not) would be caught and propagated into the or() handlers of the sequence.

Need to investigate best approach/design ideas for this. Thoughts welcomed.