trickle/README.md

Slows incoming stream data to specific intervals

# trickle

Through stream for Node to slow incoming data to specific intervals.

For example, the following script will pipe itself to `process.stdout`, limited
to one chunk per second.

``` javascript
var es = require('event-stream')
  , trickle = require('trickle')
  , fs = require('fs')

var stream = trickle({
  interval: 1000
})

fs.createReadStream(__filename, {
  encoding: 'utf8'
}).pipe(es.split(/\s+/g))
  .pipe(stream)
  .pipe(es.join('\n'))
  .pipe(process.stdout)
```

If you're looking to throttle data by *bytes per second*, check out
[throttle](http://npm.im/throttle) or [brake](http://npm.im/brake).

Of course, this stream buffers data. If you want to discard input to avoid
the stream filling up, use the `limit` option: this limits the total amount of
chunks that the stream will buffer.

By default, the stream will ignore any new data if the buffer is full. Using the
`mru` flag, the stream will instead remove the oldest chunk and add the new one
to the end of the queue.

``` javascript
// Emits the most recent recieved chunk
// every second.
trickle({
      mru: true
    , limit: 1
    , interval: 1000
})

// Stores up to 50 chunks, discarding any
// after that. Flushes one chunk every
// five seconds.
trickle({
      limit: 50
    , interval: 5000
})
```

## Parameters

* `interval`: The interval period, in milliseconds. Defaults to 50.
* `limit`: Maximum amount of chunks to buffer at once. Omit this field to
   buffer content endlessly.
* `mru`: Remove old chunks to make space for new ones. Disabled by default.
* `flush`: Amount of chunks to flush each interval. Defaults to 1.