# delayed-stream
  
  Buffers events from a stream until you are ready to handle them.
  
  ## Installation
  
  ``` bash
  npm install delayed-stream
  ```
  
  ## Usage
  
  The following example shows how to write a http echo server that delays its
  response by 1000 ms.
  
  ``` javascript
  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()`:
  
  ``` javascript
  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.