Node.js v25.0.0 文件

new ReadableStream([underlyingSource [, strategy]])#

• underlyingSource <Object>
  • start <Function> 一個使用者定義的函式，在 ReadableStream 建立時立即被呼叫。
    • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
    • 返回：undefined 或一個解析為 undefined 的 promise。
  • pull <Function> 一個使用者定義的函式，當 ReadableStream 內部佇列未滿時會重複呼叫。此操作可以是同步或非同步的。如果是非同步的，直到前一個返回的 promise 被兌現後，該函式才會再次被呼叫。
    • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
    • 返回：一個解析為 undefined 的 promise。
  • cancel <Function> 一個使用者定義的函式，當 ReadableStream 被取消時呼叫。
    • reason <any>
    • 返回：一個解析為 undefined 的 promise。
  • type <string> 必須是 'bytes' 或 undefined。
  • autoAllocateChunkSize <number> 僅在 type 等於 'bytes' 時使用。當設定為非零值時，會自動為 ReadableByteStreamController.byobRequest 分配一個檢視緩衝區。未設定時，必須使用流的內部佇列透過預設讀取器 ReadableStreamDefaultReader 來傳輸資料。
• strategy <Object>
  • highWaterMark <number> 在施加背壓之前的最大內部佇列大小。
  • size <Function> 一個使用者定義的函式，用於確定每個資料塊的大小。
    • chunk <any>
    • 返回：<number>

readableStream.locked#

• 型別: <boolean> 如果此 <ReadableStream> 有一個活動的讀取器，則設定為 true。

readableStream.locked 屬性預設為 false，當有活動的讀取器消耗流資料時，會切換為 true。

readableStream.cancel([reason])#

• reason <any>
• 返回：一個在取消操作完成後解析為 undefined 的 promise。

readableStream.getReader([options])#

• options <Object>
  • mode <string> 'byob' 或 undefined
• 返回：<ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

import { ReadableStream } from 'node:stream/web';

const stream = new ReadableStream();

const reader = stream.getReader();

console.log(await reader.read());const { ReadableStream } = require('node:stream/web');

const stream = new ReadableStream();

const reader = stream.getReader();

reader.read().then(console.log);copy

使 readableStream.locked 變為 true。

readableStream.pipeThrough(transform[, options])#

• transform <Object>
  • readable <ReadableStream> transform.writable 會將從該 ReadableStream 接收到的可能已修改的資料推送到此 ReadableStream 中。
  • writable <WritableStream> 此 ReadableStream 的資料將被寫入的 WritableStream。
• options <Object>
  • preventAbort <boolean> 當為 true 時，此 ReadableStream 中的錯誤不會導致 transform.writable 被中止。
  • preventCancel <boolean> 當為 true 時，目標 transform.writable 中的錯誤不會導致此 ReadableStream 被取消。
  • preventClose <boolean> 當為 true 時，關閉此 ReadableStream 不會導致 transform.writable 被關閉。
  • signal <AbortSignal> 允許使用 <AbortController> 來取消資料傳輸。
• 返回：<ReadableStream> 來自 transform.readable。

將此 <ReadableStream> 連線到 transform 引數中提供的一對 <ReadableStream> 和 <WritableStream>，使得此 <ReadableStream> 的資料被寫入 transform.writable，可能經過轉換，然後推送到 transform.readable。一旦管道配置完成，將返回 transform.readable。

在管道操作期間，使 readableStream.locked 變為 true。

import {
  ReadableStream,
  TransformStream,
} from 'node:stream/web';

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a');
  },
});

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const transformedStream = stream.pipeThrough(transform);

for await (const chunk of transformedStream)
  console.log(chunk);
  // Prints: Aconst {
  ReadableStream,
  TransformStream,
} = require('node:stream/web');

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a');
  },
});

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const transformedStream = stream.pipeThrough(transform);

(async () => {
  for await (const chunk of transformedStream)
    console.log(chunk);
    // Prints: A
})();copy

readableStream.pipeTo(destination[, options])#

• destination <WritableStream> 此 ReadableStream 的資料將被寫入的 <WritableStream>。
• options <Object>
  • preventAbort <boolean> 當為 true 時，此 ReadableStream 中的錯誤不會導致 destination 被中止。
  • preventCancel <boolean> 當為 true 時，destination 中的錯誤不會導致此 ReadableStream 被取消。
  • preventClose <boolean> 當為 true 時，關閉此 ReadableStream 不會導致 destination 被關閉。
  • signal <AbortSignal> 允許使用 <AbortController> 來取消資料傳輸。
• 返回：一個解析為 undefined 的 promise

在管道操作期間，使 readableStream.locked 變為 true。

readableStream.tee()#

• 返回：<ReadableStream[]>

返回一對新的 <ReadableStream> 例項，此 ReadableStream 的資料將被轉發到這兩個例項中。每個例項將接收相同的資料。

使 readableStream.locked 變為 true。

readableStream.values([options])#

• options <Object>
  • preventCancel <boolean> 當為 true 時，可防止在非同步迭代器突然終止時關閉 <ReadableStream>。預設值：false。

建立並返回一個可用於消費此 ReadableStream 資料的非同步迭代器。

在非同步迭代器活動期間，使 readableStream.locked 變為 true。

import { Buffer } from 'node:buffer';

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream.values({ preventCancel: true }))
  console.log(Buffer.from(chunk).toString()); copy

非同步迭代#

<ReadableStream> 物件支援使用 for await 語法的非同步迭代器協議。

import { Buffer } from 'node:buffer';

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream)
  console.log(Buffer.from(chunk).toString()); copy

非同步迭代器將消費 <ReadableStream> 直到其終止。

預設情況下，如果非同步迭代器提前退出（透過 break、return 或 throw），<ReadableStream> 將被關閉。為防止自動關閉 <ReadableStream>，請使用 readableStream.values() 方法獲取非同步迭代器，並將 preventCancel 選項設定為 true。

<ReadableStream> 必須未被鎖定（即，它不能有已存在的活動讀取器）。在非同步迭代期間，<ReadableStream> 將被鎖定。

使用 postMessage() 傳輸#

一個 <ReadableStream> 例項可以使用 <MessagePort> 進行傳輸。

const stream = new ReadableStream(getReadableSourceSomehow());

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  data.getReader().read().then((chunk) => {
    console.log(chunk);
  });
};

port2.postMessage(stream, [stream]); copy

new ReadableStreamDefaultReader(stream)#

• stream <ReadableStream>

建立一個新的 <ReadableStreamDefaultReader>，並鎖定到給定的 <ReadableStream>。

readableStreamDefaultReader.cancel([reason])#

• reason <any>
• 返回：一個解析為 undefined 的 promise。

取消 <ReadableStream> 並返回一個在底層流被取消時兌現的 promise。

readableStreamDefaultReader.closed#

• 型別: <Promise> 當關聯的 <ReadableStream> 關閉時，解析為 undefined；如果流出錯或在流完成關閉前讀取器的鎖被釋放，則被拒絕。

readableStreamDefaultReader.read()#

• 返回：一個解析為物件的 promise
  • value <any>
  • done <boolean>

從底層的 <ReadableStream> 請求下一個資料塊，並返回一個在資料可用時解析為該資料的 promise。

readableStreamDefaultReader.releaseLock()#

釋放此讀取器對底層 <ReadableStream> 的鎖定。

new ReadableStreamBYOBReader(stream)#

• stream <ReadableStream>

建立一個新的 ReadableStreamBYOBReader，並鎖定到給定的 <ReadableStream>。

readableStreamBYOBReader.cancel([reason])#

• reason <any>
• 返回：一個解析為 undefined 的 promise。

取消 <ReadableStream> 並返回一個在底層流被取消時兌現的 promise。

readableStreamBYOBReader.closed#

• 型別: <Promise> 當關聯的 <ReadableStream> 關閉時，解析為 undefined；如果流出錯或在流完成關閉前讀取器的鎖被釋放，則被拒絕。

readableStreamBYOBReader.read(view[, options])#

• view <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • min <number> 設定後，返回的 promise 只有在至少有 min 個元素可用時才會被兌現。未設定時，promise 在至少有一個元素可用時兌現。
• 返回：一個解析為物件的 promise
  • value <TypedArray> | <DataView>
  • done <boolean>

從底層的 <ReadableStream> 請求下一個資料塊，並返回一個在資料可用時解析為該資料的 promise。

不要將池化的 <Buffer> 物件例項傳遞給此方法。池化的 Buffer 物件是使用 Buffer.allocUnsafe() 或 Buffer.from() 建立的，或者通常由各種 node:fs 模組的回撥返回。這些型別的 Buffer 使用共享的底層 <ArrayBuffer> 物件，該物件包含所有池化 Buffer 例項的資料。當一個 Buffer、<TypedArray> 或 <DataView> 傳遞到 readableStreamBYOBReader.read() 中時，檢視的底層 ArrayBuffer 會被分離，這會使該 ArrayBuffer 上的所有現有檢視失效。這可能會對您的應用程式造成災難性的後果。

readableStreamBYOBReader.releaseLock()#

釋放此讀取器對底層 <ReadableStream> 的鎖定。

readableStreamDefaultController.close()#

關閉與此控制器關聯的 <ReadableStream>。

readableStreamDefaultController.desiredSize#

• 型別：<number>

返回填滿 <ReadableStream> 佇列所需的剩餘資料量。

readableStreamDefaultController.enqueue([chunk])#

• chunk <any>

將一個新的資料塊附加到 <ReadableStream> 的佇列中。

readableStreamDefaultController.error([error])#

• error <any>

發出一個錯誤訊號，導致 <ReadableStream> 出錯並關閉。

readableByteStreamController.byobRequest#

• 型別：<ReadableStreamBYOBRequest>

readableByteStreamController.close()#

關閉與此控制器關聯的 <ReadableStream>。

readableByteStreamController.desiredSize#

• 型別：<number>

返回填滿 <ReadableStream> 佇列所需的剩餘資料量。

readableByteStreamController.enqueue(chunk)#

• chunk <Buffer> | <TypedArray> | <DataView>

將一個新的資料塊附加到 <ReadableStream> 的佇列中。

readableByteStreamController.error([error])#

• error <any>

發出一個錯誤訊號，導致 <ReadableStream> 出錯並關閉。

readableStreamBYOBRequest.respond(bytesWritten)#

• bytesWritten <number>

通知已有 bytesWritten 數量的位元組被寫入到 readableStreamBYOBRequest.view。

readableStreamBYOBRequest.respondWithNewView(view)#

• view <Buffer> | <TypedArray> | <DataView>

通知請求已透過寫入位元組到一個新的 Buffer、TypedArray 或 DataView 中來完成。

readableStreamBYOBRequest.view#

• 型別：<Buffer> | <TypedArray> | <DataView>

new WritableStream([underlyingSink[, strategy]])#

• underlyingSink <Object>
  • start <Function> 一個使用者定義的函式，在 WritableStream 建立時立即被呼叫。
    • controller <WritableStreamDefaultController>
    • 返回：undefined 或一個解析為 undefined 的 promise。
  • write <Function> 一個使用者定義的函式，當一個數據塊被寫入 WritableStream 時呼叫。
    • chunk <any>
    • controller <WritableStreamDefaultController>
    • 返回：一個解析為 undefined 的 promise。
  • close <Function> 一個使用者定義的函式，當 WritableStream 關閉時呼叫。
    • 返回：一個解析為 undefined 的 promise。
  • abort <Function> 一個使用者定義的函式，用於突然關閉 WritableStream。
    • reason <any>
    • 返回：一個解析為 undefined 的 promise。
  • type <any> type 選項為將來使用保留，並且必須為 undefined。
• strategy <Object>
  • highWaterMark <number> 在施加背壓之前的最大內部佇列大小。
  • size <Function> 一個使用者定義的函式，用於確定每個資料塊的大小。
    • chunk <any>
    • 返回：<number>

writableStream.abort([reason])#

• reason <any>
• 返回：一個解析為 undefined 的 promise。

突然終止 WritableStream。所有排隊的寫入都將被取消，並且其關聯的 promise 將被拒絕。

writableStream.close()#

• 返回：一個解析為 undefined 的 promise。

在預計沒有更多寫入時關閉 WritableStream。

writableStream.getWriter()#

• 返回：<WritableStreamDefaultWriter>

建立並返回一個新的寫入器例項，可用於將資料寫入 WritableStream。

writableStream.locked#

• 型別：<boolean>

writableStream.locked 屬性預設為 false，當有活動的寫入器附加到此 WritableStream 時，會切換為 true。

使用 postMessage() 傳輸#

一個 <WritableStream> 例項可以使用 <MessagePort> 進行傳輸。

const stream = new WritableStream(getWritableSinkSomehow());

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  data.getWriter().write('hello');
};

port2.postMessage(stream, [stream]); copy

new WritableStreamDefaultWriter(stream)#

• stream <WritableStream>

建立一個新的 WritableStreamDefaultWriter，並鎖定到給定的 WritableStream。

writableStreamDefaultWriter.abort([reason])#

• reason <any>
• 返回：一個解析為 undefined 的 promise。

突然終止 WritableStream。所有排隊的寫入都將被取消，並且其關聯的 promise 將被拒絕。

writableStreamDefaultWriter.close()#

• 返回：一個解析為 undefined 的 promise。

在預計沒有更多寫入時關閉 WritableStream。

writableStreamDefaultWriter.closed#

• 型別: <Promise> 當關聯的 <WritableStream> 關閉時，解析為 undefined；如果流出錯或在流完成關閉前寫入器的鎖被釋放，則被拒絕。

writableStreamDefaultWriter.desiredSize#

• 型別：<number>

填滿 <WritableStream> 佇列所需的資料量。

writableStreamDefaultWriter.ready#

• 型別: <Promise> 當寫入器準備好使用時，解析為 undefined。

writableStreamDefaultWriter.releaseLock()#

釋放此寫入器對底層 <ReadableStream> 的鎖定。

writableStreamDefaultWriter.write([chunk])#

• chunk <any>
• 返回：一個解析為 undefined 的 promise。

將一個新的資料塊附加到 <WritableStream> 的佇列中。

writableStreamDefaultController.error([error])#

• error <any>

由使用者程式碼呼叫，以通知在處理 WritableStream 資料時發生錯誤。呼叫時，<WritableStream> 將被中止，當前待處理的寫入將被取消。

writableStreamDefaultController.signal#

• 型別: <AbortSignal> 一個 AbortSignal，可用於在 <WritableStream> 被中止時取消待處理的寫入或關閉操作。

new TransformStream([transformer[, writableStrategy[, readableStrategy]]])#

• transformer <Object>
  • start <Function> 一個使用者定義的函式，在 TransformStream 建立時立即被呼叫。
    • controller <TransformStreamDefaultController>
    • 返回：undefined 或一個解析為 undefined 的 promise
  • transform <Function> 一個使用者定義的函式，接收並可能修改寫入 transformStream.writable 的資料塊，然後將其轉發到 transformStream.readable。
    • chunk <any>
    • controller <TransformStreamDefaultController>
    • 返回：一個解析為 undefined 的 promise。
  • flush <Function> 一個使用者定義的函式，在 TransformStream 的可寫側關閉之前立即呼叫，標誌著轉換過程的結束。
    • controller <TransformStreamDefaultController>
    • 返回：一個解析為 undefined 的 promise。
  • readableType <any> readableType 選項為將來使用保留，並且必須為 undefined。
  • writableType <any> writableType 選項為將來使用保留，並且必須為 undefined。
• writableStrategy <Object>
  • highWaterMark <number> 在施加背壓之前的最大內部佇列大小。
  • size <Function> 一個使用者定義的函式，用於確定每個資料塊的大小。
    • chunk <any>
    • 返回：<number>
• readableStrategy <Object>
  • highWaterMark <number> 在施加背壓之前的最大內部佇列大小。
  • size <Function> 一個使用者定義的函式，用於確定每個資料塊的大小。
    • chunk <any>
    • 返回：<number>

transformStream.readable#

• 型別: <ReadableStream>

transformStream.writable#

• 型別: <WritableStream>

使用 postMessage() 傳輸#

一個 <TransformStream> 例項可以使用 <MessagePort> 進行傳輸。

const stream = new TransformStream();

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  const { writable, readable } = data;
  // ...
};

port2.postMessage(stream, [stream]); copy

transformStreamDefaultController.desiredSize#

• 型別：<number>

填滿可讀側佇列所需的資料量。

transformStreamDefaultController.enqueue([chunk])#

• chunk <any>

將一個數據塊附加到可讀側的佇列中。

transformStreamDefaultController.error([reason])#

• reason <any>

向可讀和可寫兩側傳送訊號，通知在處理轉換資料時發生錯誤，導致兩側都被突然關閉。

transformStreamDefaultController.terminate()#

關閉傳輸的可讀側，並導致可寫側因錯誤而突然關閉。

new ByteLengthQueuingStrategy(init)#

• init <Object>
  • highWaterMark <number>

byteLengthQueuingStrategy.highWaterMark#

• 型別：<number>

byteLengthQueuingStrategy.size#

• 型別: <Function>
  • chunk <any>
  • 返回：<number>

new CountQueuingStrategy(init)#

• init <Object>
  • highWaterMark <number>

countQueuingStrategy.highWaterMark#

• 型別：<number>

countQueuingStrategy.size#

• 型別: <Function>
  • chunk <any>
  • 返回：<number>

new TextEncoderStream()#

建立一個新的 TextEncoderStream 例項。

textEncoderStream.encoding#

• 型別：<string>

TextEncoderStream 例項支援的編碼。

textEncoderStream.readable#

• 型別: <ReadableStream>

textEncoderStream.writable#

• 型別: <WritableStream>

new TextDecoderStream([encoding[, options]])#

• encoding <string> 標識此 TextDecoder 例項支援的 encoding。預設值： 'utf-8'。
• options <Object>
  • fatal <boolean> 如果解碼失敗是致命的，則為 true。
  • ignoreBOM <boolean> 當為 true 時，TextDecoderStream 將在解碼結果中包含位元組順序標記 (BOM)。當為 false 時，位元組順序標記將從輸出中移除。此選項僅在 encoding 為 'utf-8'、'utf-16be' 或 'utf-16le' 時使用。預設值： false。

建立一個新的 TextDecoderStream 例項。

textDecoderStream.encoding#

• 型別：<string>

TextDecoderStream 例項支援的編碼。

textDecoderStream.fatal#

• 型別：<boolean>

如果解碼錯誤會導致丟擲 TypeError，則該值為 true。

textDecoderStream.ignoreBOM#

• 型別：<boolean>

如果解碼結果將包含位元組順序標記，則該值為 true。

textDecoderStream.readable#

• 型別: <ReadableStream>

textDecoderStream.writable#

• 型別: <WritableStream>

new CompressionStream(format)#

• format <string> 'deflate'、'deflate-raw'、'gzip' 或 'brotli' 之一。

compressionStream.readable#

• 型別: <ReadableStream>

compressionStream.writable#

• 型別: <WritableStream>

new DecompressionStream(format)#

• format <string> 'deflate'、'deflate-raw'、'gzip' 或 'brotli' 之一。

decompressionStream.readable#

• 型別: <ReadableStream>

decompressionStream.writable#

• 型別: <WritableStream>

streamConsumers.arrayBuffer(stream)#

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• 返回：<Promise> 解析為一個包含流完整內容的 ArrayBuffer。

import { arrayBuffer } from 'node:stream/consumers';
import { Readable } from 'node:stream';
import { TextEncoder } from 'node:util';

const encoder = new TextEncoder();
const dataArray = encoder.encode('hello world from consumers!');

const readable = Readable.from(dataArray);
const data = await arrayBuffer(readable);
console.log(`from readable: ${data.byteLength}`);
// Prints: from readable: 76const { arrayBuffer } = require('node:stream/consumers');
const { Readable } = require('node:stream');
const { TextEncoder } = require('node:util');

const encoder = new TextEncoder();
const dataArray = encoder.encode('hello world from consumers!');
const readable = Readable.from(dataArray);
arrayBuffer(readable).then((data) => {
  console.log(`from readable: ${data.byteLength}`);
  // Prints: from readable: 76
});copy

streamConsumers.blob(stream)#

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• 返回：<Promise> 解析為一個包含流完整內容的 <Blob>。

import { blob } from 'node:stream/consumers';

const dataBlob = new Blob(['hello world from consumers!']);

const readable = dataBlob.stream();
const data = await blob(readable);
console.log(`from readable: ${data.size}`);
// Prints: from readable: 27const { blob } = require('node:stream/consumers');

const dataBlob = new Blob(['hello world from consumers!']);

const readable = dataBlob.stream();
blob(readable).then((data) => {
  console.log(`from readable: ${data.size}`);
  // Prints: from readable: 27
});copy

streamConsumers.buffer(stream)#

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• 返回：<Promise> 解析為一個包含流完整內容的 <Buffer>。

import { buffer } from 'node:stream/consumers';
import { Readable } from 'node:stream';
import { Buffer } from 'node:buffer';

const dataBuffer = Buffer.from('hello world from consumers!');

const readable = Readable.from(dataBuffer);
const data = await buffer(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27const { buffer } = require('node:stream/consumers');
const { Readable } = require('node:stream');
const { Buffer } = require('node:buffer');

const dataBuffer = Buffer.from('hello world from consumers!');

const readable = Readable.from(dataBuffer);
buffer(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});copy

streamConsumers.json(stream)#

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• 返回：<Promise> 解析為將流內容解析為 UTF-8 編碼字串，然後透過 JSON.parse() 處理後的結果。

import { json } from 'node:stream/consumers';
import { Readable } from 'node:stream';

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  }),
);

const readable = Readable.from(JSON.stringify(items));
const data = await json(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 100const { json } = require('node:stream/consumers');
const { Readable } = require('node:stream');

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  }),
);

const readable = Readable.from(JSON.stringify(items));
json(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 100
});copy

streamConsumers.text(stream)#

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• 返回：<Promise> 解析為將流內容解析為 UTF-8 編碼字串的結果。

import { text } from 'node:stream/consumers';
import { Readable } from 'node:stream';

const readable = Readable.from('Hello world from consumers!');
const data = await text(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27const { text } = require('node:stream/consumers');
const { Readable } = require('node:stream');

const readable = Readable.from('Hello world from consumers!');
text(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});copy