Add Java [Streams] to Prior Art

[nikolaybotev]

Could you please add Java Streams to the prior art, as IMO this is the prior art closest in shape to this proposal?

The high-level structure of Iterator Helpers is almost exactly like that of Java Streams and Java Streams has outstanding documentation which describes it perfectly in one sentence at the very start:

Stream operations are divided into intermediate and terminal operations, and are combined to form stream pipelines. A stream pipeline consists of a source (such as a Collection, an array, a generator function, or an I/O channel); followed by zero or more intermediate operations such as Stream.filter or Stream.map; and a terminal operation such as Stream.forEach or Stream.reduce.

• https://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html

Iterator helpers also belong to the two groups of intermediate and terminal operations, with terminal operations being the ones that trigger the start of evaluation of the entire pipeline.

Descriptions of this logical structure of Iterator Helpers is currently lacking in the JavaScript space - the separation of source, intermediate operations and terminal operations is not mentioned here or on MDN or in the jsdoc of the Iterator Helper typescript type definitions. A careful observer, however, would note that the typescript type definitions for the Iterator Helper methods are appropriately grouped by type of operation (@bakkot ?) - intermediate operations are listed first, then terminal operations. So the understanding of this logical structure certainly exists here among those working on this proposal.

I personally remember that having this logical structure helped me a lot when learning the Java Streams API years ago when it first came out. It was an invaluable aid to build a mental model and understanding around the lazy nature of Java Streams.

If this logical structure, which also applies to Iterator Helpers, is brought to light in the documentation, starting with this proposal, it could ease learning and adoption of Iterator Helpers by the next generation of users many of whom would not be familiar with Java Streams.

Understanding this logical structure is especially relevant here, where we have multiple terminal operations. Unlike the purely functional reactiveX protocol where essentially there is only one terminal operation -- subscribe, here it is important to think of the distinction between terminal and intermediate operations while learning the API.

Even in rxjs, the subscribe method docs start with this anecdoe:

Use it when you have all these Observables, but still nothing is happening.

• https://rxjs.dev/api/index/class/Observable#subscribe

Many users who are used to calling Array.map and see .map in another context, would likely be surprised that nothing happens as a result of invoking .map. Making the type of operation a first-class citizen - here, in the MDN docs, in the jsdocs etc, tagging the function as an Intermediate operation could be the fastest hint for confused new users to learning how to correctly use the new API.

—

Parallel streams capabilities can also be implemented in JavaScript the future based on workers/tasks etc or whatever means of parallel evaluation is or becomes available in JavaScript. This can be built by extending the Iterator class, which makes this proposal a great foundation for further development.