streamlike

A set of tools for quickly processing data in a streaming way

streamlike : object

Kind: global namespace

• streamlike : object
  • .Stream
    • new Stream()
    • stream.open()
    • stream.close()
    • stream.read(recycle)
    • stream.pipe(streamContsructor, ...args)
    • Stream.END
  • .Assert ⇒ Stream
  • .Count ⇒ Stream
  • .Drain ⇒ Stream
  • .Each ⇒ Stream
  • .Expand ⇒ Stream
  • .Filter ⇒ Stream
  • .FromArray ⇒ Stream
  • .FromBlocks ⇒ Stream
  • .From ⇒ Stream
  • .Guard ⇒ Stream
  • .Map ⇒ Stream
  • .Reduce ⇒ Stream
  • .Slice ⇒ Stream
  • .Splice ⇒ Stream
  • .ToArray ⇒ Stream
  • .ToBlocks ⇒ Stream

streamlike.Stream

Kind: static class of streamlike

• .Stream
  • new Stream()
  • stream.open()
  • stream.close()
  • stream.read(recycle)
  • stream.pipe(streamContsructor, ...args)
  • Stream.END

new Stream()

Stream is the base stream class. it should always be subclassed. stream constructors should never require new.

stream.open()

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

stream.close()

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

stream.read(recycle)

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.

stream.pipe(streamContsructor, ...args)

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

Stream.END

a unique object representing a control signal marking the end of a stream

Kind: static property of Stream

streamlike.Assert ⇒ 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

streamlike.Count ⇒ Stream

// 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

streamlike.Drain ⇒ Stream

 // 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

streamlike.Each ⇒ Stream

 // 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

streamlike.Expand ⇒ Stream

 // 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

streamlike.Filter ⇒ Stream

 // 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

streamlike.FromArray ⇒ Stream

 // 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

streamlike.FromBlocks ⇒ Stream

 // 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

streamlike.From ⇒ Stream

 // 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

streamlike.Guard ⇒ Stream

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

streamlike.Map ⇒ 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

streamlike.Reduce ⇒ Stream

 // 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

streamlike.Slice ⇒ Stream

 // 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

streamlike.Splice ⇒ Stream

 // 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

streamlike.ToArray ⇒ Stream

 // 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

streamlike.ToBlocks ⇒ 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