Document using TextDecoderStream

readme.md

@@ -114,7 +114,9 @@ try {
 }
 ```
 
-## Tip
+## Tips
+
+### `node:stream/consumers`
 
 If you do not need [`maxBuffer`](#maxbuffer) nor [`error.bufferedData`](#errors), you can use [`node:stream/consumers`](https://nodejs.org/api/webstreams.html#utility-consumers) instead of this package.
 
@@ -138,6 +140,23 @@ or:
 console.log(await arrayBuffer(stream))
 ```
 
+### Non-UTF-8 encoding
+
+When all of the following conditions apply:
+  - [`getStream()`](#getstreamstream-options) is used (as opposed to [`getStreamAsBuffer()`](#getstreamasbufferstream-options) or [`getStreamAsArrayBuffer()`](#getstreamasarraybufferstream-options))
+  - The stream is binary (not text)
+  - The stream's encoding is not UTF-8 (for example, it is UTF-16, hexadecimal, or Base64)
+
+Then the stream must be decoded using a transform stream like [`TextDecoderStream`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream) or [`b64`](https://github.com/hapijs/b64).
+
+```js
+import getStream from 'get-stream';
+
+const textDecoderStream = new TextDecoderStream('utf-16le');
+const {body: readableStream} = await fetch('https://example.com');
+console.log(await getStream(readableStream.pipeThrough(textDecoderStream)));
+```
+
 ## FAQ
 
 ### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)?

test.js

@@ -15,6 +15,7 @@ const fixtureTypedArray = new TextEncoder().encode(fixtureString);
 const fixtureArrayBuffer = fixtureTypedArray.buffer;
 const fixtureUint16Array = new Uint16Array(fixtureArrayBuffer);
 const fixtureDataView = new DataView(fixtureArrayBuffer);
+const fixtureUtf16 = Buffer.from(fixtureString, 'utf-16le');
 
 const fixtureStringWide = `  ${fixtureString}  `;
 const fixtureTypedArrayWide = new TextEncoder().encode(fixtureStringWide);
@@ -283,6 +284,16 @@ if (!nodeVersion.startsWith('v16.')) {
 		const parsedResult = JSON.parse(result);
 		t.true(Array.isArray(parsedResult));
 	});
+
+	test('can use TextDecoderStream', async t => {
+		// @todo Remove the following comment when dropping support for Node 16
+		// eslint-disable-next-line no-undef
+		const textDecoderStream = new TextDecoderStream('utf-16le');
+		const result = await getStream(
+			createReadableStream(fixtureUtf16).pipeThrough(textDecoderStream),
+		);
+		t.is(result, fixtureString);
+	});
 }
 
 test('native string', async t => {