read-stream
Base class for readable streams
This should be used for object streams only.
Example push model
A push source can be turned into a Readable Stream by creating
an instance of the source and creating a stream.
When the onread listener of the stream get's called it's time
to start consuming data from the source. (like source.resume()
or source.readStart()). Note that onread may get called
multiple times even when the source your wrapping in a stream
has already started. So resume() / readStart() should be handle
being called multiple times.
When you get actual data out of the raw source you should push(data)
into the stream. push returns a boolean whether or not the
stream's buffer is full. If it's full you need to stop reading
from the source (like source.pause() or source.readStop()).
push() returns false when the internal buffer matches the
highWaterMark. This defaults to 100 for ReadStream. You can
configure it using
var stream = ReadStream({
highWaterMark: 20
}, function onread() { ... })
If the source emits some kind of EOF you should call push(null)
and if the source emits some kind of error you can just emit("error", err)
var ReadStream = require("read-stream")
var socket = connect(...)
var stream = ReadStream(function onread(push, cb) {
socket.readStart()
})
socket.ondata = function (chunk) {
var needsMore = stream.push(chunk)
if (!needsMore) {
socket.readStop()
}
}
socket.onend = function () {
stream.push(null)
}
socket.onerror = function (err) {
stream.emit("error", err)
}
stream.pipe(process.stdout)
Example pull model
A pull source can be made into a Readable Stream in a way easier
fashion. Create an instance of the raw pull source and create a
stream.
When the onread listener of the stream is called you should
pull data out of the underlying source and push() it into
the stream. If you push() data into the stream and the underlying
buffer is below the lowWaterMark then onread will be called
again immediately. The lowWaterMark can be configured and defaults
to 0
var stream = ReadStream({
lowWaterMark: 5
}, function onread() {})
When a user calls read() on the stream and the internal buffer
is below the highWaterMark after read removes an item then
onread will be called again.
Note that it the underlying source returns an err or returns
an EOF you should emit("error", err) and push(null) respectively.
var ReadStream = require("read-stream")
var source = db.cursor(...)
var stream = ReadStream(function onread(push, cb) {
cursor.nextObject(function (err, item) {
if (err) {
return stream.emit("error", err)
}
push(item || null)
})
})
stream.pipe(process.stdout)
Example array
If you want to turn an array into a stream for testing / example
purposes then use the array function.
var fromArray = require("read-stream/array")
var stream = fromArray(["one", "two"])
stream.pipe(process.stdout)
Example callback
If you want to turn a callback operation into a stream then
you can use the callback function.
var callback = require("read-stream/callback")
var stream = callback(function (cb) {
fs.readFile(someUri, cb)
})
stream.pipe(process.stdout)
Installation
npm install read-stream
Contributors
- Raynos


