✨for yield* each loops

[cowboyd]

Note: supersedes #727

Motivation

One of the design goals of Effection is to provide structured concurrency primitives that are very aligned with ordinary JavaScript and let libraries provide the higher abstractions based on those primitives. This is why we have Streams for AsyncIterables, and Subscription for AsyncIterator. What was missing was a natural way to consume streams that felt like the for await of loop.

Approach

This introduces the each() and each.next operations that let you consume any stream completely naturally.

for (let value of yield* each(stream)) {
  console.log(value);
  yield* each.next;
}

[neurosnap]

looks good to me! You mentioned previously that we might need to get the last item out of the iterable but I don't see a test/API for that in this PR?

[nandin-borjigin]

Can we change the iterate API to return Operation<AsyncIterable<T>> so that the consumer of each can do this

for await (const value of yield* each(stream)) {
   console.log(value)
}

It also removes the error-prone requirement of yield* each.next

[nandin-borjigin]

For implementation, we may move let current = yield* subscription.next() into the async iterator, and let [Symbol.asyncIterator]().next await for subscription.next() for each iteration.

[nandin-borjigin]

While, for await requires async keyword, which might be a huge pollution :(

[cowboyd]

Yeah, I think you hit the nail on the head. One of the problems that Effection solves is it heals the scar of sync/async present in everything in JavaScript. Function vs AsyncFunction, Symbol.iterator vs Symbol.asyncIterator, Symbol.dispose vs Symbol.asyncDispose

In Effection, there is no difference between how a synchronous operation in Effection and an async one because they all boil down to a continuation. Some continuations are resumed immediately, others after some ticks of runtime, but from the correctness of the program, it is immaterial.

[cowboyd]

looks good to me! You mentioned previously that we might need to get the last item out of the iterable but I don't see a test/API for that in this PR?

So unfortunately, there is no way to access the close value of an iterator or an async iterator via a for loop, so I was thinking we'd just replicate this behavior for now, and if we want to add an each.close operation later we can do it as a non-breaking change, but I was a bit nervous about it because right now, the iteration context only lives inside the for loop and nothing "leaks" out.