diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..096746c --- /dev/null +++ b/.npmignore @@ -0,0 +1 @@ +/node_modules/ \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..103dacd --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# through2-buffer + +A simple `through2` stream that buffers up a certain amount of data before passing anything through. + +This module generates a simple Transform stream that you can use in any (non-object-mode) pipeline, and that will only do a single thing: buffer up a stream to a certain amount. It's useful for eg. audio/video streams, where you want to have a 'headstart' to prevent underruns if your encoding process stalls for a moment. + +The `through2-buffer` will start out in __buffering mode__, and keep collecting incoming chunks of data until it hits the configured buffer size. At that moment, it switches to __flowing mode__, outputs the chunks it has collected, and pass through everything that comes afterwards. + +Once the stream is in flowing mode, it will *never* go back to buffering mode; this is to prevent hiccups in the source stream from causing delayed hiccups in the output. You should make sure that your initial buffer is large enough to cover *all* the hiccups that you will encounter throughout the life of the stream. + +## License + +[WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), whichever you prefer. A donation and/or attribution are appreciated, but not required. + +## Donate + +My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)! + +You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. + +## Contributing + +Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in `src/`, not those in `lib/`. + +Build tool of choice is `gulp`; simply run `gulp` while developing, and it will watch for changes. + +Be aware that by making a pull request, you agree to release your modifications under the licenses stated above. + +## Usage + +__Please be careful not to require the module as `Buffer` or `buffer`! That would cause confusion with the built-in `Buffer` type in Node.js.__ + +The following example would keep reading data from `/dev/urandom` (and converting it to hexadecimal representation), and buffer 5 MiB of it. After that it will switch into flowing mode and pass everything through to the terminal, *including* the originally buffered data. + +```javascript +'use strict'; + +const through2Buffer = require("through2-buffer"); +const fs = require("fs"); + +fs.createReadStream("/dev/urandom", "hex") + .pipe(streamBuffer(5 * 1024 * 1024)) /* 5 MiB buffer size */ + .pipe(process.stdout); +``` + +## API + +### through2Buffer(bufferSize) + +Creates and returns a new `through2-buffer` stream. Like all Node.js streams, this stream is __single-use__. + +* __bufferSize__: The amount of bytes to buffer before switching into flowing mode. diff --git a/gulpfile.js b/gulpfile.js new file mode 100644 index 0000000..1769501 --- /dev/null +++ b/gulpfile.js @@ -0,0 +1,18 @@ +var gulp = require("gulp"); +var presetES2015 = require("@joepie91/gulp-preset-es2015"); + +var source = ["src/**/*.js"] + +gulp.task('babel', function() { + return gulp.src(source) + .pipe(presetES2015({ + basePath: __dirname + })) + .pipe(gulp.dest("lib/")); +}); + +gulp.task("watch", function () { + gulp.watch(source, ["babel"]); +}); + +gulp.task("default", ["babel", "watch"]); \ No newline at end of file diff --git a/index.js b/index.js new file mode 100644 index 0000000..507257b --- /dev/null +++ b/index.js @@ -0,0 +1,3 @@ +'use strict'; + +module.exports = require("./lib"); \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..24fea1b --- /dev/null +++ b/package.json @@ -0,0 +1,30 @@ +{ + "name": "through2-buffer", + "version": "1.0.0", + "description": "A simple through2 stream that buffers up a certain amount of data before passing anything through", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "http://git.cryto.net/joepie91/node-through2-buffer.git" + }, + "keywords": [ + "through2", + "streams", + "buffering" + ], + "author": "Sven Slootweg", + "license": "WTFPL", + "dependencies": { + "bl": "^1.1.2", + "debug": "^2.2.0", + "through2": "^2.0.1" + }, + "devDependencies": { + "@joepie91/gulp-preset-es2015": "^1.0.1", + "babel-preset-es2015": "^6.6.0", + "gulp": "^3.9.1" + } +} diff --git a/src/index.js b/src/index.js new file mode 100644 index 0000000..21475b5 --- /dev/null +++ b/src/index.js @@ -0,0 +1,28 @@ +'use strict'; + +const bl = require("bl"); +const through2 = require("through2"); +const debug = require("debug")("through2-buffer"); + +module.exports = function(bufferSize) { + let buff = bl(); + let flowing = false; + + return through2(function(chunk, encoding, cb) { + if (flowing) { + this.push(chunk); + } else { + debug(`Buffering chunk of size ${chunk.length}`); + buff.append(chunk); + debug(`Buffer length now ${buff.length}`); + + if (buff.length >= bufferSize) { + debug("Buffer limit reached; setting to flowing mode"); + flowing = true; + this.push(buff.read(buff.length)); + } + } + + cb(); + }); +} \ No newline at end of file diff --git a/test.js b/test.js new file mode 100644 index 0000000..9746dff --- /dev/null +++ b/test.js @@ -0,0 +1,8 @@ +'use strict'; + +const streamBuffer = require("./"); +const fs = require("fs"); + +fs.createReadStream("/dev/urandom", "hex") + .pipe(streamBuffer(5 * 1024 * 1024)) + .pipe(process.stdout); \ No newline at end of file