# awaitify-stream

> Read or write to a stream using while and await, not event handlers.

Latest version **1.0.2** (published 2018-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install awaitify-stream
pnpm add awaitify-stream
yarn add awaitify-stream
bun add awaitify-stream
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2018-09-23 |
| First published | 2017-10-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | hashtagchris |
| Maintainers | hashtagchris |
| Keywords | async, await, stream, read, write, readAsync, writeAsync, line-by-line |

## Links

- npm: https://www.npmjs.com/package/awaitify-stream
- Repository: https://github.com/hashtagchris/node-awaitify-stream
- Homepage: https://github.com/hashtagchris/node-awaitify-stream#readme
- Issues: https://github.com/hashtagchris/node-awaitify-stream/issues
- npm.io page: https://npm.io/package/awaitify-stream

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2018-09-23
- 1.0.1 — 2018-02-25
- 1.0.0 — 2017-11-19
- 0.8.1 — 2017-11-06
- 0.8.0 — 2017-11-06
- 0.1.2 — 2017-11-06
- 0.1.1 — 2017-10-29
- 0.1.0 — 2017-10-29

## README

# node-awaitify-stream
Read or write to a stream using `while` and `await`, not event handlers.

- Read and write streams using familiar constructs, without resorting to synchronous methods for I/O.
- Read and write long streams without runaway memory usage.
- Process streams one chunk or line at a time. Await asynchronous operations inbetween.

## Requirements

- Node v8+ recommended. `async`/`await` support was added to Node v7. Node v6 will throw "SyntaxError: Unexpected token function" for the examples below. See [secondExample_without_await.js](examples/secondExample_without_await.js) for an example of using awaitify-stream without `await`.

## Install

    npm install awaitify-stream

# Reader functions

- `readAsync([size])`: Promise wrapper around [readable.read](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_readable_read_size). Returns a promise for the next chunk of data. Resolves to null at the end of the stream.

# Writer functions

- `writeAsync(chunk[, encoding])`: Promise wrapper around [writable.write](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_writable_write_chunk_encoding_callback). Returns a promise that resolves following a `drain` event (if necessary) and a call to `write`. Doesn't wait for the chunk to be flushed.

- `endAsync([chunk][, encoding])`: Promise wrapper around [writable.end](https://nodejs.org/dist/latest-v8.x/docs/api/stream.html#stream_writable_end_chunk_encoding_callback). Returns a promise that resolves when the stream is finished.

# Reader/Writer API

Use `createReader`, `createWriter` or `createDuplexer` to create a wrapper around the stream. The `stream` property can be used to later access the stream.

```javascript
const fs = require('fs');
const aw = require('awaitify-stream');

async function run() {
    let readStream = fs.createReadStream('firstExample.js');
    let reader = aw.createReader(readStream);
    let writer = aw.createWriter(process.stdout);

    // Read the file and write it to stdout.
    let chunk, count = 0;
    while (null !== (chunk = await reader.readAsync())) {
        // Perform any synchronous or asynchronous operation here.
        await writer.writeAsync(chunk);
        count++;
    }

    console.log(`\n\nDone. Read the file in ${count} chunk(s).`);
}

run();
```

# Augment Stream API

Use `addAsyncFunctions` to add the reader and/or writer functions to a stream object. The reader functions are added if `stream.readable` is true. The writer functions are added if `stream.writable` is true.

```javascript
const fs = require('fs');
const aw = require('awaitify-stream');
const lineLength = 6; // 5 digits in a zip code, plus the newline character.

function delay(ms) {
    return new Promise((resolve) => {
        setTimeout(resolve, ms);
    });
}

async function run() {
    let stream = aw.addAsyncFunctions(fs.createReadStream('zipCodes.lftxt'));
    stream.setEncoding('utf8');

    // Read and print zip codes, slowly.
    let zipCode;
    while (null !== (zipCode = await stream.readAsync(lineLength))) {
        // Remove the newline character. If you didn't set the encoding
        // above, use zipCode.toString().trim()
        zipCode = zipCode.trim();

        console.log(zipCode);
        await delay(200);
    }
}

run();
```

# Line Reading

You can use `awaitify-stream` in combination with a package like `byline` to read a line at a time.

```javascript
const fs = require('fs');
const aw = require('awaitify-stream');
const byline = require('byline');
const readline = require('readline'); // Used for prompting the user.

function checkGuess(rl, guess) {
    return new Promise((resolve) => {
        rl.question(`Is the ${guess} your card? [y/n] `, (answer) => {
            resolve(answer.startsWith('y'));
        });
    });
}

async function run() {
    let stream = fs.createReadStream('millionsOfGuesses.txt');
    stream.setEncoding('utf8');

    let lineStream = byline.createStream(stream, { keepEmptyLines: false });
    let reader = aw.createReader(lineStream);

    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout
    });

    try {
        let line;
        while (null !== (line = await reader.readAsync())) {
            let guessedCard = await checkGuess(rl, line);

            if (guessedCard) {
                console.log('Huzzah!');
                return;
            }
        }

        console.log('Drat!');
    }
    finally {
        rl.close();
    }
}

run();
```

# Related Packages

- [byline](https://github.com/jahewson/node-byline): Useful for reading streams line-by-line. I recommend using `byline` over node's builtin [readline](https://nodejs.org/dist/latest-v8.x/docs/api/readline.html#readline_example_read_file_stream_line_by_line) because you can pause the stream or await asynchronous operations inbetween each line.

- [stream-consume-promise](https://www.npmjs.com/package/stream-consume-promise): Similar to this package, but returns an iterator-style response with `value` and `done` properties. Also see [stream-produce-promise](https://github.com/Qard/stream-produce-promise).

# Notes

- The library has no dependencies. `mocha` and `byline` are required only for testing.

# Credits

[byline](https://github.com/jahewson/node-byline) served as an example package as I was writing `awaitify-stream`, my first package.

[davedoesdev](https://github.com/davedoesdev) contributed fixes.

[mknj](https://github.com/mknj) identified an issue with error handling.

---
_Source: https://npm.io/package/awaitify-stream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._