# 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.

All streams *may* emit `'close'`. `'close'` means that any underlying resources have been disposed of. 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.

### end()

calling `end` *may* set `writable` to `false`.
If the `Stream` is also readable, it *must* eventually 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.

## 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.

### 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.

### 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.

## request for comment

thank you in advance!