Suggestion: update docs to indicate "async generators" support

[getify]

I found Highland while searching for stream library support for native JS async generators (like async function *main(..) { .. }) and thus async-iteration. It seems from looking at the code and previous commits that these are supported when passing to the _(..) stream constructor, but the docs don't really make that clear.

The docs mention support for "Iterator" (from normal generators), but not "AsyncIterator"... that is, where the .next(..) call returns Promise<IteratorResult>.

I would suggest including mention of this support, including code examples, to reduce future confusion.

[maxdumas]

Is this true? It makes sense that this would be the case, and either way I imagine it would be trivial to support. As a TypeScript user, it would be great if the Typescript bindings supported an AsyncIterable as input, so that we could maintain good generics that we lose if using Readable.from.

[orept]

@getify can you please give an example of using async generator as a source?

I'm using a generator function to iterate over it, but it hangs sometimes for some reason

_(async (push) => {
  for await (const item of getItems() /* <--------- async generator */) {
    push(null, item)
  }
})

[getify]

@orept I think your same example except make the async arrow function an async generator (non arrow). You wouldn't use yield, but you'd still use the await.

To be clear, I don't necessarily see an advantage of using the async generator over the async function, except that the wider support is just generally more flexible.

Of course, any non-Highland aware async generator has to be "adapted" via an async function and for..await loop (as your code shows), so that yield is wired to push. So... not really that helpful.

Maybe the only benefit is just stylistic consistency if all your other functions are already async generators. Shrugs.

In any case, I don't use Highland myself... just ran across it years ago while doing research. Closing the issue now since it seems to be lost to time. :)