stream-to-push-stream/README.md

# @push-stream-std/stream-to-push-stream

Convert native Node.js streams to push-stream source, sink, and duplex interfaces.

Published as `@push-stream-std/stream-to-push-stream`.

## Synopsis

```js
import { source, sink, duplex } from '@push-stream-std/stream-to-push-stream';
import { Readable, Writable, Duplex } from 'node:stream';
import { PassThrough } from 'node:stream';

// Convert a Readable to a push-stream source
const readable = Readable.from(['a', 'b', 'c']);
const pushSource = source(readable);

const pushSink = {
  paused: false,
  write(v) { console.log(v); },
  end() { console.log('done'); }
};

pushSource.pipe(pushSink);
// Output: a, b, c, done

// Convert a Writable to a push-stream sink
const writable = new PassThrough();
const pushSink2 = sink(writable);

// Convert a Duplex to a push-stream source
const duplexStream = new PassThrough();
const pushSource2 = duplex(duplexStream);
```

## Install

```bash
npm config set @push-stream-std:registry https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/
npm config set -- //hub.kl1.tenere.ai/api/packages/push-stream-std/npm/:_authToken "$PACKAGE_TOKEN"
npm install @push-stream-std/stream-to-push-stream
```

## Why
Utilities for bridging between the Node.js `stream` module (Readable, Writable, Duplex) and the push-stream protocol. PushSource wraps a Readable, listening to `data`/`end`/`error` events and implementing `pipe()`, `resume()`, and `abort()`. PushSink wraps a Writable, translating `write()` calls to `writable.write()` with `drain`-based backpressure and `end()` to `writable.end()`. PushDuplex wraps a Duplex stream as a combined source/sink for bidirectional push-stream pipelines.

## API

### `source(readableStream)`

Converts a Node.js `Readable` to a push-stream source.

- **readableStream** `Readable` – A Node.js readable stream.
- **Returns** A push-stream source with `pipe()`, `resume()`, `abort()`, `paused`, and `ended`.

### `sink(writableStream)`

Converts a Node.js `Writable` to a push-stream sink.

- **writableStream** `Writable` – A Node.js writable stream.
- **Returns** A push-stream sink with `pipe()`, `write()`, `end()`, `abort()`, `paused`, and `ended`.

### `duplex(duplexStream)`

Wraps a Node.js `Duplex` stream as a push-stream source.

- **duplexStream** `Duplex` – A Node.js duplex stream.
- **Returns** A push-stream source with `pipe()`, `resume()`, `abort()`, `paused`, and `ended`.

## Tests

```bash
npm test
```

Tests cover readable-to-source data flow and end handling, writable-to-sink write and backpressure, duplex stream wrapping, error propagation, and abort cleanup.

## Requirements

Node.js 22 or later. ESM only.