buffer: implement blob.textStream()

Signed-off-by: Matthew Aitken <maitken033380023@gmail.com>
PR-URL: #64036
Refs: w3c/FileAPI@cd1d1da
Refs: nodejs/undici@0d6ecc5
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Mattias Buelens <mattias@buelens.com>

Author: KhafraDev

doc/api/buffer.md

@@ -593,6 +593,18 @@ added:
 Returns a promise that fulfills with the contents of the `Blob` decoded as a
 UTF-8 string.
 
+### `blob.textStream()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {ReadableStream}
+
+Returns a new `ReadableStream` that allows the content of the `Blob` to be read
+as a stream of UTF-8 decoded strings. It is equivalent to piping
+[`blob.stream()`][] through a [`TextDecoderStream`][] set up with UTF-8.
+
 ### `blob.type`
 
 <!-- YAML
@@ -5610,10 +5622,12 @@ introducing security vulnerabilities into an application.
 [`String.prototype.indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf
 [`String.prototype.lastIndexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf
 [`String.prototype.length`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length
+[`TextDecoderStream`]: webstreams.md#class-textdecoderstream
 [`TypedArray.from()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from
 [`TypedArray.prototype.set()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set
 [`TypedArray.prototype.slice()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/slice
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
+[`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries

lib/internal/blob.js

@@ -85,6 +85,7 @@ const kNotCloneable = Symbol('kNotCloneable');
 const disallowedTypeCharacters = /[^\u{0020}-\u{007E}]/u;
 
 let ReadableStream;
+let TextDecoderStream;
 
 const enc = new TextEncoder();
 let dec;
@@ -100,6 +101,13 @@ function lazyReadableStream(options) {
   return new ReadableStream(options);
 }
 
+function lazyTextDecoderStream() {
+  // eslint-disable-next-line no-global-assign
+  TextDecoderStream ??=
+    require('internal/webstreams/encoding').TextDecoderStream;
+  return new TextDecoderStream();
+}
+
 const { EOL } = require('internal/constants');
 
 function isBlob(object) {
@@ -325,6 +333,17 @@ class Blob {
       throw new ERR_INVALID_THIS('Blob');
     return createBlobReaderStream(this[kHandle].getReader());
   }
+
+  /**
+   * @returns {ReadableStream}
+   */
+  textStream() {
+    if (!isBlob(this))
+      throw new ERR_INVALID_THIS('Blob');
+    const stream = createBlobReaderStream(this[kHandle].getReader());
+    const decoder = lazyTextDecoderStream();
+    return stream.pipeThrough(decoder);
+  }
 }
 
 function TransferableBlob(handle, length, type = '') {
@@ -358,6 +377,7 @@ ObjectDefineProperties(Blob.prototype, {
   type: kEnumerableProperty,
   slice: kEnumerableProperty,
   stream: kEnumerableProperty,
+  textStream: kEnumerableProperty,
   text: kEnumerableProperty,
   arrayBuffer: kEnumerableProperty,
   bytes: kEnumerableProperty,

test/parallel/test-blob.js

@@ -3,7 +3,7 @@
 
 const common = require('../common');
 const assert = require('assert');
-const { Blob } = require('buffer');
+const { Blob, File } = require('buffer');
 const { inspect } = require('util');
 const { EOL } = require('os');
 const { kState } = require('internal/webstreams/util');
@@ -524,3 +524,22 @@ assert.throws(() => new Blob({}), {
     Blob.prototype.arrayBuffer = arrayBuffer;
   }
 })().then(common.mustCall());
+
+{
+  assert.strictEqual(typeof Blob.prototype.textStream, 'function');
+  assert.strictEqual(typeof File.prototype.textStream, 'function');
+  assert.strictEqual(File.prototype.textStream, Blob.prototype.textStream);
+}
+
+(async () => {
+  const smiley = Buffer.from('😀', 'utf8');
+  const blob = new Blob(['hello ', smiley.subarray(0, 2), smiley.subarray(2)]);
+  const stream = blob.textStream();
+  assert.ok(stream instanceof ReadableStream);
+  let result = '';
+  for await (const chunk of stream) {
+    assert.strictEqual(typeof chunk, 'string');
+    result += chunk;
+  }
+  assert.strictEqual(result, 'hello 😀');
+})().then(common.mustCall());