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