Readme.md
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