@util.js/node-streams

JavaScript utility methods for Node.js streams

@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:

• fromString
• stringify

Streams API

Kind: global class
Access: public

• Streams
  • .Duplex
    • new Streams#Duplex()
  • .PassThrough
    • new Streams#PassThrough()
  • .Readable
    • new Streams#Readable()
  • .Stream
    • new Streams#Stream()
  • .Transform
    • new Streams#Transform()
  • .Writable
    • new Streams#Writable()
  • .finished(stream, [callback]) ⇒ undefined | Promise
  • .fromString(string, [encoding]) ⇒ Readable
  • .newReadable([params]) ⇒ Readable
  • .newWritable([params]) ⇒ Writable
  • .pipeline([callback]) ⇒ undefined | Promise
  • .stringify(readable, [callback]) ⇒ undefined | Promise

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