100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
# Streams in node.js 10.x → Syndicate
|
|
|
|
Streams can be in binary or object mode
|
|
|
|
Desiderata: Like enumerator/observable, it seems like
|
|
readable/writable should be duals. If they're not, why not, other than
|
|
historical reasons?
|
|
|
|
## GENERAL
|
|
|
|
`stream.finished()`
|
|
|
|
## WRITABLE
|
|
|
|
Has a buffer of to-be-accepted elements.
|
|
|
|
Emits:
|
|
|
|
- `close` (optional), after all resources have been released. No more
|
|
events, no more computation, nothing more will happen.
|
|
|
|
- `drain`, when the buffer runs *empty*, to signal a demand for more
|
|
input.
|
|
|
|
- `error`
|
|
|
|
- `finish`, exactly equivalent to a callback-function acknowledging
|
|
the `end()` call: the "no more input is available" signal has been
|
|
completely processed and has made its way through to the
|
|
underlying/backing medium.
|
|
|
|
- `pipe`/`unpipe`, notifies the `Writable` of an attached/detached
|
|
pipe sender.
|
|
|
|
Methods:
|
|
|
|
- `cork`/`uncork`, for batching supplied inputs
|
|
|
|
- `destroy`, abandon the `Writable` without bothering to try to
|
|
finish; dual to `error`, more or less
|
|
|
|
- `end`, does an optional `write` and then signals the clean end of
|
|
the input stream. If a callback is supplied, it is attached as a
|
|
listener to `finish`.
|
|
|
|
- `write`, delivers a chunk of input. Yields `false` when the buffer
|
|
is *full* at the time the call to `write` returns; will issue
|
|
`drain` later in this case.
|
|
|
|
Properties:
|
|
|
|
- high water mark, length of buffer in use.
|
|
|
|
## READABLE
|
|
|
|
Has a buffer of to-be-relayed elements.
|
|
|
|
Emits:
|
|
|
|
- `close` (optional), exactly the same as for `Writable`.
|
|
|
|
- `readable`, when the buffer becomes *nonempty* from having been
|
|
empty, to signal the possibility of more output.
|
|
|
|
- `error`
|
|
|
|
- `end`, when no more data will be produced; analogous to TCP's
|
|
`FIN`. Is in-order wrt other data.
|
|
|
|
- `data`, delivers a chunk of output.
|
|
|
|
Methods:
|
|
|
|
- `pipe`/`unpipe`, for attaching a `Writable` to this `Readable`.
|
|
Many of them can be attached! I guess that makes a fan-out? By
|
|
default, the `end` method of the `Writable` is called when the
|
|
`Readable` emits its `end` event, but this can be overridden with
|
|
an option.
|
|
|
|
- `isPaused`, `pause` and `resume` control and interrogate
|
|
XON/XOFF-style flow control.
|
|
|
|
- `destroy`, abandon the `Readable` without bothering to try to
|
|
finish reading from it; not quite dual to error since a `Readable`
|
|
is a source, not a sink
|
|
|
|
- `read`, explicitly get a chunk
|
|
|
|
- `push`, internal API for poking a chunk into the "last-in" end of
|
|
the FIFO to-be-delivered buffer. Returns `false` when the buffer is
|
|
(over-)full.
|
|
|
|
- `unshift`, internalish API for poking a chunk into the "first-in"
|
|
end of the FIFO buffer, like `ungetc()` etc. There are
|
|
complications in using this, check the docs.
|
|
|
|
Properties:
|
|
|
|
- high water mark, length of buffer in use.
|