Duplex와 Transform — 두 방향을 잇는 스트림

"Duplex는 읽기와 쓰기를 한 객체에 담고, Transform은 그 두 방향을 변환 규칙으로 이어. 모양은 비슷하지만 데이터가 흐르는 까닭은 달라."

Duplex에는 독립된 입구와 출구가 있어

Duplex 스트림은 읽기 쪽과 쓰기 쪽을 함께 제공해. 하지만 쓴 데이터가 반드시 읽기 쪽으로 돌아오는 건 아냐. 두 방향이 같은 자원을 공유할 뿐 서로 독립적으로 움직일 수 있어.

네트워크 소켓이 대표적인 예야. 쓰기 쪽으로 요청 바이트를 보내고 읽기 쪽에서 응답 바이트를 받아. 둘은 같은 TCP 연결 위에 있지만, 나가는 흐름과 들어오는 흐름은 별개지. 자식 프로세스와 주고받는 표준 입출력도 같은 관점으로 볼 수 있어.

import { createConnection } from 'node:net';

const socket = createConnection({ host: 'example.com', port: 80 });
socket.write('GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');

for await (const chunk of socket) {
  process.stdout.write(chunk);
}

Transform은 입력과 출력을 규칙으로 연결해

Transform도 읽기와 쓰기를 모두 제공하지만, 안으로 들어온 데이터가 정해진 변환을 거쳐 밖으로 나와. 압축기는 원본 바이트를 받아 압축 바이트를 내보내고, 암호화 스트림은 평문을 받아 암호문을 내보내.

• zlib.createGzip()은 원본을 gzip 형식으로 압축해.
• zlib.createGunzip()은 gzip 바이트를 다시 풀어.
• crypto.createHash('sha256')는 들어온 데이터로 해시를 계산해.
• crypto.createCipheriv(...)는 평문을 암호문으로 바꿔.

이 단계를 pipeline()으로 이으면 파일을 읽는 동안 압축하고 암호화해 바로 보낼 수 있어. 입력 전체를 중간 배열에 쌓지 않아도 각 단계가 자기 청크만 처리해.

사용자 정의 Transform은 완료 신호가 핵심이야

import { Transform } from 'node:stream';

class UppercaseUtf8 extends Transform {
  _transform(chunk, _encoding, callback) {
    const upper = chunk.toString('utf8').toUpperCase();
    callback(null, upper);
  }
}

process.stdin
  .pipe(new UppercaseUtf8())
  .pipe(process.stdout);

객체 모드로 구조화된 값을 흘려보내

객체 모드의 Transform은 청크를 바이트가 아니라 JavaScript 값으로 다뤄. 줄 분리기는 바이트를 문자열 한 줄씩 바꾸고, CSV 파서는 문자열을 행 객체로 바꾸며, 필터는 조건에 맞는 객체만 다음 단계로 보내.

import { Transform } from 'node:stream';

class ParseCsvRow extends Transform {
  constructor() {
    super({ objectMode: true });
    this.columns = null;
  }

  _transform(line, _encoding, callback) {
    const fields = String(line).split(',');
    if (!this.columns) {
      this.columns = fields;
      callback();
      return;
    }
    callback(null, Object.fromEntries(
      this.columns.map((column, index) => [column, fields[index]])
    ));
  }
}

한 단계가 맡는 변환을 작게 유지하면 CSV 대신 JSONL을 읽게 바꿔도 필터와 저장 단계는 그대로 둘 수 있어. 스트림은 메모리 사용을 줄이는 도구이면서 처리 책임을 분리하는 조립 도구이기도 해.

Pippa의 고백