When creating stream modules for external consumption, we want to make sure the user of our module can clean up any left over resources our stream has held.

Ecosystem modules such as from2, through2, and to2 added an essential feature to streams: a way to stop or destroy the stream prematurely. Thanks to these modules showcasing the clear advantages of a destroy, this ability has been included as standard in Node core since Node 8. However, in Node 6 and below the stream factory methods (Readable, Writable, and so forth) do not supply a destroy method (this is another reason to always use the readable-stream module).

By default, the destroy method (whether in Node 8 or a popular ecosystem module such as from2) will cause the stream to cease from emitting data and then emit a close. It won't necessarily emit an end in this case.

To showcase the destroy method, we'll create an infinite stream (a fun sub-genre of readable streams, that allows for infinite data with finite memory) using the from2 module.

Let's create a folder called stream-destruction, initialize it as a package, install from2, and create an index.js file:

$ mkdir stream-destruction 
$ cd stream-destruction 
$ npm init -y 
$ npm install --save from2 
$ touch index.js 

At the top of index.js, we write:

const from = require('from2') 
 
function createInfiniteTickStream () { 
  var tick = 0 
  return from.obj((size, cb) => { 
    setImmediate(() => cb(null, {tick: tick++})) 
  }) 
} 

Let's create the stream and log each data event:

const stream = createInfiniteTickStream() 
 
stream.on('data', (data) => { 
  console.log(data) 
}) 

Let's run our program so far:

$ node index.js 

We'll notice that it just floods the console, as it never ends.

Since an infinite stream won't end by itself, we need to have a mechanism for which we can tell it from the outside that it should stop. We need this in case we are consuming the stream and one of the downstream dependents experiences an error which makes us want to shut down the pipeline.

Now let's add the following to our index.js file:

stream.on('close', () => { 
  console.log('(stream destroyed)') 
}) 
 
setTimeout(() => { 
  stream.destroy() 
}, 1000) 

Running the preceding code will make the tick stream flood the console for about 2 seconds and then stop, while a final message "(stream destroyed)" is printed to the console before the program exits.

The destroy method is extremely useful in many applications and more or less essential when doing any kind of stream error handling.

For this reason, using from2 (and other stream modules described in this book) is highly recommended over using the core stream module.