streams.mkd

Node is working towards a unified data stream interface.

Readable Stream

Required

event: 'data'.

• One argument, a Buffer or String object

event: 'end'

• received EOF or FIN
• does not mean any buffered data has been flushed

event: 'error'

• emitted with exception object
• does not close stream

method: pause()

• suggestion stopRead()
• this is advisory, it does not insure that you will not receive data events

method: resume()

• suggestion startRead()

Optional

method: forceClose()

• close the underlying file descriptor
• suggestion close()

member: readable

• boolean

Examples of readable streams (some of these don't exist yet): server-side HTTP request, client-side HTTP response, process.stdin, childProcess.stdout, childProcess.stderr

Writable Stream

Required

method: write(data)

• Returns true if it could be flushed to kernel, false if not. Data is always queued for writing, even if flushing is not possible. If this method returns false then the event 'drain' will be emitted later, once all data that was buffered has been written to the kernel.

method: close()

• Writes EOF or a FIN packet on the transport once the existing data buffer is drained. Further calls to write() after calling this method will throw an error.
• suggestion end()

event: 'drain'

event: 'error'

• emitted with exception object
• does not close stream

member: writable

• boolean

Examples of writable streams (some of these don't exist yet): server-side HTTP response, client-side HTTP request, process.stdout, process.stderr, childProcess.stdin

Stream.pipe(readable, writeable)

Stream.pipe proxies events from a readable stream (readableStream) argument and a a writable stream (readableStream) and interprets a few behaviors from the events.

Behaviors

• The subject of a "data" event on a readableStream is sent to the write() method of the writableStream.
• When writeableStream.write(data) returns false readableStream will be paused until the drain event occurs on the writableStream. If there is not "pause()" method one is added that will emit("pause").
• When a "pause" event is observed on writableStream a "pause" event is emitted on the readableStream.
• When a "resume" event is observed on writableStream a "resume" event is emitted on the readableStream.

Why not move this to the node wiki?