3 Buffers events from a stream until you are ready to handle them.
8 npm install delayed-stream
13 The following example shows how to write a http echo server that delays its
17 var DelayedStream = require('delayed-stream');
18 var http = require('http');
20 http.createServer(function(req, res) {
21 var delayed = DelayedStream.create(req);
23 setTimeout(function() {
30 If you are not using `Stream#pipe`, you can also manually release the buffered
31 events by calling `delayedStream.resume()`:
34 var delayed = DelayedStream.create(req);
36 setTimeout(function() {
37 // Emit all buffered events and resume underlaying source
44 In order to use this meta stream properly, here are a few things you should
45 know about the implementation.
47 ### Event Buffering / Proxying
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.
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
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
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.
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
78 ### DelayedStream.create(source, [options])
80 Returns a new `delayedStream`. Available options are:
85 The description for those properties can be found below.
87 ### delayedStream.source
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.
93 ### delayedStream.pauseStream = true
95 Whether to pause the underlaying `source` when calling
96 `DelayedStream.create()`. Modifying this property afterwards has no effect.
98 ### delayedStream.maxDataSize = 1024 * 1024
100 The amount of data to buffer before emitting an `error`.
102 If the underlaying source is emitting `Buffer` objects, the `maxDataSize`
105 If the underlaying source is emitting JavaScript strings, the size refers to
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.
111 ### delayedStream.dataSize = 0
113 The amount of data buffered so far.
115 ### delayedStream.readable
117 An ECMA5 getter that returns the value of `source.readable`.
119 ### delayedStream.resume()
121 If the `delayedStream` has not been released so far, `delayedStream.release()`
124 In either case, `source.resume()` is called.
126 ### delayedStream.pause()
128 Calls `source.pause()`.
130 ### delayedStream.pipe(dest)
132 Calls `delayedStream.resume()` and then proxies the arguments to `source.pipe`.
134 ### delayedStream.release()
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.
141 delayed-stream is licensed under the MIT license.