@eight/promise-streams

Promise-based wrappers around Node.js streams, so stream consumers and producers can be written as plain async code.

Install

npm install @eight/promise-streams

Requires Node.js 24 or newer. The package is private to the @eight scope, so npm needs a read token for it.

Usage

Reading a stream with await

import { PromiseStreams } from "@eight/promise-streams";

const reader = PromiseStreams.toPromise(process.stdin);
let chunk;
while ((chunk = await reader.read()) !== undefined) {
    // chunk is whatever the stream emits; undefined means end of stream
}

toPromise returns a PromiseReadStream, a PromiseWriteStream or both (a PromiseStream) depending on whether the Node stream is readable, writable or duplex. Stream errors surface as rejections of the pending read() / write(); pass an ErrorTransform as the second argument to wrap them.

Writing with backpressure

const writer = PromiseStreams.toPromise(fs.createWriteStream("out.bin"));
await writer.write(buffer); // resolves once the chunk has been accepted by the stream

Going back to a Node stream

const readable = PromiseStreams.toStream(promiseReadStream); // Readable in object mode

Binary helpers

• ExactReader reads exactly n bytes at a time from a PromiseReadStream<Buffer>, buffering across chunk boundaries and throwing on an unexpected end of stream.
• BufferedReader wraps a Readable and resolves each read() once at least minBuffered bytes are available or timeoutMillis has elapsed, coalescing small chunks.

Development

npm ci
npm run lint    # eslint + prettier --check
npm run build   # lint + tsc to build/
npm test        # compiles the tests and runs ava under nyc
npm run format  # prettier --write

Releasing

Bump version in package.json and add a CHANGELOG entry. On merge to master, Codefresh runs the tests, tags the commit with the version, and the tag-triggered GitHub Actions workflow publishes to npm via OIDC Trusted Publishing. Codefresh's verify_publish step confirms the version appeared on the registry.