---
id: wiki-2026-0508-스트림-stream
title: 스트림(Stream)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [stream, streaming]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [stream, async, io]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: nodejs
---

# 스트림(Stream)

## 매 한 줄
> **"매 데이터를 chunk 단위로 점진 전달한다"**. 매 entire payload 를 buffer 에 fully load 하지 않고, 매 사용 가능한 시점마다 chunk 를 yield → 매 memory footprint 감소 + first-byte latency 개선. 매 modern web (Server-Sent Events · LLM token streaming · HTTP/2 push) 의 backbone.

## 매 핵심

### 매 Stream 의 종류
- **Readable**: pull-based source (file read, HTTP response).
- **Writable**: push-based sink (file write, response.write).
- **Duplex**: read + write (TCP socket).
- **Transform**: read → mutate → write (gzip, JSON.parse).

### 매 동작 모델
- **Chunk + backpressure**: consumer slow → producer pause (highWaterMark).
- **Object mode**: chunk 가 raw bytes 가 아닌 object.
- **Pipe**: source.pipe(transform).pipe(sink) chain.

### 매 응용
1. LLM token streaming (Claude · GPT-5 의 SSE response).
2. Large file upload/download (Multipart, S3 multipart).
3. Real-time analytics (Kafka consumer).

## 💻 패턴

### Web Streams API (cross-platform)
```typescript
const response = await fetch("/api/llm");
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(value);
}
```

### Async iteration over Node stream
```typescript
import { createReadStream } from "node:fs";
const stream = createReadStream("big.log", { encoding: "utf-8" });
for await (const chunk of stream) {
  console.log(`got ${chunk.length} chars`);
}
```

### Transform stream — gzip on the fly
```typescript
import { pipeline } from "node:stream/promises";
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";
await pipeline(createReadStream("input.txt"), createGzip(), createWriteStream("output.gz"));
```

### Server-Sent Events (LLM token stream)
```typescript
// Hono / Bun
import { streamSSE } from "hono/streaming";
app.get("/chat", c => streamSSE(c, async stream => {
  for await (const tok of llm.generate(prompt)) {
    await stream.writeSSE({ data: tok });
  }
}));
```

### ReadableStream from generator
```typescript
function makeStream<T>(gen: AsyncGenerator<T>) {
  return new ReadableStream<T>({
    async pull(controller) {
      const { value, done } = await gen.next();
      done ? controller.close() : controller.enqueue(value);
    }
  });
}
```

### Backpressure handling
```typescript
const writable = createWriteStream("out.bin");
function writeChunk(buf: Buffer) {
  if (!writable.write(buf)) {
    return new Promise<void>(res => writable.once("drain", res));
  }
  return Promise.resolve();
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Browser fetch streaming | Web Streams API (`response.body`) |
| Node.js file/network | `node:stream` + async iter |
| LLM token stream | SSE or chunked transfer |
| Massive object pipeline | object mode + Transform |
| Cross-runtime (Bun/Deno) | Web Streams (standard) |

**기본값**: Web Streams API + async iteration.

## 🔗 Graph
- 부모: [[Nodejs 성능 최적화 및 디버깅]]
- Adjacent: [[API 응답 및 에러 핸들링 아키텍처]]
- 응용: [[Server Architecture]]

## 🤖 LLM 활용
**언제**: streaming chat UI · large file async processing · backpressure debug.
**언제 X**: small payload (<1MB) — buffering 이 simpler.

## ❌ 안티패턴
- **Concat all chunks before yielding**: stream 의 의미 무효화.
- **Ignore backpressure**: producer 가 consumer 추월 → memory blow up.
- **No error propagation in pipe**: 한 stage error 가 silent.
- **Sync transform on huge object**: event loop block.

## 🧪 검증 / 중복
- Verified (Node.js docs · WHATWG Streams Standard).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Stream API 패턴 정리 |