Document support for async iterables (#93)

index.d.ts

@@ -56,9 +56,20 @@ console.log(await getStream(stream));
 
 @example
 ```
+import getStream from 'get-stream';
+
 const {body: readableStream} = await fetch('https://example.com');
 console.log(await getStream(readableStream));
 ```
+
+@example
+```
+import {opendir} from 'node:fs/promises';
+import {getStreamAsArray} from 'get-stream';
+
+const asyncIterable = await opendir(directory);
+console.log(await getStreamAsArray(asyncIterable));
+```
 */
 export default function getStream(stream: AnyStream, options?: Options): Promise<string>;
 

readme.md

@@ -6,6 +6,7 @@
 
 - Works in any JavaScript environment ([Node.js](#nodejs-streams), [browsers](#web-streams), etc.).
 - Supports [text streams](#getstreamstream-options), [binary streams](#getstreamasbufferstream-options) and [object streams](#getstreamasarraystream-options).
+- Supports [async iterables](#async-iterables).
 - Can set a [maximum stream size](#maxbuffer).
 - Returns [partially read data](#errors) when the stream errors.
 
@@ -52,10 +53,22 @@ console.log(await getStream(stream));
 ### Web streams
 
 ```js
+import getStream from 'get-stream';
+
 const {body: readableStream} = await fetch('https://example.com');
 console.log(await getStream(readableStream));
 ```
 
+### Async iterables
+
+```js
+import {opendir} from 'node:fs/promises';
+import {getStreamAsArray} from 'get-stream';
+
+const asyncIterable = await opendir(directory);
+console.log(await getStreamAsArray(asyncIterable));
+```
+
 ## API
 
 The following methods read the stream's contents and return it as a promise.

test.js

@@ -2,7 +2,7 @@ import {Buffer, constants as BufferConstants} from 'node:buffer';
 import {setTimeout} from 'node:timers/promises';
 import {spawn} from 'node:child_process';
 import {createReadStream} from 'node:fs';
-import {open} from 'node:fs/promises';
+import {open, opendir} from 'node:fs/promises';
 import {version as nodeVersion} from 'node:process';
 import {Duplex} from 'node:stream';
 import {text, buffer, arrayBuffer} from 'node:stream/consumers';
@@ -334,6 +334,23 @@ test('Throws if the first argument is null', firstArgumentCheck, null);
 test('Throws if the first argument is a string', firstArgumentCheck, '');
 test('Throws if the first argument is an array', firstArgumentCheck, []);
 
+const generator = async function * () {
+	yield 'a';
+	await setTimeout(0);
+	yield 'b';
+};
+
+test('works with async iterable', async t => {
+	const result = await getStream(generator());
+	t.is(result, 'ab');
+});
+
+test('works with opendir()', async t => {
+	const directoryFiles = await opendir('.');
+	const entries = await getStreamAsArray(directoryFiles);
+	t.true(entries.some(({name}) => name === 'package.json'));
+});
+
 test('works with createReadStream() and buffers', async t => {
 	const result = await getStreamAsBuffer(createReadStream('fixture'));
 	t.true(result.equals(fixtureBuffer));