Permalink
Browse files

readme added

  • Loading branch information...
1 parent b0765af commit 582bc0c540b01db5abd705561ba60bd2e669922b @sidorares committed Aug 19, 2012
Showing with 54 additions and 0 deletions.
  1. +45 −0 README.md
  2. +5 −0 examples/README.md
  3. +4 −0 examples/slowcat.js
View
@@ -0,0 +1,45 @@
+shaper
+======
+
+### Limit stream speed to bytes per second/chunk per second
+
+Inspired by [node-throttle][nt] module, but acts as a through stream and splits input chunks if required to maintain target speed as close as possible.
+
+Installation
+------------
+
+``` bash
+$ npm install throttle
+```
+
+
+'Slow cat' example:
+
+```js
+ var shape = require('shaper');
+ process.stdin.pipe(shape(10)).pipe(process.stdout, {end: false} );
+ process.stdin.resume();
+```js
+
+output:
+
+```
+ $ time echo "this is 58-chars long string (including trailing newline)" | node examples/slowcat.js
+ this is 58-chars long string (including trailing newline)
+
+ real 0m5.912s
+ user 0m0.056s
+ sys 0m0.012s
+```
+
+parameters
+
+ shaper(byteRate, chunkRate, bufferLowWatermarkInSeconds, bufferHighWatermarkInSeconds)
+
+`byteRate` - targeted speed in bytes per second
+`chunkRate` - output chunk rate. If target speed is 20000 bytes per second and chunk rate is 100, you'll have 100 chunks per second stream, each 200 bytes in size (on average). Note that if input stream is slower then target, chunks are sent immideately at input rate, wich could be higher than target chunk rate. If input is 1000 chunks per second, each 10 bytes `shape(20000, 500)` should give same 1000 chunk per second x 10 bytes stream.
+`bufferLowWatermarkInSeconds` - if estimated time to empty buffer is less than this parameter, stream emits `drain` event
+`bufferHighWatermarkInSeconds` - if estimated time to full buffer is less than this parameter, stream `write` returns false.
+
+
+[nt]: https://github.com/TooTallNate/node-throttle
View
@@ -0,0 +1,5 @@
+TODO: explain examples
+
+slowfind requires [exec_stream][exec-stream] module
+
+[exec-stream]: https://github.com/sidorares/exec-stream/
View
@@ -0,0 +1,4 @@
+var shaper = require('..');
+
+process.stdin.pipe(shaper(10)).pipe(process.stdout, {end: false} );
+process.stdin.resume();

0 comments on commit 582bc0c

Please sign in to comment.