docs/api/run.html
<!doctype html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width">
<title>Cycle.js - API reference (run)</title>
<!-- Flatdoc -->
<script src='../support/vendor/jquery.js'></script>
<script src='../support/vendor/highlight.pack.js'></script>
<script src='../legacy.js'></script>
<script src='../flatdoc.js'></script>
<!-- Algolia's DocSearch main theme -->
<link href='//cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css' rel='stylesheet' />
<!-- Others -->
<script async src="//static.jsbin.com/js/embed.js"></script>
<!-- Flatdoc theme -->
<link href='../theme/style.css' rel='stylesheet'>
<script src='../theme/script.js'></script>
<link href='../support/vendor/highlight-github-gist.css' rel='stylesheet'>
<!-- Meta -->
<meta content="Cycle.js - API reference (run)" property="og:title">
<meta content="A functional and reactive JavaScript framework for predictable code" name="description">
<!-- Content -->
<script id="markdown" type="text/markdown" src="index.html">
# Run() for xstream - [source](https://github.com/cyclejs/cyclejs/tree/master/run)
Cycle.js `run(main, drivers)` function for applications written with xstream.
```
npm install @cycle/run xstream
```
**Note: `xstream` package is required too.**
## Basic usage
```js
import {run} from '@cycle/run'
run(main, drivers)
```
# API
## <a id="setup"></a> `setup(main, drivers)`
A function that prepares the Cycle application to be executed. Takes a `main`
function and prepares to circularly connects it to the given collection of
driver functions. As an output, `setup()` returns an object with three
properties: `sources`, `sinks` and `run`. Only when `run()` is called will
the application actually execute. Refer to the documentation of `run()` for
more details.
**Example:**
```js
import {setup} from '@cycle/run';
const {sources, sinks, run} = setup(main, drivers);
// ...
const dispose = run(); // Executes the application
// ...
dispose();
```
#### Arguments:
- `main: Function` a function that takes `sources` as input and outputs `sinks`.
- `drivers: Object` an object where keys are driver names and values are driver functions.
#### Returns:
*(Object)* an object with three properties: `sources`, `sinks` and `run`. `sources` is the collection of driver sources, `sinks` is the
collection of driver sinks, these can be used for debugging or testing. `run`
is the function that once called will execute the application.
## <a id="setupReusable"></a> `setupReusable(drivers)`
A partially-applied variant of setup() which accepts only the drivers, and
allows many `main` functions to execute and reuse this same set of drivers.
Takes an object with driver functions as input, and outputs an object which
contains the generated sources (from those drivers) and a `run` function
(which in turn expects sinks as argument). This `run` function can be called
multiple times with different arguments, and it will reuse the drivers that
were passed to `setupReusable`.
**Example:**
```js
import {setupReusable} from '@cycle/run';
const {sources, run, dispose} = setupReusable(drivers);
// ...
const sinks = main(sources);
const disposeRun = run(sinks);
// ...
disposeRun();
// ...
dispose(); // ends the reusability of drivers
```
#### Arguments:
- `drivers: Object` an object where keys are driver names and values are driver functions.
#### Returns:
*(Object)* an object with three properties: `sources`, `run` and `dispose`. `sources` is the collection of driver sources, `run` is the
function that once called with 'sinks' as argument, will execute the
application, tying together sources with sinks. `dispose` terminates the
reusable resources used by the drivers. Note also that `run` returns a
dispose function which terminates resources that are specific (not reusable)
to that run.
## <a id="run"></a> `run(main, drivers)`
Takes a `main` function and circularly connects it to the given collection
of driver functions.
**Example:**
```js
import run from '@cycle/run';
const dispose = run(main, drivers);
// ...
dispose();
```
The `main` function expects a collection of "source" streams (returned from
drivers) as input, and should return a collection of "sink" streams (to be
given to drivers). A "collection of streams" is a JavaScript object where
keys match the driver names registered by the `drivers` object, and values
are the streams. Refer to the documentation of each driver to see more
details on what types of sources it outputs and sinks it receives.
#### Arguments:
- `main: Function` a function that takes `sources` as input and outputs `sinks`.
- `drivers: Object` an object where keys are driver names and values are driver functions.
#### Returns:
*(Function)* a dispose function, used to terminate the execution of the Cycle.js program, cleaning up resources used.
</script>
<!-- Initializer -->
<script>
Flatdoc.run({
fetcher: function (callback) {
callback(null, document.getElementById('markdown').innerHTML);
},
highlight: function (code, value) {
return hljs.highlight(value, code).value;
},
});
</script>
</head>
<body role='flatdoc' class="no-literate">
<div class='header'>
<div class='left'>
<h1><a href="/"><img class="logo" src="../img/cyclejs_logo.svg">Cycle.js</a></h1>
<ul>
<li><a href='../getting-started.html'>Guide</a></li>
<li><a href='../api/index.html'>API</a></li>
<li><a href='../releases.html'>Releases</a></li>
<li><a href='https://github.com/cyclejs/cyclejs'>GitHub</a></li>
</ul>
<input id="docsearch" />
</div>
<div class='right'>
<!-- GitHub buttons: see https://ghbtns.com -->
<iframe src="https://ghbtns.com/github-btn.html?user=cyclejs&repo=cyclejs&type=watch&count=true"
allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
</div>
</div>
<div class='content-root'>
<div class='menubar'>
<div class='menu section'>
<div role='flatdoc-menu'></div>
</div>
</div>
<div role='flatdoc-content' class='content'></div>
</div>
<script>
((window.gitter = {}).chat = {}).options = {
room: 'cyclejs/cyclejs'
};
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
<script src='//cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js'></script>
<script src='../docsearch.js'></script>
</body>
</html>