Class Stream<T>

Marble diagram:

--a---b--c----d---e--
      drop(3)
--------------d---e--

When the given other stream emits an event or completes, the output stream will complete. Before that happens, the output stream will behaves like the input stream.

Marble diagram:

---1---2-----3--4----5----6---
  endWhen( --------a--b--| )
---1---2-----3--4--|

This method exists to allow one thing: circular dependency of streams. For instance, let's imagine that for some reason you need to create a circular dependency where stream first$ depends on stream second$ which in turn depends on first$:

import delay from 'xstream/extra/delay'

var first$ = second$.map(x => x * 10).take(3);
var second$ = first$.map(x => x + 1).startWith(1).compose(delay(100));

However, that is invalid JavaScript, because second$ is undefined on the first line. This is how imitate can help solve it:

import delay from 'xstream/extra/delay'

var secondProxy$ = xs.create();
var first$ = secondProxy$.map(x => x * 10).take(3);
var second$ = first$.map(x => x + 1).startWith(1).compose(delay(100));
secondProxy$.imitate(second$);

We create secondProxy$ before the others, so it can be used in the declaration of first$. Then, after both first$ and second$ are defined, we hook secondProxy$ with second$ with imitate() to tell that they are "the same". imitate will not trigger the start of any stream, it just binds secondProxy$ and second$ together.

The following is an example where imitate() is important in Cycle.js applications. A parent component contains some child components. A child has an action stream which is given to the parent to define its state:

const childActionProxy$ = xs.create();
const parent = Parent({...sources, childAction$: childActionProxy$});
const childAction$ = parent.state$.map(s => s.child.action$).flatten();
childActionProxy$.imitate(childAction$);

Note, though, that imitate() does not support MemoryStreams. If we would attempt to imitate a MemoryStream in a circular dependency, we would either get a race condition (where the symptom would be "nothing happens") or an infinite cyclic emission of values. It's useful to think about MemoryStreams as cells in a spreadsheet. It doesn't make any sense to define a spreadsheet cell A1 with a formula that depends on B1 and cell B1 defined with a formula that depends on A1.

If you find yourself wanting to use imitate() with a MemoryStream, you should rework your code around imitate() to use a Stream instead. Look for the stream in the circular dependency that represents an event stream, and that would be a candidate for creating a proxy Stream which then imitates the target Stream.

Marble diagram:

--a---b--c--d----|
      last()
-----------------d|

When (and if) an error happens on the input stream, instead of forwarding that error to the output stream, replaceError will call the replace function which returns the stream that the output stream will replicate. And, in case that new stream also emits an error, replace will be called again to get another stream to start replicating.

Marble diagram:

--1---2-----3--4-----X
  replaceError( () => --10--| )
--1---2-----3--4--------10--|

A debug listener is like any other listener. The only difference is that a debug listener is "stealthy": its presence/absence does not trigger the start/stop of the stream (or the producer inside the stream). This is useful so you can inspect what is going on without changing the behavior of the program. If you have an idle stream and you add a normal listener to it, the stream will start executing. But if you set a debug listener on an idle stream, it won't start executing (not until the first normal listener is added).

As the name indicates, we don't recommend using this method to build app logic. In fact, in most cases the debug operator works just fine. Only use this one if you know what you're doing.

As the name indicates, if you use this, you are most likely doing something The Wrong Way. Please try to understand the reactive way before using this method. Use it only when you know what you are doing.

As the name indicates, if you use this, you are most likely doing something The Wrong Way. Please try to understand the reactive way before using this method. Use it only when you know what you are doing.

As the name indicates, if you use this, you are most likely doing something The Wrong Way. Please try to understand the reactive way before using this method. Use it only when you know what you are doing.

Marble diagram:

---1---2-----3---
  startWith(0)
0--1---2-----3---

Marble diagram:

--a---b--c----d---e--
   take(3)
--a---b--c|