initial version

Author: seangarner

CHANGELOG.md

@@ -0,0 +1,5 @@
+# buffer-peek-stream changelog
+
+## 0.1.0 (2014/11/05)
+
+ - initial version

README.md

@@ -1,4 +1,55 @@
-node-buffer-peek-stream
-=======================
+# node-buffer-peek-stream
 
-Node Transform stream that lets you inspect the start of a ReadStream before deciding what to do with it
+A Transform stream which lets you take a peek at the first bytes before unpiping itself and unshifting the buffer back onto the upstream stream leaving the original stream ready to be
+piped again onto its final destination.
+
+```
+npm install buffer-peek-stream
+```
+
+Useful if you want to inspect the start of a stream before deciding what to do with it.
+
+This works with buffers and does no string decoding.  If you know you have a string and already
+know its encoding then checkout [peek-stream](https://github.com/mafintosh/peek-stream).
+
+
+## Usage
+As a function...
+```
+var peek = require('./buffer-peek-stream');
+var readstream = fs.createReadStream('package.json');
+
+peek(readstream, 65536, function (err, data) {
+  if (err) throw err;
+
+  // readstream is ready to be piped somewhere else
+  readstream.pipe(somewhere_else);
+});
+```
+
+As a stream...
+```
+var PeekStream = require('./buffer-peek-stream').Constructor;
+
+var peek = new PeekStream(65536);
+var readstream = fs.createReadStream('package.json');
+
+// peek will only emit the data event once
+peek.once('data', function (buf) {
+
+  // readstream is ready to be piped somewhere else
+  readstream.pipe(somewhere_else);
+});
+
+stream.pipe(peek);
+```
+
+
+## NOTICE
+This hasn't been run in production yet and hasn't gone through substantial testing.  The approach
+taken to unshift data back onto the origin stream in particular could turn out to be a bad idea when
+you try to peek at more bytes than are in the stream.
+
+
+## Licence
+MIT

lib/buffer-peek-stream.js

@@ -0,0 +1,93 @@
+var stream = require('stream');
+var util = require('util');
+
+function BufferPeekStream(bytes) {
+  stream.Transform.call(this);
+  this.__buffer = [];
+  this.__bufferLength = 0;
+  this.__peekBytes = bytes || 65536;
+  this.__peeking = true;
+  this.__src = null;
+  var self = this;
+
+  // when we get piped to store the parent so we can unshift what we've peeked
+  this.once('pipe', function (src) {
+    self.__src = src;
+
+    // inherit upstream encoding because sniffing seems to wipe out iconv-lite conversion
+    // ideally would like this not to happen as guessing it's an overhead though small since we're
+    // just peaking small amounts of data
+    if (src._readableState.encoding) self.setEncoding(src._readableState.encoding);
+
+    self.once('pipe', function () {
+      self.emit('error', new Error('BufferPeekStream can only be piped to once'));
+    });
+  });
+}
+
+util.inherits(BufferPeekStream, stream.Transform);
+module.exports = BufferPeekStream;
+
+
+BufferPeekStream.prototype._transform = function _transform(chunk, enc, callback) {
+  // buffer incoming chunks until we have enough for our peek
+  this.__buffer.push(chunk);
+  this.__bufferLength += chunk.length;
+
+  // buffered enough
+  if (this.__bufferLength > this.__peekBytes) this.__stopPeeking();
+
+  callback();
+};
+
+
+BufferPeekStream.prototype._flush = function _flush(callback) {
+  this.__stopPeeking();
+  callback();
+};
+
+
+BufferPeekStream.prototype.__stopPeeking = function __stopPeeking() {
+  // don't want to run this again if we get subsequent calls before drain
+  if (!this.__peeking) return;
+
+  this.__peeking = false;
+
+  // unpipe from upstream
+  this.__src.unpipe(this);
+
+  var buffer = Buffer.concat(this.__buffer);
+  var source = this.__src;
+
+  // push exactly the number of bytes we wanted to peek
+  this.push(buffer.slice(0, this.__peekBytes));
+  this.push(null);
+
+  if (source._readableState.ended) {
+    // if the source has ended then we need to modify its state so it'll start flowing again when we
+    // unshift the data back on.  these settings were naively obtained by creating a file read
+    // stream of a tiny file then leaving it hang for a timeout of 5s and dumping the state
+    source.readable = true;
+    source._readableState.ended = true;
+    source._readableState.endEmitted = false;
+    source._readableState.ranOut = false;
+    source._readableState.reading = false;
+    source._readableState.calledRead = true;
+    source._readableState.sync = false;
+    source._readableState.needReadable = false;
+    source._readableState.emittedReadable = true;
+    source._readableState.readableListening = false;
+    source._readableState.readingMore = false;
+
+    source.unshift(buffer);
+  } else {
+    // delay unshifting all chunks back onto parent until we're drained so we don't lose chunks that
+    // have already been put onto the event stack before we unpiped.
+    this.once('drain', function () {
+      source.unshift(buffer);
+    });
+  }
+
+  // we don't need to keep the original buffers
+  this.__buffer = null;
+};

lib/index.js

@@ -0,0 +1,34 @@
+var BufferPeekStream = require('./buffer-peak-stream');
+
+module.exports = peek;
+
+peek.Constructor = BufferPeekStream;
+
+function peek(input, bytes, cb) {
+  if (typeof bytes === 'function') {
+    cb = bytes;
+    bytes = 65536; // 64K
+  }
+
+  // make sure we don't callback more than once
+  cb = once(cb);
+
+  var _ = new BufferPeekStream(bytes);
+
+  _.once('data', function (data) {
+    cb(null, data);
+  });
+
+  _.once('error', cb);
+
+  input.pipe(_);
+}
+
+function once(fn) {
+  var _fired = false;
+  return function () {
+    if (_fired) return;
+    _fired = true;
+    fn.apply(this, Array.prototype.splice.call(arguments, 0));
+  };
+}

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "buffer-peek-stream",
+  "version": "0.1.0",
+  "description": "Transform stream that lets you inspect the start of a ReadStream before deciding what to do with it",
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "mocha test/buffer-peek-stream.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seangarner/node-buffer-peek-stream.git"
+  },
+  "keywords": [
+    "stream",
+    "peek",
+    "parse",
+    "buffer",
+    "inspect"
+  ],
+  "author": "Sean Garner",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/seangarner/node-buffer-peek-stream/issues"
+  },
+  "homepage": "https://github.com/seangarner/node-buffer-peek-stream"
+}