@util.js/node-streams

JavaScript utility methods for streams

Usage no npm install needed!

<script type="module">
  import utilJsNodeStreams from 'https://cdn.skypack.dev/@util.js/node-streams';
</script>

README

@util.js/node-streams

JavaScript utility methods for Node.js streams

NPM Status Travis CI Build Status

@util.js/node-streams is part of Util.js.

const streams = require("@util.js/node-streams");
const readable = streams.fromString("The programmer learneth");
streams.stringify(readable).then(console.log); // Outputs "The programmer learneth".

This class contains all the members of Stream in addition to:

Streams API

Kind: global class
Access: public

streams.Duplex

Kind: instance class of Streams
Access: public

new Streams#Duplex()

A stream that is both Readable and Writable (for example, a TCP socket connection or net.Socket).

See Node.js's documentation about Duplex.

streams.PassThrough

Kind: instance class of Streams
Access: public

new Streams#PassThrough()

A trivial implementation of a Transform stream that simply passes the input bytes across to the output.

See Node.js's documentation about PassThrough.

streams.Readable

Kind: instance class of Streams
Access: public

new Streams#Readable()

A stream from which data can be read, an abstraction of a source (for example, fs.createReadStream()).

See Node.js's documentation about Readable.

streams.Stream

Kind: instance class of Streams
Access: public

new Streams#Stream()

An abstraction of sources (a place where data can be read from) and destinations (a place where data can be written to).

See Node.js's documentation about Stream.

streams.Transform

Kind: instance class of Streams
Access: public

new Streams#Transform()

Duplex streams where the output is in some way related to the input (for example, zlib.createDeflate()).

See Node.js's documentation about Transform.

streams.Writable

Kind: instance class of Streams
Access: public

new Streams#Writable()

A stream to which data can be written, an abstraction of a destination (for example, fs.createWriteStream()).

See Node.js's documentation about Writable.

streams.finished(stream, [callback]) ⇒ undefined | Promise

Sends a notification when a stream is no longer readable, writable, or has experienced an error or a premature close event.

See Node.js's documentation about finished.

Kind: instance method of Streams
Returns: undefined | Promise - undefined if a callback is specified or a Promise that resolves once the stream has finished
Throws:

  • Error If the Node.js version does not implement stream.finished

Access: public

Param Type Description
stream Stream A readable and/or writable stream
[callback] function A callback function that takes an optional error argument

streams.fromString(string, [encoding]) ⇒ Readable

Converts a string into a stream.

A Stack Overflow answer inspired this implementation.

Kind: instance method of Streams
Returns: Readable - A stream of the specified string
Throws:

  • TypeError If string is not a string

Access: public

Param Type Description
string string The string to convert into a stream
[encoding] string Encoding of the string that must be a valid Buffer encoding, such as 'utf8' or 'ascii'

streams.newReadable([params]) ⇒ Readable

Creates a new Readable stream.

See Node.js's documentation about Readable.

Kind: instance method of Streams
Returns: Readable - A new Readable instance
Access: public

Param Type Default Description
[params] Object
[params.highWaterMark] number 16384 (16kb) or 16 for objectMode streams The maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource
[params.encoding] string null If specified, then buffers will be decoded to strings using the specified encoding
[params.objectMode] boolean false Whether this stream should behave as a stream of objects meaning that stream.read(n) returns a single value instead of a Buffer of size n
[params.read] function Implementation for the stream._read() method
[params.destroy] function Implementation for the stream._destroy() method

streams.newWritable([params]) ⇒ Writable

Creates a new Writable stream.

See Node.js's documentation about Writable.

Kind: instance method of Streams
Returns: Writable - A new Writable instance
Access: public

Param Type Default Description
[params] Object
[params.highWaterMark] number 16384 (16kb) or 16 for objectMode streams Buffer level when stream.write() starts returning false
[params.decodeStrings] boolean true Whether or not to decode strings into Buffers before passing them to stream._write()
[params.objectMode] boolean false Whether or not the stream.write(anyObj) is a valid operation. When set, it becomes possible to write JavaScript values other than string, Buffer or Uint8Array if supported by the stream implementation.
[params.emitClose] boolean true Whether or not the stream should emit 'close' after it has been destroyed
[params.write] function Implementation for the stream._write() method
[params.writev] function Implementation for the stream._writev() method
[params.destroy] function Implementation for the stream._destroy() method
[params.final] function Implementation for the stream._final() method

streams.pipeline([callback]) ⇒ undefined | Promise

Pipes between streams forwarding errors and properly cleaning up and notifies when the pipeline is complete via a callback or a Promise.

See Node.js's documentation about pipeline.

Kind: instance method of Streams
Returns: undefined | Promise - undefined if a callback is specified or a Promise that resolves once the pipeline is complete
Throws:

  • Error If the Node.js version does not implement stream.pipeline

Access: public

Param Type Description
...streams Stream Two or more streams to pipe between
[callback] function A callback function that takes an optional error argument

streams.stringify(readable, [callback]) ⇒ undefined | Promise

Converts a stream into a string.

A Stack Overflow answer inspired this implementation.

Kind: instance method of Streams
Returns: undefined | Promise - undefined if a callback is specified or a Promise that resolves with the resulting string
Access: public

Param Type Description
readable Readable The stream to convert into a string
[callback] function A callback function that takes two arguments, a string and an error