{
  "name": "readable-stream",
  "version": "0.2.0",
  "description": "An exploration of a new kind of readable streams for Node.js",
  "main": "readable.js",
  "dependencies": {},
  "devDependencies": {
    "tap": "~0.2.6"
  },
  "scripts": {
    "test": "tap test/simple/*.js"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/isaacs/readable-stream"
  },
  "keywords": [
    "readable",
    "stream",
    "pipe"
  ],
  "author": {
    "name": "Isaac Z. Schlueter",
    "email": "i@izs.me",
    "url": "http://blog.izs.me/"
  },
  "license": "BSD",
  "readme": "# readable-stream\n\n    Stability: 1 - Experimental\n\nA new kind of readable streams for Node.js\n\nThis is an abstract class designed to be extended.  It also provides a\n`wrap` method that you can use to provide the simpler readable API for\nstreams that have the \"readable stream\" interface of Node 0.8 and\nbefore.\n\nNote that Duplex, Transform, Writable, and PassThrough streams are also\nprovided as base classes.  See the full API details below.\n\n## Justification\n\n<!-- misc -->\n\nWritable streams in node are relatively straightforward to use and\nextend.  The `write` method either returns `false` if you would like\nthe user to back off a bit, in which case a `drain` event at some\npoint in the future will let them continue writing, or anything other\nthan false if the bytes could be completely handled and another\n`write` should be performed, or   The `end()` method lets the user\nindicate that no more bytes will be written.  That's pretty much the\nentire required interface for writing.\n\nHowever, readable streams in Node 0.8 and before are rather\ncomplicated.\n\n1. The `data` events start coming right away, no matter what.  There\n   is no way to do other actions before consuming data, without\n   handling buffering yourself.\n2. If you extend the interface in userland programs, then you must\n   implement `pause()` and `resume()` methods, and take care of\n   buffering yourself.\n3. In many streams, `pause()` was purely advisory, so **even while\n   paused**, you still have to be careful that you might get some\n   data.  This caused a lot of subtle b ugs.\n\nSo, while writers only have to implement `write()`, `end()`, and\n`drain`, readers have to implement (at minimum):\n\n* `pause()` method\n* `resume()` method\n* `data` event\n* `end` event\n\nAnd read consumers had to always be prepared for their backpressure\nadvice to simply be ignored.\n\nIf you are using a readable stream, and want to just get the first 10\nbytes, make a decision, and then pass the rest off to somewhere else,\nthen you have to handle buffering, pausing, slicing, and so on.  This\nis all rather brittle and easy to get wrong for all but the most\ntrivial use cases.\n\nAdditionally, this all made the `reader.pipe(writer)` method\nunnecessarily complicated and difficult to extend without breaking\nsomething.  Backpressure and error handling is especially challenging\nand brittle.\n\n### Solution\n\n<!-- misc -->\n\nThe reader does not have pause/resume methods.  If you want to consume\nthe bytes, you call `read()`.  If bytes are not being consumed, then\neffectively the stream is in a paused state.  It exerts backpressure\non upstream connections, doesn't read from files, etc.  Any data that\nwas already in the process of being read will be placed in a buffer.\n\nIf `read()` returns `null`, then a future `readable` event will be\nfired when there are more bytes ready to be consumed.\n\nThis is simpler and conceptually closer to the underlying mechanisms.\nThe resulting `pipe()` method is much shorter and simpler.  The\nproblems of data events happening while paused are alleviated.\n\n### Compatibility\n\n<!-- misc -->\n\nIt's not particularly difficult to wrap old-style streams in this\nnew interface, or to wrap this type of stream in the old-style\ninterface.\n\nThe `Readable` class provides a `wrap(oldStream)` method that takes an\nargument which is an old-style stream with `data` events and `pause()`\nand `resume()` methods, and uses that as the data source.  For\nexample:\n\n```javascript\nvar r = new Readable();\nr.wrap(oldReadableStream);\n\n// now you can use r.read(), and it will emit 'readable' events\n// but the data is based on whatever oldReadableStream spits out of\n// its 'data' events.\n```\n\nIn order to work with programs that use the old interface, some\nmagic is unfortunately required.  At some point in the future, this\nmagic will be removed.\n\nThe `Readable` class will automatically convert into an old-style\n`data`-emitting stream if any listeners are added to the `data` event.\nSo, this works fine, though you of course lose a lot of the benefits of\nthe new interface:\n\n```javascript\nvar r = new ReadableThing();\n\nr.on('data', function(chunk) {\n  // ...\n  // magic is happening!  oh no!  the animals are walking upright!\n  // the brooms are sweeping the floors all by themselves!\n});\n\n// this will also turn on magic-mode:\nr.pause();\n\n// now pause, resume, etc. are patched into place, and r will\n// continually call read() until it returns null, emitting the\n// returned chunks in 'data' events.\n\nr.on('end', function() {\n  // ...\n});\n```\n\n## Class: Readable\n\nA base class for implementing Readable streams.  Override the\n`_read(n,cb)` method to fetch data asynchronously and take advantage\nof the buffering built into the Readable class.\n\n### Example\n\nExtend the Readable class, and provide a `_read(n,cb)` implementation\nmethod.\n\n```javascript\nvar Readable = require('readable-stream');\nvar util = require('util');\n\nutil.inherits(MyReadable, Readable);\n\nfunction MyReadable(options) {\n  Readable.call(this, options);\n}\n\nMyReadable.prototype._read = function(n, cb) {\n  // your magic goes here.\n  // call the cb at some time in the future with either up to n bytes,\n  // or an error, like cb(err, resultData)\n  //\n  // The code in the Readable class will call this to keep an internal\n  // buffer at a healthy level, as the user calls var chunk=stream.read(n)\n  // to consume chunks.\n};\n\nvar r = new MyReadable();\n\nr.on('end', function() {\n  // no more bytes will be provided.\n});\n\nr.on('readable', function() {\n  // now is the time to call read() again.\n});\n\n// to get some bytes out of it:\nvar data = r.read(optionalLengthArgument);\n// now data is either null, or a buffer of optionalLengthArgument\n// length.  If you don't provide an argument, then it returns whatever\n// it has.\n\n// typically you'd just r.pipe() into some writable stream, but you\n// can of course do stuff like this, as well:\nfunction flow() {\n  var chunk;\n  while (null !== (chunk = r.read())) {\n    doSomethingWithData(chunk);\n  }\n  r.once('readable', flow);\n}\nflow();\n```\n\n### new Readable(options)\n\n* `options` {Object}\n  * `lowWaterMark` {Number} The minimum number of bytes before the\n    stream is considered 'readable'.  Default = `0`\n  * `bufferSize` {Number} The number of bytes to try to read from the\n    underlying `_read` function.  Default = `16 * 1024`\n\nMake sure to call the `Readable` constructor in your extension\nclasses, or else the stream will not be properly initialized.\n\n### readable.read([size])\n\n* `size` {Number} Optional number of bytes to read.  If not provided,\n  then return however many bytes are available.\n* Returns: {Buffer | null}\n\nPulls the requested number of bytes out of the internal buffer.  If\nthat many bytes are not available, then it returns `null`.\n\n### readable.\\_read(size, callback)\n\n* `size` {Number} Number of bytes to read from the underlying\n  asynchronous data source.\n* `callback` {Function} Callback function\n  * `error` {Error Object}\n  * `data` {Buffer | null}\n\n**Note: This function is not implemented in the Readable base class.**\nRather, it is up to you to implement `_read` in your extension\nclasses.\n\n`_read` should fetch the specified number of bytes, and call the\nprovided callback with `cb(error, data)`, where `error` is any error\nencountered, and `data` is the returned data.\n\nThis method is prefixed with an underscore because it is internal to\nthe class that defines it, and should not be called directly by user\nprograms.  However, you **are** expected to override this method in\nyour own extension classes.\n\nThe `size` argument is purely advisory.  You may call the callback\nwith more or fewer bytes.  However, if you call the callback with\n`null`, or an empty buffer, then it will assume that the end of the\ndata was reached.\n\n### readable.pipe(destination)\n\n* `destination` {Writable Stream object}\n\nContinually `read()` data out of the readable stream, and `write()` it\ninto the writable stream.  When the `writable.write(chunk)` call\nreturns `false`, then it will back off until the next `drain` event,\nto do backpressure.\n\nPiping to multiple destinations is supported.  The slowest destination\nstream will limit the speed of the `pipe()` flow.\n\nNote that this puts the readable stream into a state where not very\nmuch can be done with it.  You can no longer `read()` from the stream\nin other code, without upsetting the pipe() process.  However, since\nmultiple pipe destinations are supported, you can always create a\n`PassThrough` stream, and pipe the reader to that.  For example:\n\n```\nvar r = new ReadableWhatever();\nvar pt = new PassThrough();\n\nr.pipe(someWritableThing);\nr.pipe(pt);\n\n// now I can call pt.read() to my heart's content.\n// note that if I *don't* call pt.read(), then it'll back up and\n// prevent the pipe() from flowing!\n```\n\n### readable.unpipe([destination])\n\n* `destination` {Writable Stream object} Optional\n\nRemove the provided `destination` stream from the pipe flow.  If no\nargument is provided, then it will unhook all piped destinations.\n\n### readable.on('readable')\n\nAn event that signals more data is now available to be read from the\nstream.  Emitted when more data arrives, after previously calling\n`read()` and getting a null result.\n\n### readable.on('end')\n\nAn event that signals that no more data will ever be available on this\nstream.  It's over.\n\n### readable.\\_readableState\n\n* {Object}\n\nAn object that tracks the state of the stream.  Buffer information,\nwhether or not it has reached the end of the underlying data source,\netc., are all tracked on this object.\n\nYou are strongly encouraged not to modify this in any way, but it is\noften useful to read from.\n\n## Class: Writable\n\nA base class for creating Writable streams.  Similar to Readable, you\ncan create child classes by overriding the asynchronous\n`_write(chunk,cb)` method, and it will take care of buffering,\nbackpressure, and so on.\n\n### new Writable(options)\n\n* `options` {Object}\n  * `highWaterMark` {Number} The number of bytes to store up before it\n    starts returning `false` from write() calls.  Default = `16 * 1024`\n  * `lowWaterMark` {Number} The number of bytes that the buffer must\n    get down to before it emits `drain`.  Default = `1024`\n\nMake sure to call the `Writable` constructor in your extension\nclasses, or else the stream will not be properly initialized.\n\n### writable.write(chunk, [encoding])\n\n* `chunk` {Buffer | String}\n* `encoding` {String} An encoding argument to turn the string chunk\n  into a buffer.  Only relevant if `chunk` is a string.\n  Default = `'utf8'`.\n* Returns `false` if you should not write until the next `drain`\n  event, or some other value otherwise.\n\nThe basic write function.\n\n### writable.\\_write(chunk, callback)\n\n* `chunk` {Buffer}\n* `callback` {Function}\n  * `error` {Error | null} Call with an error object as the first\n    argument to indicate that the write() failed for unfixable\n    reasons.\n\n**Note: This function is not implemented in the Writable base class.**\nRather, it is up to you to implement `_write` in your extension\nclasses.\n\n`_write` should do whatever has to be done in this specific Writable\nclass, to handle the bytes being written.  Write to a file, send along\na socket, encrypt as an mp3, whatever needs to be done.  Do your I/O\nasynchronously, and call the callback when it's complete.\n\nThis method is prefixed with an underscore because it is internal to\nthe class that defines it, and should not be called directly by user\nprograms.  However, you **are** expected to override this method in\nyour own extension classes.\n\n### writable.end([chunk], [encoding])\n\n* `chunk` {Buffer | String}\n* `encoding` {String}\n\nIf a chunk (and, optionally, an encoding) are provided, then that\nchunk is first passed to `this.write(chunk, encoding)`.\n\nThis method is a way to signal to the writable stream that you will\nnot be writing any more data.  It should be called exactly once for\nevery writable stream.\n\nCalling `write()` *after* calling `end()` will trigger an error.\n\n### writable.on('pipe', source)\n\nEmitted when calling `source.pipe(writable)`.  See above for the\ndescription of the `readable.pipe()` method.\n\n### writable.on('unpipe', source)\n\nEmitted when calling `source.unpipe(writable)`.  See above for the\ndescription of the `readable.unpipe()` method.\n\n### writable.on('drain')\n\nIf a call to `writable.write()` returns false, then at some point in\nthe future, this event will tell you to start writing again.\n\n### writable.on('finish')\n\nWhen the stream has been ended, and all the data in its internal\nbuffer has been consumed, then it emits a `finish` event to let you\nknow that it's completely done.\n\nThis is particularly handy if you want to know when it is safe to shut\ndown a socket or close a file descriptor.  At this time, the writable\nstream may be safely disposed.  Its mission in life has been\naccomplished.\n\n## Class: Duplex\n\nA base class for Duplex streams (ie, streams that are both readable\nand writable).\n\nSince JS doesn't have multiple prototypal inheritance, this class\nprototypally inherits from Readable, and then parasitically from\nWritable.  It is thus up to the user to implement both the lowlevel\n`_read(n,cb)` method as well as the lowlevel `_write(chunk,cb)`\nmethod on extension duplex classes.\n\nFor cases where the written data is transformed into the output, it\nmay be simpler to use the `Transform` class instead.\n\n### new Duplex(options)\n\n* `options` {Object}  Passed to both the Writable and Readable\n  constructors.\n\nMake sure to call the `Duplex` constructor in your extension\nclasses, or else the stream will not be properly initialized.\n\nIf `options.allowHalfOpen` is set to the value `false`, then the\nstream will automatically end the readable side when the writable\nside ends, and vice versa.\n\n### duplex.allowHalfOpen\n\n* {Boolean} Default = `true`\n\nSet this flag to either `true` or `false` to determine whether or not\nto automatically close the writable side when the readable side ends,\nand vice versa.\n\n\n## Class: Transform\n\nA duplex (ie, both readable and writable) stream that is designed to\nmake it easy to implement transform operations such as encryption,\ndecryption, compression, and so on.\n\nTransform streams are `instanceof` Readable, but they have all of the\nmethods and properties of both Readable and Writable streams.  See\nabove for the list of events and methods that Transform inherits from\nWritable and Readable.\n\nOverride the `_transform(chunk, outputFunction, callback)` method in\nyour implementation classes to take advantage of it.\n\n### new Transform(options)\n\n* `options` {Object}  Passed to both the Writable and Readable\n  constructors.\n\nMake sure to call the `Transform` constructor in your extension\nclasses, or else the stream will not be properly initialized.\n\n### transform.\\_transform(chunk, outputFn, callback)\n\n* `chunk` {Buffer} The chunk to be transformed.\n* `outputFn` {Function} Call this function with any output data to be\n  passed to the readable interface.\n* `callback` {Function} Call this function (optionally with an error\n  argument) when you are done processing the supplied chunk.\n\n**Note: This function is not implemented in the Transform base class.**\nRather, it is up to you to implement `_transform` in your extension\nclasses.\n\n`_transform` should do whatever has to be done in this specific\nTransform class, to handle the bytes being written, and pass them off\nto the readable portion of the interface.  Do asynchronous I/O,\nprocess things, and so on.\n\nCall the callback function only when the current chunk is completely\nconsumed.  Note that this may mean that you call the `outputFn` zero\nor more times, depending on how much data you want to output as a\nresult of this chunk.\n\nThis method is prefixed with an underscore because it is internal to\nthe class that defines it, and should not be called directly by user\nprograms.  However, you **are** expected to override this method in\nyour own extension classes.\n\n### transform.\\_flush(outputFn, callback)\n\n* `outputFn` {Function} Call this function with any output data to be\n  passed to the readable interface.\n* `callback` {Function} Call this function (optionally with an error\n  argument) when you are done flushing any remaining data.\n\n**Note: This function is not implemented in the Transform base class.**\nRather, it is up to you to implement `_flush` in your extension\nclasses optionally, if it applies to your use case.\n\nIn some cases, your transform operation may need to emit a bit more\ndata at the end of the stream.  For example, a `Zlib` compression\nstream will store up some internal state so that it can optimally\ncompress the output.  At the end, however, it needs to do the best it\ncan with what is left, so that the data will be complete.\n\nIn those cases, you can implement a `_flush` method, which will be\ncalled at the very end, after all the written data is consumed, but\nbefore emitting `end` to signal the end of the readable side.  Just\nlike with `_transform`, call `outputFn` zero or more times, as\nappropriate, and call `callback` when the flush operation is complete.\n\nThis method is prefixed with an underscore because it is internal to\nthe class that defines it, and should not be called directly by user\nprograms.  However, you **are** expected to override this method in\nyour own extension classes.\n\n\n## Class: PassThrough\n\nThis is a trivial implementation of a `Transform` stream that simply\npasses the input bytes across to the output.  Its purpose is mainly\nfor examples and testing, but there are occasionally use cases where\nit can come in handy.\n",
  "readmeFilename": "README.md",
  "bugs": {
    "url": "https://github.com/isaacs/readable-stream/issues"
  },
  "_id": "readable-stream@0.2.0",
  "_from": "readable-stream@~0.2.0"
}
