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