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