Web Streams API

[History]

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

[안정적: 2 - 안정적]

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

WHATWG Streams 표준의 구현입니다.

개요

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

세 가지 주요 유형의 객체가 있습니다.

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

예시 `ReadableStream`

이 예시는 현재 performance.now() 타임스탬프를 매초마다 무한정 푸시하는 간단한 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>에 활성 reader가 있는 경우 true로 설정됩니다.

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

`readableStream.cancel([reason])`

추가된 버전: v16.5.0

reason <any>
반환값: 취소가 완료되면 undefined로 채워지는 promise입니다.

`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)
// 출력: 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)
  // 출력: A
})()

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

추가된 버전: 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	추가된 버전: v16.5.0

반환 값: <ReadableStream[]>

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

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

`readableStream.values([options])`

추가된 버전: 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>에 대한 이 판독기의 잠금을 해제합니다.

클래스: `ReadableStreamBYOBReader`

[기록]

버전	변경 사항
v18.0.0	이제 이 클래스가 전역 객체에 노출됩니다.
v16.5.0	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]

버전	변경 사항
v21.7.0, v20.17.0	`min` 옵션 추가.
v16.5.0	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()`

추가된 버전: v16.5.0

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

클래스: `ReadableStreamDefaultController`

추가된 버전: v16.5.0

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

`readableStreamDefaultController.close()`

추가된 버전: v16.5.0

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

`readableStreamDefaultController.desiredSize`

추가된 버전: v16.5.0

유형: <number>

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

`readableStreamDefaultController.enqueue([chunk])`

추가된 버전: v16.5.0

chunk <any>

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

`readableStreamDefaultController.error([error])`

추가된 버전: v16.5.0

error <any>

<ReadableStream>에 오류를 발생시키고 닫히도록 하는 오류를 신호합니다.

클래스: `ReadableByteStreamController`

[기록]

버전	변경 사항
v18.10.0	릴리스된 리더로부터의 BYOB 풀 요청 처리를 지원합니다.
v16.5.0	추가된 버전: v16.5.0

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

`readableByteStreamController.byobRequest`

추가된 버전: v16.5.0

유형: <ReadableStreamBYOBRequest>

`readableByteStreamController.close()`

추가된 버전: v16.5.0

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

`readableByteStreamController.desiredSize`

추가된 버전: v16.5.0

유형: <number>

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

`readableByteStreamController.enqueue(chunk)`

추가된 버전: v16.5.0

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

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

`readableByteStreamController.error([error])`

추가된 버전: v16.5.0

error <any>

<ReadableStream>을 에러 상태로 만들고 닫게 만드는 에러를 알립니다.

클래스: `ReadableStreamBYOBRequest`

[히스토리]

버전	변경 사항
v18.0.0	이 클래스는 이제 전역 객체에 노출됩니다.
v16.5.0	추가된 버전: 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 옵션은 나중에 사용할 목적으로 예약되어 있으며 반드시 정의되지 않아야 합니다.
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에 데이터를 쓰는 데 사용할 수 있는 새로운 작성기 인스턴스를 생성하여 반환합니다.

`writableStream.locked`

추가된 버전: v16.5.0

유형: <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])

클래스: `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()`

Added in: v16.5.0

반환 값: undefined로 이행된 Promise입니다.

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

`writableStreamDefaultWriter.closed`

Added in: v16.5.0

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

`writableStreamDefaultWriter.desiredSize`

Added in: v16.5.0

유형: <number>

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

`writableStreamDefaultWriter.ready`

Added in: v16.5.0

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

`writableStreamDefaultWriter.releaseLock()`

Added in: v16.5.0

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

`writableStreamDefaultWriter.write([chunk])`

Added in: v16.5.0

chunk: <any>
반환 값: undefined로 이행된 Promise입니다.

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

Class: `WritableStreamDefaultController`

[기록]

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

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

`writableStreamDefaultController.error([error])`

Added in: v16.5.0

error <any>

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

`writableStreamDefaultController.signal`

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

클래스: `TransformStream`

[기록]

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

TransformStream은 WritableStream에 작성된 데이터를 수신하고 잠재적으로 변환한 후 ReadableStream의 대기열로 푸시하도록 연결된 <ReadableStream>과 <WritableStream>으로 구성됩니다.

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로 충족된 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`

Added in: v16.5.0

Type: <ReadableStream>

`transformStream.writable`

Added in: v16.5.0

Type: <WritableStream>

postMessage()를 사용한 전송

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

const stream = new TransformStream()

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Class: `TransformStreamDefaultController`

[기록]

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

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

`transformStreamDefaultController.desiredSize`

Added in: v16.5.0

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

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

Class: `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

Type: <number>

`byteLengthQueuingStrategy.size`

Added in: v16.5.0

Type: <Function>
- chunk <any>
- Returns: <number>

Class: `CountQueuingStrategy`

[History]

Version	Changes
v18.0.0	This class is now exposed on the global object.
v16.5.0	Added in: v16.5.0

`new CountQueuingStrategy(init)`

Added in: v16.5.0

init <Object>
- highWaterMark <number>

`countQueuingStrategy.highWaterMark`

Added in: v16.5.0

Type: <number>

`countQueuingStrategy.size`

Added in: v16.5.0

Type: <Function>
- chunk <any>
- Returns: <number>

Class: `TextEncoderStream`

[History]

Version	Changes
v18.0.0	This class is now exposed on the global object.
v16.6.0	Added in: v16.6.0

`new TextEncoderStream()`

추가된 버전: v16.6.0

새로운 TextEncoderStream 인스턴스를 만듭니다.

`textEncoderStream.encoding`

추가된 버전: v16.6.0

타입: <string>

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

`textEncoderStream.readable`

추가된 버전: v16.6.0

타입: <ReadableStream>

`textEncoderStream.writable`

추가된 버전: v16.6.0

타입: <WritableStream>

클래스: `TextDecoderStream`

[기록]

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

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

추가된 버전: 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`

추가된 버전: v16.6.0

타입: <string>

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

`textDecoderStream.fatal`

추가된 버전: v16.6.0

타입: <boolean>

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

`textDecoderStream.ignoreBOM`

추가된 버전: v16.6.0

유형: <boolean>

디코딩 결과에 바이트 순서 표시가 포함되면 값이 true가 됩니다.

`textDecoderStream.readable`

추가된 버전: v16.6.0

유형: <ReadableStream>

`textDecoderStream.writable`

추가된 버전: v16.6.0

유형: <WritableStream>

클래스: `CompressionStream`

[기록]

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

`new CompressionStream(format)`

[기록]

버전	변경 사항
v21.2.0, v20.12.0	format은 이제 `deflate-raw` 값을 허용합니다.
v17.0.0	추가된 버전: v17.0.0

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

`compressionStream.readable`

추가된 버전: v17.0.0

유형: <ReadableStream>

`compressionStream.writable`

추가된 버전: v17.0.0

유형: <WritableStream>

클래스: `DecompressionStream`

[기록]

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

`new DecompressionStream(format)`

[기록]

버전	변경 사항
v21.2.0, v20.12.0	format은 이제 `deflate-raw` 값을 허용합니다.
v17.0.0	추가된 버전: v17.0.0

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

`decompressionStream.readable`

추가된 버전: v17.0.0

유형: <ReadableStream>

`decompressionStream.writable`

추가된 버전: v17.0.0

유형: <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}`)
// 출력: 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}`)
  // 출력: 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}`)
// 출력: 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}`)
  // 출력: 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() ​

클래스: 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]) ​

Class: WritableStreamDefaultController ​

writableStreamDefaultController.error([error]) ​

writableStreamDefaultController.signal ​

클래스: TransformStream ​

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

transformStream.readable ​

transformStream.writable ​

postMessage()를 사용한 전송 ​

Class: TransformStreamDefaultController ​

transformStreamDefaultController.desiredSize ​

transformStreamDefaultController.enqueue([chunk]) ​

transformStreamDefaultController.error([reason]) ​

transformStreamDefaultController.terminate() ​

Class: 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()`

클래스: `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])`

Class: `WritableStreamDefaultController`

`writableStreamDefaultController.error([error])`

`writableStreamDefaultController.signal`

클래스: `TransformStream`

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

`transformStream.readable`

`transformStream.writable`

postMessage()를 사용한 전송

Class: `TransformStreamDefaultController`

`transformStreamDefaultController.desiredSize`

`transformStreamDefaultController.enqueue([chunk])`

`transformStreamDefaultController.error([reason])`

`transformStreamDefaultController.terminate()`

Class: `ByteLengthQueuingStrategy`

`new ByteLengthQueuingStrategy(init)`

`byteLengthQueuingStrategy.highWaterMark`

`byteLengthQueuingStrategy.size`

Class: `CountQueuingStrategy`

`new CountQueuingStrategy(init)`

`countQueuingStrategy.highWaterMark`

`countQueuingStrategy.size`