ACE-Responsive Admin Template

# readable-stream A new class of streams for Node.js This module provides the new Stream base classes introduced in Node v0.10, for use in Node v0.8. You can use it to have programs that have to work with node v0.8, while being forward-compatible for v0.10 and beyond. When you drop support for v0.8, you can remove this module, and only use the native streams. This is almost exactly the same codebase as appears in Node v0.10. However: 1. The exported object is actually the Readable class. Decorating the native `stream` module would be global pollution. 2. In v0.10, you can safely use `base64` as an argument to `setEncoding` in Readable streams. However, in v0.8, the StringDecoder class has no `end()` method, which is problematic for Base64. So, don't use that, because it'll break and be weird. Other than that, the API is the same as `require('stream')` in v0.10, so the API docs are reproduced below. ---------- Stability: 2 - Unstable A stream is an abstract interface implemented by various objects in Node. For example a request to an HTTP server is a stream, as is stdout. Streams are readable, writable, or both. All streams are instances of [EventEmitter][] You can load the Stream base classes by doing `require('stream')`. There are base classes provided for Readable streams, Writable streams, Duplex streams, and Transform streams. ## Compatibility In earlier versions of Node, the Readable stream interface was simpler, but also less powerful and less useful. * Rather than waiting for you to call the `read()` method, `'data'` events would start emitting immediately. If you needed to do some I/O to decide how to handle data, then you had to store the chunks in some kind of buffer so that they would not be lost. * The `pause()` method was advisory, rather than guaranteed. This meant that you still had to be prepared to receive `'data'` events even when the stream was in a paused state. In Node v0.10, the Readable class described below was added. For backwards compatibility with older Node programs, Readable streams switch into "old mode" when a `'data'` event handler is added, or when the `pause()` or `resume()` methods are called. The effect is that, even if you are not using the new `read()` method and `'readable'` event, you no longer have to worry about losing `'data'` chunks. Most programs will continue to function normally. However, this introduces an edge case in the following conditions: * No `'data'` event handler is added. * The `pause()` and `resume()` methods are never called. For example, consider the following code: ```javascript // WARNING! BROKEN! net.createServer(function(socket) { // we add an 'end' method, but never consume the data socket.on('end', function() { // It will never get here. socket.end('I got your message (but didnt read it)\n'); }); }).listen(1337); ``` In versions of node prior to v0.10, the incoming message data would be simply discarded. However, in Node v0.10 and beyond, the socket will remain paused forever. The workaround in this situation is to call the `resume()` method to trigger "old mode" behavior: ```javascript // Workaround net.createServer(function(socket) { socket.on('end', function() { socket.end('I got your message (but didnt read it)\n'); }); // start the flow of data, discarding it. socket.resume(); }).listen(1337); ``` In addition to new Readable streams switching into old-mode, pre-v0.10 style streams can be wrapped in a Readable class using the `wrap()` method. ## Class: stream.Readable <!--type=class--> A `Readable Stream` has the following methods, members, and events. Note that `stream.Readable` is an abstract class designed to be extended with an underlying implementation of the `_read(size)` method. (See below.) ### new stream.Readable([options]) * `options` {Object} * `highWaterMark` {Number} The maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource. Default=16kb * `encoding` {String} If specified, then buffers will be decoded to strings using the specified encoding. Default=null * `objectMode` {Boolean} Whether this stream should behave as a stream of objects. Meaning that stream.read(n) returns a single value instead of a Buffer of size n In classes that extend the Readable class, make sure to call the constructor so that the buffering settings can be properly initialized. ### readable.\_read(size) * `size` {Number} Number of bytes to read asynchronously Note: **This function should NOT be called directly.** It should be implemented by child classes, and called by the internal Readable class methods only. All Readable stream implementations must provide a `_read` method to fetch data from the underlying resource. This method is prefixed with an underscore because it is internal to the class that defines it, and should not be called directly by user programs. However, you **are** expected to override this method in your own extension classes. When data is available, put it into the read queue by calling `readable.push(chunk)`. If `push` returns false, then you should stop reading. When `_read` is called again, you should start pushing more data. The `size` argument is advisory. Implementations where a "read" is a single call that returns data can use this to know how much data to fetch. Implementations where that is not relevant, such as TCP or TLS, may ignore this argument, and simply provide data whenever it becomes available. There is no need, for example to "wait" until `size` bytes are available before calling `stream.push(chunk)`. ### readable.push(chunk) * `chunk` {Buffer | null | String} Chunk of data to push into the read queue * return {Boolean} Whether or not more pushes should be performed Note: **This function should be called by Readable implementors, NOT by consumers of Readable subclasses.** The `_read()` function will not be called again until at least one `push(chunk)` call is made. If no data is available, then you MAY call `push('')` (an empty string) to allow a future `_read` call, without adding any data to the queue. The `Readable` class works by putting data into a read queue to be pulled out later by calling the `read()` method when the `'readable'` event fires. The `push()` method will explicitly insert some data into the read queue. If it is called with `null` then it will signal the end of the data. In some cases, you may be wrapping a lower-level source which has some sort of pause/resume mechanism, and a data callback. In those cases, you could wrap the low-level source object by doing something like this: ```javascript // source is an object with readStop() and readStart() methods, // and an `ondata` member that gets called when it has data, and // an `onend` member that gets called when the data is over. var stream = new Readable(); source.ondata = function(chunk) { // if push() returns false, then we need to stop reading from source if (!stream.push(chunk)) source.readStop(); }; source.onend = function() { stream.push(null); }; // _read will be called when the stream wants to pull more data in // the advisory size argument is ignored in this case. stream._read = function(n) { source.readStart(); }; ``` ### readable.unshift(chunk) * `chunk` {Buffer | null | String} Chunk of data to unshift onto the read queue * return {Boolean} Whether or not more pushes should be performed This is the corollary of `readable.push(chunk)`. Rather than putting the data at the *end* of the read queue, it puts it at the *front* of the read queue. This is useful in certain use-cases where a stream is being consumed by a parser, which needs to "un-consume" some data that it has optimistically pulled out of the source. ```javascript // A parser for a simple data protocol. // The "header" is a JSON object, followed by 2 \n characters, and // then a message body.