A set of tools for quickly processing data in a streaming way
Kind: global namespace
- streamlike :
object
Kind: static class of streamlike
Stream
is the base stream class.
it should always be subclassed.
stream constructors should never require new.
open is the method that's called when a stream needs to be opened. streams should always open as late as possible. if read is called on an unopened stream, it should open before reading. if open is called twice, it should be safe. if open is called on a closed stream, the stream should remain closed.
Kind: instance method of Stream
close is the method that's called when a stream needs to be close. streams should always close as early as possible. if read is called on a closed stream, it should stay closed (return Stream.END). if close is called twice, it should be safe. if open is called on a closed stream, the stream should remain closed.
Kind: instance method of Stream
read is the core method of streams. read should return the next value in the stream. if there are no more values to read, or the stream is closed, read should return Stream.END
Kind: instance method of Stream
Params
- recycle - a 'container' value to re-use when returning the next value. always optional.
// this
let stream = From(1, 2, 3, 4);
stream = Slice(stream, 0, 10);
stream = Assert(stream, (val, i) => Number.isInteger(val));
stream = ToArray(stream);
// is equivalent to this
const stream = From(1, 2, 3, "4")
.pipe(Slice, 0, 10)
.pipe(Assert, (val, i) => Number.isInteger(val))
.pipe(ToArray);
pipe is a utility method to wrap one stream in another.
Kind: instance method of Stream
Params
- streamContsructor - the constructor function for another Stream. pipe assumes the constructor takes a source stream as its first argument
- ...args
*
- any number of additional args to pass into streamConstructor
a unique object representing a control signal marking the end of a stream
Kind: static property of Stream
// works
const integers = From(1, 2, 3, 4)
.pipe(Slice, 0, 10)
.pipe(Assert, (val, i) => Number.isInteger(val))
.pipe(ToArray)
.read();
// throws error
const integers = From(1, 2, 3, "4")
.pipe(Assert, (val, i) => Number.isInteger(val))
.pipe(ToArray)
.read();
Assert
is a stream constructor that builds a stream to run an assertion against every value in the stream
Kind: static property of streamlike
Params
- source
Stream
- a source stream - assert
function
- an assertion function - error
function
- an error builder function
// array of [ 0, 1, 2, 3 ]
const integers = Count()
.pipe(Slice, 0, 4)
.pipe(ToArray)
.read();
Count
is a stream constructor that builds a stream that counts integers upward
Count
never terminates, so make sure to add a terminating stream like a Slice
somewhere after it.
Kind: static property of streamlike
Params
- start
number
- the number to start counting from
// returns Stream.END
Count()
.pipe(Slice, 0, 4)
.pipe(Drain)
.read();
Drain
is a stream constructor wraps a source stream, and when read is called it reads the entire stream and throws it away.
Useful for streams with side-effects.
Kind: static property of streamlike
Params
- source
Stream
- the source stream to drain
// should log:
// element 0 is 1
// element 1 is 2
// element 2 is 3
Count()
.pipe(Slice, 1, 4)
.pipe(Each, (val, i) => console.log(`element ${i} is ${val}`))
.pipe(Drain)
.read();
Each
is a stream constructor wraps a source stream, and when read is called it reads the entire stream and throws it away.
Useful for streams with side-effects.
Kind: static property of streamlike
Params
- source
Stream
- the source stream to drain - each
function
- a function to get called for each value
// should log:
// element 0 is 1
// element 1 is 2
// element 2 is 3
Expand((i) => i)
.pipe(Slice, 1, 4)
.pipe(Each, (val, i) => console.log(`element ${i} is ${val}`))
.pipe(Drain)
.read();
Expand
is useful when you need custom code to expand something into a stream.
Keep in mind you'll need to return Stream.END
at some point.
Kind: static property of streamlike
Params
- expander
function
- a function to get called for each value
// res is [0, 10, 20, 30, 40]:
let res = Count()
.pipe(Slice, 0, 50)
.pipe(Filter, (val, i) => (val % 10 === 0))
.pipe(ToArray)
.read();
Filter
removes some items from a stream.
Kind: static property of streamlike
Params
- source
Stream
- a source stream - filter
function
- a filter function
// res is [1, 2, 3]:
let res = FromArray([ 1, 2, 3 ])
.pipe(ToArray)
.read();
FromArray
builds a stream from its arguments.
Kind: static property of streamlike
Params
- values
array
- values to return in the stream, in order
// res is [1, 2, 3, 4, 5, 6]:
let res = From([ 1, 2, 3 ], [4, 5, 6])
.pipe(FromBlocks)
.pipe(ToArray)
.read();
FromBlocks
'flattens' a stream of arrays into a stream of elements.
Kind: static property of streamlike
Params
- source
Stream
- a stream of arrays
// res is [1, 2, 3]:
let res = From(1, 2, 3)
.pipe(ToArray)
.read();
From
builds a stream from its arguments.
Kind: static property of streamlike
Params
- ...values
*
- values to return in the stream, in order
Guard
is a special-purpose stream wrapper designed to 'protect' a stream,
and make sure it gets opened and closed properly, even in the event of an error
Kind: static property of streamlike
Params
- source
Stream
- a source stream
// res is [1, 2, 3]:
let res = Count()
.pipe(Slice, 0, 4)
.pipe(Map, (val, i) => val + 1)
.pipe(ToArray)
.read();
Map
transforms each element in a stream.
Kind: static property of streamlike
Params
- source
Stream
- a source stream - map
function
- a map function
// res is 6:
let res = Count()
.pipe(Slice, 0, 4)
.pipe(Reduce, (state, val, i) => state + val)
.read();
Reduce
'reduces' a stream of elements to a single result.
Kind: static property of streamlike
Params
- source
Stream
- a source stream - reduce
function
- a reduce function - state
*
- the initial value of the state
// res is [1, 2, 3]:
let res = Count()
.pipe(Slice, 0, 4)
.pipe(ToArray)
.read();
Slice
'slices' out a piece of a stream to use
Kind: static property of streamlike
Params
- source
Stream
- a source stream - reduce
function
- a reduce function - state
*
- the initial value of the state
// res is [1, 2, 3, 4, 5, 6]:
let res = Splice(From(1, 2, 3), From(4, 5, 6))
.pipe(ToArray)
.read();
Splice
'splices' several streams together, concatenating them into a single stream
Kind: static property of streamlike
Params
- ...sources
Streams
- the source streams
// res is [1, 2, 3]:
let res = From(1, 2, 3)
.pipe(ToArray)
.read();
ToArray
converts a stream into an array
Kind: static property of streamlike
Params
- source
Stream
- the source stream
// res is [ [1, 2, 3], [4, 5, 6] ]:
let res = From(1, 2, 3, 4, 5, 6)
.pipe(ToBlocks, 3)
.pipe(ToArray)
.read();
ToBlocks
converts a stream into a stream of 'blocks' (fixed-size arrays of the elements)
Kind: static property of streamlike
Params
- source
Stream
- the source stream - size
number
- the size of blocks to emit - padding
*
- the padding for partial blocks