Stream Magic

A simple module that can convert any variable into a Node.js stream

What it does

Stream Magic extends the prototypes of all variable types within Node.JS with a .toStream() method, which lets you easily transform objects and variables into streams.

A safe mode that doesn't extend prototypes is also available.

Installation

You can install the streammagic package using npm.

$ npm install streammagic

Usage

The module exports a single function that attaches the .toStream() method to the prototypes. To use it, simply require the module and run the function once.

// No need to assign this as the function doesn't return anything
require('streammagic')();

Once this is done, the .toStream() method should be available on all variables.

// Logs 'hello world' to stdout (the console)
let myString = 'hello world';
let myStream = myString.toStream();
myStream.pipe(process.stdout);

// Or shorter
'hello world'.toStream().pipe(process.stdout)

Safe mode

The safe mode is available as a method of the module. Simply require it like this:

const toStream = require('streammagic').toStream;

// Same as above
let myString = 'hello world';
let myStream = toStream(myString);
myStream.pipe(process.stdout);

// Short version
toStream('hello world').pipe(process.stdout);

Datatypes

Primitive datatypes

All primitive datatypes (number, boolean, string) will be pushed to the stream in one piece. This cause a slight performance loss for long strings, depending on the actions of the subsequent pipes. This is something that may be addressed later on.

// Boolean
let stream = false.toStream() // stream.on('data') will contain: false

// Number
let stream = (35).toStream() // stream.on('data') will contain: 35

// String
let stream = 'foo'.toStream() // stream.on('data') will contain: foo

Arrays

Arrays will be piped one item at a time. This can be useful for processing datasets.

let myArray = ['hello', 'world'];
let myStream = myArray.toStream();

myStream.on('data', function(data){
	// The data event will fire twice. Data will contain 'hello' the first time, 'world' the second.
});

Objects

Objects are piped one property at a time as {key: value} objects. Keep this in mind, as assembling the original object on the other end of the pipe will require some manual work.

let myObject = {
	hello: 'world',
	foo: 'bar'
};
let myStream = myObject.toStream();

myStream.on('data', function(data){
	// The data event will fire twice. Data will contain {hello: 'world'} the first time, {foo: 'bar'} the second.
});

Tip

If you need an object or an array to be piped as one instead of being split up, you can simply wrap it inside another array. Only the outermost array or object will be split.

let myArray = ['hello', 'world'];
let myStream = [myArray].toStream();

myStream.on('data', function(data){
	console.log(data); // ['hello', 'world']
});

Buffers

Node buffers will be piped as they are, just like primitive datatypes.

Issues

If you find any bugs or problems with this module, please create an issue so we can look into it. Pull requests with bugfixes are of course welcome.

License

This module is licensed under the MIT License.