Pirandello
A better Stream abstraction for node.js. npm install pirandello
Use
Creating
There's a bunch of ways to create a Stream.
Stream.of
Creates a stream that sends a single value and ends.
Stream//> hello world
Stream.empty
Just ends immediately.
Stream.fromArray
Sends each item in the array, then ends.
Stream//> hello world
Stream.fromReadable
Takes a node Readable stream and sends it one data chunk at a time.
Stream
new Stream
To construct your own Streams, call the constructor (new
is optional) with a function that takes two arguments. Each argument is a function: call the first one with an object to send it over the stream, call the second one to end the stream. From the implementation of fromArray
:
Stream { return }
Modifying
Pirandello Streams are immutable; the methods below return a new stream. Streams are a fantasy-land MonadPlus.
Stream::concat
Returns a new stream that sends the contents of the current stream followed by the contents of the other stream.
Stream//> hello world
Stream::chain
Takes a function that operates on each chunk and should return a new Stream. Useful for concatenating lists.
{ return Stream;} Stream
Stream::map
Maps over the chunk.
Stream.fromArray(["hello ","world"]).map(function(s) {return s.toUpperCase()})
//> HELLO WORLD
Stream::ap
Applies a stream of functions to a stream of inputs, returns a stream of outputs.
Stream//> HELLO WORLD hello world Hello
Stream::toCharstream
Converts a Stream of strings into a Stream of individual characters.
Stream::take
Given a number, returns a stream of the first n chunks. Useful with toCharstream
.
Stream//> hello
Stream::drop
Given a number, returns a stream without the first n chunks. Useful with toCharstream
.
Stream//> world
Consuming
Stream::pipe
Mostly compatible with Readable::pipe
, sends every chunk to the destination Writable.
Stream::generator
When you really need low-level chunk functionality (maybe you're extending Pirandello? Good for you!), generator
is what you want. It is, in fact, the function passed in when the Stream is instantiated; call it with two arguments, one function to deal with each chunk, and one which is called at the end. FUrom the implementation of pipe
:
Streamprototype { this}
Why?
I tried to make Readables look nice, I really did. The API is ugly, and the abstraction is leaky. Here's to a fresh start.