1# delayed-stream 2 3Buffers events from a stream until you are ready to handle them. 4 5## Installation 6 7``` bash 8npm install delayed-stream 9``` 10 11## Usage 12 13The following example shows how to write a http echo server that delays its 14response by 1000 ms. 15 16``` javascript 17var DelayedStream = require('delayed-stream'); 18var http = require('http'); 19 20http.createServer(function(req, res) { 21 var delayed = DelayedStream.create(req); 22 23 setTimeout(function() { 24 res.writeHead(200); 25 delayed.pipe(res); 26 }, 1000); 27}); 28``` 29 30If you are not using `Stream#pipe`, you can also manually release the buffered 31events by calling `delayedStream.resume()`: 32 33``` javascript 34var delayed = DelayedStream.create(req); 35 36setTimeout(function() { 37 // Emit all buffered events and resume underlaying source 38 delayed.resume(); 39}, 1000); 40``` 41 42## Implementation 43 44In order to use this meta stream properly, here are a few things you should 45know about the implementation. 46 47### Event Buffering / Proxying 48 49All events of the `source` stream are hijacked by overwriting the `source.emit` 50method. Until node implements a catch-all event listener, this is the only way. 51 52However, delayed-stream still continues to emit all events it captures on the 53`source`, regardless of whether you have released the delayed stream yet or 54not. 55 56Upon creation, delayed-stream captures all `source` events and stores them in 57an internal event buffer. Once `delayedStream.release()` is called, all 58buffered events are emitted on the `delayedStream`, and the event buffer is 59cleared. After that, delayed-stream merely acts as a proxy for the underlaying 60source. 61 62### Error handling 63 64Error events on `source` are buffered / proxied just like any other events. 65However, `delayedStream.create` attaches a no-op `'error'` listener to the 66`source`. This way you only have to handle errors on the `delayedStream` 67object, rather than in two places. 68 69### Buffer limits 70 71delayed-stream provides a `maxDataSize` property that can be used to limit 72the amount of data being buffered. In order to protect you from bad `source` 73streams that don't react to `source.pause()`, this feature is enabled by 74default. 75 76## API 77 78### DelayedStream.create(source, [options]) 79 80Returns a new `delayedStream`. Available options are: 81 82* `pauseStream` 83* `maxDataSize` 84 85The description for those properties can be found below. 86 87### delayedStream.source 88 89The `source` stream managed by this object. This is useful if you are 90passing your `delayedStream` around, and you still want to access properties 91on the `source` object. 92 93### delayedStream.pauseStream = true 94 95Whether to pause the underlaying `source` when calling 96`DelayedStream.create()`. Modifying this property afterwards has no effect. 97 98### delayedStream.maxDataSize = 1024 * 1024 99 100The amount of data to buffer before emitting an `error`. 101 102If the underlaying source is emitting `Buffer` objects, the `maxDataSize` 103refers to bytes. 104 105If the underlaying source is emitting JavaScript strings, the size refers to 106characters. 107 108If you know what you are doing, you can set this property to `Infinity` to 109disable this feature. You can also modify this property during runtime. 110 111### delayedStream.dataSize = 0 112 113The amount of data buffered so far. 114 115### delayedStream.readable 116 117An ECMA5 getter that returns the value of `source.readable`. 118 119### delayedStream.resume() 120 121If the `delayedStream` has not been released so far, `delayedStream.release()` 122is called. 123 124In either case, `source.resume()` is called. 125 126### delayedStream.pause() 127 128Calls `source.pause()`. 129 130### delayedStream.pipe(dest) 131 132Calls `delayedStream.resume()` and then proxies the arguments to `source.pipe`. 133 134### delayedStream.release() 135 136Emits and clears all events that have been buffered up so far. This does not 137resume the underlaying source, use `delayedStream.resume()` instead. 138 139## License 140 141delayed-stream is licensed under the MIT license. 142