Web Streams API

[History]

버전	변경 사항
v21.0.0	더 이상 실험적이지 않습니다.
v18.0.0	이 API를 사용해도 더 이상 런타임 경고가 발생하지 않습니다.
v16.5.0	추가됨: v16.5.0

[Stable: 2 - 안정적]

Stable: 2 안정성: 2 - 안정적

WHATWG Streams Standard의 구현입니다.

개요

WHATWG Streams Standard (또는 "웹 스트림")는 스트리밍 데이터 처리를 위한 API를 정의합니다. 이는 Node.js Streams API와 유사하지만 나중에 등장했으며 여러 JavaScript 환경에서 스트리밍 데이터를 위한 "표준" API가 되었습니다.

다음과 같은 세 가지 주요 유형의 객체가 있습니다.

ReadableStream - 스트리밍 데이터의 소스를 나타냅니다.
WritableStream - 스트리밍 데이터의 대상을 나타냅니다.
TransformStream - 스트리밍 데이터 변환 알고리즘을 나타냅니다.

`ReadableStream` 예제

이 예제는 현재 performance.now() 타임스탬프를 1초마다 영원히 푸시하는 간단한 ReadableStream을 만듭니다. 비동기 반복기는 스트림에서 데이터를 읽는 데 사용됩니다.

ESMCJS

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

import {
  setInterval as every,
} from 'node:timers/promises';

import {
  performance,
} from 'node:perf_hooks';

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

for await (const value of stream)
  console.log(value);

const {
  ReadableStream,
} = require('node:stream/web');

const {
  setInterval: every,
} = require('node:timers/promises');

const {
  performance,
} = require('node:perf_hooks');

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

(async () => {
  for await (const value of stream)
    console.log(value);
})();

API

클래스: `ReadableStream`

[기록]

버전	변경 사항
v18.0.0	이 클래스가 이제 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

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

추가됨: v16.5.0

underlyingSource <Object>
- start <Function> ReadableStream이 생성될 때 즉시 호출되는 사용자 정의 함수입니다.
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- 반환: undefined 또는 undefined로 이행되는 프로미스.
- pull <Function> ReadableStream 내부 큐가 가득 차지 않았을 때 반복적으로 호출되는 사용자 정의 함수입니다. 작업은 동기 또는 비동기일 수 있습니다. 비동기인 경우 이전에 반환된 프로미스가 이행될 때까지 함수가 다시 호출되지 않습니다.
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- 반환: undefined로 이행되는 프로미스.
- cancel <Function> ReadableStream이 취소될 때 호출되는 사용자 정의 함수입니다.
- reason <any>
- 반환: undefined로 이행되는 프로미스.
- type <string> 'bytes' 또는 undefined여야 합니다.
- autoAllocateChunkSize <number> type이 'bytes'와 같을 때만 사용됩니다. 0이 아닌 값으로 설정하면 보기 버퍼가 ReadableByteStreamController.byobRequest에 자동으로 할당됩니다. 설정하지 않으면 스트림의 내부 큐를 사용하여 기본 판독기 ReadableStreamDefaultReader를 통해 데이터를 전송해야 합니다.
strategy <Object>
- highWaterMark <number> 배압이 적용되기 전의 최대 내부 큐 크기입니다.
- size <Function> 각 데이터 청크의 크기를 식별하는 데 사용되는 사용자 정의 함수입니다.
- chunk <any>
- 반환: <number>

`readableStream.locked`

추가된 버전: v16.5.0

유형: <boolean> 이 <ReadableStream>에 활성 판독기가 있으면 true로 설정됩니다.

readableStream.locked 속성은 기본적으로 false이며 스트림의 데이터를 소비하는 활성 판독기가 있는 동안 true로 전환됩니다.

`readableStream.cancel([reason])`

추가된 버전: v16.5.0

reason <any>
반환: 취소가 완료되면 undefined로 이행되는 프로미스.

`readableStream.getReader([options])`

추가된 버전: v16.5.0

options <Object>
- mode <string> 'byob' 또는 undefined
반환: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

ESMCJS

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);

readableStream.locked가 true가 되도록 합니다.

`readableStream.pipeThrough(transform[, options])`

추가된 버전: v16.5.0

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가 되도록 합니다.

ESMCJS

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: A

const {
  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
})();

`readableStream.pipeTo(destination[, options])`

Added in: v16.5.0

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로 이행되는 프로미스

파이프 작동이 활성인 동안 readableStream.locked가 true가 되게 합니다.

`readableStream.tee()`

[기록]

버전	변경 사항
v18.10.0, v16.18.0	읽을 수 있는 바이트 스트림 티 지원.
v16.5.0	Added in: v16.5.0

반환: <ReadableStream[]>

이 ReadableStream의 데이터가 전달될 새로운 <ReadableStream> 인스턴스 쌍을 반환합니다. 각 인스턴스는 동일한 데이터를 받게 됩니다.

readableStream.locked가 true가 되게 합니다.

`readableStream.values([options])`

Added in: v16.5.0

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());

비동기 반복

<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());

비동기 반복기는 <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]);

`ReadableStream.from(iterable)`

추가된 버전: v20.6.0

iterable <Iterable> Symbol.asyncIterator 또는 Symbol.iterator 반복기 프로토콜을 구현하는 객체입니다.

반복기에서 새 <ReadableStream>을 만드는 유틸리티 메서드입니다.

ESMCJS

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

async function* asyncIterableGenerator() {
  yield 'a';
  yield 'b';
  yield 'c';
}

const stream = ReadableStream.from(asyncIterableGenerator());

for await (const chunk of stream)
  console.log(chunk); // Prints: 'a', 'b', 'c'

const { ReadableStream } = require('node:stream/web');

async function* asyncIterableGenerator() {
  yield 'a';
  yield 'b';
  yield 'c';
}

(async () => {
  const stream = ReadableStream.from(asyncIterableGenerator());

  for await (const chunk of stream)
    console.log(chunk); // Prints: 'a', 'b', 'c'
})();

클래스: `ReadableStreamDefaultReader`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

기본적으로, 인수 없이 readableStream.getReader()를 호출하면 ReadableStreamDefaultReader의 인스턴스가 반환됩니다. 기본 리더는 스트림을 통해 전달되는 데이터 청크를 불투명한 값으로 취급하여 <ReadableStream>이 일반적으로 모든 JavaScript 값과 함께 작동할 수 있도록 합니다.

`new ReadableStreamDefaultReader(stream)`

추가됨: v16.5.0

stream <ReadableStream>

주어진 <ReadableStream>에 잠긴 새로운 <ReadableStreamDefaultReader>를 생성합니다.

`readableStreamDefaultReader.cancel([reason])`

추가됨: v16.5.0

reason <any>
반환: undefined로 이행되는 프로미스.

<ReadableStream>을 취소하고 기본 스트림이 취소되었을 때 이행되는 프로미스를 반환합니다.

`readableStreamDefaultReader.closed`

추가됨: v16.5.0

유형: <Promise> 연결된 <ReadableStream>이 닫힐 때 undefined로 이행되거나 스트림 오류가 발생하거나 스트림이 닫히기 전에 리더의 잠금이 해제되면 거부됩니다.

`readableStreamDefaultReader.read()`

추가됨: v16.5.0

반환: 객체로 이행되는 프로미스:
- value <any>
- done <boolean>

기본 <ReadableStream>에서 다음 데이터 청크를 요청하고 사용 가능해지면 데이터로 이행되는 프로미스를 반환합니다.

`readableStreamDefaultReader.releaseLock()`

Added in: v16.5.0

기본 <ReadableStream>에서 이 리더의 잠금을 해제합니다.

Class: `ReadableStreamBYOBReader`

[History]

Version	Changes
v18.0.0	이 클래스가 이제 전역 객체에 노출됩니다.
v16.5.0	Added in: v16.5.0

ReadableStreamBYOBReader는 바이트 지향 <ReadableStream>에 대한 대안적인 소비자입니다 (<ReadableStream>이 생성될 때 underlyingSource.type이 'bytes'로 설정되어 생성된 스트림).

BYOB는 "bring your own buffer"의 약자입니다. 이는 불필요한 복사를 피하면서 바이트 지향 데이터를 보다 효율적으로 읽을 수 있도록 하는 패턴입니다.

import {
  open,
} from 'node:fs/promises';

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

import { Buffer } from 'node:buffer';

class Source {
  type = 'bytes';
  autoAllocateChunkSize = 1024;

  async start(controller) {
    this.file = await open(new URL(import.meta.url));
    this.controller = controller;
  }

  async pull(controller) {
    const view = controller.byobRequest?.view;
    const {
      bytesRead,
    } = await this.file.read({
      buffer: view,
      offset: view.byteOffset,
      length: view.byteLength,
    });

    if (bytesRead === 0) {
      await this.file.close();
      this.controller.close();
    }
    controller.byobRequest.respond(bytesRead);
  }
}

const stream = new ReadableStream(new Source());

async function read(stream) {
  const reader = stream.getReader({ mode: 'byob' });

  const chunks = [];
  let result;
  do {
    result = await reader.read(Buffer.alloc(100));
    if (result.value !== undefined)
      chunks.push(Buffer.from(result.value));
  } while (!result.done);

  return Buffer.concat(chunks);
}

const data = await read(stream);
console.log(Buffer.from(data).toString());

`new ReadableStreamBYOBReader(stream)`

Added in: v16.5.0

stream <ReadableStream>

주어진 <ReadableStream>에 잠긴 새 ReadableStreamBYOBReader를 만듭니다.

`readableStreamBYOBReader.cancel([reason])`

Added in: v16.5.0

reason <any>
반환: undefined로 이행되는 Promise를 반환합니다.

<ReadableStream>을 취소하고, 기본 스트림이 취소되었을 때 이행되는 Promise를 반환합니다.

`readableStreamBYOBReader.closed`

Added in: v16.5.0

타입: <Promise> 연결된 <ReadableStream>이 닫히면 undefined로 이행되고, 스트림에 오류가 발생하거나 스트림이 닫히기 전에 리더의 잠금이 해제되면 거부됩니다.

`readableStreamBYOBReader.read(view[, options])`

[History]

Version	Changes
v21.7.0, v20.17.0	`min` 옵션이 추가되었습니다.
v16.5.0	Added in: v16.5.0

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는 모든 풀링된 Buffer 인스턴스의 모든 데이터를 포함하는 공유 기본 <ArrayBuffer> 객체를 사용합니다. Buffer, <TypedArray> 또는 <DataView>가 readableStreamBYOBReader.read()에 전달되면 뷰의 기본 ArrayBuffer가 분리되어 해당 ArrayBuffer에 존재할 수 있는 기존 뷰가 모두 무효화됩니다. 이는 애플리케이션에 치명적인 결과를 초래할 수 있습니다.

`readableStreamBYOBReader.releaseLock()`

Added in: v16.5.0

기본 <ReadableStream>에 대한 이 판독기의 잠금을 해제합니다.

클래스: `ReadableStreamDefaultController`

Added in: v16.5.0

모든 <ReadableStream>에는 스트림 큐의 내부 상태 및 관리를 담당하는 컨트롤러가 있습니다. ReadableStreamDefaultController는 바이트 지향이 아닌 ReadableStream에 대한 기본 컨트롤러 구현입니다.

`readableStreamDefaultController.close()`

Added in: v16.5.0

이 컨트롤러가 연결된 <ReadableStream>을 닫습니다.

`readableStreamDefaultController.desiredSize`

Added in: v16.5.0

유형: <number>

<ReadableStream> 큐를 채우는 데 남은 데이터 양을 반환합니다.

`readableStreamDefaultController.enqueue([chunk])`

Added in: v16.5.0

chunk <any>

<ReadableStream> 큐에 새로운 데이터 청크를 추가합니다.

`readableStreamDefaultController.error([error])`

Added in: v16.5.0

error <any>

<ReadableStream>에서 오류가 발생하여 닫히도록 하는 오류를 알립니다.

클래스: `ReadableByteStreamController`

[기록]

버전	변경 사항
v18.10.0	릴리스된 판독기에서 BYOB 풀 요청 처리를 지원합니다.
v16.5.0	Added in: v16.5.0

모든 <ReadableStream>에는 스트림 큐의 내부 상태 및 관리를 담당하는 컨트롤러가 있습니다. ReadableByteStreamController는 바이트 지향 ReadableStream을 위한 것입니다.

`readableByteStreamController.byobRequest`

Added in: v16.5.0

유형: <ReadableStreamBYOBRequest>

`readableByteStreamController.close()`

Added in: v16.5.0

이 컨트롤러가 연결된 <ReadableStream>을 닫습니다.

`readableByteStreamController.desiredSize`

Added in: v16.5.0

유형: <number>

<ReadableStream>의 큐를 채우기 위해 남아 있는 데이터 양을 반환합니다.

`readableByteStreamController.enqueue(chunk)`

Added in: v16.5.0

chunk: <Buffer> | <TypedArray> | <DataView>

새로운 데이터 청크를 <ReadableStream>의 큐에 추가합니다.

`readableByteStreamController.error([error])`

Added in: v16.5.0

error <any>

<ReadableStream>을 오류 발생시키고 닫히게 하는 오류를 알립니다.

클래스: `ReadableStreamBYOBRequest`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	Added in: v16.5.0

바이트 지향 스트림에서 ReadableByteStreamController를 사용하고 ReadableStreamBYOBReader를 사용할 때, readableByteStreamController.byobRequest 속성은 현재 읽기 요청을 나타내는 ReadableStreamBYOBRequest 인스턴스에 대한 액세스를 제공합니다. 이 객체는 채우기 위해 읽기 요청에 제공된 ArrayBuffer/TypedArray에 대한 액세스를 얻고 데이터가 제공되었음을 알리는 메서드를 제공하는 데 사용됩니다.

`readableStreamBYOBRequest.respond(bytesWritten)`

추가된 버전: v16.5.0

bytesWritten <number>

bytesWritten 바이트 수가 readableStreamBYOBRequest.view에 쓰여졌음을 알립니다.

`readableStreamBYOBRequest.respondWithNewView(view)`

추가된 버전: v16.5.0

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

새 Buffer, TypedArray 또는 DataView에 쓰여진 바이트로 요청이 완료되었음을 알립니다.

`readableStreamBYOBRequest.view`

추가된 버전: v16.5.0

유형: <Buffer> | <TypedArray> | <DataView>

클래스: `WritableStream`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가된 버전: v16.5.0

WritableStream은 스트림 데이터가 전송되는 대상입니다.

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

const stream = new WritableStream({
  write(chunk) {
    console.log(chunk);
  },
});

await stream.getWriter().write('Hello World');

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

추가된 버전: v16.5.0

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])`

추가된 버전: v16.5.0

reason <any>
반환값: undefined로 이행되는 프로미스.

WritableStream을 갑자기 종료합니다. 대기열에 있는 모든 쓰기가 취소되고 관련 프로미스가 거부됩니다.

`writableStream.close()`

추가된 버전: v16.5.0

반환값: undefined로 이행되는 프로미스.

더 이상 쓰기가 예상되지 않을 때 WritableStream을 닫습니다.

`writableStream.getWriter()`

추가된 버전: v16.5.0

반환값: <WritableStreamDefaultWriter>

WritableStream에 데이터를 쓰는 데 사용할 수 있는 새 writer 인스턴스를 만들고 반환합니다.

`writableStream.locked`

추가된 버전: v16.5.0

유형: <boolean>

writableStream.locked 속성은 기본적으로 false이며, 이 WritableStream에 연결된 활성 writer가 있는 동안 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]);

클래스: `WritableStreamDefaultWriter`

[히스토리]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가된 버전: v16.5.0

`new WritableStreamDefaultWriter(stream)`

추가된 버전: v16.5.0

stream <WritableStream>

지정된 WritableStream에 잠긴 새 WritableStreamDefaultWriter를 만듭니다.

`writableStreamDefaultWriter.abort([reason])`

추가된 버전: v16.5.0

reason <any>
반환값: undefined로 이행되는 프로미스.

WritableStream을 갑자기 종료합니다. 대기열에 있는 모든 쓰기가 취소되고 관련 프로미스가 거부됩니다.

`writableStreamDefaultWriter.close()`

추가된 버전: v16.5.0

반환값: undefined로 이행되는 Promise.

추가 쓰기가 예상되지 않을 때 WritableStream을 닫습니다.

`writableStreamDefaultWriter.closed`

추가된 버전: v16.5.0

타입: <Promise> 연결된 <WritableStream>이 닫힐 때 undefined로 이행되거나 스트림 오류가 발생하거나 스트림이 닫히기 전에 작성기의 잠금이 해제되면 거부됩니다.

`writableStreamDefaultWriter.desiredSize`

추가된 버전: v16.5.0

타입: <number>

<WritableStream>의 큐를 채우는 데 필요한 데이터 양입니다.

`writableStreamDefaultWriter.ready`

추가된 버전: v16.5.0

타입: <Promise> 작성기를 사용할 준비가 되면 undefined로 이행됩니다.

`writableStreamDefaultWriter.releaseLock()`

추가된 버전: v16.5.0

기본 <ReadableStream>에 대한 이 작성기의 잠금을 해제합니다.

`writableStreamDefaultWriter.write([chunk])`

추가된 버전: v16.5.0

chunk: <any>
반환값: undefined로 이행되는 Promise.

<WritableStream>의 큐에 새로운 데이터 청크를 추가합니다.

클래스: `WritableStreamDefaultController`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가된 버전: v16.5.0

WritableStreamDefaultController는 <WritableStream>의 내부 상태를 관리합니다.

`writableStreamDefaultController.error([error])`

추가된 버전: v16.5.0

error <any>

사용자 코드가 WritableStream 데이터를 처리하는 동안 오류가 발생했음을 알리기 위해 호출됩니다. 호출되면 <WritableStream>이 중단되고 현재 보류 중인 쓰기가 취소됩니다.

`writableStreamDefaultController.signal`

유형: <AbortSignal> <WritableStream>이 중단될 때 보류 중인 쓰기 또는 닫기 작업을 취소하는 데 사용할 수 있는 AbortSignal입니다.

클래스: `TransformStream`

[기록]

버전	변경 사항
v18.0.0	이제 이 클래스는 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

TransformStream은 <ReadableStream>과 <WritableStream>으로 구성되며, WritableStream에 쓰여진 데이터가 수신되어 잠재적으로 변환된 후 ReadableStream의 큐에 푸시되도록 연결되어 있습니다.

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

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

await Promise.all([
  transform.writable.getWriter().write('A'),
  transform.readable.getReader().read(),
]);

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

추가됨: v16.5.0

transformer <Object>
- start <Function> TransformStream이 생성될 때 즉시 호출되는 사용자 정의 함수입니다.
- controller <TransformStreamDefaultController>
- 반환: undefined 또는 undefined로 이행된 프로미스
- transform <Function> transformStream.writable에 쓰여진 데이터 청크를 수신하고 잠재적으로 수정하여 transformStream.readable로 전달하기 전에 수행하는 사용자 정의 함수입니다.
- chunk <any>
- controller <TransformStreamDefaultController>
- 반환: undefined로 이행된 프로미스.
- flush <Function> TransformStream의 쓰기 가능한 측면이 닫히기 직전에 호출되어 변환 프로세스의 끝을 알리는 사용자 정의 함수입니다.
- controller <TransformStreamDefaultController>
- 반환: undefined로 이행된 프로미스.
- 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`

Added in: v16.5.0

유형: <ReadableStream>

`transformStream.writable`

Added in: v16.5.0

유형: <WritableStream>

postMessage()를 사용하여 전송하기

<TransformStream> 인스턴스는 <MessagePort>를 사용하여 전송할 수 있습니다.

const stream = new TransformStream();

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

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

port2.postMessage(stream, [stream]);

클래스: `TransformStreamDefaultController`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

TransformStreamDefaultController는 TransformStream의 내부 상태를 관리합니다.

`transformStreamDefaultController.desiredSize`

Added in: v16.5.0

유형: <number>

읽기 가능한 쪽 큐를 채우는 데 필요한 데이터 양입니다.

`transformStreamDefaultController.enqueue([chunk])`

Added in: v16.5.0

chunk <any>

읽기 가능한 쪽 큐에 데이터 청크를 추가합니다.

`transformStreamDefaultController.error([reason])`

Added in: v16.5.0

reason <any>

변환 데이터를 처리하는 동안 오류가 발생했음을 읽기 가능 및 쓰기 가능 양쪽에 신호를 보내 양쪽이 갑자기 닫히도록 합니다.

`transformStreamDefaultController.terminate()`

Added in: v16.5.0

전송의 읽기 가능한 쪽을 닫고 쓰기 가능한 쪽이 오류와 함께 갑자기 닫히도록 합니다.

클래스: `ByteLengthQueuingStrategy`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

`new ByteLengthQueuingStrategy(init)`

Added in: v16.5.0

init <Object>
- highWaterMark <number>

`byteLengthQueuingStrategy.highWaterMark`

Added in: v16.5.0

유형: <number>

`byteLengthQueuingStrategy.size`

Added in: v16.5.0

유형: <Function>
- chunk <any>
- 반환: <number>

Class: `CountQueuingStrategy`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가됨: v16.5.0

`new CountQueuingStrategy(init)`

Added in: v16.5.0

init <Object>
- highWaterMark <number>

`countQueuingStrategy.highWaterMark`

Added in: v16.5.0

유형: <number>

`countQueuingStrategy.size`

Added in: v16.5.0

유형: <Function>
- chunk <any>
- 반환: <number>

Class: `TextEncoderStream`

[기록]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.6.0	추가됨: v16.6.0

`new TextEncoderStream()`

Added in: v16.6.0

새로운 TextEncoderStream 인스턴스를 생성합니다.

`textEncoderStream.encoding`

Added in: v16.6.0

Type: <string>

TextEncoderStream 인스턴스에서 지원하는 인코딩입니다.

`textEncoderStream.readable`

Added in: v16.6.0

Type: <ReadableStream>

`textEncoderStream.writable`

Added in: v16.6.0

Type: <WritableStream>

Class: `TextDecoderStream`

[기록]

버전	변경 사항
v18.0.0	이제 이 클래스가 전역 객체에 노출됩니다.
v16.6.0	Added in: v16.6.0

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

Added in: v16.6.0

encoding <string> 이 TextDecoder 인스턴스에서 지원하는 encoding을 식별합니다. 기본값: 'utf-8'.
options <Object>
- fatal <boolean> 디코딩 실패가 치명적인 경우 true입니다.
- ignoreBOM <boolean> true인 경우 TextDecoderStream은 디코딩된 결과에 바이트 순서 표시를 포함합니다. false인 경우 바이트 순서 표시는 출력에서 제거됩니다. 이 옵션은 encoding이 'utf-8', 'utf-16be' 또는 'utf-16le'인 경우에만 사용됩니다. 기본값: false.

새로운 TextDecoderStream 인스턴스를 생성합니다.

`textDecoderStream.encoding`

Added in: v16.6.0

Type: <string>

TextDecoderStream 인스턴스에서 지원하는 인코딩입니다.

`textDecoderStream.fatal`

Added in: v16.6.0

Type: <boolean>

디코딩 오류로 인해 TypeError가 발생하는 경우 값은 true가 됩니다.

`textDecoderStream.ignoreBOM`

Added in: v16.6.0

Type: <boolean>

디코딩 결과에 바이트 순서 표시가 포함될 경우 값은 true가 됩니다.

`textDecoderStream.readable`

Added in: v16.6.0

Type: <ReadableStream>

`textDecoderStream.writable`

Added in: v16.6.0

Type: <WritableStream>

Class: `CompressionStream`

[기록]

버전	변경 사항
v18.0.0	이제 이 클래스가 전역 객체에 노출됩니다.
v17.0.0	Added in: v17.0.0

`new CompressionStream(format)`

[기록]

버전	변경 사항
v21.2.0, v20.12.0	이제 format에서 `deflate-raw` 값을 허용합니다.
v17.0.0	Added in: v17.0.0

format <string> 'deflate', 'deflate-raw', 또는 'gzip' 중 하나입니다.

`compressionStream.readable`

Added in: v17.0.0

Type: <ReadableStream>

`compressionStream.writable`

Added in: v17.0.0

Type: <WritableStream>

Class: `DecompressionStream`

[기록]

버전	변경 사항
v18.0.0	이제 이 클래스가 전역 객체에 노출됩니다.
v17.0.0	Added in: v17.0.0

`new DecompressionStream(format)`

[기록]

버전	변경 사항
v21.2.0, v20.12.0	이제 format에서 `deflate-raw` 값을 허용합니다.
v17.0.0	Added in: v17.0.0

format <string> 'deflate', 'deflate-raw', 또는 'gzip' 중 하나입니다.

`decompressionStream.readable`

Added in: v17.0.0

Type: <ReadableStream>

`decompressionStream.writable`

Added in: v17.0.0

Type: <WritableStream>

유틸리티 소비자

추가된 버전: v16.7.0

유틸리티 소비자 함수는 스트림을 소비하기 위한 일반적인 옵션을 제공합니다.

다음과 같이 접근할 수 있습니다.

ESMCJS

import {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} from 'node:stream/consumers';

const {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} = require('node:stream/consumers');

`streamConsumers.arrayBuffer(stream)`

추가된 버전: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
반환: <Promise> 스트림의 전체 내용을 포함하는 ArrayBuffer로 이행됩니다.

ESMCJS

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: 76

const { 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
});

`streamConsumers.blob(stream)`

추가된 버전: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
반환: <Promise> 스트림의 전체 내용을 포함하는 <Blob>으로 이행됩니다.

ESMCJS

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: 27

const { 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
});

`streamConsumers.buffer(stream)`

추가됨: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
반환: <Promise> 스트림의 전체 내용을 담은 <Buffer>로 이행됩니다.

ESMCJS

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: 27

const { 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
});

`streamConsumers.json(stream)`

추가됨: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
반환: <Promise> 스트림의 내용을 UTF-8로 인코딩된 문자열로 파싱한 다음 JSON.parse()를 통과시킨 결과로 이행됩니다.

ESMCJS

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: 100

const { 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
});

`streamConsumers.text(stream)`

추가된 버전: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
반환: <Promise> UTF-8 인코딩 문자열로 구문 분석된 스트림의 내용으로 이행됩니다.

ESMCJS

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: 27

const { 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
});

Web Streams API ​

개요 ​

ReadableStream 예제 ​

API ​

클래스: ReadableStream ​

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

readableStream.locked ​

readableStream.cancel([reason]) ​

readableStream.getReader([options]) ​

readableStream.pipeThrough(transform[, options]) ​

readableStream.pipeTo(destination[, options]) ​

readableStream.tee() ​

readableStream.values([options]) ​

비동기 반복 ​

postMessage()로 전송하기 ​

ReadableStream.from(iterable) ​

클래스: ReadableStreamDefaultReader ​

new ReadableStreamDefaultReader(stream) ​

readableStreamDefaultReader.cancel([reason]) ​

readableStreamDefaultReader.closed ​

readableStreamDefaultReader.read() ​

readableStreamDefaultReader.releaseLock() ​

Class: ReadableStreamBYOBReader ​

new ReadableStreamBYOBReader(stream) ​

readableStreamBYOBReader.cancel([reason]) ​

readableStreamBYOBReader.closed ​

readableStreamBYOBReader.read(view[, options]) ​

readableStreamBYOBReader.releaseLock() ​

클래스: ReadableStreamDefaultController ​

readableStreamDefaultController.close() ​

readableStreamDefaultController.desiredSize ​

readableStreamDefaultController.enqueue([chunk]) ​

readableStreamDefaultController.error([error]) ​

클래스: ReadableByteStreamController ​

readableByteStreamController.byobRequest ​

readableByteStreamController.close() ​

readableByteStreamController.desiredSize ​

readableByteStreamController.enqueue(chunk) ​

readableByteStreamController.error([error]) ​

클래스: ReadableStreamBYOBRequest ​

readableStreamBYOBRequest.respond(bytesWritten) ​

readableStreamBYOBRequest.respondWithNewView(view) ​

readableStreamBYOBRequest.view ​

클래스: WritableStream ​

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

writableStream.abort([reason]) ​

writableStream.close() ​

writableStream.getWriter() ​

writableStream.locked ​

postMessage()를 사용한 전송 ​

클래스: WritableStreamDefaultWriter ​

new WritableStreamDefaultWriter(stream) ​

writableStreamDefaultWriter.abort([reason]) ​

writableStreamDefaultWriter.close() ​

writableStreamDefaultWriter.closed ​

writableStreamDefaultWriter.desiredSize ​

writableStreamDefaultWriter.ready ​

writableStreamDefaultWriter.releaseLock() ​

writableStreamDefaultWriter.write([chunk]) ​

클래스: WritableStreamDefaultController ​

writableStreamDefaultController.error([error]) ​

writableStreamDefaultController.signal ​

클래스: TransformStream ​

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

transformStream.readable ​

transformStream.writable ​

postMessage()를 사용하여 전송하기 ​

클래스: TransformStreamDefaultController ​

transformStreamDefaultController.desiredSize ​

transformStreamDefaultController.enqueue([chunk]) ​

transformStreamDefaultController.error([reason]) ​

transformStreamDefaultController.terminate() ​

클래스: ByteLengthQueuingStrategy ​

new ByteLengthQueuingStrategy(init) ​

byteLengthQueuingStrategy.highWaterMark ​

byteLengthQueuingStrategy.size ​

Class: CountQueuingStrategy ​

new CountQueuingStrategy(init) ​

countQueuingStrategy.highWaterMark ​

countQueuingStrategy.size ​

Web Streams API

개요

`ReadableStream` 예제

API

클래스: `ReadableStream`

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

`readableStream.locked`

`readableStream.cancel([reason])`

`readableStream.getReader([options])`

`readableStream.pipeThrough(transform[, options])`

`readableStream.pipeTo(destination[, options])`

`readableStream.tee()`

`readableStream.values([options])`

비동기 반복

`postMessage()`로 전송하기

`ReadableStream.from(iterable)`

클래스: `ReadableStreamDefaultReader`

`new ReadableStreamDefaultReader(stream)`

`readableStreamDefaultReader.cancel([reason])`

`readableStreamDefaultReader.closed`

`readableStreamDefaultReader.read()`

`readableStreamDefaultReader.releaseLock()`

Class: `ReadableStreamBYOBReader`

`new ReadableStreamBYOBReader(stream)`

`readableStreamBYOBReader.cancel([reason])`

`readableStreamBYOBReader.closed`

`readableStreamBYOBReader.read(view[, options])`

`readableStreamBYOBReader.releaseLock()`

클래스: `ReadableStreamDefaultController`

`readableStreamDefaultController.close()`

`readableStreamDefaultController.desiredSize`

`readableStreamDefaultController.enqueue([chunk])`

`readableStreamDefaultController.error([error])`

클래스: `ReadableByteStreamController`

`readableByteStreamController.byobRequest`

`readableByteStreamController.close()`

`readableByteStreamController.desiredSize`

`readableByteStreamController.enqueue(chunk)`

`readableByteStreamController.error([error])`

클래스: `ReadableStreamBYOBRequest`

`readableStreamBYOBRequest.respond(bytesWritten)`

`readableStreamBYOBRequest.respondWithNewView(view)`

`readableStreamBYOBRequest.view`

클래스: `WritableStream`

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

`writableStream.abort([reason])`

`writableStream.close()`

`writableStream.getWriter()`

`writableStream.locked`

postMessage()를 사용한 전송

클래스: `WritableStreamDefaultWriter`

`new WritableStreamDefaultWriter(stream)`

`writableStreamDefaultWriter.abort([reason])`

`writableStreamDefaultWriter.close()`

`writableStreamDefaultWriter.closed`

`writableStreamDefaultWriter.desiredSize`

`writableStreamDefaultWriter.ready`

`writableStreamDefaultWriter.releaseLock()`

`writableStreamDefaultWriter.write([chunk])`

클래스: `WritableStreamDefaultController`

`writableStreamDefaultController.error([error])`

`writableStreamDefaultController.signal`

클래스: `TransformStream`

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

`transformStream.readable`

`transformStream.writable`

postMessage()를 사용하여 전송하기

클래스: `TransformStreamDefaultController`

`transformStreamDefaultController.desiredSize`

`transformStreamDefaultController.enqueue([chunk])`

`transformStreamDefaultController.error([reason])`

`transformStreamDefaultController.terminate()`

클래스: `ByteLengthQueuingStrategy`

`new ByteLengthQueuingStrategy(init)`

`byteLengthQueuingStrategy.highWaterMark`

`byteLengthQueuingStrategy.size`

Class: `CountQueuingStrategy`

`new CountQueuingStrategy(init)`

`countQueuingStrategy.highWaterMark`

`countQueuingStrategy.size`