Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/felixge/node-delayed-stream

Buffers events from a stream until you are ready to handle them.
https://github.com/felixge/node-delayed-stream

Last synced: 2 days ago
JSON representation

Buffers events from a stream until you are ready to handle them.

Awesome Lists containing this project

README 

        
# delayed-stream



Buffers events from a stream until you are ready to handle them.



## Installation



``` bash

npm install delayed-stream

```



## Usage



The following example shows how to write a http echo server that delays its

response by 1000 ms.



``` javascript

var DelayedStream = require('delayed-stream');

var http = require('http');



http.createServer(function(req, res) {

  var delayed = DelayedStream.create(req);



  setTimeout(function() {

    res.writeHead(200);

    delayed.pipe(res);

  }, 1000);

});

```



If you are not using `Stream#pipe`, you can also manually release the buffered

events by calling `delayedStream.resume()`:



``` javascript

var delayed = DelayedStream.create(req);



setTimeout(function() {

  // Emit all buffered events and resume underlaying source

  delayed.resume();

}, 1000);

```



## Implementation



In order to use this meta stream properly, here are a few things you should

know about the implementation.



### Event Buffering / Proxying



All events of the `source` stream are hijacked by overwriting the `source.emit`

method. Until node implements a catch-all event listener, this is the only way.



However, delayed-stream still continues to emit all events it captures on the

`source`, regardless of whether you have released the delayed stream yet or

not.



Upon creation, delayed-stream captures all `source` events and stores them in

an internal event buffer. Once `delayedStream.release()` is called, all

buffered events are emitted on the `delayedStream`, and the event buffer is

cleared. After that, delayed-stream merely acts as a proxy for the underlaying

source.



### Error handling



Error events on `source` are buffered / proxied just like any other events.

However, `delayedStream.create` attaches a no-op `'error'` listener to the

`source`. This way you only have to handle errors on the `delayedStream`

object, rather than in two places.



### Buffer limits



delayed-stream provides a `maxDataSize` property that can be used to limit

the amount of data being buffered. In order to protect you from bad `source`

streams that don't react to `source.pause()`, this feature is enabled by

default.



## API



### DelayedStream.create(source, [options])



Returns a new `delayedStream`. Available options are:



* `pauseStream`

* `maxDataSize`



The description for those properties can be found below.



### delayedStream.source



The `source` stream managed by this object. This is useful if you are

passing your `delayedStream` around, and you still want to access properties

on the `source` object.



### delayedStream.pauseStream = true



Whether to pause the underlaying `source` when calling

`DelayedStream.create()`. Modifying this property afterwards has no effect.



### delayedStream.maxDataSize = 1024 * 1024



The amount of data to buffer before emitting an `error`.



If the underlaying source is emitting `Buffer` objects, the `maxDataSize`

refers to bytes.



If the underlaying source is emitting JavaScript strings, the size refers to

characters.



If you know what you are doing, you can set this property to `Infinity` to

disable this feature. You can also modify this property during runtime.



### delayedStream.dataSize = 0



The amount of data buffered so far.



### delayedStream.readable



An ECMA5 getter that returns the value of `source.readable`.



### delayedStream.resume()



If the `delayedStream` has not been released so far, `delayedStream.release()`

is called.



In either case, `source.resume()` is called.



### delayedStream.pause()



Calls `source.pause()`.



### delayedStream.pipe(dest)



Calls `delayedStream.resume()` and then proxies the arguments to `source.pipe`.



### delayedStream.release()



Emits and clears all events that have been buffered up so far. This does not

resume the underlaying source, use `delayedStream.resume()` instead.



## License



delayed-stream is licensed under the MIT license.