Stream is a sequence of elements made available over time. In streamer library stream is a representation of eventual value, that resolves into a head, tail pair or to null if stream is empty. head holds a reference to it's first element while tail holds reference to a stream of rest of the elements. Image below is a visual representation of this:

Streams implement CommonJS Promises/A interface (more specifically then method) for representing eventual value of head, tail pairs.

Once stream's then method is called, it will start resolving it's head and tail. After resolution, appropriate callback will be called, that optionally may be passed as arguments:

• resolve - callback (if given) is called when promise is resolved. Resolution value is passed a first argument. Resolution value is an object implementing enclosing stream API via head, tail properties. If enclosing stream is empty then it's resolution value is null.

• reject - callback (if given) is called when promise fails to resolve (gets rejected) with a reason of error as an argument.

Method then returns a value implementing same interface as owner object and is resolved with a return value of an appropriate callback function after resolution. If callbacks are not passed that it will resolved to the same value as owner.

Stream.of(1, 2, 3).then(console.log)
//=> { head: 1, tail: { then: [Function: then] } }

Stream.empty.then(console.log)
//=> null

Library exposes multiple functions for making basic streams of elements:

Raw API is using Stream function that must be passed desired head and tail as arguments. If only head is passed then tail is assumed to be empty:

// Raw API
Stream(1, Stream(2, Stream(3)))  // => <stream 1 2 3 />

Simple streams of existing elements more easily can be created via dedicated Stream.of function:

// Make stream of given elements
Stream.of(1, 2, 3)            // => <stream 1 2 3 />

Finally streams may be created out of the existing array elements or string characters or an arguments of a function:

// Make stream from value (string / array / arguments)
Stream.from('hello world')       // => <stream h e l l o   w o r l d />

The are also multiple functions that may be used to create more advance, infinite streams:

Raw API is again using Stream function that takes head as a first argument and a function as second argument which must to return a tail. First argument to that function is a stream it returns tail for.

var ones = Stream(1, function rest(self) { return self })

Again, there is a dedicated API for making infinite streams of the same element:

var ones = Stream.repeat(1)

Streams are powerful and can be easily used instead of any kind of (for, while) iteration loops and Stream.iterate(f, x) is there for that exact reason. It begins with a value x and continues forever, applying a function f to each value to calculate the next item:

var numbers = Stream.iterate(function(n) { return n + 1 }, 0)