ListStream


Collect chunks / objects from a readable stream, write obejcts / chunks to a writable stream


Built on a DuplexStream, ListStream can collect the chunks as they come in so you can use them later as an array, or pipe them on to another stream.

Using the same callback style as bl and a similar style to concat-stream, you can use ListStream as a terminal stream collecting the chunks or objects for use once the stream has ended. This is particularly helpful for object streams where each chunk is a discrete object.

``js
var ListStream = require('list-stream')
, db = require('level')('/path/to/db', { valueEncoding: 'json' }) // stream from LevelDB!

db.createValueStream().pipe(ListStream.obj(function (err, data) {
if (err)
throw err

console.log('Values in the database:')
// data is an array of objects from the database, serialised from JSON strings
data.forEach(function (value, i) {
console.log(i, JSON.stringify(value))
})
}))
`

Or emulate fs.readFile():

`js
var ListStream = require('list-stream')
, fs = require('fs')

fs.createReadStream('/path/to/file.dat').pipe(ListStream(function (err, data) {
if (err)
throw err

console.log('Contents of /path/to/file.dat:')
// data is an array of Buffer objects
console.log(Buffer.concat(data).toString('utf8'))
}))
`

See bl for nicer Buffer stream handling

Or use as a store to stream from later

`js
var list = require('list-stream').obj()
, db = require('level')('/path/to/db')

list.write({ key: 'name', value: 'Yuri Irsenovich Kim' })
list.write({ key: 'dob', value: '16 February 1941' })
list.write({ key: 'spouse', value: 'Kim Young-sook' })
list.write({ key: 'occupation', value: 'Clown' })

list.pipe(db.createWriteStream()) // write all of the stored entries to a database
`

API

* [new ]ListStream([ options, ][ callback ])
* ListStream.obj([ options, ][ callback ])
* listStream.length
* listStream.append(obj)
* listStream.get(index)
* listStream.end()
* listStream.duplicate()


--------------------------------------------------------



$3

Create a new ListStream with the given options which will be passed up to the parent DuplexStream.

The optional callback will be called when the stream reaches an end event. You will receive both an error argument and a data argument where the error will come off 'error' events emitted by any piped stream and the data will be an Array of chunks or objects fed in to the stream.

--------------------------------------------------------



$3

Same as the standard constructor but shorthand for new ListStream({ objectMode:true }, callback).

Use this for when you're not dealing with Buffers or Strings in your streams.

--------------------------------------------------------



$3

The number of chunks currently being held. (Not available in pre-ES5 environments as it uses a getter)

--------------------------------------------------------



$3

Append a chunk / object to the list.

--------------------------------------------------------



$3

Get the chunk / object from the list at index index.

--------------------------------------------------------



$3

End the stream. A standard WritableStream method, can be used when piping to another stream:

`js
listStream.pipe(fs.createWriteStream(os.tmpDir() + '/randombytes.dat'))

for (var i = 0; i < 100)
listStream.append(crypto.randomBytes(32))

listStream.end()
`

--------------------------------------------------------



$3

Create a full duplicate of this ListStream. Each item in the list will be .append()`ed to the new copy. The copy will be returned.

License

ListStream is Copyright (c) 2014 Rod Vagg @rvagg and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.