opusdev/vector-similarity-api

1# delayed-stream2 3Buffers events from a stream until you are ready to handle them.4 5## Installation6 7``` bash8npm install delayed-stream9```10 11## Usage12 13The following example shows how to write a http echo server that delays its14response by 1000 ms.15 16``` javascript17var 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 buffered31events by calling `delayedStream.resume()`:32 33``` javascript34var delayed = DelayedStream.create(req);35 36setTimeout(function() {37  // Emit all buffered events and resume underlaying source38  delayed.resume();39}, 1000);40```41 42## Implementation43 44In order to use this meta stream properly, here are a few things you should45know about the implementation.46 47### Event Buffering / Proxying48 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 the53`source`, regardless of whether you have released the delayed stream yet or54not.55 56Upon creation, delayed-stream captures all `source` events and stores them in57an internal event buffer. Once `delayedStream.release()` is called, all58buffered events are emitted on the `delayedStream`, and the event buffer is59cleared. After that, delayed-stream merely acts as a proxy for the underlaying60source.61 62### Error handling63 64Error events on `source` are buffered / proxied just like any other events.65However, `delayedStream.create` attaches a no-op `'error'` listener to the66`source`. This way you only have to handle errors on the `delayedStream`67object, rather than in two places.68 69### Buffer limits70 71delayed-stream provides a `maxDataSize` property that can be used to limit72the 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 by74default.75 76## API77 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.source88 89The `source` stream managed by this object. This is useful if you are90passing your `delayedStream` around, and you still want to access properties91on the `source` object.92 93### delayedStream.pauseStream = true94 95Whether to pause the underlaying `source` when calling96`DelayedStream.create()`. Modifying this property afterwards has no effect.97 98### delayedStream.maxDataSize = 1024 * 102499 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 to106characters.107 108If you know what you are doing, you can set this property to `Infinity` to109disable this feature. You can also modify this property during runtime.110 111### delayedStream.dataSize = 0112 113The amount of data buffered so far.114 115### delayedStream.readable116 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 not137resume the underlaying source, use `delayedStream.resume()` instead.138 139## License140 141delayed-stream is licensed under the MIT license.142