streammagic
Version:
Convert anything to a stream
122 lines (88 loc) • 4.24 kB
Markdown
# Stream Magic
[](https://semaphoreci.com/primetime/node-streammagic)
[](https://www.npm.com/package/streammagic)
[](https://github.com/primetime/node-streammagic/issues)
[](https://snyk.io/test/github/primetime/node-streammagic)
[](https://raw.githubusercontent.com/primetime/node-streammagic/master/license.txt)
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](https://www.npmjs.com/package/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.
```Javascript
// 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.
```Javascript
// 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:
```Javascript
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_.
```Javascript
// 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.
```Javascript
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.
```Javascript
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.
```Javascript
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](https://github.com/primetime/node-streammagic/issues) so we can look into it. Pull requests with bugfixes are of course welcome.
## License
This module is licensed under the [MIT License](https://github.com/primetime/node-streammagic/blob/master/license.txt).