cloneable-readable

What is cloneable-readable?

The cloneable-readable npm package allows you to create cloneable versions of Node.js readable streams. This means you can create multiple independent readers from a single readable stream, which can be useful in scenarios where you need to process the same stream data in different ways simultaneously.

What are cloneable-readable's main functionalities?

Cloning a Readable Stream

This feature allows you to clone a readable stream. The code sample demonstrates how to create a cloneable version of a readable stream and then read data from both the original and cloned streams.

const cloneable = require('cloneable-readable');
const { Readable } = require('stream');

const originalStream = new Readable({
  read() {
    this.push('data');
    this.push(null);
  }
});

const clonedStream = cloneable(originalStream);

clonedStream.on('data', (chunk) => {
  console.log(`Cloned stream data: ${chunk}`);
});

originalStream.on('data', (chunk) => {
  console.log(`Original stream data: ${chunk}`);
});

Multiple Clones

This feature allows you to create multiple clones of a readable stream. The code sample demonstrates how to create two clones from the original stream and read data from both clones.

const cloneable = require('cloneable-readable');
const { Readable } = require('stream');

const originalStream = new Readable({
  read() {
    this.push('data');
    this.push(null);
  }
});

const clonedStream1 = cloneable(originalStream);
const clonedStream2 = clonedStream1.clone();

clonedStream1.on('data', (chunk) => {
  console.log(`Cloned stream 1 data: ${chunk}`);
});

clonedStream2.on('data', (chunk) => {
  console.log(`Cloned stream 2 data: ${chunk}`);
});

Other packages similar to cloneable-readable

multistream

The multistream package allows you to combine multiple streams into a single readable stream. While it does not provide cloning functionality, it is useful for merging streams together, which can be an alternative approach depending on the use case.

through2

The through2 package is a tiny wrapper around Node.js streams2 Transform to avoid explicit subclassing noise. While it does not provide cloning functionality, it is useful for creating transform streams that can process data in a pipeline.

README

cloneable-readable

Clone a Readable stream, safely.

'use strict'

var cloneable = require('cloneable-readable')
var fs = require('fs')
var pump = require('pump')

var stream = cloneable(fs.createReadStream('./package.json'))

pump(stream.clone(), fs.createWriteStream('./out1'))

// simulate some asynchronicity
setImmediate(function () {
  pump(stream, fs.createWriteStream('./out2'))
})

cloneable-readable automatically handles objectMode: true.

This module comes out of an healthy discussion on the 'right' way to clone a Readable in https://github.com/gulpjs/vinyl/issues/85 and https://github.com/nodejs/readable-stream/issues/202. This is my take.

YOU MUST PIPE ALL CLONES TO START THE FLOW

You can also attach 'data' and 'readable' events to them.

API

cloneable(stream)

Create a Cloneable stream. A Cloneable has a clone() method to create more clones. All clones must be resumed/piped to start the flow.

cloneable.isCloneable(stream)

Check if stream needs to be wrapped in a Cloneable or not.

Acknowledgements

This project was kindly sponsored by nearForm.

License

MIT