index.html

<!doctype html>
<html>
  <head>
    <title>CONNECTIVE</title>
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
    <meta name="subject" content='Reactive Programming At Scale'/>
    <meta name="robots" content='index,follow'/>
    <meta name="description" content='A thin library enabling large-scale, efficient reactive programming in Javascript/Typescript.'/>
    <meta name="keywords" content="reactive, rxjs, programming, asynchronous, async, agent, actor, library, asynchronous programming, javascript, typescript, rx"/>
    <meta name="theme-color" content="#212121">
    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

    <link rel="shortcut icon" href="/docs/assets/favicon.ico"/>

    <link href="https://fonts.googleapis.com/css?family=Hind:400,700&display=swap" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400&display=swap" rel="stylesheet">

    <link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js"></script>

    <script src="https://cdn.jsdelivr.net/npm/clipboard@2/dist/clipboard.min.js"></script>

    <script async defer src="https://buttons.github.io/buttons.js"></script>

    <script src="https://unpkg.com/rxjs/bundles/rxjs.umd.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/lodash@4.17.14/lodash.min.js"></script>
    <script src="https://unpkg.com/@connectv/core/dist/bundles/connective.es5.min.js"></script>

    <link href="/docs/assets/styles.css" rel="stylesheet">
    <script src="/docs/assets/main.js"></script>
  </head>
  <body>
    <div id="header">
      
<a class="github-button" href="https://github.com/connect-platform/connective" data-color-scheme="no-preference: dark; light: dark; dark: dark;" data-show-count="true" aria-label="Star connect-platform/connective on GitHub">Star</a>
      
    </div>
    <div class="container">

      
<div class="logo-group">
<img class="logo light" src="/logo.svg"/>
<img class="logo dark" src="/docs/assets/logo-type-dark.svg"/>
</div>

<b>CONNECTIVE</b> facilitates large-scale
<a href="https://en.wikipedia.org/wiki/Reactive_programming" target="_blank">reactive programming</a>
in Javascript/Typescript.
It enables declarative creation of large and complex data/event flows and encourages re-use of flows.

<pre copy><code class="bash">npm i @connectv/core</code></pre>

<br><br>

A <i>Hellow World!</i> example:
<pre try="https://stackblitz.com/edit/connective-hellow-world" 
      preview="https://connective-hellow-world.stackblitz.io">
<code class="javascript">/*!*/import { wrap, map, filter } from '@connectv/core';
import { fromEvent } from 'rxjs';

let a = document.getElementById('a') as HTMLInputElement;
let p = document.getElementById('p');

//
// Will say hello to everyone but 'Donald'.
// For obvious reasons.
//

/*!*/wrap(fromEvent(a, 'input'))           // --&gt; wrap the `Observable` in a `Pin`
/*!*/.to(map(() =&gt; a.value))               // --&gt; map the event to value of the input
/*!*/.to(filter(name =&gt; name != 'Donald')) // --&gt; filter 'Donald' out
/*!*/.to(map(name =&gt; 'hellow ' + name))    // --&gt; add 'hellow' to the name
/*!*/.subscribe(msg =&gt; p.innerHTML = msg); // --&gt; write it to the &lt;p&gt; element</code>
</pre>

A more elaborate example:
<pre try="https://stackblitz.com/edit/connective-sample-fib" 
    preview="https://connective-sample-fib.stackblitz.io">
<code class="javascript">/*!*/import { wrap, pipe, map, filter, sink } from '@connectv/core';
import { fromEvent, timer } from 'rxjs';
import { delay, debounceTime } from 'rxjs/operators';

let a = document.getElementById('a');
let p = document.getElementById('p');

//
// Will calculate fibonacci sequence up to given index, displaying every number in the
// sequence along the way.
//

// --&gt; calculate next iteration step on fibonacci sequence
/*!*/let m = map(([next, prev, l]) =&gt; [next + prev, next, l - 1]);

/*!*/wrap(fromEvent(a, 'input'))                    // --&gt; wrap the `Observable` in a `Pin`
/*!*/.to(pipe(debounceTime(1000)))                // --&gt; wait for people to type in the number
/*!*/.to(map(() =&gt; parseInt((a as any).value)))   // --&gt; map the input event to value of the input
/*!*/.to(map(n =&gt; [1, 0, n]))                     // --&gt; map the number to start iteration
/*!*/.to(filter(([_, __, l]) =&gt; l &gt;= 0))          // --&gt; check if we should do any iteration
/*!*/.to(m)                                       // --&gt; calculate next step
/*!*/.to(pipe(delay(300)))                        // --&gt; take a breath
/*!*/.to(filter(([_, __, l]) =&gt; l &gt; 0))           // --&gt; check if we should continue
/*!*/.to(m)                                       // --&gt; back to the loop
/*!*/.to(map(([_, f, __]) =&gt; f))                  // --&gt; btw, lets take each number in the sequence
/*!*/.to(sink(v =&gt; p.innerHTML = v))              // --&gt; set the text of &lt;p&gt; to the fib number
/*!*/.subscribe();                                // --&gt; bind the whole thing.</code>
</pre>


<br>

<b>CONNECTIVE</b> is a thin layer on top of
<a href="https://github.com/ReactiveX/rxjs" target="_blank">RxJS</a>.
While <b>RxJS</b>'s API excels at short-lived and small reactive flows, <b>CONNECTIVE</b> provides
an API that makes creating long-living and large and/or complex reactive flows easy and intuitive.
<br><br>

<h1 id="install">How To Install</h1>
Using <b>NPM</b>:
<pre copy><code class="bash">npm i @connectv/core</code></pre>

<br>
Getting it via a CDN:
<pre><code class="html">&lt;!-- Click on each line to copy it --&gt;

&lt;!-- Dependencies --&gt;
&lt;script src="https://unpkg.com/rxjs/bundles/rxjs.umd.min.js"&gt;&lt;/script&gt;
&lt;script src="https://cdn.jsdelivr.net/npm/lodash@4.17.14/lodash.min.js"&gt;&lt;/script&gt;

&lt;script src="https://unpkg.com/@connectv/core/dist/bundles/connective.es5.min.js"&gt;&lt;/script&gt;</code></pre>

<br><br>

<h1 id="usage">How To Use</h1>
<a href="https://connective.dev/docs/overview">Read the docs</a>
for properly utilizing <b>CONNECTIVE</b>. A
<a href="https://www.learnrxjs.io/" target="_blank">basic knowledge of <b>RxJS</b></a>
would also help, though it is not mandatory. For basic usage and/or for getting started, here is a quick-dive:

<br><br>

<h2 id="quick-dive">Quick Dive</h2>
<b>CONNECTIVE</b> is about creating reactive flows. A reactive flow typically starts with some source of data/events,
leading to some sinks for those data/events which would consume them, possibly going through and being transformed by
some other nodes along the way:

<pre try="https://stackblitz.com/edit/connective-cheat-1">
<code class="javascript">/*!*/import { source, sink, pin } from '@connectv/core';

let a = source();
let b = pin();
let c = sink(value =&gt; console.log(value));

/*!*/a.to(b).to(c); // --&gt; data/events go from a to b then to c.

c.bind();

a.send('hellow!');
a.send('world!');</code>
</pre>

<pre try="https://stackblitz.com/edit/connective-cheat-2">
<code class="javascript">/*!*/import { source, sink, pin } from '@connectv/core';

let a = source();
let b = pin();
let c = sink(v =&gt; console.log(v));

/*!*/c.from(b).from(a); // --&gt; data/events that c receives come from b which in turn come from a.

c.bind();

a.send('hellow!');
a.send('world!');</code>
</pre>

Every node of such a flow is represented by a
<a href="/docs/pin">Pin</a>
(or some
<a href="https://github.com/CONNECT-platform/connective/blob/master/src/pin/pin-like.ts" target="_blank">PinLike</a>
object). The
<a href="/docs/pin"><span code>pin()</span></a>,
<a href="/docs/source"><span code>source()</span></a> and
<a href="/docs/sink"><span code>sink()</span></a> functions all return a <i>Pin</i>.

<br><br>

You can connect pins to each other using their
<a href="/docs/pin#connecting"><span code>.to()</span></a> and <span code>.from()</span> methods.
You can pass multiple parameters to <span code>.to()</span> and <span code>.from()</span>, causing the <i>Pin</i>
to be connected to multiple pins:

<pre try="https://stackblitz.com/edit/connective-cheat-3">
<code class="javascript">import { source, sink } from '@connectv/core';

let a = source();
let b = sink(value =&gt; console.log('B::' + value));
let c = sink(value =&gt; console.log('C::' + value));

/*!*/a.to(b, c); // --&gt; stuff from a goes to both b and c
b.bind(); c.bind();

a.send('hellow!');
a.send('world!');</code>
</pre>

<pre try="https://stackblitz.com/edit/connective-cheat-4">
<code class="javascript">import { source, sink } from '@connectv/core';

let a = source();
let b = source();
let c = sink(value =&gt; console.log(value));

/*!*/c.from(a, b); c.bind(); // --&gt; c's stuff come from both a and b

a.send('hellow!');
b.send('world!');</code>
</pre>

<!---------- QUICK-DIVE : SERIAL TO/FROM ---------->

<h3 id="serial" skip-toc>Serial connections</h3>

You can also connect series of pins to each other using <span code>.serialTo()</span>
and <span code>.serialFrom()</span> methods:

<pre try="https://stackblitz.com/edit/connective-cheat-4">
<code class="javascript">/*!*/import { source, sink, group } from '@connectv/core';

let a = source();
let b = source();
let c = sink(value =&gt; console.log('C::' + value));
let d = sink(value =&gt; console.log('D::' + value));

/*!*/group(a, b).serialTo(c, d);
/*!*/group(c, d).bind();

a.send('hellow!');
b.send('world!');</code>
</pre>

This means <span code>a</span> is connected to <span code>c</span> and
<span code>b</span> is connected to <span code>d</span>.

<br><br>

Also note how you can call <span code>.bind()</span> on both <span code>c</span> and <span code>d</span>
simultaenously using <span code>group()</span>.

<br><br>

<!---------- QUICK-DIVE : SUBSCRIBE ---------->

<h3 id="subscribe" skip-toc>Subscribing</h3>

You can directly subscribe on any <i>Pin</i> using its <a href="/docs/pin#subscribe"><span code>.subscribe()</span></a> method, so you don't need to use <span code>sink()</span> all the time.
You can also use <a href="/docs/group"><span code>group()</span></a> to work with a multitude of <i>Pins</i> at once:

<pre try="https://stackblitz.com/edit/connective-cheat-5">
<code class="javascript">import { source, pin, group } from '@connectv/core';

let a = source();
let b = source();

/*!*/group(a, b).to(pin()).subscribe(v =&gt; console.log(v));

a.send('hellow!');
b.send('world!');</code>
</pre>

Note that:
<ul>
  <li>the <span code>.bind()</span> method is not present on all pin types.</li>
  <li>when you call <span code>.subscribe()</span> or <span code>.bind()</span> methods of a pin, the pin
becomes <i>locked</i>. You cannot connect any new pin to a locked pin.</li>
  <li>if a pin is connected to another locked pin, it will become locked as well.</li>
  <li>you can check if a pin is locked via its <span code>.locked</span> property.</li>
</ul>

<pre try="https://stackblitz.com/edit/connective-cheat-6">
<code class="javascript">import { pin } from '@connectv/core';

let a = pin();
let b = pin();
a.to(b);

console.log('A:: ' + a.locked + ' B:: ' + b.locked);
// &gt; 'A:: false B:: false'

b.subscribe();
console.log('A:: ' + a.locked + ' B:: ' + b.locked);
// &gt; 'A:: true B:: true'</code>
</pre>

<!---------- QUICK-DIVE : OTHER SOURCES ---------->

<h3 id="other-sources" skip-toc>Sources</h3>

You can also create sources from plain values or from <i>Observables</i>:

<pre try="https://stackblitz.com/edit/connective-cheat-7">
<code class="javascript">/*!*/import { wrap, value, pin, group } from '@connectv/core';
import { interval } from 'rxjs';

/*!*/let a = value('hellow world!'); // --&gt; a emits 'hellow world!' once
/*!*/let b = wrap(interval(1000));   // --&gt; b emits a number every 1000ms

group(a, b).to(pin()).subscribe(v =&gt; console.log(v));</code>
</pre>

Note that you cannot connect any pin to <a href="/docs/wrap"><span code>wrap()</span></a>.
<br><br>

<!---------- QUICK-DIVE : SPREAD ---------->

<h3 id="spread" skip-toc>Spread</h3>

You can use <a href="/docs/spread"><span code>spread()</span></a> to turn incoming values into multiple emissions:

<pre try="https://stackblitz.com/edit/connective-cheat-8">
<code class="javascript">/*!*/import { spread, value } from '@connectv/core';

value([1, 2, 3, 4, 5, 6])
/*!*/.to(spread())
.subscribe(v =&gt; console.log(v));</code>
</pre>

<!---------- QUICK-DIVE : FILTER & MAP ---------->

<h3 id="filter-n-map" skip-toc>Filter & Map</h3>

You can change incoming values using <a href="/docs/map"><span code>map()</span></a>, and let them through or block them using
<a href="/docs/filter"><span code>filter()</span></a>:

<pre try="https://stackblitz.com/edit/connective-cheat-9">
<code class="javascript">/*!*/import { spread, value, filter, map } from '@connectv/core';

value([1, 2, 3, 4, 5, 6])
.to(spread())
/*!*/.to(filter(v =&gt; v % 2 == 0)) // --&gt; only allow even ones through
/*!*/.to(map(v =&gt; v * 10))        // --&gt; multiply each value by 10
.subscribe(v =&gt; console.log(v));</code>
</pre>

<!---------- QUICK-DIVE : CONTROL ---------->

<h3 id="control" skip-toc>Control</h3>

You can break your flow into multiple branches and join them back using <a href="/docs/control"><span code>control()</span></a>:

<pre try="https://stackblitz.com/edit/connective-cheat-10">
<code class="javascript">/*!*/import { spread, value, map, control } from '@connectv/core';

value([1, 2, 3, 4, 5, 6])
.to(spread())
.to(
  map(v =&gt; v * 10),
  map(v =&gt; v * 100),
)
/*!*/.to(control()) // --&gt; will wait for all incoming emissions and join them pair-wise
.subscribe(v =&gt; console.log(v));</code>
</pre>

<!---------- QUICK-DIVE : LOOP ---------->

<h3 id="loop" skip-toc>Loops</h3>

You can even create loops in your flow:

<pre try="https://stackblitz.com/edit/connective-cheat-11">
<code class="javascript">/*!*/import { source, map, filter } from '@connectv/core';

let a = source();
/*!*/let m = map(x =&gt; x + 1); // --&gt; lets give this pin a name so we can loop back to it

a.to(m)
/*!*/.to(filter(x =&gt; x &lt; 10)) // --&gt; keep looping until we reach 10
/*!*/.to(m)                   // --&gt; looping back to m
.subscribe(v =&gt; console.log(v));

a.send(0);</code>
</pre>

<!---------- QUICK-DIVE : PIPE ---------->

<h3 id="pipe" skip-toc>Pipe</h3>

In the example above, the order is not necessarily preserved. You can for example enforce the order by using
<b>RxJS</b>'s <span code>delay()</span> operator:

<pre try="https://stackblitz.com/edit/connective-cheat-12">
<code class="javascript">/*!*/import { source, map, filter, pipe } from '@connectv/core';
import { delay } from 'rxjs';

let a = source();
let m = map(x =&gt; x + 1); // --&gt; lets give this pin a name so we can loop back to it

a.to(m)
.to(filter(x =&gt; x &lt; 10)) // --&gt; keep looping until we reach 10
/*!*/.to(pipe(delay(1)))      // --&gt; wait a bit
.to(m)                   // --&gt; looping back to m
.subscribe(v =&gt; console.log(v));

a.send(0);</code>
</pre>

<a href="/docs/pipe"><span code>pipe()</span></a> allows you to use any <b>RxJS</b> pipeable operator.
Note that values are not passed directly to pipeable operators, they are wrapped in
<a href="/docs/emission">Emission</a>
objects, and their return value should
also be of that type.

<br><br>

<!---------- QUICK-DIVE : COMPOSITION ---------->

<h3 id="composition" skip-toc>Composition</h3>

You can re-use parts of your reactive flows using
<a href="/docs/composition"><span code>composition()</span></a>:

<pre try="https://stackblitz.com/edit/connective-cheat-13">
<code class="javascript">/*!*/import { composition, source, pin, filter, sink } from '@connectv/core';

/*!*/const evenOdd = composition(() =&gt; {             //--&gt; define the composition
/*!*/  let input = pin();                            //--&gt; it has one input pin
/*!*/  let odd = input.to(filter(x =&gt; x % 2 == 1));  
/*!*/  let even = input.to(filter(x =&gt; x % 2 == 0));
/*!*/
/*!*/  return [{ input }, { odd, even }];            //--&gt; return the inputs and outputs in the end
/*!*/});

//
// now using the composition:
//

let a = source();
/*!*/a.to(evenOdd()).serialTo(                      //--&gt; `serialTo()` here connects ...
  sink(v =&gt; console.log('ODD:: ' + v)),        //... the first output of `evenOdd()` to this sink ...
  sink(v =&gt; console.log('EVEN:: ' + v))        //... and the second output to this sink.
).subscribe();

a.send(2);
a.send(3);
a.send(4);</code>
</pre>

The composition is just a part of your reactive flow, with some pins going into it (i.e. inputs)
and some pins coming out of it (i.e. outputs). These two groups of pins are marked in the
composition definition:

<pre><code class="javascript">  return [{ input }, { odd, even }];</code></pre>

Which means <span code>input</span> is the input pin of this composition and
<span code>odd</span> and <span code>even</span> are the output pins.

<br><br>

In the example above, <span code>a.to(evenOdd())</span> connects <span code>a</span> to all of the input
pins of <span code>evenOdd()</span> (which is one pin, <span code>input</span>), and the 
<span code>serialTo()</span> connects the outputs (<span code>odd</span> and <span code>even</span>) correspondingly
to provided sinks. You can access these input and output pins individually as well:

<pre><code class="javascript">let e = evenOdd();

// --&gt; so basically these are all equivalent:

/*!*/a.to(e.in('input'));
/*!*/e.out('even').to(sink(v =&gt; console.log('ODD:: ' + v))).subscribe();
/*!*/e.out('odd').to(sink(v =&gt; console.log('EVEN:: ' + v))).subscribe();

// ... using group:

/*!*/a.to(e.in('input'));
/*!*/group(e.out('odd'), e.out('even'))
/*!*/.serialTo(
/*!*/  sink(v =&gt; console.log('ODD:: ' + v)),
/*!*/  sink(v =&gt; console.log('EVEN:: ' + v))
/*!*/).subscribe();

// ... implicit connections:

/*!*/a.to(e).serialTo(
/*!*/  sink(v =&gt; console.log('ODD:: ' + v)),
/*!*/  sink(v =&gt; console.log('EVEN:: ' + v))
/*!*/).subscribe();</code></pre>

<br><br>

<!---------- QUICK-DIVE : AGENT ---------->
<h3 id="agent" skip-toc>Agent</h3>

Compositions are sub-classes of
<a href="/docs/agent">Agent</a>
class. This base class represents all re-usable reactive flows. <b>CONNECTIVE</b> comes with a number
of useful agents that you can use in creating your own flows and compositions.

<br><br>

The main property of an Agent is its <i>Signature</i>. A signature is simply an object with a list of
strings named <span code>inputs</span> and a list of strings named <span code>outputs</span>. These two lists
denote the possible names of the incoming and outgoing pins of the Agent.

<br><br>

<!---------- QUICK-DIVE : EXPR ---------->
<h3 id="expr" skip-toc>Expr</h3>

<a href="/docs/expr"><span code>expr()</span></a> allows you to convert any function into an agent:


<pre try="https://stackblitz.com/edit/connective-cheat-14">
<code class="javascript">/*!*/import { source, expr, group } from '@connectv/core';

let a = source();
let b = source();

group(a, b)
/*!*/.serialTo(expr((a, b) => `${a} + ${b} = ${a + b}`)) //--> a is connected to the first input of the expr,
                                                    //... b to the second
.subscribe(console.log);                            //... and the output is subscribed to.

a.send(2); b.send(3);
a.send(42); b.send(30);</code>
</pre>

Notice how the expr is called for every new value provided by the sources after the two initial values.

<br><br>

In the example above, we have again used <span code>.serialTo()</span> to implicitly connect to inputs
of the <span code>expr()</span>, but you could retrieve them individually as well:

<pre><code class="javascript">let e = expr((a, b) => a + b);

group(a, b).serialTo(e.in(0), e.in(1));
e.result.subscribe(console.log);        // --&gt; this is short-hand for `e.out('result')`</code></pre>

<br><br>

<!---------- QUICK-DIVE : NODE ---------->
<h3 id="node" skip-toc>Node</h3>
A <a href="/docs/node">Node</a>
is basically a more complex version of an Expr, allowing you to emit to any outputs denoted in the signature
(instead of just <span code>"result"</span> pin). You can create nodes easily using <span code>node()</span> function:

<pre try="https://stackblitz.com/edit/connective-cheat-15">
<code class="javascript">/*!*/import { source, node } from '@connectv/core';

/*!*/let N = node({ inputs: ['a'], outputs: ['even', 'odd']}, // --&gt; set the signature
/*!*/  (input, output) =&gt; {
/*!*/    if (input.a % 2 == 0) output('even', input.a);
/*!*/    else output('odd', input.a);
/*!*/  });


let a = source();
/*!*/let n = N(); // --&gt; create a new instance of the agent we defined above
/*!*/
/*!*/a.to(n.in('a'));
/*!*/n.out('even').subscribe(v =&gt; console.log('EVEN:: ' + v));
/*!*/n.out('odd').subscribe(v =&gt; console.log('ODD:: ' + v));

a.send(3);
a.send(4);
a.send(5);</code>
</pre>

In this example we have fetched each input and output pin of <span code>n</span> individually and connected
to it. You can of-course shorten this code using <span code>.serialTo()</span>:

<pre try="https://stackblitz.com/edit/connective-cheat-15b">
<code class="javascript">import { source, node, sink } from '@connectv/core';

let N = node({ inputs: ['a'], outputs: ['even', 'odd']}, // --> set the signature
  (input, output) => {
    if (input.a % 2 == 0) output('even', input.a);
    else output('odd', input.a);
  });


let a = source();
/*!*/a.to(N()).serialTo(
/*!*/  sink(v => console.log('EVEN:: ' + v)),
/*!*/  sink(v => console.log('ODD:: ' + v))
/*!*/).subscribe();

a.send(3);
a.send(4);
a.send(5);</code>
</pre>

<!---------- QUICK-DIVE : GATE ---------->
<h3 id="gate" skip-toc>Gate</h3>

You can control when some emission passes through using <a href="/docs/gate"><span code>gate()</span></a>

<pre try="https://stackblitz.com/edit/connective-cheat-16">
<code class="javascript">/*!*/import { source, gate, map, spread, pipe, group, control } from '@connectv/core';
import { delay } from 'rxjs/operators';

let a = source();
/*!*/let g = gate();

/*!*/group(g.output, control())   // --&gt; when the gate outputs something,
                             // ... `control()` here ensures one opening of 
                             // ... the gate before the first output
.to(pipe(delay(1000)))       // --&gt; wait one second,
/*!*/.to(g.control);              // --&gt; open the gate

a.to(map(v =&gt; v.split(' '))) // --&gt; get all the words
.to(spread())                // --&gt; spread them
/*!*/.to(g)                       // --&gt; pass it through the gate
.subscribe(console.log);     // --&gt; log it when it comes out

a.send("Hellow darkness my old friend I've come to talk with you again");</code>
</pre>

In this example, <span code>g.control</span> is a <a href="/docs/control">control pin</a> that will cause the
gate to let emissions through when it receives a value itself. This pin is not mentioned in the gate's
signature. Alongside gate, some other agent types (such as <span code>node()</span> and <span code>expr()</span>)
also have this controlling pin (always accessible via <span code>.control</span>) which allows controlling
the behavior of the agent.

<br><br>

<!---------- QUICK-DIVE : STATE ---------->
<h3 id="state" skip-toc>State</h3>
You can keep reactive state values within your flows using <a href="/docs/state"><span code>state()</span></a>. For example, the following code
introduces a composition that represents the state of a <i>html input</i>, which is built on top of
<span code>state()</span>,
and then uses that composition to bind two inputs together:

<pre try="https://stackblitz.com/edit/connective-cheat-17">
<code class="javascript">/*!*/import { wrap, map, state, sink, composition, pin } from '@connectv/core';
import { fromEvent } from 'rxjs';

function inputState(el: HTMLInputElement) {
  return composition(track =&gt; {
    let input = pin(), output = pin();
/*!*/    let model = state(); track(model);   //--&gt; track the state for later cleaning it up ...

/*!*/    input.to(model)                      //--&gt; the input sets the state
/*!*/      .to(sink(v =&gt; el.value = v))       //--&gt; the HTML element value is also set based on that
/*!*/      .to(output);                       //--&gt; and it all goes to the output

    wrap(fromEvent(el, 'input'))         //--&gt; when the user changes the input as well
      .to(map(() =&gt; el.value))           //--&gt; we will fetch the new value of the input
      .to(model);                        //--&gt; and update the state using it

    return [{input}, {output}];
  })();
}


let a = inputState(document.getElementById('a') as HTMLInputElement);
let b = inputState(document.getElementById('b') as HTMLInputElement);

/*!*/a.to(b);  // --&gt; literal two-way binding
/*!*/b.to(a);

a.bind(); // --&gt; .bind() on composition will call .bind() on all child nodes having that method
b.bind();</code>
</pre>

<!---------- QUICK-DIVE : SEQUENCE ---------->
<h3 id="sequence" skip-toc>Sequence</h3>

The <a href="/docs/sequence"><span code>sequence()</span></a> agent allows you to distinguish specific sequences of events
coming from various sources:

<pre try="https://stackblitz.com/edit/connective-cheat-18">
<code class="javascript">/*!*/import { wrap, map, sequence, group } from '@connectv/core';
import { fromEvent } from 'rxjs';

group(
  wrap(fromEvent(document, 'mousedown')),
  wrap(fromEvent(document, 'mousemove')),
  wrap(fromEvent(document, 'mouseup'))
)
.serialTo(
/*!*/  sequence(1, 0, 1),   //--&gt; click is 1 mouse down, 0 mousemove, 1 mouse up
/*!*/  sequence(1, '+', 1)  //--&gt; drag is 1 mouse down, +1 mousemoves, 1 mouse up
)
.serialTo(
  map(() =&gt; 'CLICK'),
  map(() =&gt; 'DRAG')
).subscribe(console.log);</code>
</pre>

<!---------- QUICK-DIVE : MEMORY ---------->

<h3 id="memory" skip-toc>Memory Management</h3>

All pins and agents in <b>CONNECTIVE</b> come with a <span code>.clear()</span> method that will dispose
all of their internal references. The <span code>.clear()</span> method of a <i>Composition</i> will also
clear all of its child nodes.
<br><br>
<b>WARNING</b>: Calling <span code>.clear()</span> will make the pin or the agent completely unusable afterwards,
so you should call it only when you are done with the object.

<pre>
<code class="javascript">let myPin = ...;
let myAgent = ...;

//
// do your stuff
//

myPin.clear();
myAgent.clear();</code>
</pre>

Additionally, every <span code>.subscribe()</span> method returns an instance of
<a href="https://rxjs-dev.firebaseapp.com/guide/subscription" target="_blank">
  <b>RxJS</b>'s Subscription
</a>
, which is equiped with a <span code>.unsubscribe()</span> method. You should maintain the references
for subscribptions that you would want to dispose of later, and call their <span code>.unsubscribe()</span>
method.

<pre>
<code class="javascript">let myPin = ...;
//
// do whatever
//

let sub = myPin.subscribe(...);

//
// some other stuff
//

sub.unsubscribe();</code>
</pre>

If you need to call your clearing logic when some other flow is finished/cleared, call it on
<i>complete</i> notification of your subscription to the flow:

<pre>
<code class="javascript">mySource
.to(...)
.to(...)
.subscribe(
  value =&gt; do_something_with_value(value),
  undefined,
  () =&gt; clear_everything_up()
);</code>
</pre>

You can find more details about memory management in <b>CONNECTIVE</b> <a href="/docs/memory">here</a>.


<br><br>
<br><br>

<h1 id="under-the-hood">Under the Hood</h1>

As stated above, <b>CONNECTIVE</b> is just a thin layer on top of <b>RxJS</b>. This means that <b>CONNECTIVE</b>
constructs <b>RxJS</b> observable sequences for you based on the description of the reactive flow you have provided.

<br><br>

More precisely, each <i>Pin</i> is basically a lazy <i>Observable</i>. When you connect it to other pins or connect pins
to it the <i>Observable</i> is still not realized, and when the <i>Observable</i> is accessed, for example through
<span code>.subscribe()</span> method or through <span code>.observable</span> property, the <i>Observable</i> will be
created and the <i>Pin</i> will be locked.

<br><br>

Generally <b>CONNECTIVE</b> masks the API of <b>RxJS</b> so for simpler use cases you do not need to work with
<b>RxJS</b> directly, that's why knowledge of <b>RxJS</b> is not mandatory to get started with <b>CONNECTIVE</b>.
However, none of the functionality of <b>RxJS</b> is masked just for masking it, so for more advanced usage
you would definitely need to be familiar with <b>RxJS</b>.

<br><br>

You can read more in detail on how <b>CONNECTIVE</b> creates observable sequences based on your flows
<a href="/docs/under-the-hood">here</a>.

<br><br>
<br><br>

<h1 id="connective-v-rxjs">CONNECTIVE v RxJS</h1>

An important thing to notice is that <b>CONNECTIVE</b> is designed NOT as an alternative
to <b>RxJS</b>. It is rather meant to act as a <i>complement to <b>RxJS</b></i> specifically in the following
ways:

<ul>
<li>It allows description of a reactive flow in any order,</li>
<li>It provides a different model of reactive flows,</li>
<li>It provides standard abstractions for flow re-use.</li>
</ul>

<br><br>

This simply means that for smaller and simpler flows, the difference between the two is negligble. However the benefits of <b>CONNECTIVE</b> become more and more pronounced over larger and more complex reactive flows. 
You can read more about this <a href="/docs/connective-v-rxjs">in this entry</a>.

<br><br>
<br><br>

<h1 id="contact">Contact</h1>

<ul>
  <li>
    For bugs, issues and suggestions, the best way is to create issues or pull requests to
      <a href="https://github.com/CONNECT-platform/connective" target="_blank">the repository</a>.
  </li>
  <li>
    For questions, feedback, etc. join the conversation on
    <a href="https://gitter.im/connectv" target="_blank">Gitter</a>.
  </li>
  <li>
    You can also <a href="mailto:eugene@connect-platform.com">drop me an email</a> anytime.
  </li>
</ul>


      <br><br>

      
      <img class="bottom-logo" src="/docs/assets/logo-unframed.svg"/>
      
    </div>

    <div id="toc">
    </div>

    <div id="nav">
  <div class="contents">
    <a href="/">Home</a>
    <hr>
    <a href="/docs/overview">Overview</a>

    <br><br>

    <h3>Pins</h3>
    <a href="/docs/pin">pin</a>
    <hr>
    <a href="/docs/source">source</a>
    <hr>
    <a href="/docs/wrap">wrap</a>
    <hr>
    <a href="/docs/map">map</a>
    <hr>
    <a href="/docs/filter">filter</a>
    <hr>
    <a href="/docs/control">control</a>
    <hr>
    <a href="/docs/value">value</a>
    <hr>
    <a href="/docs/pack">pack</a>
    <hr>
    <a href="/docs/spread">spread</a>
    <hr>
    <a href="/docs/group">group</a>
    <hr>
    <a href="/docs/sink">sink</a>
    <hr>
    <a href="/docs/pipe">pipe</a>
    <hr>
    <a href="/docs/fork">fork</a>
    <hr>
    <a href="/docs/reduce">reduce</a>

    <br><br>

    <h3>Agents</h3>
    <a href="/docs/agent">Agent</a>
    <hr>
    <a href="/docs/expr">expr</a>
    <hr>
    <a href="/docs/state">state</a>
    <hr>
    <a href="/docs/deep">deep states</a>
    <hr>
    <a href="/docs/sampler">sampler</a>
    <hr>
    <a href="/docs/gate">gate</a>
    <hr>
    <a href="/docs/check">check</a>
    <hr>
    <a href="/docs/handle-error">handleError</a>
    <hr>
    <a href="/docs/composition">Composition</a>
    <hr>
    <a href="/docs/node">node</a>
    <hr>
    <a href="/docs/invoke">invoke</a>
    <hr>
    <a href="/docs/sequence">sequence</a>
    <!--<hr>
    <a href="/docs/switch">switch</a>-->
    <hr>
    <a href="/docs/proxy">proxy</a>
    <hr>
    <a href="/docs/join">join</a>

    <br><br>

    <h3>Misc.</h3>
    <a href="/docs/memory">Memory management</a>
    <hr>
    <a href="/docs/emission">Emission and context</a>
    <hr>
    <a href="/docs/interfaces">Interfaces & Types</a>
    <hr>
    <a href="/docs/under-the-hood">Under the hood</a>
    <hr>
    <a href="/docs/connective-v-rxjs">CONNECTIVE v RxJS</a>

  </div>
  <div class="search">
    <input id="navsearch" type="text" placeholder="Search..."/>
    <p><b>NOTE:</b> GitHub limits the rate for searching to 10 queries per minute.</p>
    <div id="navsearchicon" class="icon">
      <img class="handle" src="/docs/assets/search-handle.svg"/>
      <img class="ring" src="/docs/assets/search-ring.svg"/>
    </div>
  </div>
</div>


    <div class="footer">
  <a href="/docs/overview">Docs</a>
  <hr>
  <a href="javascript:void()" class="gitter">Community</a>

  <div id="dmtoggle">
    <div class="arc"></div>
    <div class="darc"></div>
    <div class="ray one"></div>
    <div class="ray two"></div>
    <div class="ray three"></div>
    <div class="ray four"></div>
    <div class="ray five"></div>
    <div class="ray six"></div>
    <div class="ray seven"></div>
    <div class="ray eight"></div>
  </div>

  <a id="navtoggle" class="nav no-underline">
    <div class="line"></div>
    <div class="line"></div>
    <div class="line"></div>
  </a>
</div>

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'connectv/community',
    activationElement: '.footer a.gitter',
  };
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>


<div id="gitter-overlay" class="overlay fade">
</div>

    <div id="copy-confirm" class="overlay">
      Copied to Clipboard!
    </div>
  </body>
</html>