@cycle/run
Version:
The Cycle.js run() function to use with xstream
153 lines • 6.06 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
var internals_1 = require("./internals");
/**
* 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();
* ```
*
* @param {Function} main a function that takes `sources` as input and outputs
* `sinks`.
* @param {Object} drivers an object where keys are driver names and values
* are driver functions.
* @return {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.
* @function setup
*/
function setup(main, drivers) {
if (typeof main !== "function") {
throw new Error("First argument given to Cycle must be the 'main' " + "function.");
}
if (typeof drivers !== "object" || drivers === null) {
throw new Error("Second argument given to Cycle must be an object " +
"with driver functions as properties.");
}
if (internals_1.isObjectEmpty(drivers)) {
throw new Error("Second argument given to Cycle must be an object " +
"with at least one driver function declared as a property.");
}
var engine = setupReusable(drivers);
var sinks = main(engine.sources);
if (typeof window !== 'undefined') {
window.Cyclejs = window.Cyclejs || {};
window.Cyclejs.sinks = sinks;
}
function _run() {
var disposeRun = engine.run(sinks);
return function dispose() {
disposeRun();
engine.dispose();
};
}
return { sinks: sinks, sources: engine.sources, run: _run };
}
exports.setup = setup;
/**
* 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
* ```
*
* @param {Object} drivers an object where keys are driver names and values
* are driver functions.
* @return {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.
* @function setupReusable
*/
function setupReusable(drivers) {
if (typeof drivers !== "object" || drivers === null) {
throw new Error("Argument given to setupReusable must be an object " +
"with driver functions as properties.");
}
if (internals_1.isObjectEmpty(drivers)) {
throw new Error("Argument given to setupReusable must be an object " +
"with at least one driver function declared as a property.");
}
var sinkProxies = internals_1.makeSinkProxies(drivers);
var rawSources = internals_1.callDrivers(drivers, sinkProxies);
var sources = internals_1.adaptSources(rawSources);
function _run(sinks) {
return internals_1.replicateMany(sinks, sinkProxies);
}
function disposeEngine() {
internals_1.disposeSources(sources);
internals_1.disposeSinkProxies(sinkProxies);
}
return { sources: sources, run: _run, dispose: disposeEngine };
}
exports.setupReusable = setupReusable;
/**
* 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.
*
* @param {Function} main a function that takes `sources` as input and outputs
* `sinks`.
* @param {Object} drivers an object where keys are driver names and values
* are driver functions.
* @return {Function} a dispose function, used to terminate the execution of the
* Cycle.js program, cleaning up resources used.
* @function run
*/
function run(main, drivers) {
var program = setup(main, drivers);
if (typeof window !== 'undefined' &&
window.CyclejsDevTool_startGraphSerializer) {
window.CyclejsDevTool_startGraphSerializer(program.sinks);
}
return program.run();
}
exports.run = run;
exports.default = run;
//# sourceMappingURL=index.js.map