stream-spec/stream_spec.md

a Stream spec

This document defines the behaviour that a Stream must implement in order to be compatible with Stream#pipe. This is not an official document, but is intended as a guide to produce correct behaviour in user-land streams.

Stream

All streams must emit 'error' if writing to or reading from becomes physically impossible. 'error' implys that the stream has ended, do not emit 'end' after error, 'close' may be emitted.

All streams should emit 'close'. 'close' means that any underlying resources have been disposed of. 'close' must be emitted either after end, or instead of 'end'.

Emitting 'close' without 'end' indicates a broken pipe - Stream#pipe will call dest.destroy()

If a ReadableStream has ended normally, it must not emit 'close' before 'end'.

A Stream must not emit 'error' if the error is recoverable. (that is not in the stream spec)

All streams should implement destroy but a WritableStream must implement destroy.

emit('error')

All streams must emit 'error' when an error that is not recoverable has occurred. If it has become physically impossible to write to or read from the Stream, then emit 'error'.

A WriteableStream may throw an error if write has been called after end. (which should never happen, in correct usage)

otherwise, a stream must never throw an error. (always emit)

WritableStream

A WritableStream must implement methods write, end, and destroy, and writable must be set to true, and must inherit Stream#pipe

write(data)

write must return either true or false. (if false then the writer should pause) If write is called after end, an error may be thrown.

If write returns false,it must eventually emit 'drain'. write returning false means the stream is paused. paused means (or downstream) is at capacity, and the writer/upstream should attempt to slow down or stop. It does not mean all data must be buffered, although that is something a stream may reasonably do.

end()

Calling end must set writable to false. If the Stream is also readable, it must eventually emit 'end', and then 'close'. If the Stream in not also readable, it must eventually emit 'close' but not emit 'end'.

destroy()

Used to dispose of a Stream.

Calling destroy must dispose of any underlying resources. Calling destroy must emit 'close' eventually, once any underlying resources are disposed of.

emit ('drain')

After pausing, a Stream must eventually emit 'drain'. For example, when if a call to write() === false,
Stream#pipe will call pause on the source and
then call source.resume(), when the dest emits 'drain'.

If drain is not emitted correctly, it's possible for 'data' events to stop coming (depending on the source's behaviour when paused).

ReadableStream

A ReadableStream must inherit pipe from Stream, and set readable to true, and must emit zero or more 'data' events, followed by a single end event. A ReadableStream may implement pause and resume methods.

• I will not bother to specify the behaviour of pipe because I am attempting to document what must be done in order for your Stream to be compatible with pipe.

emit('data', data)

A ReadableStream may emit one or more 'data' events. A ReadableStream must not emit emit a 'data' event after it has emitted 'end'

emit('end')

A ReadableStream should emit an 'end' event when it is not going to emit any more 'data' events. 'end' must not be emitted more than once. A ReadableStream may set readable to false after it has emitted the 'end' event.

Also, a Stream should internally call destroy after it has emitted 'end'.

emit ('close')

A ReadableStream must emit a 'close' event after the 'end' event. 'close' must only be emitted once. if destroy is called, 'close' must be emitted, unless the stream has already ended normally. If 'close' is emitted before 'end' that signifies a broken stream, this should only happen if destroy was called.

Emitting close will cause pipe to call destroy on the down stream pipe, if it is emitted before end.

pause()

A readable Stream may implement the pause method. When pause is called, the stream should attempt to emit 'data' less often. (possibly stopping altogether until resume is called)

resume()

A ReadableStream may implement the resume method. If the Stream has been paused, it may now emit 'data' more often, or commence emitting data if it has stopped all together.

If a stream is also writable, and has returned false on write it must now eventually emit drain

destroy()

A ReadableStream should implement destroy.

Calling destroy must dispose of any underlying resources. Calling destroy must emit 'close' eventually, once any underlying resources are disposed of.