munchy

• API reference - TypeDoc
• Markdown reference - the full API and runtime behavior in one file. Also ships in the package.
• GitHub

A producer Node stream for draining different data, including Readable streams.

This is an ESM only package.

$ npm i --save munchy

examples:

import fs from "node:fs";
import { Munchy } from "munchy";

const munchy = new Munchy();
munchy.munch("hello world", fs.createReadStream("blah"), "bye bye");
munchy.munch(null); // null terminates it
munchy.pipe(process.stdout);

import fs from "node:fs";
import Munchy from "munchy"; // default export works too

const munchy = new Munchy({}, fs.createReadStream("foo"), fs.createReadStream("bar"));
munchy.munch(fs.createReadStream("blah"), "bye bye", null); // null terminates it
munchy.pipe(process.stdout);

API

constructor

Munchy(opts, ...sources);

| name | description | | --------- | ------------------------------------------------- | | opts | options for Node Readable stream, or null | | sources | variadic params of sources to munch |

opts may be null or omitted entirely, in which case every argument is treated as a source.

sources

A source can be any of:

| type | behavior | | -------------------------------- | ------------------------------------------------- | | string / Buffer / Uint8Array | pushed as is | | Node Readable | drained, with backpressure applied to the source | | Web ReadableStream | converted with Readable.fromWeb and drained | | AsyncIterable | drained one value at a time | | Iterable | each value pushed | | Promise | awaited, then handled as the resolved value | | null | ends the stream | | anything else | pushed as is (useful with objectMode) |

A rejected Promise or a stream error goes through handleStreamError below.

Munchy specific options:

| name | description | | ------------------- | ---------------------------------------------------- | | handleStreamError | callback to handle error from a stream being drained |

handleStreamError should take the error object and return an object with these fields:

| name | description | | -------- | -------------------------------------------------------------------------------------------------------------------- | | result | string data to add to the output | | remit | Set to false and munchy will continue without destroying itself, else it emits the error again and stop processing |

If handleStreamError returns a falsy value, then Munchy will emit the error and destroys itself.

For example:

const munchy = new Munchy({
  handleStreamError: err => {
    return { result: err.stack, remit: false };
  }
});

munch

munchy.munch(...sources);

| name | description | | --------- | ----------------------------------- | | sources | variadic params of sources to munch |

• Returns this.

• To end and terminate munchy stream:

munchy.munch(null);

Events

Munchy emits the following custom events:

| name | description | payload | | ---------- | ------------------------------------ | ------------ | | draining | starting to drain a stream source. | { stream } | | drained | done with a stream source, including one recovered by handleStreamError. | { stream } | | munched | all sources munched, ready for more. | |

ie:

munchy.on("draining", ({ stream }) => {});

Demos

• Hapi - https://github.com/jchip/hapi-stream-sample
• Koa - https://github.com/jchip/koa-stream-sample
• express - https://github.com/jchip/express-stream-sample

License

Licensed under the Apache License, Version 2.0