BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / delayed-stream / Readme.md

Readme.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
Readme.md 3.8 KiB Download Raw

delayed-stream

Buffers events from a stream until you are ready to handle them.

Installation

npm install delayed-stream

Usage

The following example shows how to write a http echo server that delays its response by 1000 ms.

var DelayedStream = require('delayed-stream');
var http = require('http');

http.createServer(function(req, res) {
  var delayed = DelayedStream.create(req);

  setTimeout(function() {
    res.writeHead(200);
    delayed.pipe(res);
  }, 1000);
});

If you are not using Stream#pipe, you can also manually release the buffered events by calling delayedStream.resume():

var delayed = DelayedStream.create(req);

setTimeout(function() {
  // Emit all buffered events and resume underlaying source
  delayed.resume();
}, 1000);

Implementation

In order to use this meta stream properly, here are a few things you should know about the implementation.

Event Buffering / Proxying

All events of the source stream are hijacked by overwriting the source.emit method. Until node implements a catch-all event listener, this is the only way.

However, delayed-stream still continues to emit all events it captures on the source, regardless of whether you have released the delayed stream yet or not.

Upon creation, delayed-stream captures all source events and stores them in an internal event buffer. Once delayedStream.release() is called, all buffered events are emitted on the delayedStream, and the event buffer is cleared. After that, delayed-stream merely acts as a proxy for the underlaying source.

Error handling

Error events on source are buffered / proxied just like any other events. However, delayedStream.create attaches a no-op 'error' listener to the source. This way you only have to handle errors on the delayedStream object, rather than in two places.

Buffer limits

delayed-stream provides a maxDataSize property that can be used to limit the amount of data being buffered. In order to protect you from bad source streams that don't react to source.pause(), this feature is enabled by default.

API

DelayedStream.create(source, [options])

Returns a new delayedStream. Available options are:

  • pauseStream
  • maxDataSize

The description for those properties can be found below.

delayedStream.source

The source stream managed by this object. This is useful if you are passing your delayedStream around, and you still want to access properties on the source object.

delayedStream.pauseStream = true

Whether to pause the underlaying source when calling DelayedStream.create(). Modifying this property afterwards has no effect.

delayedStream.maxDataSize = 1024 * 1024

The amount of data to buffer before emitting an error.

If the underlaying source is emitting Buffer objects, the maxDataSize refers to bytes.

If the underlaying source is emitting JavaScript strings, the size refers to characters.

If you know what you are doing, you can set this property to Infinity to disable this feature. You can also modify this property during runtime.

delayedStream.dataSize = 0

The amount of data buffered so far.

delayedStream.readable

An ECMA5 getter that returns the value of source.readable.

delayedStream.resume()

If the delayedStream has not been released so far, delayedStream.release() is called.

In either case, source.resume() is called.

delayedStream.pause()

Calls source.pause().

delayedStream.pipe(dest)

Calls delayedStream.resume() and then proxies the arguments to source.pipe.

delayedStream.release()

Emits and clears all events that have been buffered up so far. This does not resume the underlaying source, use delayedStream.resume() instead.

License

delayed-stream is licensed under the MIT license.

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