Readme.md - buddy - node MVC discord bot

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.