pax_global_header00006660000000000000000000000064125205235030014507gustar00rootroot0000000000000052 comment=07a9dc99fb8f1a488160026b9ad77493f766fb84 node-delayed-stream-1.0.0/000077500000000000000000000000001252052350300153305ustar00rootroot00000000000000node-delayed-stream-1.0.0/.gitignore000066400000000000000000000000631252052350300173170ustar00rootroot00000000000000*.un~ /node_modules/* # Vim swap files .*.sw[a-z] node-delayed-stream-1.0.0/.npmignore000066400000000000000000000000051252052350300173220ustar00rootroot00000000000000test node-delayed-stream-1.0.0/License000066400000000000000000000020751252052350300166410ustar00rootroot00000000000000Copyright (c) 2011 Debuggable Limited Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. node-delayed-stream-1.0.0/Makefile000066400000000000000000000000711252052350300167660ustar00rootroot00000000000000SHELL := /bin/bash test: @./test/run.js .PHONY: test node-delayed-stream-1.0.0/Readme.md000066400000000000000000000074371252052350300170620ustar00rootroot00000000000000# 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. node-delayed-stream-1.0.0/lib/000077500000000000000000000000001252052350300160765ustar00rootroot00000000000000node-delayed-stream-1.0.0/lib/delayed_stream.js000066400000000000000000000044171252052350300214240ustar00rootroot00000000000000var Stream = require('stream').Stream; var util = require('util'); module.exports = DelayedStream; function DelayedStream() { this.source = null; this.dataSize = 0; this.maxDataSize = 1024 * 1024; this.pauseStream = true; this._maxDataSizeExceeded = false; this._released = false; this._bufferedEvents = []; } util.inherits(DelayedStream, Stream); DelayedStream.create = function(source, options) { var delayedStream = new this(); options = options || {}; for (var option in options) { delayedStream[option] = options[option]; } delayedStream.source = source; var realEmit = source.emit; source.emit = function() { delayedStream._handleEmit(arguments); return realEmit.apply(source, arguments); }; source.on('error', function() {}); if (delayedStream.pauseStream) { source.pause(); } return delayedStream; }; Object.defineProperty(DelayedStream.prototype, 'readable', { configurable: true, enumerable: true, get: function() { return this.source.readable; } }); DelayedStream.prototype.setEncoding = function() { return this.source.setEncoding.apply(this.source, arguments); }; DelayedStream.prototype.resume = function() { if (!this._released) { this.release(); } this.source.resume(); }; DelayedStream.prototype.pause = function() { this.source.pause(); }; DelayedStream.prototype.release = function() { this._released = true; this._bufferedEvents.forEach(function(args) { this.emit.apply(this, args); }.bind(this)); this._bufferedEvents = []; }; DelayedStream.prototype.pipe = function() { var r = Stream.prototype.pipe.apply(this, arguments); this.resume(); return r; }; DelayedStream.prototype._handleEmit = function(args) { if (this._released) { this.emit.apply(this, args); return; } if (args[0] === 'data') { this.dataSize += args[1].length; this._checkIfMaxDataSizeExceeded(); } this._bufferedEvents.push(args); }; DelayedStream.prototype._checkIfMaxDataSizeExceeded = function() { if (this._maxDataSizeExceeded) { return; } if (this.dataSize <= this.maxDataSize) { return; } this._maxDataSizeExceeded = true; var message = 'DelayedStream#maxDataSize of ' + this.maxDataSize + ' bytes exceeded.' this.emit('error', new Error(message)); }; node-delayed-stream-1.0.0/package.json000066400000000000000000000012541252052350300176200ustar00rootroot00000000000000{ "author": "Felix Geisendörfer (http://debuggable.com/)", "contributors": [ "Mike Atkins " ], "name": "delayed-stream", "description": "Buffers events from a stream until you are ready to handle them.", "license": "MIT", "version": "1.0.0", "homepage": "https://github.com/felixge/node-delayed-stream", "repository": { "type": "git", "url": "git://github.com/felixge/node-delayed-stream.git" }, "main": "./lib/delayed_stream", "engines": { "node": ">=0.4.0" }, "scripts": { "test": "make test" }, "dependencies": {}, "devDependencies": { "fake": "0.2.0", "far": "0.0.1" } } node-delayed-stream-1.0.0/test/000077500000000000000000000000001252052350300163075ustar00rootroot00000000000000node-delayed-stream-1.0.0/test/common.js000066400000000000000000000002331252052350300201330ustar00rootroot00000000000000var common = module.exports; common.DelayedStream = require('..'); common.assert = require('assert'); common.fake = require('fake'); common.PORT = 49252; node-delayed-stream-1.0.0/test/integration/000077500000000000000000000000001252052350300206325ustar00rootroot00000000000000node-delayed-stream-1.0.0/test/integration/test-delayed-http-upload.js000066400000000000000000000014741252052350300260210ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var DelayedStream = common.DelayedStream; var http = require('http'); var UPLOAD = new Buffer(10 * 1024 * 1024); var server = http.createServer(function(req, res) { var delayed = DelayedStream.create(req, {maxDataSize: UPLOAD.length}); setTimeout(function() { res.writeHead(200); delayed.pipe(res); }, 10); }); server.listen(common.PORT, function() { var request = http.request({ method: 'POST', port: common.PORT, }); request.write(UPLOAD); request.end(); request.on('response', function(res) { var received = 0; res .on('data', function(chunk) { received += chunk.length; }) .on('end', function() { assert.equal(received, UPLOAD.length); server.close(); }); }); }); node-delayed-stream-1.0.0/test/integration/test-delayed-stream-auto-pause.js000066400000000000000000000010401252052350300271210ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testAutoPause() { var source = new Stream(); fake.expect(source, 'pause', 1); var delayedStream = DelayedStream.create(source); fake.verify(); })(); (function testDisableAutoPause() { var source = new Stream(); fake.expect(source, 'pause', 0); var delayedStream = DelayedStream.create(source, {pauseStream: false}); fake.verify(); })(); node-delayed-stream-1.0.0/test/integration/test-delayed-stream-pause.js000066400000000000000000000006231252052350300261610ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testDelayEventsUntilResume() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {pauseStream: false}); fake.expect(source, 'pause'); delayedStream.pause(); fake.verify(); })(); node-delayed-stream-1.0.0/test/integration/test-delayed-stream.js000066400000000000000000000024501252052350300250460ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testDelayEventsUntilResume() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {pauseStream: false}); // delayedStream must not emit until we resume fake.expect(delayedStream, 'emit', 0); // but our original source must emit var params = []; source.on('foo', function(param) { params.push(param); }); source.emit('foo', 1); source.emit('foo', 2); // Make sure delayedStream did not emit, and source did assert.deepEqual(params, [1, 2]); fake.verify(); // After resume, delayedStream must playback all events fake .stub(delayedStream, 'emit') .times(Infinity) .withArg(1, 'newListener'); fake.expect(delayedStream, 'emit', ['foo', 1]); fake.expect(delayedStream, 'emit', ['foo', 2]); fake.expect(source, 'resume'); delayedStream.resume(); fake.verify(); // Calling resume again will delegate to source fake.expect(source, 'resume'); delayedStream.resume(); fake.verify(); // Emitting more events directly leads to them being emitted fake.expect(delayedStream, 'emit', ['foo', 3]); source.emit('foo', 3); fake.verify(); })(); node-delayed-stream-1.0.0/test/integration/test-handle-source-errors.js000066400000000000000000000010541252052350300262100ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testHandleSourceErrors() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {pauseStream: false}); // We deal with this by attaching a no-op listener to 'error' on the source // when creating a new DelayedStream. This way error events on the source // won't throw. source.emit('error', new Error('something went wrong')); })(); node-delayed-stream-1.0.0/test/integration/test-max-data-size.js000066400000000000000000000007661252052350300246220ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testMaxDataSize() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {maxDataSize: 1024, pauseStream: false}); source.emit('data', new Buffer(1024)); fake .expect(delayedStream, 'emit') .withArg(1, 'error'); source.emit('data', new Buffer(1)); fake.verify(); })(); node-delayed-stream-1.0.0/test/integration/test-pipe-resumes.js000066400000000000000000000006131252052350300245630ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testPipeReleases() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {pauseStream: false}); fake.expect(delayedStream, 'resume'); delayedStream.pipe(new Stream()); })(); node-delayed-stream-1.0.0/test/integration/test-proxy-readable.js000066400000000000000000000006721252052350300250700ustar00rootroot00000000000000var common = require('../common'); var assert = common.assert; var fake = common.fake.create(); var DelayedStream = common.DelayedStream; var Stream = require('stream').Stream; (function testProxyReadableProperty() { var source = new Stream(); var delayedStream = DelayedStream.create(source, {pauseStream: false}); source.readable = fake.value('source.readable'); assert.strictEqual(delayedStream.readable, source.readable); })(); node-delayed-stream-1.0.0/test/run.js000077500000000000000000000001711252052350300174530ustar00rootroot00000000000000#!/usr/bin/env node var far = require('far').create(); far.add(__dirname); far.include(/test-.*\.js$/); far.execute();