2.7 KiB
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 theend()
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 theWritable
of an attached/detached pipe sender.
Methods:
-
cork
/uncork
, for batching supplied inputs -
destroy
, abandon theWritable
without bothering to try to finish; dual toerror
, more or less -
end
, does an optionalwrite
and then signals the clean end of the input stream. If a callback is supplied, it is attached as a listener tofinish
. -
write
, delivers a chunk of input. Yieldsfalse
when the buffer is full at the time the call towrite
returns; will issuedrain
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 forWritable
. -
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'sFIN
. Is in-order wrt other data. -
data
, delivers a chunk of output.
Methods:
-
pipe
/unpipe
, for attaching aWritable
to thisReadable
. Many of them can be attached! I guess that makes a fan-out? By default, theend
method of theWritable
is called when theReadable
emits itsend
event, but this can be overridden with an option. -
isPaused
,pause
andresume
control and interrogate XON/XOFF-style flow control. -
destroy
, abandon theReadable
without bothering to try to finish reading from it; not quite dual to error since aReadable
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. Returnsfalse
when the buffer is (over-)full. -
unshift
, internalish API for poking a chunk into the "first-in" end of the FIFO buffer, likeungetc()
etc. There are complications in using this, check the docs.
Properties:
- high water mark, length of buffer in use.