pipette
v0.9.3
Published
Stream and pipe utilities for Node
Downloads
15,757
Readme
pipette: Pipe-like utilities for Node
This Node module provides a couple utility classes that offer pipe-like functionality.
Pipe
The Pipe
class is a simple in-memory pipe, which provides writer and
reader ends, which both obey the standard Node stream protocols, including
event emission, encoding handling, and pause/resume semantics.
This class is useful if you have code that wants to call writable stream style methods, and you want it to be directly attached to some other code that expects to be listening for events. For example:
var listeningThingy = ...;
var writingThingy = ...;
var pipe = new Pipe();
listeningThingy.listenTo(pipe.reader);
writingThingy.writeTo(pipe.writer);
Valve
The Valve
class is a bufferer of readable stream events, which in turn
provides the standard Node readable stream protocol, including event
emission and pause/resume semantics. (It doesn't do any data re-encoding,
though; it's just a pass-through on that front.)
One of the major use cases of this class is to use it to capture the data coming from a network stream that's already in the middle of producing data, particularly when you don't immediately know where that data needs to go to. The author has run into this on multiple occasions when trying hand off reading from an HTTP connection across a tick boundary, along these lines for example (obviously simplified here):
var thingThatWantsToRead = {
startReading: function (stream) {
stream.on("data", ...);
stream.resume();
...
},
...
}
function httpRequestCallback(request, response) {
var valve = new Valve(request);
process.nextTick(function () {
thingThatWantsToRead.startReading(valve);
});
}
Building and Installing
npm install pipette
Or grab the source. As of this writing, this module has no dependencies, so once you have the source, there's nothing more to do to "build" it.
Testing
npm test
Or
node ./test/test.js
API Details
Pipe
var pipe = new Pipe([paused])
Construct and return a new pipe pair. The result is an object with
mappings for { reader, writer }
for the two ends of the pipe.
If the optional paused
argument is specified, it indicates whether
or not the reader side should start out in the paused state. It defaults
to false
.
The reader and writer side each implement the standard Node stream protocol for readable and writable streams (respectively).
The specified protocol allows writers to ignore the fd
argument
to stream.write()
, and this implementation in fact ignores it.
Valve
var valve = new Valve(source, [paused])
Construct and return a new valve, which listens to the given source.
If the optional paused
argument is specified, it indicates whether
or not the new instance should start out in the paused state. It defaults
to true
, because that's the overwhelmingly most common use case.
The constructed instance obeys the full standard Node stream protocol
for readers, except that setEncoding()
throws when called. This
class provides only pass-through of data, not translation.
To Do
- Come up with something to do.
Contributing
Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.
Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests that update the test suite. Thanks!
Author
Dan Bornstein (personal website), supported by The Obvious Corporation.
License
Copyright 2012 The Obvious Corporation.
Licensed under the Apache License, Version 2.0.
See the top-level file LICENSE.txt
and
(http://www.apache.org/licenses/LICENSE-2.0).