I am confused between promiseBuffer.iterator.next(value) and promiseBuffer.generator.yield(value)

[domenic]

I imagine if I went and thought about it for a bit I'd see the difference, but having it spelled out would be quite helpful. They both seem like ways to "put things in the buffer."

There is a paragraph saying they are "duals," without explaining what that means practically, and when you would use each, or which parties in a system would use each.

[kriskowal]

Yes, and this is an interesting problem. If we renamed next to yield and add return to the iterator side, they will be completely symmetric, like message ports, and which you give to the producer and which you give to the consumer would be irrelevant. However, generally data flows one way and a bunch of promises that resolve to undefined flow the other direction to indicate relief of pressure. I’ll have to find a place to elaborate on that.

[domenic]

If we renamed next to yield and add return to the iterator side, they will be completely symmetric, like message ports, and which you give to the producer and which you give to the consumer would be irrelevant.

That is very interesting...

[kriskowal]

I should also make a note to self to rant about how each of the DOM things like message ports are and are not like their platonic ideals. There are a lot of DOM things that have the same interfaces but vary in whether they are streams or pubsub, lossy or buffered. Consider the postMessage on window. This is clearly more like Ethernet than TCP, requiring any meaningful communication to be mediated by various protocols that hope not to step on each other’s toes.

[kriskowal]

New sketch of Stream uses a symmetric Reader/Writer interface, using yield and next interchangeably, and all applicable sketches use the revealing constructor pattern. I also added a paragraph to discuss this speciality of promise buffers transporting objects.

I am doing a sketch of byte streams that does not have this symmetry. In this sketch, a byte buffer transports bytes forward and promises for undefined when there is memory available in the buffer backward. Additionally, ignoring back-pressure will get you an error. The buffer uses next/yield to signal that the previous next/yield segment of the circular buffer can be reused. All in the name of zero-copy. Of course, you can pipe the more abstract stream into a byte buffer, or pipe chunks out of a byte stream into the more abstract stream (but must take a snapshot!).